@peopl-health/nexus 6.3.0-dev.18429 → 6.3.0

package/README.md

@@ -169,6 +169,11 @@ The route helpers intentionally leave authentication to the host application. Mo
 tenant authentication and authorization middleware before exposing them; patient routes return
 protected health information and must never be public.
 
+`POST /api/message/send`, `/send-bulk` and `/send-bulk-airtable` accept an optional `expiresAt`
+(ISO 8601 with an offset or `Z`) for messages that only matter until a moment, such as a session
+reminder. Once it has passed the send is refused with `status: 'expired'`, a scheduled one is
+cancelled, and a failed one is never recovered, retried, replayed or nudged.
+
 ## Support-session routing
 
 `supportCandidateService` is exported for consumers that coordinate first-session

package/lib/clinical/services/clinicalAirtableService.js

@@ -1,6 +1,7 @@
 const { createHash } = require('crypto');
 const { isShadowRun } = require('../helpers/shadowHelper');
 const { decodeUnicodeEscapes } = require('../../utils/sanitizerUtils');
+const { isAtOrBefore } = require('../../utils/dateUtils');
 
 const { Monitoreo_ID, Estado_General_ID, Symptoms_ID } = require('../../config/airtableConfig');
 const runtimeConfig = require('../../config/runtimeConfig');
@@ -483,11 +484,6 @@ async function readPendingFollowUpsForPatient({ code, now = new Date() }) {
   })).filter((plan) => !isAtOrBefore(plan.expiresAt, now) && !isAtOrBefore(plan.fireAt, new Date(now).getTime() - FIRE_TRIGGER_GRACE_MS));
 }
 
-function isAtOrBefore(when, now) {
-  const at = when ? new Date(when).getTime() : NaN;
-  return Number.isFinite(at) && at <= new Date(now).getTime();
-}
-
 async function hasCheckInNear({ code, withinMinutes, excludeReminderId, fireAt = null }) {
   const window = Number(withinMinutes);
   if (!code || !Number.isFinite(window) || window <= 0) return false;

package/lib/clinical/tools/deliverPatientMessageTool.js

@@ -9,7 +9,7 @@ const EMPTY_OUTBOUND_FALLBACK = 'Recibí tu mensaje. Si quieres contarme más o
 const definition = {
   name: 'DeliverPatientMessage',
   replayArgs: ['message_text', 'purpose'],
-  description: '**Does:** Delivers the final, patient-facing message in Spanish — the only tool that produces text the patient sees. Call exactly ONCE as the last action of every CHAT turn.\n\n**Required inputs:** `message_text` (the message itself, in Spanish); `purpose` (the conversational purpose); `reasoning` (one short sentence, never shown to the patient, explaining why this is the right message for this turn).\n\n**When to call:** at the end of every chat turn — once. Every substantive inbound must first complete an intake/classification decision. When that decision extracts clinical mentions, code enforces: processed risk through `getRouterContextBundle` (or its dedicated recovery) → `submitRoutingDecision` → this tool. A committed non-clinical terminal workflow may deliver without clinical risk/routing. A rejected call returns the missing step in `data.recovery`; perform it and regenerate the message.\n\n**When NOT to call:**\n- More than once per turn — only ONE patient-facing message per turn.\n- Before the required classification or clinical chain is complete. A rejected call does not set outbound text.\n\n**When the patient asks what the care team answered:** say where the case stands from `turn_focus.team_cases` (load `getRouterContextBundle` first if you have not this turn). Never add a time, and never say the team already reviewed or saw something unless the status is one where the team answered (`Esperando paciente`, `Indicaciones dadas`, `En vigilancia`).\n\n**Returns:** a RECORD, not a send — `{purpose, recorded, delivered:false, still_active, means}`. The reply is stored as the outbound of this turn and leaves only when the turn finishes as the active run; a newer patient message drops it and `still_active` is `false`. Never treat the patient as informed because this call succeeded.\n\n**Side effects:** records the final patient-facing message on the turn trace; delivery to the patient is handled downstream.',
+  description: '**Does:** Delivers the final, patient-facing message in Spanish — the only tool that produces text the patient sees. Call exactly ONCE as the last action of every CHAT turn.\n\n**Required inputs:** `message_text` (the message itself, in Spanish); `purpose` (the conversational purpose); `reasoning` (one short sentence, never shown to the patient, explaining why this is the right message for this turn).\n\n**When to call:** at the end of every chat turn — once. Every substantive inbound must first complete an intake/classification decision. When that decision extracts clinical mentions, code enforces: processed risk through `getRouterContextBundle` (or its dedicated recovery) → `submitRoutingDecision` → this tool. A committed non-clinical terminal workflow may deliver without clinical risk/routing. A rejected call returns the missing step in `data.recovery`; perform it and regenerate the message.\n\n**When NOT to call:**\n- More than once per turn — only ONE patient-facing message per turn.\n- Before the required classification or clinical chain is complete. A rejected call does not set outbound text.\n\n**When the patient asks what the care team answered:** say where the case stands from `turn_focus.team_cases` (load `getRouterContextBundle` first if you have not this turn). Never add a time, and never say the team already reviewed or saw something unless the status is one where the team answered (`Esperando paciente`, `Indicaciones dadas`, `En vigilancia`).\n\n**When you relay what a doctor indicated:** name the doctor the team instruction names, even when it is not the `Médico tratante` of the clinical context. Saying the treating doctor reviewed the case when another doctor did tells the patient something false.\n\n**Returns:** a RECORD, not a send — `{purpose, recorded, delivered:false, still_active, means}`. The reply is stored as the outbound of this turn and leaves only when the turn finishes as the active run; a newer patient message drops it and `still_active` is `false`. Never treat the patient as informed because this call succeeded.\n\n**Side effects:** records the final patient-facing message on the turn trace; delivery to the patient is handled downstream.',
   strict: false,
   parameters: {
     type: 'object',

package/lib/controllers/messageController.js

@@ -1,5 +1,6 @@
 const moment = require('moment-timezone');
 const mongoose = require('mongoose');
+const { z } = require('zod');
 
 const { logger } = require('../utils/logger');
 const { withTimeout } = require('../utils/timeoutUtils');
@@ -14,7 +15,7 @@ const { CAREGIVER_ROLE, resolveCaregiver } = require('../helpers/caregiverHelper
 
 const { getRecordByFilter } = require('../services/airtableService');
 const { getMessages } = require('../services/messageService');
-const { recordDirectIndication } = require('../services/escalationReviewService');
+const { recordDirectIndication, recordPatientSend } = require('../services/escalationReviewService');
 const { resolveThreadCode } = require('../services/threadService');
 
 const INDICATION_WAIT_MS = 5000;
@@ -41,6 +42,14 @@ const _validateMessagingDeps = (res, requireAirtable = false) => {
   return true;
 };
 
+const expiresAtSchema = z.iso.datetime({ offset: true }).nullable();
+
+const _validateExpiresAt = (res, expiresAt) => {
+  if (expiresAtSchema.safeParse(expiresAt).success) return true;
+  res.status(400).json({ success: false, error: 'expiresAt must be an ISO 8601 datetime with an offset or Z' });
+  return false;
+};
+
 const _pickMessageId = (result, fallback) => 
   result?.sid || result?.messageId || result?.id || result?._id ||
   fallback?.wa_id || fallback?.sid || fallback?.id || fallback?._id?.toString() || null;
@@ -75,7 +84,8 @@ const sendMessageController = async (req, res) => {
     triggeredBy = null,
     idempotencyKey = null,
     contactCode = null,
-    asIndication = false
+    asIndication = false,
+    expiresAt = null
   } = req.body || {};
 
   if (!ensureWhatsAppFormat(code)) {
@@ -86,6 +96,8 @@ const sendMessageController = async (req, res) => {
     return res.status(400).json({ success: false, error: 'message, fileUrl or contentSid is required' });
   }
 
+  if (!_validateExpiresAt(res, expiresAt)) return;
+
   try {
     const formattedCode = await resolveThreadCode(ensureWhatsAppFormat(code));
     let contact = {};
@@ -107,8 +119,11 @@ const sendMessageController = async (req, res) => {
       const result = await sendMessage({
         fileUrl, body: message, fileType, contentSid, hidePreview,
         variables: finalVariables, code: formattedCode,
-        frontendId, triggeredBy, idempotencyKey, ...contact
+        frontendId, triggeredBy, idempotencyKey, expiresAt, ...contact
       });
+      if (result?.success && message && !contentSid && !contact.contactCode) {
+        recordPatientSend({ code: formattedCode, channel: 'staff_message', sentBy: triggeredBy, text: message, messageId: _pickMessageId(result, null), deferred: result?.deferred === true || result?.preemptive === true });
+      }
       if (asIndication === true && result?.success && triggeredBy && message && !contentSid && !contact.contactCode) {
         await withTimeout(recordDirectIndication({
           code: formattedCode,
@@ -138,7 +153,8 @@ const sendMessageController = async (req, res) => {
       timeZone: timeZone || null,
       sendTime: moment.tz(sendTime, timeZone) + 2500,
       code: formattedCode,
-      triggeredBy
+      triggeredBy,
+      expiresAt
     };
 
     const { result, saved } = await _sendAndPersist(payload);
@@ -163,9 +179,12 @@ const sendBulkMessageController = async (req, res) => {
     hidePreview = false,
     contentSid = null,
     variables = null,
-    triggeredBy = null
+    triggeredBy = null,
+    expiresAt = null
   } = req.body || {};
 
+  if (!_validateExpiresAt(res, expiresAt)) return;
+
   try {
     const isFlowTemplate = contentSid && await FlowRouting.findOne({ contentSid }).lean();
 
@@ -179,7 +198,8 @@ const sendBulkMessageController = async (req, res) => {
           variables: isFlowTemplate ? await ensureFlowTokenInVariables(contentSid, variables) : variables,
           timeZone: timeZone || null,
           code: ensureWhatsAppFormat(recipient),
-          triggeredBy
+          triggeredBy,
+          expiresAt
         }
       });
       extraDelay += Math.floor(Math.random() * 5001) + 5000;
@@ -208,8 +228,12 @@ const sendBulkMessageAirtableController = async (req, res) => {
     contentSid = null,
     condition = '1',
     variables = null,
-    triggeredBy = null
+    triggeredBy = null,
+    expiresAt = null
   } = req.body || {};
+
+  if (!_validateExpiresAt(res, expiresAt)) return;
+
   const sendMoment = sendTime ? moment.tz(sendTime, timeZone) + 20000 : new Date();
 
   try {
@@ -241,7 +265,8 @@ const sendBulkMessageAirtableController = async (req, res) => {
         timeZone: timeZone || null,
         sendTime: new Date(sendMoment + extraDelay),
         code,
-        triggeredBy
+        triggeredBy,
+        expiresAt
       });
       extraDelay += Math.floor(Math.random() * 5001) + 5000;
     }

package/lib/core/NexusMessaging.js

@@ -12,6 +12,7 @@ const { logger } = require('../utils/logger');
 
 const { createEvent, safeEmit } = require('../utils/eventUtils');
 const { withTimeout } = require('../utils/timeoutUtils');
+const { isAtOrBefore } = require('../utils/dateUtils');
 const { Message } = require('../models/messageModel');
 const { Thread } = require('../models/threadModel');
 
@@ -113,6 +114,7 @@ function createDefaultLlmMonitor(options, loader = loadDefaultLlmMonitor) {
  * Core messaging orchestrator for providers, storage, and assistant processing.
  */
 const NOT_SENT_DECEASED = { success: false, messageId: null, status: 'patient_deceased', delivered: false, deferred: false };
+const NOT_SENT_EXPIRED = { success: false, messageId: null, status: 'expired', delivered: false, deferred: false };
 
 class NexusMessaging {
   constructor(config = {}) {
@@ -389,6 +391,7 @@ class NexusMessaging {
    */
 
   async sendMessage(messageData) {
+    if (isAtOrBefore(messageData.expiresAt, Date.now())) return NOT_SENT_EXPIRED;
     messageData = { ...messageData, code: await resolveThreadCode(messageData.code) };
     // Only an operator writing now still reaches a deceased patient's phone; automations and scheduled sends do not.
     const operatorNow = isStaffSend(messageData.triggeredBy) && !String(messageData.idempotencyKey || '').startsWith('scheduled:');
@@ -476,7 +479,8 @@ class NexusMessaging {
     if (messageData.parentMessageId) {
       const [found] = await getMessages({ _id: messageData.parentMessageId }, { limit: 1 });
       if (!found) return { success: false, delivered: false, deferred: true };
-      await triggerTemplateRecovery(found, { source: 'preemptive' });
+      const queued = await triggerTemplateRecovery(found, { source: 'preemptive' });
+      if (queued?.expired) return { ...NOT_SENT_EXPIRED, messageId: String(found._id) };
       return { success: true, messageId: String(found._id), status: 'queued', preemptive: true, delivered: false, deferred: true };
     }
     const saveFn = this.messageStorage.savePendingMessage.bind(this.messageStorage);
@@ -492,7 +496,10 @@ class NexusMessaging {
         // triggerTemplateRecovery swallows its own errors and returns undefined. Reporting "queued"
         // regardless is how a template that was never created still counts as an outreach, and the
         // weekly guard then stops us ever trying again.
-        const queued = await triggerTemplateRecovery({ _id, body, numero: messageData.code, media: messageData.media }, { source: 'preemptive' });
+        const queued = await triggerTemplateRecovery({ _id, body, numero: messageData.code, media: messageData.media, expiresAt: messageData.expiresAt }, { source: 'preemptive' });
+        if (queued?.expired) {
+          return { ...NOT_SENT_EXPIRED, messageId: String(_id) };
+        }
         if (!queued?.deferred) {
           logger.error('[NexusMessaging] template recovery setup failed; message not queued', { code: messageData.code, messageId: String(_id) });
           return { success: false, messageId: String(_id), status: 'failed', preemptive: true, delivered: false, deferred: false };
@@ -1079,6 +1086,8 @@ class NexusMessaging {
     };
 
     let runResult = null;
+    let auditRowId = null;
+    let sendThrew = false;
     const executeTurn = () => this._executeWithPipeline(code, 'outreach', 'queue',
       async (preProcessResult, shouldContinue, runId) => this.assistantProcessor.process({
         code,
@@ -1099,7 +1108,7 @@ class NexusMessaging {
           runId,
         }
       }),
-      { sendResponse: !dryRun });
+      { sendResponse: !dryRun, onSendSettled: async (settled) => { sendThrew = settled === 'threw'; } });
 
     if (dryRun) {
       runResult = await runInShadowScope(executeTurn);
@@ -1108,6 +1117,7 @@ class NexusMessaging {
         messageData,
         this._saveMessageFn,
         async ({ _id }) => {
+          auditRowId = _id;
           runResult = await executeTurn();
           if (_id) {
             try {
@@ -1121,6 +1131,20 @@ class NexusMessaging {
       );
     }
 
+    const result = this._outreachResult(code, runResult, { dryRun, firstName });
+    if (auditRowId) {
+      // A send that threw may have reached the patient in part.
+      const outcome = { decision: result.decision, holdReason: result.holdReason, nextCheckAt: result.nextCheckAt, sent: sendThrew ? null : Boolean(result.accepted), traceId: result.traceId };
+      try {
+        await updateMessage({ _id: auditRowId }, { $set: { 'raw.outcome': outcome } });
+      } catch (err) {
+        logger.error('[processOutreach] Could not record the outreach outcome', { error: err.message, code });
+      }
+    }
+    return result;
+  }
+
+  _outreachResult(code, runResult, { dryRun, firstName }) {
     // The pipeline returns null when the turn was superseded or a preProcess hook skipped it. That is
     // not the agent choosing to stay quiet, and counting it as a hold would flatter the hold rate.
     if (!runResult) {
@@ -1345,6 +1369,8 @@ class NexusMessaging {
       executeWithPipeline: this._executeWithPipeline.bind(this),
       assistantProcessor: this.assistantProcessor,
       getAbortSignal: this.batchingManager.getAbortSignal.bind(this.batchingManager),
+      // Required lazily: escalationReviewService reaches back into this module.
+      recordPatientSend: (send) => require('../services/escalationReviewService').recordPatientSend(send),
     });
   }
 

package/lib/helpers/channelRetryHelper.js

@@ -2,6 +2,7 @@ const runtimeConfig = require('../config/runtimeConfig');
 
 const { logger } = require('../utils/logger');
 const { createEvent, safeEmit } = require('../utils/eventUtils');
+const { isAtOrBefore } = require('../utils/dateUtils');
 
 const { Message } = require('../models/messageModel');
 const { ScheduledMessage } = require('../models/agendaMessageModel');
@@ -111,6 +112,11 @@ async function handleRetryableChannelError(messageDoc, twilioSid, errorCode) {
   const priorAttempts = await DeliveryAttempt.countDocuments({ messageId, kind: 'template' });
   const delay = retryDelays()[priorAttempts - 1];
 
+  if (isAtOrBefore(messageDoc.expiresAt, new Date(Date.now() + (delay ?? 0)))) {
+    logger.info('[ChannelRetry] Message expires before the retry, skipping', { ...logCtx, expiresAt: messageDoc.expiresAt });
+    return { retried: false, reason: 'expires_before_retry' };
+  }
+
   if (delay === undefined) {
     alertUndeliverable({ ...logCtx, contentSid: attempt.contentSid, attempts: priorAttempts, reason: 'max_attempts' });
     return { retried: false, reason: 'max_attempts' };
@@ -133,7 +139,8 @@ async function handleRetryableChannelError(messageDoc, twilioSid, errorCode) {
     variables,
     sendTime,
     parentMessageId: messageId,
-    triggeredBy: 'channel_retry'
+    triggeredBy: 'channel_retry',
+    expiresAt: messageDoc.expiresAt
   });
 
   try {

package/lib/helpers/templateRecoveryHelper.js

@@ -1,5 +1,6 @@
 const { generatePresignedUrl } = require('../config/awsConfig');
 const { logger } = require('../utils/logger');
+const { isAtOrBefore } = require('../utils/dateUtils');
 const { Message } = require('../models/messageModel');
 const { Template: TemplateModel } = require('../models/templateModel');
 const { Template } = require('../templates/templateStructure');
@@ -32,6 +33,24 @@ async function resolveRecoveryBody(messageDoc) {
   return decoded || messageDoc.body;
 }
 
+async function closeExpiredRecovery(messageDoc) {
+  const claim = await Message.updateOne(
+    { _id: messageDoc._id, 'statusInfo.recoveryReleasedAt': null, 'statusInfo.recoverySentAt': null },
+    {
+      $set: {
+        'statusInfo.recoveryReleasedAt': new Date(),
+        'statusInfo.status': 'failed',
+        'statusInfo.errorCode': 'expired',
+        'statusInfo.errorMessage': 'Expired before it could be delivered',
+        'statusInfo.updatedAt': new Date()
+      }
+    }
+  );
+  if (!claim.modifiedCount && !claim.nModified) return;
+  logger.info('[TemplateRecovery] Expired before delivery, recovery closed', { messageDocId: String(messageDoc._id), expiresAt: messageDoc.expiresAt });
+  await cleanupRecoveryTemplate(messageDoc);
+}
+
 async function triggerTemplateRecovery(messageDoc, { source = 'reactive', messageSid = null } = {}) {
   try {
     if (!messageDoc?.body || !messageDoc?.numero || !messageDoc?._id) return;
@@ -44,6 +63,11 @@ async function triggerTemplateRecovery(messageDoc, { source = 'reactive', messag
       return;
     }
 
+    if (isAtOrBefore(messageDoc.expiresAt, Date.now())) {
+      await closeExpiredRecovery(messageDoc);
+      return { delivered: false, deferred: false, expired: true };
+    }
+
     try {
       const claim = await Message.updateOne(
         { _id: messageDocId, 'statusInfo.recoveryStartedAt': null },
@@ -172,4 +196,4 @@ async function cleanupRecoveryTemplate(messageDoc) {
   }
 }
 
-module.exports = { handle24HourWindowError, triggerTemplateRecovery, cleanupRecoveryTemplate, resolveRecoveryBody, hasUnresolvedPhi };
+module.exports = { handle24HourWindowError, triggerTemplateRecovery, cleanupRecoveryTemplate, resolveRecoveryBody, hasUnresolvedPhi, closeExpiredRecovery };

package/lib/index.d.ts

@@ -18,6 +18,7 @@ declare module '@peopl-health/nexus' {
     fileType?: 'text' | 'image' | 'document' | 'audio' | 'video';
     contentSid?: string;
     variables?: Record<string, string>;
+    expiresAt?: string | Date;
     interactive?: InteractiveData;
     media?: MediaData;
     command?: CommandData;

package/lib/jobs/ScheduledMessageJob.js

@@ -109,6 +109,7 @@ class ScheduledMessageJob extends BaseJob {
         variables: msg.variables,
         hidePreview: msg.hidePreview,
         triggeredBy: msg.triggeredBy,
+        expiresAt: msg.expiresAt,
         processed: true,
         idempotencyKey: `scheduled:${scheduledMessageId}`,
         ...(parentMessageId ? { parentMessageId } : {
@@ -144,6 +145,15 @@ class ScheduledMessageJob extends BaseJob {
         return { success: false, reason: result.status };
       }
 
+      if (result?.status === 'expired') {
+        await ScheduledMessage.updateOne(
+          { _id: scheduledMessageId },
+          { $set: { status: 'cancelled', errorCode: result.status, errorMessage: 'Expired before it could be sent' } }
+        );
+        logger.info('[ScheduledMessageJob] Not sent, the message expired before it could be sent', { scheduledMessageId });
+        return { success: false, reason: result.status };
+      }
+
       if (result?.status === 'outbound_blocked') {
         await ScheduledMessage.updateOne(
           { _id: scheduledMessageId },

package/lib/jobs/TemplateApprovalJob.js

@@ -2,6 +2,7 @@ const runtimeConfig = require('../config/runtimeConfig');
 
 const { logger } = require('../utils/logger');
 const { withTimeout } = require('../utils/timeoutUtils');
+const { isAtOrBefore } = require('../utils/dateUtils');
 const { createEvent, safeEmit } = require('../utils/eventUtils');
 const { Message } = require('../models/messageModel');
 const { DeliveryAttempt } = require('../models/deliveryAttemptModel');
@@ -9,6 +10,7 @@ const { DeliveryAttempt } = require('../models/deliveryAttemptModel');
 const { alertUndeliverable } = require('../helpers/channelRetryHelper');
 
 const { contactOf } = require('../helpers/caregiverHelper');
+const { closeExpiredRecovery } = require('../helpers/templateRecoveryHelper');
 const { getMessages } = require('../services/messageService');
 const { recordUndeliverable } = require('../services/undeliverableService');
 
@@ -102,6 +104,7 @@ class TemplateApprovalJob extends BaseJob {
 
     let provider;
     let approvalStatus;
+    let checkError = null;
     try {
       provider = this.requireProvider();
       const status = await withTimeout(
@@ -111,8 +114,16 @@ class TemplateApprovalJob extends BaseJob {
       );
       approvalStatus = status?.approvalRequest?.status?.toUpperCase();
     } catch (err) {
+      checkError = err;
+    }
+
+    if (isAtOrBefore(message.expiresAt, Date.now())) {
+      await closeExpiredRecovery(message);
+      return { success: false, reason: 'expired' };
+    }
+    if (checkError) {
       logger.error('[TemplateApprovalJob] Provider error during approval check, treating as transient', {
-        templateSid, messageId, attempt, error: err.message
+        templateSid, messageId, attempt, error: checkError.message
       });
       return await this._rescheduleOrGiveUp({ templateSid, message, originalMessageSid, attempt, reason: 'error' });
     }

package/lib/models/agendaMessageModel.js

@@ -20,6 +20,7 @@ const scheduledMessageSchema = new mongoose.Schema({
   wa_id: { type: String, default: null },
   triggeredBy: { type: String, default: null },
   parentMessageId: { type: mongoose.Schema.Types.ObjectId, ref: 'Message', default: null },
+  expiresAt: { type: Date, default: null },
   createdAt: { type: Date, default: Date.now }
 });
 

package/lib/models/escalationReviewModel.js

@@ -217,6 +217,15 @@ const patientDeliverySchema = new mongoose.Schema({
   sentBy: { type: String, required: true },
 }, { timestamps: { createdAt: true, updatedAt: false } });
 
+const patientSendSchema = new mongoose.Schema({
+  channel: { type: String, enum: ['assistant_instruction', 'staff_message'], required: true },
+  text: { type: String, required: true },
+  messageId: { type: String, default: null },
+  deferred: { type: Boolean, default: false },
+  sentBy: { type: String, required: true },
+  sentAt: { type: Date, required: true },
+}, { _id: false });
+
 const pendingCaseMirrorSchema = new mongoose.Schema({
   recordId: { type: String, required: true },
   changes: { type: mongoose.Schema.Types.Mixed, required: true },
@@ -299,6 +308,7 @@ const escalationReviewSchema = new mongoose.Schema({
   doctorHandoffs: { type: [doctorHandoffSchema], default: [] },
   decisions: { type: [decisionSchema], default: [] },
   patientDelivery: { type: patientDeliverySchema, default: null },
+  patientSends: { type: [patientSendSchema], default: undefined },
   pendingCaseMirrors: { type: [pendingCaseMirrorSchema], default: [] },
   interruptionResolution: { type: interruptionResolutionSchema, default: null },
   identityBlock: { type: identityBlockSchema, default: null },

package/lib/models/messageModel.js

@@ -89,7 +89,8 @@ const messageSchema = new mongoose.Schema({
   turnId: { type: String },
   processedByTurnId: { type: String },
   traceId: { type: String },
-  triggeredBy: { type: String, default: null }
+  triggeredBy: { type: String, default: null },
+  expiresAt: { type: Date, default: null }
 }, { timestamps: true });
 
 messageSchema.index({ numero: 1, createdAt: -1 });

package/lib/services/assistantMessageService.js

@@ -75,7 +75,7 @@ async function processAssistantSystemMessage(code, messages, role = 'system', op
     throw new AssistantMessageError('CONVERSATION_UNAVAILABLE');
   }
   if (!thread) throw new AssistantMessageError('CONVERSATION_NOT_FOUND');
-  const { messageStorage, saveMessage, phiProcessor, executeWithPipeline, assistantProcessor, getAbortSignal } = dependencies;
+  const { messageStorage, saveMessage, phiProcessor, executeWithPipeline, assistantProcessor, getAbortSignal, recordPatientSend } = dependencies;
   if (typeof messageStorage?.saveMessage !== 'function') throw new AssistantMessageError('MESSAGE_PERSISTENCE_FAILED');
 
   let acceptedCount = 0;
@@ -115,6 +115,7 @@ async function processAssistantSystemMessage(code, messages, role = 'system', op
   }
 
   if (!reply) return;
+  recordPatientSend?.({ code, channel: 'assistant_instruction', sentBy: triggeredBy, text: input.messages.join('\n') });
 
   try {
     await executeWithPipeline(code, 'system', 'queue',

package/lib/services/escalationReviewService.js

@@ -72,6 +72,9 @@ const RECHECK_DELAY_MS = 60 * 1000;
 const ALERT_RETRY_DELAY_MS = 2 * 60 * 1000;
 const MAX_ALERT_ATTEMPTS = 3;
 const BOOKKEEPING = { timestamps: false };
+const SEND_CHANNELS = ['assistant_instruction', 'staff_message'];
+const MAX_SENDS = 100;
+const MAX_SEND_LENGTH = 4000;
 const PREVIOUS_REVIEW_WINDOW_MS = 30 * 24 * 60 * 60 * 1000;
 const DUPLICATE_KEY_ERROR = 11000;
 const HANDING_OFF_WAIT_MS = 3000;
@@ -1941,6 +1944,27 @@ async function recordDirectIndication({ code, triggeredBy, body, messageId = nul
   }
 }
 
+// A log, not a state change: it leaves updatedAt alone so it never trips another write's guard.
+async function recordPatientSend({ code, channel, sentBy, text, messageId = null, deferred = false } = {}) {
+  try {
+    const operator = String(sentBy ?? '').trim();
+    const body = String(text ?? '').trim();
+    if (!SEND_CHANNELS.includes(channel) || !operator.includes('@') || !body || !PATIENT_CODE.test(String(code ?? ''))) return false;
+    const send = { channel, text: body.slice(0, MAX_SEND_LENGTH), messageId, deferred: Boolean(deferred), sentBy: operator, sentAt: new Date() };
+    const { modifiedCount } = await getEscalationReview().updateOne(
+      { patientCode: patientCodeOf(code), closedAt: null },
+      { $push: { patientSends: { $each: [send], $slice: -MAX_SENDS } } },
+      BOOKKEEPING,
+    );
+    return modifiedCount > 0;
+  } catch (error) {
+    logger.error('[EscalationReview] A message to the patient could not be recorded on the open review', {
+      channel, error: redactedError(error), stack: redactedStack(error),
+    });
+    return false;
+  }
+}
+
 const latestUpdateGuard = (review) => {
   const updates = review.updates ?? [];
   if (!updates.length) return { 'updates.0': { $exists: false } };
@@ -2241,6 +2265,7 @@ module.exports = {
   reclassifyUrgency,
   recordEscalationAlarm,
   recordDirectIndication,
+  recordPatientSend,
   recordDoctorDecision,
   sendScheduledDoctorAlert,
   recordReviewUpdate,

package/lib/services/heldMessageService.js

@@ -1,11 +1,12 @@
 const { logger } = require('../utils/logger');
 const { isWithinHourWindow, contactHoursBetween } = require('../utils/scheduleUtils');
+const { isAtOrBefore } = require('../utils/dateUtils');
 
 const { Message } = require('../models/messageModel');
 
 const { isWithin24HourWindow } = require('../helpers/conversationWindowHelper');
 const { contactOf } = require('../helpers/caregiverHelper');
-const { cleanupRecoveryTemplate, resolveRecoveryBody, hasUnresolvedPhi } = require('../helpers/templateRecoveryHelper');
+const { cleanupRecoveryTemplate, resolveRecoveryBody, hasUnresolvedPhi, closeExpiredRecovery } = require('../helpers/templateRecoveryHelper');
 
 const { getMessages } = require('./messageService');
 
@@ -39,6 +40,11 @@ async function releaseClaim(messageId) {
 async function releaseOne(message, now) {
   const logCtx = { messageId: String(message._id), to: message.numero };
 
+  if (isAtOrBefore(message.expiresAt, now)) {
+    await closeExpiredRecovery(message);
+    return false;
+  }
+
   const aged = contactHoursBetween(message.createdAt, now, PATIENT_CONTACT_WINDOW);
   if (aged === null || aged > MAX_CONTACT_HOURS) {
     logger.info('[HeldMessage] Held message is past its freshness bound, leaving it for staff', {

package/lib/storage/MongoStorage.js

@@ -130,6 +130,7 @@ class MongoStorage {
       statusInfo: messageData.statusInfo,
       clinical_context: messageData.clinicalContext || null,
       triggeredBy: messageData.triggeredBy || null,
+      expiresAt: messageData.expiresAt,
       ...(messageData.contactCode && {
         contact_code: ensureWhatsAppFormat(messageData.contactCode),
         contact_role: messageData.contactRole || null,

package/lib/utils/dateUtils.js

@@ -104,6 +104,11 @@ const addWorkingMinutes = (start, minutes, { timeZone, days, startHour, endHour
   return null;
 };
 
+function isAtOrBefore(when, now) {
+  const at = when ? new Date(when).getTime() : NaN;
+  return Number.isFinite(at) && at <= new Date(now).getTime();
+}
+
 module.exports = {
   addDays,
   addWorkingMinutes,
@@ -121,5 +126,6 @@ module.exports = {
   mexicoIsoWeek,
   mexicoWeekStart,
   mexicoStamp,
-  daysSince
+  daysSince,
+  isAtOrBefore
 };

package/package.json

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