@peopl-health/nexus 5.68.0-dev.12044 → 5.68.0-dev.12084

package/lib/clinical/flags/clinicalPatternFloorFlags.js

@@ -1,6 +1,6 @@
 const runtimeConfig = require('../../config/runtimeConfig');
 
-const DEFAULT_TIMEOUT_MS = 8000;
+const DEFAULT_TIMEOUT_MS = 20000;
 const MAX_TIMEOUT_MS = 60000;
 
 function clinicalPatternFloorLive() {

package/lib/clinical/providers/BaseLLMProvider.js

@@ -317,7 +317,7 @@ class BaseLLMProvider {
       role: 'developer',
       content: [
         '## Seguimiento, recordatorio y contingencia — no son intercambiables',
-        '- SEGUIMIENTO: tú decides volver a contactar para mantener continuidad cuando ya no falta un dato clínico que pueda cambiar el riesgo. Elige cuándo y redacta la pregunta exacta para esa persona. Usa schedulePatientReminder con reminder_type seguimiento y la utility_basis concreta. Prográmalo cuando indicaste una acción (medicamento de venta libre, autocuidado, educación) cuyo efecto se ve en 24–72 h; cuando la paciente ya dio el dato y quieres saber si el síntoma vuelve o cruza un umbral que nombraste; cuando cerraste un episodio que vale la pena revisar; o cuando tiene un evento próximo (inicio de tratamiento, cita, infusión) cuyo resultado importa. Si en este turno le indicaste un medicamento, una medida de autocuidado o que contacte a alguien (dentista, su médico, urgencias), o le transmitiste un tratamiento que indicó el equipo, decide el seguimiento en este mismo turno: si no queda una red ni un seguimiento activo para ese síntoma, programa uno a 24–48 h con utility_basis agreed_action: si fue un medicamento o una medida, para saber si funcionó; si fue una cita o un estudio, para saber si pudo agendarlo o si ya fue y cuándo. Pedirle «avísame cómo te va» no sustituye ese seguimiento. No lo programes por inactividad sola. Si la paciente vuelve a escribir antes, el seguimiento sigue pendiente y lo verás en «Seguimientos ya programados»: mantenlo, actualízalo o cancélalo según lo que cambió.',
+        '- SEGUIMIENTO: tú decides volver a contactar para mantener continuidad cuando ya no falta un dato clínico que pueda cambiar el riesgo. Elige cuándo y redacta la pregunta exacta para esa persona. Usa schedulePatientReminder con reminder_type seguimiento y la utility_basis concreta. Prográmalo cuando indicaste una acción (medicamento de venta libre, autocuidado, educación) cuyo efecto se ve en 24–72 h; cuando la paciente ya dio el dato y quieres saber si el síntoma vuelve o cruza un umbral que nombraste; cuando cerraste un episodio que vale la pena revisar; o cuando tiene un evento próximo (inicio de tratamiento, cita, infusión) cuyo resultado importa. Si en este turno le indicaste un medicamento, una medida de autocuidado o que contacte a alguien (dentista, su médico, urgencias), o le transmitiste un tratamiento que indicó el equipo, decide el seguimiento en este mismo turno: si no hay ya un seguimiento activo que lo cubra, programa uno a 24–48 h (una red abierta no lo impide: la red espera su dato y el seguimiento pregunta por lo indicado) con utility_basis agreed_action: si fue un medicamento o una medida, para saber si funcionó; si fue una cita o un estudio, para saber si pudo agendarlo o si ya fue y cuándo. Pedirle «avísame cómo te va» no sustituye ese seguimiento. No lo programes por inactividad sola. Si la paciente vuelve a escribir antes, el seguimiento sigue pendiente y lo verás en «Seguimientos ya programados»: mantenlo, actualízalo o cancélalo según lo que cambió.',
         '- RECORDATORIO: sólo existe si la paciente pidió explícitamente que se lo recuerdes o aceptó explícitamente tu oferta de recordárselo. Usa schedulePatientReminder con el tipo concreto (medicamento, cita, examen u otros) y exactamente a la hora que pidió. No lo adelantes para que llegue antes de una cita o tarea salvo que ella haya pedido ese adelanto. No infieras un recordatorio porque mencionó o agendó algo, ni lo uses para preguntar cómo sigue o vigilar incertidumbre clínica.',
         '- CONTINGENCIA: protege una incertidumbre clínica todavía abierta; falta un dato u observación que podría cambiar el grado, la urgencia o la conducta. Usa setContingencyPlan: la contingencia define qué se espera, cuánto silencio tolerar y, si corresponde, la escalada posterior. Nunca la sustituyas por seguimiento ni por recordatorio.',
         'Regla de desempate: si esperas saber “cómo sigue” por continuidad, es seguimiento; si la paciente pidió explícitamente o aceptó que le recuerdes hacer algo, es recordatorio; si esperas un dato porque no tenerlo podría volver insegura la conducta, es contingencia. Una tarea acordada o agendada sin esa petición no es un recordatorio. Una contingencia activa gana sólo mientras siga faltando su dato; cuando la resuelves porque la paciente ya lo dio o porque la preocupación quedó atendida, la vigilancia que queda es un seguimiento, no una red rearmada ni un cierre del tema. Una indicación del equipo de agendar o hacerse una visita o un estudio no resuelve por sí sola una red cuyo dato sigue faltando: la red se mantiene tal como está y, además, programa el seguimiento sobre la visita o el estudio: una red abierta no lo detiene.',
@@ -429,7 +429,7 @@ class BaseLLMProvider {
       role: 'developer',
       content: [
         '## Antes de entregar tu respuesta',
-        '- Si en esta respuesta indicas un medicamento, una medida de cuidado o que contacte a alguien (su médico, el dentista, urgencias), o transmites una indicación del equipo, programa en este turno un seguimiento con schedulePatientReminder (reminder_type seguimiento, utility_basis agreed_action) a 24–48 h: si fue un medicamento o una medida, para saber si funcionó; si fue una cita, visita o estudio, para saber si pudo agendarla o si ya fue y cuándo (el resultado se pregunta más adelante, cuando ya ocurrió). Nunca lo programes a más de 48 h. No lo hagas si ya hay un seguimiento o una red activa para eso o si la paciente pidió que no. Pedirle «avísame cómo te va» no lo sustituye.',
+        '- Si en esta respuesta indicas un medicamento, una medida de cuidado o que contacte a alguien (su médico, el dentista, urgencias), o transmites una indicación del equipo, programa en este turno un seguimiento con schedulePatientReminder (reminder_type seguimiento, utility_basis agreed_action) a 24–48 h: si fue un medicamento o una medida, para saber si funcionó; si fue una cita, visita o estudio, para saber si pudo agendarla o si ya fue y cuándo (el resultado se pregunta más adelante, cuando ya ocurrió). Nunca lo programes a más de 48 h. No lo hagas si ya hay un seguimiento que lo cubra o si la paciente pidió que no; una red abierta no lo impide. Pedirle «avísame cómo te va» no lo sustituye.',
         '- Un síntoma físico nuevo o que empeora en una persona en tratamiento oncológico o que terminó quimio hace poco es clínico aunque parezca de otra especialidad: regístralo como síntoma y escálalo si corresponde; no lo mandes sólo como pedido non_oncology_medical.',
       ].join('\n'),
       [TAIL_PLACEMENT]: true,

package/lib/clinical/services/clinicalAirtableService.js

@@ -462,8 +462,9 @@ function isAtOrBefore(when, now) {
 
 /*
  * Another check-in about to reach this patient: a net's patient check-in or another routine
- * follow-up, due within `withinMinutes` either side of now so two rows firing together see each
- * other. Patient-requested reminders are left out; they are what she asked for.
+ * follow-up due within `withinMinutes`. The lower bound is the trigger's own 5-minute lead, so two
+ * rows firing together see each other; an unsent row older than that, or expired, was missed and
+ * is not coming. Patient-requested reminders are left out; they are what she asked for.
  */
 async function hasCheckInNear({ code, withinMinutes, excludeReminderId }) {
   const window = Number(withinMinutes);
@@ -471,7 +472,7 @@ async function hasCheckInNear({ code, withinMinutes, excludeReminderId }) {
   const rows = await airtableService.getRecordByFilter(
     Monitoreo_ID,
     'reminder',
-    `AND(${fieldEquals('whatsapp_id', code)}, ${PENDING_ROW_FILTER}, OR(RIGHT({schedule_id}, 8) = "-patient", ${ROUTINE_OUTREACH_FILTER}), NOT(${fieldEquals('schedule_id', excludeReminderId)}), ABS(DATETIME_DIFF({reminder_date}, NOW(), 'minutes')) <= ${window})`,
+    `AND(${fieldEquals('whatsapp_id', code)}, ${PENDING_ROW_FILTER}, OR(RIGHT({schedule_id}, 8) = "-patient", ${ROUTINE_OUTREACH_FILTER}), NOT(${fieldEquals('schedule_id', excludeReminderId)}), DATETIME_DIFF({reminder_date}, NOW(), 'minutes') >= -5, DATETIME_DIFF({reminder_date}, NOW(), 'minutes') <= ${window}, OR({expires_at} = BLANK(), IS_AFTER({expires_at}, NOW())))`,
     null,
     ['schedule_id'],
   );

package/lib/clinical/tools/schedulePatientReminderTool.js

@@ -10,7 +10,7 @@ const { DEFAULT_TIMEZONE } = require('../../utils/scheduleUtils');
 
 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.\\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, 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',
@@ -218,9 +218,11 @@ async function cancelSeguimiento(args, runtime) {
   const { patientCode, trace } = runtime;
   const notPending = () => JSON.stringify({ success: false, error: 'not_pending — only a pending seguimiento listed under «Seguimientos ya programados» can be cancelled.', data: { reminder_id: reminderId } });
   if (!reminderId.startsWith('followup_')) return notPending();
-  if (patientCode && !isShadowRun()) {
+  if (patientCode) {
     const pending = await readPendingFollowUpsForPatient({ code: patientCode });
     if (!pending.some((plan) => plan.reminderId === reminderId)) return notPending();
+  }
+  if (patientCode && !isShadowRun()) {
     if (!await cancelFollowUp({ code: patientCode, reminderId, trace, reason: 'agent_cancelled', isLive: runtime.isLive?.bind(runtime) })) {
       return JSON.stringify({ success: false, error: 'seguimiento cancellation failed; retry', data: { reminder_id: reminderId } });
     }

package/lib/core/NexusMessaging.js

@@ -38,7 +38,7 @@ const { preProcessMessages, configureOpenAIProvider, AssistantProcessor, TURN_KI
 const { deliveryOutcome } = require('../clinical/AssistantProcessor');
 const { UNASSIGNED, alertOpsForClaimedMessage, coverIfUnassigned, coverUnansweredPatient } = require('../clinical/services/pausedSafetyNetService');
 const { buildOutreachCarrier } = require('../clinical/services/outreachCarrierService');
-const { routineOutreachCollisionReason } = require('../clinical/services/outreachSweepService');
+const { routineOutreachCollisionReason, isWithinTriageProtectionWindow } = require('../clinical/services/outreachSweepService');
 const {
   readPendingReminderForPatient,
   cancelPendingFollowUps,
@@ -60,6 +60,11 @@ const { PhiProcessor } = require('./PhiProcessor');
 
 const FOLLOW_UP_SPACING_MIN = 180;
 
+async function followUpCollisionReason(code, reminderId, now) {
+  if (!reminderId.startsWith('followup_')) return routineOutreachCollisionReason(code, { now });
+  return isWithinTriageProtectionWindow(now) ? 'triage_protection_window' : null;
+}
+
 const unbatchedRoutes = {
   __proto__: null,
   flow: 'handleFlow',
@@ -1052,6 +1057,12 @@ class NexusMessaging {
    * 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 };
+  }
+
   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');
@@ -1073,20 +1084,19 @@ class NexusMessaging {
       }
       const expiresAt = plan.expiresAt ? new Date(plan.expiresAt) : null;
       if (expiresAt && !Number.isNaN(expiresAt.getTime()) && expiresAt.getTime() <= startedAt.getTime()) {
-        await cancelFollowUp({ code, reminderId, reason: 'expired' });
-        result = { decision: 'skipped', holdReason: 'expired', accepted: false, delivered: false };
+        result = await this._retireSkippedFollowUp(code, reminderId, 'expired');
         return result;
       }
 
       // An open net alone does not hold a seguimiento: the two ask different things. Hold only when
-      // another check-in is about to reach the patient. The fire trigger does not come back for a
-      // skipped row, so a skip retires it with its reason instead of leaving a plan that never sends.
+      // another check-in is about to reach the patient. Same-day activity does not hold an agent
+      // seguimiento: the agent saw it on every turn since and kept it. The fire trigger does not come
+      // back for a skipped row, so a skip retires it with its reason instead of leaving it armed.
       const holdReason = await hasCheckInNear({ code, withinMinutes: FOLLOW_UP_SPACING_MIN, excludeReminderId: reminderId })
         ? 'check_in_near'
-        : await routineOutreachCollisionReason(code, { now: startedAt });
+        : await followUpCollisionReason(code, reminderId, startedAt);
       if (holdReason) {
-        await cancelFollowUp({ code, reminderId, reason: `skipped_${holdReason}` });
-        result = { decision: 'skipped', holdReason, accepted: false, delivered: false };
+        result = await this._retireSkippedFollowUp(code, reminderId, holdReason);
         return result;
       }
 

package/lib/index.d.ts

@@ -494,6 +494,7 @@ declare module '@peopl-health/nexus' {
     deliveryStatus?: string | null;
     deferred?: boolean;
     idempotent?: boolean;
+    retired?: boolean;
   }
 
   export interface OutreachSweepResult {

package/package.json

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