@peopl-health/nexus 5.68.2 → 5.68.4

package/lib/clinical/helpers/dateAnchorHelper.js

@@ -1,12 +1,18 @@
-const { getCurrentMexicoDateTime, getMexicoDayLabels } = require('../../utils/dateUtils');
+const { getCurrentMexicoDateTime, getMexicoDayLabels, getMexicoUpcomingDayLabels } = require('../../utils/dateUtils');
 
 const ANCHOR_SPAN_DAYS = 7;
+const UPCOMING_SPAN_DAYS = 14;
 
 function buildDateAnchor() {
   const at = Date.now();
   const labels = getMexicoDayLabels({ days: ANCHOR_SPAN_DAYS, at });
   const week = labels.map((label, i) => (i === labels.length - 1 ? `${label} (hoy)` : label));
-  return `${getCurrentMexicoDateTime(at)}\nLos últimos siete días: ${week.join('; ')}.`;
+  const upcoming = getMexicoUpcomingDayLabels({ days: UPCOMING_SPAN_DAYS, at });
+  return [
+    getCurrentMexicoDateTime(at),
+    `Los últimos siete días: ${week.join('; ')}.`,
+    `Los próximos días: ${upcoming.join('; ')}.`,
+  ].join('\n');
 }
 
 module.exports = { buildDateAnchor };

package/lib/clinical/providers/BaseLLMProvider.js

@@ -1,3 +1,5 @@
+const moment = require('moment-timezone');
+
 const { DefaultMemoryManager } = require('../memory/DefaultMemoryManager');
 const { REFUSAL, isPurelyConversational } = require('../helpers/clinicalWorkflowGuard');
 const { isToolFailure, toolRecoveryContract } = require('../helpers/toolResultHelper');
@@ -14,6 +16,7 @@ const runtimeConfig = require('../../config/runtimeConfig');
 const { TAIL_PLACEMENT, CURRENT_TURN } = require('../promptPlacement');
 const { logger } = require('../../utils/logger');
 const { sanitizeInlineText } = require('../../utils/sanitizerUtils');
+const { DEFAULT_TIMEZONE } = require('../../utils/scheduleUtils');
 const { isJsonBlob } = require('../../utils/formatUtils');
 const { isPlainObject, safeParse } = require('../../utils/jsonUtils');
 const { MAX_ADDITIONAL_TOOL_IDS } = require('../../core/runtimeToolPolicy');
@@ -33,6 +36,11 @@ const outreachMinute = (value) => {
   return match ? `${match[1]}T${match[2]}` : null;
 };
 
+const localFireTime = (value) => {
+  const at = moment.tz(value, DEFAULT_TIMEZONE);
+  return value && at.isValid() ? `${at.format('YYYY-MM-DD HH:mm')} (hora de la paciente)` : sanitizeInlineText(value);
+};
+
 const NEGATIVE_GUIDANCE_MARKER = '**When NOT to call';
 const CONTINGENCY_RULE = [
   '[REGLA DE CONTINGENCIA (prioritaria) para este turno]',
@@ -439,7 +447,7 @@ class BaseLLMProvider {
   _buildFollowUpMessage(promptVariables) {
     const pending = Array.isArray(promptVariables?.active_follow_ups) ? promptVariables.active_follow_ups : [];
     if (!pending.length) return [];
-    const rows = pending.map((item) => `- ${sanitizeInlineText(item.reminderId)} a las ${sanitizeInlineText(item.fireAt)}: ${sanitizeInlineText(item.message)}`);
+    const rows = pending.map((item) => `- ${sanitizeInlineText(item.reminderId)} a las ${localFireTime(item.fireAt)}: ${sanitizeInlineText(item.message, 600)}`);
     return [{
       role: 'developer',
       content: [

package/lib/clinical/services/outreachSweepService.js

@@ -5,6 +5,7 @@ const { Symptoms_ID } = require('../../config/airtableConfig');
 const { getMessages } = require('../../services/messageService');
 const { DEFAULT_TIMEZONE, isWithinHourWindow } = require('../../utils/scheduleUtils');
 const { logger } = require('../../utils/logger');
+const { botIsPaused } = require('../../helpers/pausedThreadHelper');
 const { PATIENT_CONTACT_WINDOW } = require('./contingencyDispatchService');
 const { hasPendingReminderForPatient } = require('./clinicalAirtableService');
 
@@ -48,6 +49,16 @@ const AUDIT = {
   turnId: 'seguimiento_turn_id',
 };
 
+const UNDELIVERED_STATUSES = ['failed', 'undelivered'];
+const CONTACT_SENT = {
+  from_me: true,
+  origin: { $nin: ['instruction', 'system'] },
+  $or: [
+    { 'statusInfo.status': { $nin: UNDELIVERED_STATUSES } },
+    { 'statusInfo.recoveryTemplateSid': { $ne: null }, 'statusInfo.recoverySentAt': null },
+  ],
+};
+
 const RECENT_OUTBOUND_HOURS = 24;
 const COLLIDING_REMINDER_MINUTES = 24 * 60;
 const INACTIVITY_DAYS = 7;
@@ -226,6 +237,7 @@ async function rejectionReason(candidate, {
 } = {}) {
   const opsReason = opsOptedOut(candidate, { now });
   if (opsReason) return opsReason;
+  if (await botIsPaused(candidate.code, { label: '[outreachSweep]' })) return 'bot_paused';
   if (!includePreviouslySwept) {
     const sweptReason = priorSweepReason(candidate);
     if (sweptReason) return sweptReason;
@@ -236,7 +248,7 @@ async function rejectionReason(candidate, {
     const recentOutbound = await getMessages(
       {
         numero: candidate.code,
-        from_me: true,
+        ...CONTACT_SENT,
         createdAt: { $gt: since },
         ...(mode === 'monday_triage_recovery' && candidate.triageContentSid
           ? { content_sid: { $ne: candidate.triageContentSid } }
@@ -271,7 +283,7 @@ async function rejectionReason(candidate, {
       const recentOutreach = await getMessages(
         {
           numero: candidate.code,
-          from_me: true,
+          ...CONTACT_SENT,
           triggeredBy: { $regex: '^(?:seguimiento:|followup_)' },
           createdAt: { $gte: inactiveSince },
         },
@@ -283,7 +295,7 @@ async function rejectionReason(candidate, {
       const lastTwoOutreaches = await getMessages(
         {
           numero: candidate.code,
-          from_me: true,
+          ...CONTACT_SENT,
           triggeredBy: { $regex: '^(?:seguimiento:|followup_)' },
           createdAt: { $gte: unansweredSince },
         },
@@ -320,7 +332,7 @@ async function routineOutreachCollisionReason(code, { now = new Date() } = {}) {
       { sort: { createdAt: -1 }, limit: 1 },
     ),
     getMessages(
-      { numero: code, from_me: true, createdAt: { $gte: today } },
+      { numero: code, ...CONTACT_SENT, createdAt: { $gte: today } },
       { sort: { createdAt: -1 }, limit: 1 },
     ),
   ]);
@@ -331,7 +343,7 @@ async function routineOutreachCollisionReason(code, { now = new Date() } = {}) {
 
 async function enrichBrief(candidate) {
   const [lastInbound] = await getMessages({ numero: candidate.code, from_me: false }, { sort: { createdAt: -1 }, limit: 1 });
-  const [lastOutbound] = await getMessages({ numero: candidate.code, from_me: true }, { sort: { createdAt: -1 }, limit: 1 });
+  const [lastOutbound] = await getMessages({ numero: candidate.code, ...CONTACT_SENT }, { sort: { createdAt: -1 }, limit: 1 });
   const fmt = (doc) => (doc?.createdAt ? moment.tz(doc.createdAt, DEFAULT_TIMEZONE).format('YYYY-MM-DD HH:mm') : null);
   return {
     ...candidate.brief,

package/lib/clinical/services/pausedSafetyNetService.js

@@ -219,9 +219,9 @@ async function applyChoice(code, choice) {
   const queued = await fileUrgentRequest(code, choice);
   if (!queued) return { queued, pledge: null };
 
-  await cancelPendingFollowUps({ code, reason: 'safety_net_request' }).catch((error) =>
-    logger.error('[PausedSafetyNet] Pending follow-ups were not stood down', { code, error: error.message })
-  );
+  if (!(await cancelPendingFollowUps({ code, reason: 'safety_net_request' }))) {
+    logger.error('[PausedSafetyNet] Pending follow-ups were not stood down', { code });
+  }
 
   try {
     return { queued, pledge: await openPledge({ code }) };

package/lib/clinical/tools/schedulePatientReminderTool.js

@@ -6,11 +6,12 @@ const { recordReminder, readPendingFollowUpsForPatient, cancelFollowUp } = requi
 const { isWithinTriageProtectionWindow } = require('../services/outreachSweepService');
 const { UTILITY_BASES, sanitizeVariable } = require('../services/outreachCarrierService');
 const { logger } = require('../../utils/logger');
-const { DEFAULT_TIMEZONE } = require('../../utils/scheduleUtils');
+const { DEFAULT_TIMEZONE, isWithinHourWindow } = require('../../utils/scheduleUtils');
+const { botIsPaused } = require('../../helpers/pausedThreadHelper');
 
 const definition = {
   name: 'schedulePatientReminder',
-  description: '**Does:** Creates or updates one agent-authored WhatsApp reminder. An ordinary reminder (medication, appointment, exam, or other task) is allowed only when the patient explicitly asks for or explicitly accepts that reminder. Do not infer a reminder merely because the patient mentioned or scheduled something. Schedule it at the exact date and time the patient requested. Never move it earlier to precede an appointment or task unless the patient explicitly requested that offset. On any patient conversation—not only a triage—or on a proactive review, use reminder_type seguimiento when this turn decides both when to check in again and the exact patient-facing words. Schedule one whenever a later contact materially helps continuity and has a concrete utility_basis — typically: you recommended an action (OTC medication, self-care, education) whose effect shows within 24–72h; the patient already gave the deciding datum and you want to know whether the symptom comes back or crosses a threshold you named; you closed a symptom episode worth checking on; or the patient has an upcoming event (starting a treatment, an appointment, an infusion) whose outcome matters. Inactivity alone is not a basis. An open contingency net does not prevent one: the net awaits its datum, the seguimiento asks about what was indicated (e.g. whether a visit or test was booked).\\n\\nA seguimiento is a lightweight engagement plan: it is capped at 600 characters, never truncated, fires at most 48 hours ahead, expires 24 hours after its chosen fire time, and cannot be created while another seguimiento is active. It stays pending when the patient writes again: later turns list it under «Seguimientos ya programados» so you keep it, update it, or cancel it (reminder_action_type cancel) when the conversation already answered it.\\n\\n**When NOT to call:** when the reminder guards unresolved clinical uncertainty, use setContingencyPlan instead; that plan owns its silence window and lifecycle. Never update a contingency-owned `plan_…-patient` reminder here.\\n\\nRequired: future patient-local reminder_date, reminder_description, reminder_type, action type, reminder_id for updates, and utility_basis for seguimiento.',
+  description: '**Does:** Creates or updates one agent-authored WhatsApp reminder. An ordinary reminder (medication, appointment, exam, or other task) is allowed only when the patient explicitly asks for or explicitly accepts that reminder. Do not infer a reminder merely because the patient mentioned or scheduled something. Schedule it at the exact date and time the patient requested. Never move it earlier to precede an appointment or task unless the patient explicitly requested that offset. On any patient conversation—not only a triage—or on a proactive review, use reminder_type seguimiento when this turn decides both when to check in again and the exact patient-facing words. Schedule one whenever a later contact materially helps continuity and has a concrete utility_basis — typically: you recommended an action (OTC medication, self-care, education) whose effect shows within 24–72h; the patient already gave the deciding datum and you want to know whether the symptom comes back or crosses a threshold you named; you closed a symptom episode worth checking on; or the patient has an upcoming event (starting a treatment, an appointment, an infusion) whose outcome matters. Inactivity alone is not a basis. An open contingency net does not prevent one: the net awaits its datum, the seguimiento asks about what was indicated (e.g. whether a visit or test was booked).\\n\\nA seguimiento is a lightweight engagement plan: it is capped at 600 characters, never truncated, fires at most 48 hours ahead and only between 11:00 and 21:00 patient-local time, expires 24 hours after its chosen fire time, and cannot be created while another seguimiento is active. It stays pending when the patient writes again: later turns list it under «Seguimientos ya programados» so you keep it, update it, or cancel it (reminder_action_type cancel) when the conversation already answered it.\\n\\n**When NOT to call:** when the reminder guards unresolved clinical uncertainty, use setContingencyPlan instead; that plan owns its silence window and lifecycle. Never update a contingency-owned `plan_…-patient` reminder here.\\n\\nRequired: future patient-local reminder_date, reminder_description, reminder_type, action type, reminder_id for updates, and utility_basis for seguimiento.',
   strict: true,
   parameters: {
     type: 'object',
@@ -52,6 +53,9 @@ const REMINDER_TYPES = definition.parameters.properties.reminder_type.enum;
 const ACTION_TYPES = definition.parameters.properties.reminder_action_type.enum;
 
 const MAX_FOLLOW_UP_LEAD_HOURS = 48;
+const ROUTINE_OUTREACH_START_HOUR = 11;
+const ROUTINE_OUTREACH_END_HOUR = 21;
+const PAUSED_ERROR = 'thread_paused — do not schedule a seguimiento in this turn.';
 
 const ISO_DATETIME = /^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}(?::\d{2}(?:\.\d{1,6})?)?$/;
 const FIRE_AT_FORMATS = ['YYYY-MM-DDTHH:mm:ss', 'YYYY-MM-DDTHH:mm', 'YYYY-MM-DD HH:mm:ss', 'YYYY-MM-DD HH:mm'];
@@ -128,7 +132,13 @@ async function handler(args = {}, context = {}) {
     if (isRoutineOutreach && isWithinTriageProtectionWindow(fireMoment.toDate())) {
       return JSON.stringify({ success: false, error: 'routine outreach cannot be scheduled during the 07:30-11:00 triage protection window; choose 11:00 or later.', data: {} });
     }
+    if (isRoutineOutreach && !isWithinHourWindow(fireMoment.toDate(), { timeZone, startHour: ROUTINE_OUTREACH_START_HOUR, endHour: ROUTINE_OUTREACH_END_HOUR })) {
+      return JSON.stringify({ success: false, error: `routine outreach must go out between ${ROUTINE_OUTREACH_START_HOUR}:00 and ${ROUTINE_OUTREACH_END_HOUR}:00 patient time; choose a time in that range.`, data: {} });
+    }
     if (isRoutineOutreach && actionType === 'create' && runtime.patientCode) {
+      if (await botIsPaused(runtime.patientCode, { label: '[schedulePatientReminder]' })) {
+        return JSON.stringify({ success: false, error: PAUSED_ERROR, data: {} });
+      }
       const pending = await readPendingFollowUpsForPatient({ code: runtime.patientCode });
       if (pending.length) {
         return JSON.stringify({ success: false, error: 'active_follow_up_exists — update the existing plan instead of crossing it.', data: { reminder_id: pending[0].reminderId } });
@@ -182,6 +192,12 @@ async function handler(args = {}, context = {}) {
       if (!persisted) {
         return JSON.stringify({ success: false, error: 'reminder persistence failed; retry scheduling', data: {} });
       }
+      if (isRoutineOutreach && actionType === 'create' && await botIsPaused(runtime.patientCode, { label: '[schedulePatientReminder]' })) {
+        if (!await cancelFollowUp({ code: runtime.patientCode, reminderId, trace, reason: 'thread_paused' })) {
+          logger.error('[schedulePatientReminder] seguimiento created on a paused thread was not stood down', { reminderId });
+        }
+        return JSON.stringify({ success: false, error: PAUSED_ERROR, data: {} });
+      }
     }
 
     trace.setSignals({ reminderIntents: [...existing, intent] });

package/lib/controllers/assistantController.js

@@ -9,6 +9,7 @@ const { getThreadInfo, setThreadDoNotAlert, switchThreadStoppedStatus } = requir
 const { getRecordByFilter } = require('../services/airtableService');
 const { sendMessage, processInstruction, processSystemMessage } = require('../core/NexusMessaging');
 const { createAssistant, switchAssistant } = require('../clinical');
+const { cancelPendingFollowUps } = require('../clinical/services/clinicalAirtableService');
 
 const asBoolean = (value) => (typeof value === 'string' ? value === 'true' : !!value);
 
@@ -19,6 +20,9 @@ const stopAssistantController = async (req, res) => {
   const stopped = asBoolean(stop);
   try {
     await switchThreadStoppedStatus(code, stopped, { byOperator: true });
+    if (stopped && !(await cancelPendingFollowUps({ code, reason: 'thread_paused' }))) {
+      logger.error('[AssistantController] Pending follow-ups were not stood down on pause', { code });
+    }
     return res.status(200).json({ success: true, message: stopped ? 'Assistant stopped' : 'Assistant resumed' });
   } catch (error) {
     logger.error('[AssistantController] Failed to stop assistant', { error: error.message, code });

package/lib/core/NexusMessaging.js

@@ -20,6 +20,7 @@ const { isWithin24HourWindow } = require('../helpers/conversationWindowHelper');
 const { maskCaregiverLabel, remapCaregiverSender, replyContactFor } = require('../helpers/caregiverHelper');
 const { triggerTemplateRecovery } = require('../helpers/templateRecoveryHelper');
 const { prepareMessageMedia } = require('../helpers/mediaHelper');
+const { botIsPaused } = require('../helpers/pausedThreadHelper');
 const { acquireSendClaim, completeSendClaim, releaseSendClaim } = require('../helpers/sendClaimHelper');
 
 const { createMessagingProvider } = require('../adapters/registry');
@@ -490,6 +491,10 @@ class NexusMessaging {
         logger.info('[NexusMessaging] proactive send cancelled — patient became active', { code: messageData.code });
         return { success: false, messageId: null, status: 'patient_active', delivered: false, deferred: false };
       }
+      if (await botIsPaused(messageData.code, { label: '[NexusMessaging]' })) {
+        logger.info('[NexusMessaging] proactive send cancelled — bot paused by the team', { code: messageData.code });
+        return { success: false, messageId: null, status: 'bot_paused', delivered: false, deferred: false };
+      }
     }
     if (!this.provider) throw new Error('No provider initialized');
 
@@ -1027,6 +1032,9 @@ class NexusMessaging {
     if (delivery?.status === 'patient_active') {
       return { decision: 'skipped', rationale: 'la paciente escribió durante la decisión', holdReason: 'patient_active', nextCheckAt: null, draft: null, accepted: false, delivered: false, deferred: false, deliveryStatus: 'patient_active', turnId: runResult.turnId || null, traceId: runResult.traceId || null };
     }
+    if (delivery?.status === 'bot_paused') {
+      return { decision: 'skipped', rationale: 'el equipo pausó el bot durante la decisión', holdReason: 'bot_paused', nextCheckAt: null, draft: null, accepted: false, delivered: false, deferred: false, deliveryStatus: 'bot_paused', turnId: runResult.turnId || null, traceId: runResult.traceId || null };
+    }
     const accepted = Boolean(runResult.output) && delivery?.success === true && delivery?.deferred !== true;
     const delivered = ['delivered', 'read'].includes(String(delivery?.status || '').toLowerCase());
     if (!dryRun && (decision.decision === 'write') !== accepted) {
@@ -1050,18 +1058,18 @@ class NexusMessaging {
     };
   }
 
-  /*
-   * Delivers a message the agent previously authored and scheduled with schedulePatientReminder.
-   * The clock only wakes this method; it does not choose copy or timing. Running inside the same
-   * patient queue as inbound WhatsApp traffic prevents an already-received message from crossing
-   * the follow-up.
-   */
   async _retireSkippedFollowUp(code, reminderId, holdReason) {
     const retired = await cancelFollowUp({ code, reminderId, reason: `skipped_${holdReason}` });
     if (!retired) logger.warn('[processScheduledFollowUp] skipped follow-up was not stood down', { reminderId, holdReason });
     return { decision: 'skipped', holdReason, accepted: false, delivered: false, retired };
   }
 
+  /*
+   * Delivers a message the agent previously authored and scheduled with schedulePatientReminder.
+   * The clock only wakes this method; it does not choose copy or timing. Running inside the same
+   * patient queue as inbound WhatsApp traffic prevents an already-received message from crossing
+   * the follow-up.
+   */
   async processScheduledFollowUp(code, { reminderId, firstName, now = new Date() } = {}) {
     if (!code || !reminderId) throw new Error('code and reminderId are required');
     if (typeof firstName !== 'string' || !firstName.trim()) throw new Error('firstName is required');

package/lib/utils/dateUtils.js

@@ -6,13 +6,20 @@ const nowInMexico = (at) => moment(at).tz(MEXICO_TZ).locale('es');
 
 const getCurrentMexicoDateTime = (at) => nowInMexico(at).format(MEXICO_STAMP);
 
+const dayLabel = (day, now) => (day.year() === now.year() ? day.format('dddd D [de] MMMM') : day.format('dddd D [de] MMMM [de] YYYY'));
+
 const getMexicoDayLabels = ({ days, at }) => {
   const now = nowInMexico(at);
   const labels = [];
-  for (let back = days - 1; back >= 0; back -= 1) {
-    const at = now.clone().subtract(back, 'days');
-    labels.push(at.year() === now.year() ? at.format('dddd D [de] MMMM') : at.format('dddd D [de] MMMM [de] YYYY'));
-  }
+  for (let back = days - 1; back >= 0; back -= 1) labels.push(dayLabel(now.clone().subtract(back, 'days'), now));
+  return labels;
+};
+
+// The days after today, nearest first; today itself is not included.
+const getMexicoUpcomingDayLabels = ({ days, at }) => {
+  const now = nowInMexico(at);
+  const labels = [];
+  for (let ahead = 1; ahead <= days; ahead += 1) labels.push(dayLabel(now.clone().add(ahead, 'days'), now));
   return labels;
 };
 
@@ -83,6 +90,7 @@ module.exports = {
   addWorkingMinutes,
   getCurrentMexicoDateTime,
   getMexicoDayLabels,
+  getMexicoUpcomingDayLabels,
   parseDate,
   toIsoInstant,
   ageInYears,

package/package.json

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