@peopl-health/nexus 5.52.0-dev.7696 → 5.52.0-dev.7711

package/lib/clinical/config/safetyNetConfig.js

@@ -0,0 +1,62 @@
+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 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)
+};

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,267 @@
+const {
+  CONTACT_WINDOW,
+  SAFETY_NET_SOURCE,
+  getHumanQuietMs,
+  getOfferWindowMs,
+  getPledgeMs,
+  getSafetyNetContentSid,
+  getSafetyNetLabel,
+  getSafetyNetPhone,
+  getTapWindowMs
+} = require('../config/safetyNetConfig');
+const { logger } = require('../../utils/logger');
+
+const { acquireSendClaim, completeSendClaim } = require('../../helpers/sendClaimHelper');
+
+const { 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 normalize = (value) => String(value ?? '').trim().toLowerCase();
+
+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) 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 true;
+
+  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: 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 withPhone('Gracias, lo anotamos. 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 });
+  } catch (error) {
+    logger.error('[PausedSafetyNet] Could not acknowledge the tap', { code, choice, error: error.message });
+  }
+}
+
+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' };
+
+  try {
+    if (!await offerClaims().get(code)) {
+      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 tapKey = `${code}:${choice}`;
+    const repeated = Boolean(await tapClaims().get(tapKey));
+
+    let outcome = { queued: true, pledge: null, repeated };
+    if (!repeated) {
+      try {
+        outcome = { ...await applyChoice(code, choice), repeated: false };
+        await tapClaims().set(tapKey, true);
+      } catch (error) {
+        logger.error('[PausedSafetyNet] Could not record the tap', { code, choice, error: error.message });
+        outcome = { queued: false, pledge: null, repeated: false };
+      }
+    }
+
+    await sendAck(code, choice, outcome);
+    return { handled: true, choice, ...outcome };
+  } finally {
+    await completeSendClaim(claim.claimId);
+  }
+}
+
+function registerSafetyNetRoutes() {
+  if (!getSafetyNetContentSid()) 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,100 @@
+const { CONTACT_WINDOW, getPledgeMs, 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;
+}
+
+module.exports = {
+  humanRepliedSince,
+  openPledge,
+  pledgeDueAt,
+  sweepSafetyNetPledges,
+  BREACH_QUESTION
+};

package/lib/config/lifecycle.js

@@ -3,7 +3,10 @@ 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 { _clearRecentIntakeCache } = require('../clinical/services/clinicalAirtableService');
 const { _clearExtractorConfigCache } = require('../clinical/services/clinicalExtractionService');
 const { _resetRegistry } = require('../clinical/services/assistantResolver');
@@ -14,6 +17,9 @@ function resetAll() {
   _resetRegistry();
   _resetLLMState();
   setPreprocessingHandler(null);
+  clearInteractiveRoutes();
+  _resetSafetyNetConfig();
+  _resetSafetyNetState();
   _resetOverrides();
   _resetMetaConfig();
   _clearClinicalContextCache();

package/lib/core/NexusMessaging.js

@@ -30,6 +30,7 @@ const { releaseHeldMessages, sweepHeldMessages } = require('../services/heldMess
 
 const { BatchingManager } = require('../core/BatchingManager');
 const { ProcessingPipeline } = require('../core/ProcessingPipeline');
+const { sweepSafetyNetPledges } = require('../clinical/services/safetyNetPledgeService');
 const { preProcessMessages, configureOpenAIProvider, AssistantProcessor, TURN_KIND } = require('../clinical');
 const { buildOutreachCarrier } = require('../clinical/services/outreachCarrierService');
 const { routineOutreachCollisionReason } = require('../clinical/services/outreachSweepService');
@@ -45,6 +46,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');
 
@@ -169,7 +171,8 @@ class NexusMessaging {
       ...(config.queueReconciliation || {}),
       scheduleMessage: (options) => this.scheduledMessageJob.schedule(options),
       scheduleTemplateApproval: (options) => this.scheduleTemplateApproval(options),
-      sweepHeldMessages: () => sweepHeldMessages()
+      sweepHeldMessages: () => sweepHeldMessages(),
+      sweepSafetyNetPledges
     });
 
     this._providerStores = false;
@@ -580,6 +583,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,58 @@
+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 = {
+  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,9 @@ 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 { requestIdMiddleware, getRequestId } = require('./middleware/requestId');
 const { QueueAdapter, LocalQueueAdapter, RedisQueueAdapter, createQueueAdapter, registerQueueAdapter } = require('./queue');
 const { createWorkflowRunner } = require('./core/workflowRunner');
@@ -184,6 +187,13 @@ class Nexus {
       logger.warn('Warning: failed to register clinical tools:', e?.message || e);
     }
 
+    try {
+      configureSafetyNet(options.safetyNet || {});
+      if (registerSafetyNetRoutes()) 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;
@@ -280,6 +290,8 @@ module.exports = {
   setPreprocessingHandler,
   hasPreprocessingHandler,
   invokePreprocessingHandler,
+  registerInteractiveRoute,
+  clearInteractiveRoutes,
   routes,
   syncClinicalContext,
   runProactiveOutreachSweep,

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/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/lib/services/queueReconciliationService.js

@@ -13,6 +13,7 @@ class QueueReconciliationService {
     scheduleMessage,
     scheduleTemplateApproval,
     sweepHeldMessages,
+    sweepSafetyNetPledges,
     intervalMs = DEFAULT_INTERVAL_MS,
     lookbackMs = DEFAULT_LOOKBACK_MS,
     staleAfterMs = DEFAULT_STALE_AFTER_MS,
@@ -21,6 +22,7 @@ class QueueReconciliationService {
     this.scheduleMessage = scheduleMessage;
     this.scheduleTemplateApproval = scheduleTemplateApproval;
     this.sweepHeldMessages = sweepHeldMessages;
+    this.sweepSafetyNetPledges = sweepSafetyNetPledges;
     this.intervalMs = intervalMs;
     this.lookbackMs = lookbackMs;
     this.staleAfterMs = staleAfterMs;
@@ -60,19 +62,20 @@ class QueueReconciliationService {
   }
 
   async runOnce() {
-    if (this.stopped) return { scheduledMessages: 0, recoveries: 0, heldMessages: 0 };
+    if (this.stopped) return { scheduledMessages: 0, recoveries: 0, heldMessages: 0, breachedPledges: 0 };
     const since = new Date(Date.now() - this.lookbackMs);
-    const [scheduledMessages, recoveries, heldMessages] = await Promise.all([
+    const [scheduledMessages, recoveries, heldMessages, breachedPledges] = await Promise.all([
       this._reEnqueueScheduledMessages(since),
       this._reArmTemplateApprovals(since),
-      this._releaseHeldMessages()
+      this._releaseHeldMessages(),
+      this._resolveSafetyNetPledges()
     ]);
 
-    if (scheduledMessages || recoveries || heldMessages) {
-      logger.warn('[QueueReconciliation] Re-armed dropped jobs', { scheduledMessages, recoveries, heldMessages });
+    if (scheduledMessages || recoveries || heldMessages || breachedPledges) {
+      logger.warn('[QueueReconciliation] Re-armed dropped jobs', { scheduledMessages, recoveries, heldMessages, breachedPledges });
     }
 
-    return { scheduledMessages, recoveries, heldMessages };
+    return { scheduledMessages, recoveries, heldMessages, breachedPledges };
   }
 
   async _releaseHeldMessages() {
@@ -85,6 +88,16 @@ class QueueReconciliationService {
     }
   }
 
+  async _resolveSafetyNetPledges() {
+    if (typeof this.sweepSafetyNetPledges !== 'function') return 0;
+    try {
+      return await this.sweepSafetyNetPledges();
+    } catch (error) {
+      logger.error('[QueueReconciliation] Safety-net pledge sweep failed', { error: error.message });
+      return 0;
+    }
+  }
+
   async _reEnqueueScheduledMessages(since) {
     if (typeof this.scheduleMessage !== 'function') return 0;
 

package/package.json

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