@peopl-health/nexus 5.68.1 → 5.68.3

package/lib/clinical/helpers/doctorReviewMessageHelper.js

@@ -6,12 +6,12 @@ const URGENCY_LABELS = {
   stat: 'inmediata', asap: 'lo antes posible', urgent: 'urgente', routine: 'rutina',
 };
 
-const PROPOSAL_HEADING = 'Propuesta de tratamiento (sugerencia para su aprobación, no es una indicación):';
-const REQUESTED_ACTION = 'Acción solicitada: ¿aprueba la propuesta, la modifica o prefiere una valoración presencial?';
-const ASSESSMENT_ACTION = 'Acción solicitada: valoración médica prioritaria. ¿La valora en persona, la envía a urgencias o indica otra conducta?';
+const REQUESTED_ACTION = '¿Aprueba la propuesta, la modifica o prefiere una valoración presencial?';
+const ASSESSMENT_ACTION = 'Requiere valoración médica: ¿la valora en persona, la envía a urgencias o indica otra conducta?';
 const DOCTOR_TITLE = /^(dr|dra)\.?\s/i;
 
 const withTitle = (name) => (DOCTOR_TITLE.test(name) ? name : `Dr./Dra. ${name}`);
+const sentence = (text) => (/[.!?]$/.test(text) ? text : `${text}.`);
 
 function latestAlarm(review) {
   const alarms = Array.isArray(review?.alarms) ? review.alarms : [];
@@ -28,19 +28,6 @@ function flagsByStatus(sections) {
   };
 }
 
-function symptomLines(sections, stamp, fallbackSymptom = null) {
-  const grade = [1, 2, 3].includes(sections?.grade) ? `G${sections.grade}` : 'grado no establecido';
-  const said = [inlineOf(sections?.symptom) || fallbackSymptom || 'síntoma no especificado', grade, ...stamp].filter(Boolean);
-  const { present, absent, unassessed } = flagsByStatus(sections);
-  if (!present.length && !absent.length && !unassessed.length) return [`Síntoma: ${said.join(' · ')}`, 'Banderas rojas: no documentadas.'];
-  return [
-    `Síntoma: ${said.join(' · ')}`,
-    `Banderas rojas presentes: ${present.length ? present.join(', ') : 'ninguna'}.`,
-    `Banderas rojas ausentes: ${absent.length ? absent.join(', ') : 'ninguna revisada'}.`,
-    ...(unassessed.length ? [`Banderas rojas sin evaluar: ${unassessed.join(', ')}.`] : []),
-  ];
-}
-
 function vitalsLine(vitals) {
   const parts = [];
   if (vitals?.temperatureC != null) parts.push(`T ${vitals.temperatureC} °C`);
@@ -48,62 +35,66 @@ function vitalsLine(vitals) {
   if (vitals?.systolic != null || vitals?.diastolic != null) parts.push(`PA ${vitals.systolic ?? '?'}/${vitals.diastolic ?? '?'} mmHg`);
   if (vitals?.spo2 != null) parts.push(`SpO2 ${vitals.spo2}%`);
   if (vitals?.respiratoryRate != null) parts.push(`FR ${vitals.respiratoryRate} rpm`);
-  return parts.length ? `Signos vitales: ${parts.join(' · ')}.` : 'Signos vitales: no reportados.';
+  return parts.length ? `Signos vitales: ${parts.join(' · ')}.` : null;
 }
 
-function proposalItemLine(symptom, item) {
+function drugOf(symptom, item) {
   const entry = formularyFor(symptom);
   const drug = entry ? findDrug(entry, item) : null;
   if (!drug) return null;
-  const name = [drug.drug, drug.brand ? `(${drug.brand})` : null, drug.strength].filter(Boolean).join(' ');
-  const parts = [`- ${name}`];
-  if (drug.instructions) parts.push(drug.instructions);
-  parts.push(`posición en la tabla: ${drug.tableLabel}`);
-  const why = inlineOf(item?.justification?.text);
-  if (why) parts.push(`motivo: ${why}`);
-  return parts.join(' — ');
+  const name = [drug.drug, drug.strength].filter(Boolean).join(' ');
+  const why = inlineOf(item?.justification?.text)?.replace(/[.;]+$/, '');
+  return [drug.instructions ? `${name} (${drug.instructions})` : name, why && `motivo: ${why}`].filter(Boolean).join(', ');
 }
 
-function proposalBody({ proposal, withheldReason }) {
-  if (!proposal?.items?.length) {
-    const reason = inlineOf(withheldReason) || 'sin propuesta farmacológica';
-    return [`No se propone tratamiento sintomático: ${reason}. Se prioriza la valoración médica.`];
-  }
-  const lines = proposal.items.map((item) => proposalItemLine(proposal.symptom, item)).filter(Boolean);
-  const declared = [...(proposal.conditions ?? []), ...(proposal.ruledOut ?? []).map((key) => `descartado: ${key}`)].map(inlineOf).filter(Boolean);
-  if (declared.length) lines.push(`Condiciones que se declararon para esta propuesta (verificar): ${declared.join(', ')}.`);
-  return lines;
+const proposedDrugs = ({ proposal }) => (proposal?.items ?? []).map((item) => drugOf(proposal.symptom, item)).filter(Boolean);
+
+function proposalLine({ proposal, withheldReason }) {
+  const drugs = proposedDrugs({ proposal });
+  if (!drugs.length) return `→ Sin propuesta de tratamiento: ${sentence(inlineOf(withheldReason) || 'requiere valoración médica')}`;
+  const declared = [...(proposal.conditions ?? []), ...(proposal.ruledOut ?? []).map((key) => `descartado ${key}`)]
+    .map((key) => inlineOf(key)?.replace(/_/g, ' ')).filter(Boolean);
+  const table = formularyFor(proposal.symptom)?.label;
+  return [`→ Propuesta para su aprobación (tabla ${table}): ${sentence(drugs.join('; '))}`, declared.length && `Verificar: ${sentence(declared.join(', '))}`].filter(Boolean).join(' ');
 }
 
-function proposalHeading(entry, symptomName) {
-  const tableLabel = entry.proposal?.items?.length ? formularyFor(entry.proposal.symptom)?.label : null;
-  return tableLabel ? `${symptomName} (tabla: ${tableLabel})` : symptomName;
+function symptomParagraph(entry, fallbackSymptom) {
+  const sections = entry.sections ?? {};
+  const grade = [1, 2, 3].includes(sections.grade) ? `G${sections.grade}` : 'grado no establecido';
+  const { present, absent, unassessed } = flagsByStatus(sections);
+  const isUndocumented = !present.length && !absent.length && !unassessed.length;
+  const summary = inlineOf(sections.characterizationSummary);
+  return [
+    `${inlineOf(sections.symptom) || fallbackSymptom || 'Síntoma no especificado'} (${grade}):`,
+    summary && sentence(summary),
+    present.length && `${present.length > 1 ? 'Banderas rojas presentes' : 'Bandera roja presente'}: ${sentence(present.join(', '))}`,
+    unassessed.length && `Falta confirmar: ${sentence(unassessed.join(', '))}`,
+    isUndocumented && 'Banderas rojas no documentadas.',
+    !present.length && !unassessed.length && absent.length && 'Sin banderas rojas.',
+    proposalLine(entry),
+  ].filter(Boolean).join(' ');
 }
 
 function composeDoctorBody({ alarm, shared, symptoms }) {
-  const several = symptoms.length > 1;
-  const name = (entry) => inlineOf(entry.sections?.symptom) || 'Síntoma';
-  const stamp = [
-    URGENCY_LABELS[alarm?.urgencyLevel] ?? inlineOf(alarm?.urgencyLevel),
-    alarm?.raisedAt ? mexicoStamp(alarm.raisedAt) : null,
-  ];
   const context = shared?.oncologyContext;
-  const value = (text) => inlineOf(text) || 'no disponible';
+  const treatment = inlineOf(context?.treatment);
+  const lastDose = inlineOf(context?.lastDose);
+  const priorManagement = inlineOf(context?.priorManagement);
+  const response = inlineOf(context?.response);
+  const urgency = [URGENCY_LABELS[alarm?.urgencyLevel] ?? inlineOf(alarm?.urgencyLevel), alarm?.raisedAt ? mexicoStamp(alarm.raisedAt) : null].filter(Boolean);
+  const priorities = inlineOf(shared?.doctorPriorities);
   return [
-    ...symptoms.flatMap((entry, index) => symptomLines(entry.sections, index === 0 ? stamp : [], several ? null : inlineOf(alarm?.symptom))),
-    '',
-    ...symptoms.map((entry) => `${several ? `Caracterización (${name(entry)})` : 'Caracterización'}: ${inlineOf(entry.sections?.characterizationSummary) || 'no disponible'}`),
+    urgency.length ? `Urgencia: ${urgency.join(' · ')}` : null,
+    `Tratamiento: ${treatment || 'no disponible'}; última dosis ${lastDose || 'no disponible'}.`,
+    priorManagement || response ? `Manejo previo: ${sentence([priorManagement, response && `respuesta ${response}`].filter(Boolean).join('; '))}` : null,
     vitalsLine(shared?.vitals),
-    ...(inlineOf(shared?.objectiveData) ? [`Datos objetivos: ${inlineOf(shared.objectiveData)}`] : []),
-    '',
-    `Contexto oncológico: tratamiento ${value(context?.treatment)}; última dosis ${value(context?.lastDose)}.`,
-    `Manejo previo y respuesta: ${value(context?.priorManagement)}; respuesta ${value(context?.response)}.`,
+    inlineOf(shared?.objectiveData) ? `Datos objetivos: ${sentence(inlineOf(shared.objectiveData))}` : null,
     '',
-    PROPOSAL_HEADING,
-    ...symptoms.flatMap((entry) => (several ? [`${proposalHeading(entry, name(entry))}:`, ...proposalBody(entry)] : proposalBody(entry))),
+    ...symptoms.map((entry) => symptomParagraph(entry, symptoms.length > 1 ? null : inlineOf(alarm?.symptom))),
     '',
-    symptoms.some((entry) => entry.proposal?.items?.length) ? REQUESTED_ACTION : ASSESSMENT_ACTION,
-  ].join('\n');
+    priorities ? `Prioridades: ${sentence(priorities)}` : null,
+    symptoms.some((entry) => proposedDrugs(entry).length) ? REQUESTED_ACTION : ASSESSMENT_ACTION,
+  ].filter((line) => line !== null).join('\n');
 }
 
 function identityLines({ identity, review }) {

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/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

@@ -1050,18 +1050,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/package.json

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