@peopl-health/nexus 5.52.0-dev.7705 → 5.52.0-dev.7717

package/lib/clinical/config/safetyNetConfig.js

@@ -0,0 +1,64 @@
+const runtimeConfig = require('../../config/runtimeConfig');
+
+const DEFAULT_OFFER_WINDOW_MS = 4 * 60 * 60 * 1000;
+const DEFAULT_HUMAN_QUIET_MS = 60 * 60 * 1000;
+const DEFAULT_TAP_WINDOW_MS = 30 * 60 * 1000;
+const DEFAULT_PLEDGE_MS = 30 * 60 * 1000;
+const DEFAULT_SWEEP_INTERVAL_MS = 5 * 60 * 1000;
+
+const CONTACT_WINDOW = { timeZone: 'America/Mexico_City', startHour: 8, endHour: 21 };
+
+const SAFETY_NET_SOURCE = 'paused_safety_net';
+
+const humanReplyFilter = (code, since) => ({
+  numero: code,
+  from_me: true,
+  content_sid: null,
+  origin: { $ne: 'assistant' },
+  triggeredBy: { $ne: SAFETY_NET_SOURCE },
+  createdAt: { $gt: since }
+});
+
+const CHOICE_LABEL_KEYS = {
+  urgent: 'PAUSED_SAFETY_NET_URGENT_LABEL',
+  callback: 'PAUSED_SAFETY_NET_CALLBACK_LABEL',
+  later: 'PAUSED_SAFETY_NET_LATER_LABEL'
+};
+
+let injected = {};
+
+const configureSafetyNet = (config = {}) => {
+  injected = config && typeof config === 'object' ? config : {};
+};
+
+const _resetSafetyNetConfig = () => {
+  injected = {};
+};
+
+const text = (key, envKey) => {
+  const raw = injected[key] ?? runtimeConfig.get(envKey);
+  const value = String(raw ?? '').trim();
+  return value || null;
+};
+
+const duration = (key, envKey, fallback) => {
+  const raw = Number(injected[key] ?? runtimeConfig.get(envKey));
+  return Number.isFinite(raw) && raw > 0 ? raw : fallback;
+};
+
+module.exports = {
+  CONTACT_WINDOW,
+  SAFETY_NET_SOURCE,
+  humanReplyFilter,
+  CHOICE_LABEL_KEYS,
+  configureSafetyNet,
+  _resetSafetyNetConfig,
+  getSafetyNetContentSid: () => text('contentSid', 'PAUSED_SAFETY_NET_CONTENT_SID'),
+  getSafetyNetPhone: () => text('phone', 'PAUSED_SAFETY_NET_PHONE'),
+  getSafetyNetLabel: (choice) => text(`${choice}Label`, CHOICE_LABEL_KEYS[choice]),
+  getOfferWindowMs: () => duration('offerWindowMs', 'PAUSED_SAFETY_NET_WINDOW_MS', DEFAULT_OFFER_WINDOW_MS),
+  getHumanQuietMs: () => duration('humanQuietMs', 'SAFETY_NET_HUMAN_QUIET_MS', DEFAULT_HUMAN_QUIET_MS),
+  getTapWindowMs: () => duration('tapWindowMs', 'SAFETY_NET_TAP_WINDOW_MS', DEFAULT_TAP_WINDOW_MS),
+  getPledgeMs: () => duration('pledgeMs', 'SAFETY_NET_PLEDGE_MS', DEFAULT_PLEDGE_MS),
+  getSweepIntervalMs: () => duration('sweepIntervalMs', 'SAFETY_NET_SWEEP_INTERVAL_MS', DEFAULT_SWEEP_INTERVAL_MS)
+};

package/lib/clinical/services/assistantService.js

@@ -16,9 +16,19 @@ const { getMessages, countMessages } = require('../../services/messageService');
 
 const { getAssistantById } = require('./assistantResolver');
 const { recordPausedThreadMessage } = require('./clinicalAirtableService');
+const { offerSafetyNet } = require('./pausedSafetyNetService');
 
 const MEDIA_BACKLOG_LIMIT = 10;
 
+const pausedAlertText = async (code, newest) => {
+  if (!newest.interactive_type) return newest.plainBody || newest.body;
+  const [written] = await getMessages(
+    { numero: code, from_me: false, interactive_type: null, createdAt: { $lte: newest.createdAt } },
+    { sort: { createdAt: -1 }, limit: 1 }
+  );
+  return written ? written.plainBody || written.body : null;
+};
+
 const fetchMediaBacklog = async (code, trigger) => {
   const [lastOutbound] = await getMessages(
     { numero: code, from_me: true, createdAt: { $lt: trigger.createdAt } },
@@ -112,7 +122,12 @@ const preProcessMessagesCore = async (code, message_ = null, thread) => {
       return { shouldProcess: false, messages: null, timings, pendingMediaUpdates: [] };
     }
 
-    if (thread.stopped) await recordPausedThreadMessage({ code, text: lastMessage[0].plainBody || lastMessage[0].body });
+    if (thread.stopped) {
+      await Promise.allSettled([
+        recordPausedThreadMessage({ code, text: await pausedAlertText(code, lastMessage[0]) }),
+        offerSafetyNet({ code })
+      ]);
+    }
 
     const backlog = await fetchMediaBacklog(code, lastMessage[0]);
     const replies = [...backlog, ...lastMessage];

package/lib/clinical/services/clinicalAirtableService.js

@@ -14,6 +14,7 @@ const recentIntakeCache = new WriteClaimStore({ namespace: 'intake', ttlMs: INTA
 const EMERGENCY_MERGE_WINDOW_MS = 5 * 60 * 1000;
 const EMERGENCY_URGENCY_RANK = { routine: 0, urgent: 1, asap: 2, stat: 3 };
 const recentEmergencyCache = new WriteClaimStore({ namespace: 'emergency', ttlMs: EMERGENCY_MERGE_WINDOW_MS, maxSize: 500 });
+const PAUSED_THREAD_DETAILS_PREFIX = 'Bot en pausa:';
 const PAUSED_ALERT_WINDOW_MS = 4 * 60 * 60 * 1000;
 const recentPausedAlertCache = new WriteClaimStore({ namespace: 'paused-alert', ttlMs: PAUSED_ALERT_WINDOW_MS, maxSize: 1000 });
 const UNRESOLVED_WINDOW_MS = 30 * 60 * 1000;
@@ -119,7 +120,7 @@ async function recordPausedThreadMessage({ code, text }) {
     code,
     trace: null,
     question: text || 'El paciente envió un archivo sin texto.',
-    details: `Bot en pausa: el paciente ${code} escribió y nadie ha respondido. Revisar la conversación.`,
+    details: `${PAUSED_THREAD_DETAILS_PREFIX} el paciente ${code} escribió y nadie ha respondido. Revisar la conversación.`,
     category: 'contact_team_member',
     urgency: 'soon',
   });
@@ -501,6 +502,7 @@ async function recordClusterRecommendationsMirror({ code, triageRecordId, step1
 }
 
 module.exports = {
+  PAUSED_THREAD_DETAILS_PREFIX,
   recordUnresolvedRequest,
   recordPausedThreadMessage,
   recordEmergency,

package/lib/clinical/services/pausedSafetyNetService.js

@@ -0,0 +1,275 @@
+const {
+  CONTACT_WINDOW,
+  SAFETY_NET_SOURCE,
+  getHumanQuietMs,
+  getOfferWindowMs,
+  getPledgeMs,
+  getSafetyNetContentSid,
+  getSafetyNetLabel,
+  getSafetyNetPhone,
+  getTapWindowMs
+} = require('../config/safetyNetConfig');
+const { logger } = require('../../utils/logger');
+
+const { acquireSendClaim, completeSendClaim, releaseSendClaim } = require('../../helpers/sendClaimHelper');
+
+const { normalizePayload: normalize, registerInteractiveRoute } = require('../../core/interactiveRouteService');
+const { getPatientTasks, updatePatientTask } = require('../../services/patientTaskService');
+
+const { WriteClaimStore } = require('./writeClaimStore');
+const { PAUSED_THREAD_DETAILS_PREFIX, recordUnresolvedRequest } = require('./clinicalAirtableService');
+const { humanRepliedSince, openPledge } = require('./safetyNetPledgeService');
+
+const getMessaging = () => require('../../core/NexusMessaging');
+
+const SOURCE = SAFETY_NET_SOURCE;
+const PAYLOAD_PREFIX = 'peopl_safetynet_';
+const CHOICES = ['urgent', 'callback', 'later'];
+const REQUEST_CATEGORY = 'contact_team_member';
+const CAN_WAIT_NOTE = 'El paciente indicó que su solicitud puede esperar.';
+const ATTENDED_STATUS = 'sin atender';
+
+const REQUEST_COPY = {
+  urgent: {
+    question: 'El paciente indicó que su situación es urgente',
+    details: (code) => `El paciente ${code} recibió el aviso de bot en pausa y eligió "urgencia". Se le dio el número para llamar. Revisar la conversación ahora.`
+  },
+  callback: {
+    question: 'El paciente pidió que el equipo lo contacte hoy',
+    details: (code) => `El paciente ${code} recibió el aviso de bot en pausa y pidió que lo contacten. Se le prometió contacto; revisar la conversación.`
+  }
+};
+
+let offerClaimStore = null;
+let tapClaimStore = null;
+let phoneCheckedFor = null;
+
+const offerClaims = () => {
+  if (!offerClaimStore) offerClaimStore = new WriteClaimStore({ namespace: 'paused-safety-net', ttlMs: getOfferWindowMs() });
+  return offerClaimStore;
+};
+
+const tapClaims = () => {
+  if (!tapClaimStore) tapClaimStore = new WriteClaimStore({ namespace: 'safety-net-choice', ttlMs: getTapWindowMs() });
+  return tapClaimStore;
+};
+
+const _resetSafetyNetState = () => {
+  offerClaimStore = null;
+  tapClaimStore = null;
+  phoneCheckedFor = null;
+};
+
+function matchSafetyNetChoice(payload, title) {
+  const candidate = normalize(payload);
+  if (candidate.startsWith(PAYLOAD_PREFIX)) {
+    const suffix = candidate.slice(PAYLOAD_PREFIX.length);
+    return CHOICES.find((choice) => choice === suffix) || null;
+  }
+
+  const label = normalize(title) || candidate;
+  if (!label) return null;
+  return CHOICES.find((choice) => {
+    const configured = normalize(getSafetyNetLabel(choice));
+    return configured && configured === label;
+  }) || null;
+}
+
+async function warnIfPhoneDiffersFromTemplate(contentSid) {
+  const phone = getSafetyNetPhone();
+  if (!phone || phoneCheckedFor === contentSid) return;
+  phoneCheckedFor = contentSid;
+  try {
+    const body = await getMessaging().requireProvider().renderTemplate(contentSid);
+    const digits = (value) => String(value ?? '').replace(/\D/g, '');
+    if (body && !digits(body).includes(digits(phone))) {
+      logger.error('[PausedSafetyNet] The configured phone number is absent from the template body', { contentSid });
+    }
+  } catch (error) {
+    phoneCheckedFor = null;
+    logger.warn('[PausedSafetyNet] Could not read the template to check the phone number', { contentSid, error: error.message });
+  }
+}
+
+async function offerSafetyNet({ code }) {
+  try {
+    const contentSid = getSafetyNetContentSid();
+    if (!code || !contentSid || !getSafetyNetPhone()) return { sent: false, reason: 'not_configured' };
+    if (await offerClaims().get(code)) return { sent: false, reason: 'recent_offer' };
+    if (await humanRepliedSince(code, new Date(Date.now() - getHumanQuietMs()))) return { sent: false, reason: 'human_active' };
+
+    await warnIfPhoneDiffersFromTemplate(contentSid);
+
+    const result = await getMessaging().sendMessage({ code, contentSid, triggeredBy: SOURCE });
+    const sent = result?.success === true || result?.completed === true;
+    if (!sent) return { sent: false, reason: result?.status || 'send_failed' };
+
+    await offerClaims().set(code, true);
+    return { sent: true, reason: null };
+  } catch (error) {
+    logger.error('[PausedSafetyNet] Could not offer the safety net', { code, error: error.message });
+    return { sent: false, reason: 'error' };
+  }
+}
+
+async function fileUrgentRequest(code, choice) {
+  const copy = REQUEST_COPY[choice];
+  return recordUnresolvedRequest({
+    code,
+    trace: null,
+    question: copy.question,
+    details: copy.details(code),
+    category: REQUEST_CATEGORY,
+    urgency: 'urgent'
+  });
+}
+
+async function markCanWait(code) {
+  const { requests = [] } = await getPatientTasks(code);
+  const target = requests.find((request) => request.status === ATTENDED_STATUS
+    && request.category === REQUEST_CATEGORY
+    && String(request.details || '').startsWith(PAUSED_THREAD_DETAILS_PREFIX));
+  if (!target) return false;
+
+  await updatePatientTask({
+    code,
+    kind: 'requests',
+    recordId: target.recordId,
+    changes: {
+      urgency: 'routine',
+      note: [target.note, CAN_WAIT_NOTE].filter(Boolean).join('\n')
+    },
+    updatedBy: SOURCE,
+    source: SOURCE
+  });
+  return true;
+}
+
+async function applyChoice(code, choice) {
+  if (choice === 'later') return { queued: true, downgraded: await markCanWait(code), pledge: null };
+
+  const queued = await fileUrgentRequest(code, choice);
+  if (choice !== 'callback') return { queued, pledge: null };
+  if (!queued) return { queued, pledge: null };
+
+  try {
+    return { queued, pledge: await openPledge({ code }) };
+  } catch (error) {
+    logger.error('[PausedSafetyNet] The request was filed but no pledge was opened', { code, error: error.message });
+    return { queued, pledge: null };
+  }
+}
+
+const withPhone = (text, closing) => {
+  const phone = getSafetyNetPhone();
+  return phone ? `${text} ${closing.replace('{phone}', phone)}` : text;
+};
+
+function ackFor(choice, outcome) {
+  if (outcome.stale) {
+    return withPhone('Recibimos tu respuesta y el equipo va a revisar tu conversación.', 'Si necesitas ayuda ahora, llámanos al {phone}.');
+  }
+
+  if (!outcome.queued) {
+    return withPhone('No pudimos registrar tu solicitud.', 'Por favor llámanos al {phone} para que te atendamos.');
+  }
+
+  if (choice === 'urgent') {
+    return withPhone('Entendido, ya avisamos al equipo.', 'Si es una urgencia médica, llámanos ahora al {phone}.');
+  }
+
+  if (choice === 'later') {
+    return outcome.downgraded
+      ? withPhone('Gracias, lo anotamos. El equipo revisará tu mensaje.', 'Si necesitas ayuda antes, llámanos al {phone}.')
+      : withPhone('Gracias. El equipo revisará tu mensaje.', 'Si necesitas ayuda antes, llámanos al {phone}.');
+  }
+
+  if (!outcome.pledge) {
+    return withPhone('Listo, ya avisamos al equipo y te van a contactar.', 'Si te sientes peor antes, llámanos al {phone}.');
+  }
+
+  if (outcome.pledge.deferredToWindow) {
+    return withPhone(
+      `Listo, ya avisamos al equipo. Te van a contactar en cuanto abran, a partir de las ${CONTACT_WINDOW.startHour}:00.`,
+      'Si es una urgencia médica, llámanos ahora al {phone}.'
+    );
+  }
+
+  const minutes = Math.round(getPledgeMs() / 60000);
+  return withPhone(
+    `Listo. Un miembro del equipo te va a contactar en los próximos ${minutes} minutos.`,
+    'Si te sientes peor antes, llámanos al {phone}.'
+  );
+}
+
+async function sendAck(code, choice, outcome) {
+  try {
+    await getMessaging().sendMessage({ code, body: ackFor(choice, outcome), triggeredBy: SOURCE });
+    return true;
+  } catch (error) {
+    logger.error('[PausedSafetyNet] Could not acknowledge the tap', { code, choice, error: error.message });
+    return false;
+  }
+}
+
+async function handleSafetyNetTap({ code, payload, title }) {
+  const choice = matchSafetyNetChoice(payload, title);
+  if (!choice || !code) return { handled: false };
+
+  const claim = await acquireSendClaim({ idempotencyKey: `safetynet:${code}:${choice}` });
+  if (!claim.acquired) return { handled: true, choice, reason: 'concurrent_tap' };
+
+  let acknowledged = false;
+  try {
+    if (!await offerClaims().get(code)) {
+      acknowledged = await sendAck(code, choice, { queued: true, pledge: null, repeated: false, stale: true });
+      return { handled: true, choice, queued: false, stale: true };
+    }
+    await offerClaims().set(code, true);
+
+    const chosen = await tapClaims().get(code);
+    const repeated = Boolean(chosen);
+
+    let outcome = { queued: true, pledge: null, repeated };
+    if (!repeated) {
+      try {
+        outcome = { ...await applyChoice(code, choice), repeated: false };
+        await tapClaims().set(code, choice);
+      } catch (error) {
+        logger.error('[PausedSafetyNet] Could not record the tap', { code, choice, error: error.message });
+        outcome = { queued: false, pledge: null, repeated: false };
+      }
+    }
+
+    acknowledged = await sendAck(code, choice, outcome);
+    return { handled: true, choice, ...outcome };
+  } finally {
+    if (acknowledged) await completeSendClaim(claim.claimId);
+    else await releaseSendClaim(claim.claimId);
+  }
+}
+
+function registerSafetyNetRoutes() {
+  if (!getSafetyNetContentSid()) return false;
+  if (!getSafetyNetPhone()) {
+    logger.error('[PausedSafetyNet] A template is configured without a phone number; the safety net stays disarmed');
+    return false;
+  }
+
+  registerInteractiveRoute(PAYLOAD_PREFIX, handleSafetyNetTap);
+  for (const choice of CHOICES) {
+    const label = getSafetyNetLabel(choice);
+    if (label) registerInteractiveRoute(label, handleSafetyNetTap);
+  }
+  return true;
+}
+
+module.exports = {
+  offerSafetyNet,
+  handleSafetyNetTap,
+  matchSafetyNetChoice,
+  registerSafetyNetRoutes,
+  _resetSafetyNetState,
+  PAYLOAD_PREFIX,
+  CHOICES
+};

package/lib/clinical/services/safetyNetPledgeService.js

@@ -0,0 +1,120 @@
+const { CONTACT_WINDOW, getPledgeMs, getSweepIntervalMs, humanReplyFilter } = require('../config/safetyNetConfig');
+const { logger } = require('../../utils/logger');
+const { clampToHourWindow } = require('../../utils/scheduleUtils');
+
+const { SafetyNetPledge } = require('../../models/safetyNetPledgeModel');
+
+const { getMessages } = require('../../services/messageService');
+
+const { recordUnresolvedRequest } = require('./clinicalAirtableService');
+
+const SWEEP_LIMIT = 200;
+const BREACH_CATEGORY = 'contact_team_member';
+const BREACH_QUESTION = 'El paciente sigue esperando el contacto que se le prometió';
+
+async function humanRepliedSince(code, since) {
+  const [reply] = await getMessages(humanReplyFilter(code, since), { sort: { createdAt: -1 }, limit: 1 });
+  return Boolean(reply);
+}
+
+function pledgeDueAt(pledgedAt) {
+  const target = new Date(pledgedAt.getTime() + getPledgeMs());
+  const opened = clampToHourWindow(target, CONTACT_WINDOW);
+  if (!opened) return { dueAt: target, deferredToWindow: false };
+  return { dueAt: opened, deferredToWindow: opened.getTime() > target.getTime() };
+}
+
+async function openPledge({ code }) {
+  const pledgedAt = new Date();
+  const { dueAt, deferredToWindow } = pledgeDueAt(pledgedAt);
+  const pledge = await SafetyNetPledge.create({ code, pledgedAt, dueAt, deferredToWindow });
+  logger.info('[SafetyNetPledge] Contact pledged', { code, dueAt, deferredToWindow });
+  return { pledgeId: pledge._id, dueAt, deferredToWindow };
+}
+
+async function reportBreach(pledge) {
+  const waitedMinutes = Math.round((Date.now() - new Date(pledge.pledgedAt).getTime()) / 60000);
+  return recordUnresolvedRequest({
+    code: pledge.code,
+    trace: null,
+    question: BREACH_QUESTION,
+    details: `El paciente ${pledge.code} pidió que lo contactaran y lleva ${waitedMinutes} minutos sin respuesta. Revisar la conversación ahora.`,
+    category: BREACH_CATEGORY,
+    urgency: 'urgent'
+  });
+}
+
+const REPORT_LEASE_MS = 5 * 60 * 1000;
+
+const settle = async (id, from, state) => Boolean(
+  await SafetyNetPledge.findOneAndUpdate({ _id: id, state: from }, { $set: { state, resolvedAt: new Date() } }).lean()
+);
+
+const takeReportingLease = async (id) => Boolean(
+  await SafetyNetPledge.findOneAndUpdate(
+    { _id: id, $or: [{ state: 'pending' }, { state: 'reporting', reportingSince: { $lt: new Date(Date.now() - REPORT_LEASE_MS) } }] },
+    { $set: { state: 'reporting', reportingSince: new Date() } },
+  ).lean()
+);
+
+async function sweepSafetyNetPledges() {
+  const due = await SafetyNetPledge.find({
+    state: { $in: ['pending', 'reporting'] },
+    dueAt: { $lte: new Date() },
+  })
+    .select({ _id: 1, code: 1, pledgedAt: 1 })
+    .limit(SWEEP_LIMIT)
+    .lean();
+
+  let breached = 0;
+
+  for (const pledge of due) {
+    try {
+      if (!await takeReportingLease(pledge._id)) continue;
+
+      if (await humanRepliedSince(pledge.code, pledge.pledgedAt)) {
+        await settle(pledge._id, 'reporting', 'met');
+        continue;
+      }
+
+      if (!await reportBreach(pledge)) {
+        await SafetyNetPledge.updateOne({ _id: pledge._id, state: 'reporting' }, { $set: { state: 'pending', reportingSince: null } });
+        logger.error('[SafetyNetPledge] Breach was not recorded, pledge returns to pending for the next sweep', { code: pledge.code });
+        continue;
+      }
+      if (await settle(pledge._id, 'reporting', 'breached')) breached += 1;
+    } catch (error) {
+      logger.error('[SafetyNetPledge] Could not resolve a pledge', { code: pledge.code, error: error.message });
+    }
+  }
+
+  return breached;
+}
+
+let sweepTimer = null;
+
+function startSafetyNetSweep({ intervalMs = getSweepIntervalMs() } = {}) {
+  if (sweepTimer) return sweepTimer;
+  sweepTimer = setInterval(() => {
+    sweepSafetyNetPledges().catch((error) =>
+      logger.error('[SafetyNetPledge] Sweep failed', { error: error.message }));
+  }, intervalMs);
+  if (typeof sweepTimer.unref === 'function') sweepTimer.unref();
+  return sweepTimer;
+}
+
+function stopSafetyNetSweep() {
+  if (!sweepTimer) return;
+  clearInterval(sweepTimer);
+  sweepTimer = null;
+}
+
+module.exports = {
+  startSafetyNetSweep,
+  stopSafetyNetSweep,
+  humanRepliedSince,
+  openPledge,
+  pledgeDueAt,
+  sweepSafetyNetPledges,
+  BREACH_QUESTION
+};

package/lib/config/lifecycle.js

@@ -3,7 +3,11 @@ const { _resetMetaConfig } = require('../config/metaConfig');
 const { _clearClinicalContextCache } = require('../helpers/patientInformationHelper');
 const { setPreprocessingHandler } = require('../services/preprocessingService');
 const { clearTriageHistoryCache } = require('../services/triageHistoryService');
+const { clearInteractiveRoutes } = require('../core/interactiveRouteService');
 const { _resetDefaultInstance } = require('../core/NexusMessaging');
+const { _resetSafetyNetConfig } = require('../clinical/config/safetyNetConfig');
+const { _resetSafetyNetState } = require('../clinical/services/pausedSafetyNetService');
+const { stopSafetyNetSweep } = require('../clinical/services/safetyNetPledgeService');
 const { _clearRecentIntakeCache } = require('../clinical/services/clinicalAirtableService');
 const { _clearExtractorConfigCache } = require('../clinical/services/clinicalExtractionService');
 const { _resetRegistry } = require('../clinical/services/assistantResolver');
@@ -14,6 +18,10 @@ function resetAll() {
   _resetRegistry();
   _resetLLMState();
   setPreprocessingHandler(null);
+  clearInteractiveRoutes();
+  _resetSafetyNetConfig();
+  _resetSafetyNetState();
+  stopSafetyNetSweep();
   _resetOverrides();
   _resetMetaConfig();
   _clearClinicalContextCache();

package/lib/controllers/escalationReviewController.js

@@ -4,7 +4,6 @@ const { redactDirectIdentifiers } = require('../utils/sanitizerUtils');
 const {
   addCallLog,
   addDraft,
-  cancelEscalationReview,
   closeEscalationReview,
   getEscalationReviewById,
   handOffToDoctor,
@@ -136,16 +135,6 @@ const closeEscalationReviewController = async (req, res) => {
   }
 };
 
-const cancelEscalationReviewController = async (req, res) => {
-  try {
-    const { triggeredBy, reason = null } = req.body || {};
-    const review = await cancelEscalationReview({ id: req.params.id, cancelledBy: triggeredBy, reason, requestId: req.requestId });
-    res.status(200).json({ success: true, review });
-  } catch (error) {
-    respondWithError(res, error, 'cancelling escalation review', { reviewId: req.params?.id });
-  }
-};
-
 const syncEscalationReviewCaseController = async (req, res) => {
   try {
     const { triggeredBy } = req.body || {};
@@ -163,7 +152,6 @@ const syncEscalationReviewCaseController = async (req, res) => {
 module.exports = {
   addEscalationReviewCallLogController,
   addEscalationReviewDraftController,
-  cancelEscalationReviewController,
   closeEscalationReviewController,
   getEscalationReviewController,
   handOffEscalationReviewController,

package/lib/core/NexusMessaging.js

@@ -45,6 +45,7 @@ const { isLlmMonitorEnabled } = require('../clinical/flags/llmMonitorConfig');
 const { createQueueAdapter } = require('../queue');
 const { ScheduledMessageJob } = require('../jobs/ScheduledMessageJob');
 const { TemplateApprovalJob } = require('../jobs/TemplateApprovalJob');
+const { invokeInteractiveRoute } = require('./interactiveRouteService');
 
 const { PhiProcessor } = require('./PhiProcessor');
 
@@ -580,6 +581,7 @@ class NexusMessaging {
   }
 
   async handleInteractive(messageData) {
+    await invokeInteractiveRoute(messageData);
     if (this.handlers.onInteractive) return await this.handlers.onInteractive(messageData, this);
   }
 

package/lib/core/interactiveRouteService.js

@@ -0,0 +1,59 @@
+const { logger } = require('../utils/logger');
+
+const routes = new Map();
+
+const normalizePayload = (value) => String(value ?? '').trim().toLowerCase();
+
+function registerInteractiveRoute(prefix, handler) {
+  const key = normalizePayload(prefix);
+  if (!key) throw new Error('registerInteractiveRoute requires a payload prefix');
+  if (typeof handler !== 'function') throw new Error('registerInteractiveRoute requires a handler function');
+  routes.set(key, handler);
+}
+
+function clearInteractiveRoutes() {
+  routes.clear();
+}
+
+function hasInteractiveRoutes() {
+  return routes.size > 0;
+}
+
+function resolveInteractiveRoute(payload) {
+  const candidate = normalizePayload(payload);
+  if (!candidate) return null;
+  for (const [prefix, handler] of routes) {
+    if (candidate.startsWith(prefix)) return handler;
+  }
+  return null;
+}
+
+async function invokeInteractiveRoute(messageData) {
+  if (!routes.size) return false;
+
+  const interactive = messageData?.interactive || {};
+  const handler = resolveInteractiveRoute(interactive.payload);
+  if (!handler) return false;
+
+  try {
+    await handler({
+      code: messageData.code,
+      payload: interactive.payload ?? null,
+      title: interactive.title ?? null,
+      messageData
+    });
+    return true;
+  } catch (error) {
+    logger.error('[InteractiveRoutes] Route handler failed', { error: error?.message || error });
+    return false;
+  }
+}
+
+module.exports = {
+  normalizePayload,
+  registerInteractiveRoute,
+  clearInteractiveRoutes,
+  hasInteractiveRoutes,
+  resolveInteractiveRoute,
+  invokeInteractiveRoute
+};

package/lib/helpers/patientTaskRulesHelper.js

@@ -14,6 +14,7 @@ const ATTENTION_OPERATIONS_STATUS = 'pendiente';
 const ATTENTION_CASE_WINDOW_DAYS = 14;
 const ATTENTION_CASE_WINDOW_MS = ATTENTION_CASE_WINDOW_DAYS * 24 * 60 * 60 * 1000;
 const URGENT_REQUEST_URGENCY = 'urgent';
+const REQUEST_URGENCIES = ['routine', 'soon', 'urgent'];
 const URGENT_CASE_TYPES = ['Urgencia', 'Emergencia'];
 
 const isRequestOpen = (status) => !CLOSED_REQUEST_STATUSES.includes(status);
@@ -40,6 +41,7 @@ module.exports = {
   ATTENTION_CASE_WINDOW_DAYS,
   ATTENTION_OPERATIONS_STATUS,
   ATTENTION_REQUEST_STATUS,
+  REQUEST_URGENCIES,
   isCaseOpen,
   isCaseUrgent,
   isRequestOpen,

package/lib/index.d.ts

@@ -22,8 +22,14 @@ declare module '@peopl-health/nexus' {
     type?: 'message' | 'interactive' | 'media' | 'command' | 'keyword' | 'flow' | 'empty';
   }
 
+  export function registerInteractiveRoute(
+    prefix: string,
+    handler: (tap: { code: string; payload: string | null; title: string | null; messageData: unknown }) => unknown
+  ): void;
+  export function clearInteractiveRoutes(): void;
+
   export interface InteractiveData {
-    type: 'button' | 'list' | 'flow';
+    type: 'button' | 'list' | 'flow' | 'quick_reply';
     payload?: string;
     title?: string;
     description?: string;

package/lib/index.js

@@ -26,6 +26,10 @@ const { setModelDatabases, setModelDatabase, getModelDatabase, connect: mongoCon
 const { TwilioProvider } = require('./adapters/TwilioProvider');
 const { BaileysProvider } = require('./adapters/BaileysProvider');
 const { setPreprocessingHandler, hasPreprocessingHandler, invokePreprocessingHandler } = require('./services/preprocessingService');
+const { registerInteractiveRoute, clearInteractiveRoutes } = require('./core/interactiveRouteService');
+const { configureSafetyNet } = require('./clinical/config/safetyNetConfig');
+const { registerSafetyNetRoutes } = require('./clinical/services/pausedSafetyNetService');
+const { startSafetyNetSweep, stopSafetyNetSweep } = require('./clinical/services/safetyNetPledgeService');
 const { requestIdMiddleware, getRequestId } = require('./middleware/requestId');
 const { QueueAdapter, LocalQueueAdapter, RedisQueueAdapter, createQueueAdapter, registerQueueAdapter } = require('./queue');
 const { createWorkflowRunner } = require('./core/workflowRunner');
@@ -184,6 +188,16 @@ class Nexus {
       logger.warn('Warning: failed to register clinical tools:', e?.message || e);
     }
 
+    try {
+      configureSafetyNet(options.safetyNet || {});
+      if (registerSafetyNetRoutes()) {
+        startSafetyNetSweep();
+        logger.info('[Nexus] paused-thread safety net armed');
+      }
+    } catch (e) {
+      logger.warn('Warning: failed to arm the paused-thread safety net:', e?.message || e);
+    }
+
     await this.messaging.initializeLlmMonitor();
 
     this.isInitialized = true;
@@ -238,6 +252,7 @@ class Nexus {
   }
 
   async shutdown({ drainMs, abortGraceMs, teardownMs, closeStorage = true } = {}) {
+    stopSafetyNetSweep();
     if (this._shutdownPromise) return this._shutdownPromise;
     this._shutdownPromise = (async () => {
       const result = await this.messaging.shutdown({ drainMs, abortGraceMs, teardownMs });
@@ -280,6 +295,8 @@ module.exports = {
   setPreprocessingHandler,
   hasPreprocessingHandler,
   invokePreprocessingHandler,
+  registerInteractiveRoute,
+  clearInteractiveRoutes,
   routes,
   syncClinicalContext,
   runProactiveOutreachSweep,

package/lib/models/escalationReviewModel.js

@@ -7,7 +7,6 @@ const { logger } = require('../utils/logger');
 const CALL_OUTCOMES = ['contacted', 'no_answer', 'voicemail'];
 const HANDOFF_MODES = ['sent_whatsapp', 'copied'];
 const INTERRUPTED_STATUSES = ['handing_off', 'sending'];
-const CANCELLABLE_STATUSES = ['open', 'documenting', 'draft_ready'];
 const DOCTOR_DECISIONS = ['approved', 'edited_approved', 'needs_intervention', 'returned'];
 const DECISION_SOURCES = ['platform', 'registered_by_navigator'];
 
@@ -84,7 +83,6 @@ const escalationReviewSchema = new mongoose.Schema({
       'indications_queued',
       'indications_sent',
       'closed',
-      'cancelled',
     ],
     default: 'open',
   },
@@ -102,7 +100,6 @@ const escalationReviewSchema = new mongoose.Schema({
 
 escalationReviewSchema.index({ patientCode: 1, createdAt: -1 });
 escalationReviewSchema.index({ activeCaseKey: 1 }, { unique: true, sparse: true });
-escalationReviewSchema.index({ patientCode: 1 }, { unique: true, partialFilterExpression: { closedAt: null } });
 
 const getEscalationReview = () => {
   const dbName = getModelDatabase('EscalationReview');
@@ -113,7 +110,6 @@ const getEscalationReview = () => {
 
 module.exports = {
   CALL_OUTCOMES,
-  CANCELLABLE_STATUSES,
   DECISION_SOURCES,
   DOCTOR_DECISIONS,
   HANDOFF_MODES,

package/lib/models/safetyNetPledgeModel.js

@@ -0,0 +1,20 @@
+const mongoose = require('mongoose');
+
+const PLEDGE_STATES = ['pending', 'reporting', 'met', 'breached'];
+
+const safetyNetPledgeSchema = new mongoose.Schema({
+  code: { type: String, required: true },
+  pledgedAt: { type: Date, required: true },
+  dueAt: { type: Date, required: true },
+  deferredToWindow: { type: Boolean, default: false },
+  state: { type: String, enum: PLEDGE_STATES, default: 'pending' },
+  reportingSince: { type: Date, default: null },
+  resolvedAt: { type: Date, default: null },
+  createdAt: { type: Date, default: Date.now }
+});
+
+safetyNetPledgeSchema.index({ state: 1, dueAt: 1 }, { name: 'safety_net_pledge_due_idx' });
+
+const SafetyNetPledge = mongoose.model('SafetyNetPledge', safetyNetPledgeSchema);
+
+module.exports = { SafetyNetPledge, PLEDGE_STATES };

package/lib/routes/index.js

@@ -126,7 +126,6 @@ const escalationReviewRouteDefinitions = {
   'POST /:id/decisions': 'recordEscalationReviewDecisionController',
   'POST /:id/patient-deliveries': 'sendEscalationReviewIndicationsController',
   'POST /:id/close': 'closeEscalationReviewController',
-  'POST /:id/cancel': 'cancelEscalationReviewController',
   'POST /:id/case-sync': 'syncEscalationReviewCaseController'
 };
 
@@ -286,7 +285,6 @@ const builtInControllers = {
   recordEscalationReviewDecisionController: escalationReviewController.recordEscalationReviewDecisionController,
   sendEscalationReviewIndicationsController: escalationReviewController.sendEscalationReviewIndicationsController,
   closeEscalationReviewController: escalationReviewController.closeEscalationReviewController,
-  cancelEscalationReviewController: escalationReviewController.cancelEscalationReviewController,
   syncEscalationReviewCaseController: escalationReviewController.syncEscalationReviewCaseController
 };
 

package/lib/services/escalationReviewService.js

@@ -6,7 +6,6 @@ const { logger } = require('../utils/logger');
 const { PATIENT_CODE, redactDirectIdentifiers } = require('../utils/sanitizerUtils');
 const {
   CALL_OUTCOMES,
-  CANCELLABLE_STATUSES,
   DECISION_SOURCES,
   DOCTOR_DECISIONS,
   HANDOFF_MODES,
@@ -249,24 +248,6 @@ const deliveryTransport = (message, result) => {
   return result.deferred ? 'template_recovery' : 'text';
 };
 
-let indexesReady = new WeakMap();
-
-function ensureActiveReviewIndex(EscalationReview) {
-  const pending = indexesReady.get(EscalationReview);
-  if (pending) return pending;
-
-  const building = EscalationReview.ensureIndexes().catch((error) => {
-    indexesReady.delete(EscalationReview);
-    if (error?.code !== DUPLICATE_KEY_ERROR) throw error;
-    logger.error('[EscalationReview] A uniqueness index could not be built', { error: redactedError(error) });
-    throw httpError(409, 'Escalation reviews cannot be opened: a uniqueness index could not be built. The server log names the index and the conflict; resolve it and retry.');
-  });
-  indexesReady.set(EscalationReview, building);
-  return building;
-}
-
-const _resetEscalationReviewIndexes = () => { indexesReady = new WeakMap(); };
-
 async function openEscalationReview({ code, patientCaseRecordId = null, openedBy, requestId = null } = {}) {
   const patientCode = patientCodeOf(code);
   const operator = requiredText(openedBy, 'openedBy');
@@ -283,14 +264,14 @@ async function openEscalationReview({ code, patientCaseRecordId = null, openedBy
   }
 
   const EscalationReview = getEscalationReview();
-  await ensureActiveReviewIndex(EscalationReview);
+  await EscalationReview.init();
   let review;
   try {
     review = (await EscalationReview.create(fields)).toObject();
   } catch (error) {
-    if (error?.code !== DUPLICATE_KEY_ERROR) throw error;
-    const existing = await EscalationReview.findOne({ patientCode, closedAt: null }).lean();
-    if (!existing) throw httpError(409, 'A closed review still holds this patient case; try again in a moment');
+    if (error?.code !== DUPLICATE_KEY_ERROR || !fields.activeCaseKey) throw error;
+    const existing = await EscalationReview.findOne({ activeCaseKey: fields.activeCaseKey }).lean();
+    if (!existing) throw httpError(409, 'The patient case review changed while opening; try again');
     return { review: existing, created: false };
   }
   await audit(review, operator, requestId, { action: 'opened', patientCaseRecordId });
@@ -543,17 +524,6 @@ async function closeEscalationReview({ id, closedBy, deliveryConfirmed = false,
   return syncCase(review, operator, requestId);
 }
 
-async function cancelEscalationReview({ id, cancelledBy, reason = null, requestId = null } = {}) {
-  const reviewId = reviewIdOf(id);
-  const operator = requiredText(cancelledBy, 'cancelledBy');
-  const review = await updateReview(reviewId, CANCELLABLE_STATUSES, {
-    $set: { status: 'cancelled', closedBy: operator, closedAt: new Date() },
-    $unset: { activeCaseKey: '' },
-  });
-  await audit(review, operator, requestId, { action: 'cancelled', reason: optionalText(reason) });
-  return review;
-}
-
 async function syncEscalationReviewCase({ id, syncedBy, requestId = null } = {}) {
   const reviewId = reviewIdOf(id);
   const operator = requiredText(syncedBy, 'syncedBy');
@@ -561,10 +531,8 @@ async function syncEscalationReviewCase({ id, syncedBy, requestId = null } = {})
 }
 
 module.exports = {
-  _resetEscalationReviewIndexes,
   addCallLog,
   addDraft,
-  cancelEscalationReview,
   closeEscalationReview,
   getEscalationReviewById,
   handOffToDoctor,

package/lib/services/patientTaskService.js

@@ -4,6 +4,7 @@ const { httpError } = require('../utils/httpErrorUtils');
 
 const { escapeFormulaValue, fieldEquals, recordIdIn } = require('../helpers/airtableFormulaHelper');
 const {
+  REQUEST_URGENCIES,
   isCaseOpen,
   isCaseUrgent,
   isRequestOpen,
@@ -109,6 +110,7 @@ const TASK_KINDS = {
     toTask: toRequest,
     writable: {
       status: { field: 'status', options: REQUEST_STATUSES },
+      urgency: { field: 'urgency', options: REQUEST_URGENCIES },
       note: { field: 'Observaciones' },
     },
   },
@@ -170,7 +172,7 @@ async function getPatientTasks(code) {
       requests: requests.attentionCount,
       isUrgent: requests.isUrgent || cases.isUrgent,
     },
-    options: { requestStatus: REQUEST_STATUSES, caseStatus: CASE_STATUSES, operationsStatus: OPERATIONS_STATUSES },
+    options: { requestStatus: REQUEST_STATUSES, requestUrgency: REQUEST_URGENCIES, caseStatus: CASE_STATUSES, operationsStatus: OPERATIONS_STATUSES },
   };
 }
 

package/package.json

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