@peopl-health/nexus 5.67.0-dev.11889 → 5.67.0-dev.11930

package/lib/clinical/providers/AnthropicProvider.js

@@ -475,14 +475,17 @@ class AnthropicProvider extends BaseLLMProvider {
   // Split placement: the inline copy carries recency on single-round turns, the hoisted developer
   // turn persists once tool results are appended after it on multi-round turns.
   _buildInput({ additionalInstructions, ...rest }) {
-    const input = super._buildInput({ additionalInstructions, ...rest });
-    const pinned = { role: 'developer', content: `${RISK_HEADLINE_MARKER}\n${RISK_HEADLINE_DISCLAIMER}` };
-    const ordered = [...input.filter(i => !i[TAIL_PLACEMENT]), pinned, ...input.filter(i => i[TAIL_PLACEMENT])];
+    const ordered = this._orderRuntimeMessages(super._buildInput({ additionalInstructions, ...rest }));
     if (!additionalInstructions) return ordered;
     const { content } = this._operatorInstructionTurn(additionalInstructions);
     return [...ordered, { role: 'user', content: `${OPERATOR_TURN_PREFIX} ${content}`, type: 'message' }];
   }
 
+  _orderRuntimeMessages(input) {
+    const pinned = { role: 'developer', content: `${RISK_HEADLINE_MARKER}\n${RISK_HEADLINE_DISCLAIMER}` };
+    return [...input.filter(i => !i[TAIL_PLACEMENT]), pinned, ...input.filter(i => i[TAIL_PLACEMENT])];
+  }
+
   _mapModelConfig(modelConfig) {
     const mapped = { ...(modelConfig || {}) };
     if (mapped.max_tokens == null && mapped.max_output_tokens != null) mapped.max_tokens = mapped.max_output_tokens;

package/lib/clinical/providers/BaseLLMProvider.js

@@ -783,6 +783,11 @@ class BaseLLMProvider {
     };
   }
 
+  // Providers that pin runtime messages around the tail-placed block override this.
+  _orderRuntimeMessages(input) {
+    return input;
+  }
+
   _sanitizeInput(input) {
     const isMessage = (item) => !item.type || item.type === 'message';
     const items = (input || []).filter(item => isMessage(item) ? this._hasTextContent(item.content) : true);

package/lib/clinical/providers/GatewayProvider.js

@@ -38,6 +38,11 @@ class GatewayProvider extends BaseLLMProvider {
     return this._sub(vendor)._buildInput(config);
   }
 
+  _orderRuntimeMessages(input, modelConfig = null) {
+    const { vendor } = this._route(modelConfig?.model);
+    return this._sub(vendor)._orderRuntimeMessages(input);
+  }
+
   _route(model) {
     if (!model) return { vendor: 'openai', model: undefined };
     const slash = model.indexOf('/');

package/lib/clinical/services/nutritionPlanService.js

@@ -1,6 +1,7 @@
 const { safeParse, isPlainObject } = require('../../utils/jsonUtils');
 const { logger } = require('../../utils/logger');
 const { sanitizeInlineText } = require('../../utils/sanitizerUtils');
+const { withTimeout } = require('../../utils/timeoutUtils');
 const { composePrompt } = require('./promptComposerService');
 
 const NUTRITION_GUIDE_PROMPT_ID = 'nutrition_plan_guide';
@@ -33,32 +34,41 @@ function readPlanSection(section) {
 
 let lastGuide = '';
 let guideRead = null;
+let readSeq = 0;
+let appliedSeq = 0;
 
-// One shared read; a failure keeps the last guide that was read successfully.
 function readGuide() {
   if (guideRead) return guideRead;
-  guideRead = composePrompt({ promptId: NUTRITION_GUIDE_PROMPT_ID })
+  const seq = ++readSeq;
+  const read = composePrompt({ promptId: NUTRITION_GUIDE_PROMPT_ID })
     .then(({ resolvedPrompt }) => {
-      lastGuide = keepLines(resolvedPrompt || '', GUIDE_MAX_CHARS);
+      // A read that hung past a newer one must not overwrite what the newer one found.
+      if (seq > appliedSeq) {
+        appliedSeq = seq;
+        lastGuide = keepLines(resolvedPrompt || '', GUIDE_MAX_CHARS);
+      }
       return lastGuide;
     })
     .catch((error) => {
       logger.warn('[nutritionPlanService] nutrition guide unreadable; using the last one read', { error: error.message });
       return lastGuide;
     })
-    .finally(() => { guideRead = null; });
-  return guideRead;
+    .finally(() => { if (guideRead === read) guideRead = null; });
+  guideRead = read;
+  return read;
 }
 
-// The guide only adds to the plan, so a slow read must not hold the patient's turn.
+// The guide only adds to the plan, so a slow read must not hold the patient's turn,
+// and a read that never settles must not hold every later turn either.
 async function loadNutritionGuide() {
-  let timer;
-  const timedOut = new Promise((resolve) => { timer = setTimeout(() => resolve(null), GUIDE_TIMEOUT_MS); });
-  const guide = await Promise.race([readGuide(), timedOut]);
-  clearTimeout(timer);
-  if (guide !== null) return guide;
-  logger.warn('[nutritionPlanService] nutrition guide read timed out; using the last one read', { timeoutMs: GUIDE_TIMEOUT_MS });
-  return lastGuide;
+  const read = readGuide();
+  try {
+    return await withTimeout(read, GUIDE_TIMEOUT_MS, 'nutrition guide read');
+  } catch {
+    if (guideRead === read) guideRead = null;
+    logger.warn('[nutritionPlanService] nutrition guide read timed out; using the last one read', { timeoutMs: GUIDE_TIMEOUT_MS });
+    return lastGuide;
+  }
 }
 
 async function resolveNutritionPlan(section, { now = new Date() } = {}) {
@@ -78,5 +88,5 @@ module.exports = {
   NUTRITION_GUIDE_PROMPT_ID,
   GUIDE_TIMEOUT_MS,
   resolveNutritionPlan,
-  _test: { reset: () => { lastGuide = ''; guideRead = null; } },
+  _test: { reset: () => { lastGuide = ''; guideRead = null; readSeq = 0; appliedSeq = 0; } },
 };

package/lib/clinical/services/promptComposerService.js

@@ -14,6 +14,8 @@ const promptCache = new MapCache({ maxSize: 50, ttl: CACHE_TTL });
 const snippetCache = new MapCache({ maxSize: 200, ttl: CACHE_TTL });
 const toolCache = new MapCache({ maxSize: 50, ttl: CACHE_TTL });
 const presetCache = new MapCache({ maxSize: 50, ttl: CACHE_TTL });
+let promptReadClock = 0;
+let promptCacheEpoch = 0;
 
 async function fetchConfigRecords(table, filter) {
   const records = await getRecordByFilter(Config_ID, table, filter);
@@ -47,11 +49,17 @@ async function fetchPreset(presetId, version = null) {
 async function fetchBasePrompt(promptId) {
   const cacheKey = `prompt:${promptId}`;
   const cached = promptCache.get(cacheKey);
-  if (cached) return cached;
+  if (cached) return cached.record;
 
+  // A result may fill the cache unless a read started later already did, or the cache was cleared meanwhile.
+  const startedAt = ++promptReadClock;
+  const epoch = promptCacheEpoch;
   const records = await getRecordByFilter(Config_ID, 'responses', `{prompt_id} = "${promptId}"`);
   const record = records?.[0] || null;
-  if (record) promptCache.set(cacheKey, record);
+  const current = promptCache.get(cacheKey);
+  if (record && epoch === promptCacheEpoch && !(current && current.startedAt > startedAt)) {
+    promptCache.set(cacheKey, { record, startedAt });
+  }
   return record;
 }
 
@@ -257,9 +265,10 @@ async function resolveTools({ promptId, assistant, presetToolIds = null, status
 
 function clearCache() {
   promptCache.clear();
+  promptCacheEpoch += 1;
   snippetCache.clear();
   toolCache.clear();
   presetCache.clear();
 }
 
-module.exports = { composePrompt, resolveTools, clearCache, _test: { applyVariables, sortSnippets, resetUnlinkedWarnings: () => warnedUnlinked.clear() } };
+module.exports = { composePrompt, resolveTools, clearCache, variablesReferencedIn, _test: { applyVariables, sortSnippets, resetUnlinkedWarnings: () => warnedUnlinked.clear() } };

package/lib/controllers/escalationReviewController.js

@@ -11,6 +11,7 @@ const {
   handOffToDoctor,
   listEscalationReviews,
   openEscalationReview,
+  reclassifyUrgency,
   recordDoctorDecision,
   requestBotDraft,
   sendApprovedIndications,
@@ -49,8 +50,8 @@ const openEscalationReviewController = async (req, res) => {
 
 const getEscalationReviewController = async (req, res) => {
   try {
-    const { review, isApprover } = await getEscalationReviewById({ id: req.params.id, requestedBy: req.query.requestedBy });
-    res.status(200).json({ success: true, review, isApprover });
+    const { review, isApprover, responseDeadline } = await getEscalationReviewById({ id: req.params.id, requestedBy: req.query.requestedBy });
+    res.status(200).json({ success: true, review, isApprover, responseDeadline });
   } catch (error) {
     respondWithError(res, error, 'reading escalation review', { reviewId: req.params?.id });
   }
@@ -223,6 +224,22 @@ const closeEscalationReviewController = async (req, res) => {
   }
 };
 
+const reclassifyEscalationReviewUrgencyController = async (req, res) => {
+  try {
+    const { urgencyLevel, reason, triggeredBy } = req.body || {};
+    const { review, responseDeadline } = await reclassifyUrgency({
+      id: req.params.id,
+      urgencyLevel,
+      reason,
+      reclassifiedBy: triggeredBy,
+      requestId: req.requestId,
+    });
+    res.status(200).json({ success: true, review, responseDeadline });
+  } catch (error) {
+    respondWithError(res, error, 'reclassifying escalation review urgency', { reviewId: req.params?.id });
+  }
+};
+
 const cancelEscalationReviewController = async (req, res) => {
   try {
     const { triggeredBy, reason = null } = req.body || {};
@@ -265,6 +282,7 @@ module.exports = {
   listEscalationReviewsController,
   listReviewBoardController,
   openEscalationReviewController,
+  reclassifyEscalationReviewUrgencyController,
   recordEscalationReviewDecisionController,
   sendEscalationReviewIndicationsController,
   setEscalationReviewCasesController,

package/lib/eval/EvalProvider.js

@@ -7,6 +7,7 @@ const { PhiProcessor } = require('../core/PhiProcessor');
 const { buildDateAnchor } = require('../clinical/helpers/dateAnchorHelper');
 const { DefaultMemoryManager, EnhancedMemoryManager, createLLMProvider, composePrompt, resolveTools, getAssistantById } = require('../clinical');
 const { resolveClinicalContext } = require('../clinical/services/clinicalContextReadService');
+const { variablesReferencedIn } = require('../clinical/services/promptComposerService');
 
 /**
  * Promptfoo-compatible eval provider that wraps the real Nexus pipeline.
@@ -159,7 +160,7 @@ class EvalProvider {
       resolvedPresetId = composedPresetId || resolvedPresetId;
     } else {
       devContent = fallbackPrompt;
-      interpolatedVariables = [...new Set([...(devContent || '').matchAll(/\{\{(\w+)\}\}/g)].map((m) => m[1]))];
+      interpolatedVariables = variablesReferencedIn(devContent);
       devContent = devContent.replace(/\{\{(\w+)\}\}/g, (_, key) => promptVariables[key] ?? '');
     }
 
@@ -224,17 +225,21 @@ class EvalProvider {
     const clinicalMessage = typeof this.provider._buildClinicalMessage === 'function'
       ? this.provider._buildClinicalMessage(promptVariables, interpolatedVariables)
       : [];
-    const input = this.provider._sanitizeInput([...memoryMessage, ...clinicalMessage, ...convertedMessages]);
     const isContextOnly = this.mode === 'context-only';
 
     const shouldUsePromptRegistry = !presetId && this.provider.supportsPromptRegistry && !!assistantId;
+    const modelConfig = shouldUsePromptRegistry ? {} : this._modelConfig(presetModelConfig);
+    const input = this.provider._orderRuntimeMessages(
+      this.provider._sanitizeInput([...memoryMessage, ...clinicalMessage, ...convertedMessages]),
+      modelConfig,
+    );
 
     return {
       instructions: devContent || '',
       input,
       toolSchemas: isContextOnly ? [] : toolSchemas,
       toolChoice: isContextOnly ? 'none' : this.toolChoice,
-      modelConfig: shouldUsePromptRegistry ? {} : this._modelConfig(presetModelConfig),
+      modelConfig,
       assistant: isContextOnly ? null : assistant,
       phiProcessor: this.phiProcessor,
       promptVariables,

package/lib/models/escalationReviewModel.js

@@ -145,6 +145,14 @@ const interruptionResolutionSchema = new mongoose.Schema({
   notes: { type: String, required: true },
 }, { timestamps: { createdAt: true, updatedAt: false } });
 
+const urgencyReclassificationSchema = new mongoose.Schema({
+  fromLevel: { type: String, enum: URGENCY_LEVELS, required: true },
+  toLevel: { type: String, enum: URGENCY_LEVELS, required: true },
+  reason: { type: String, required: true },
+  reclassifiedBy: { type: String, required: true },
+  at: { type: Date, required: true },
+}, { _id: false });
+
 const identityBlockSchema = new mongoose.Schema({
   missing: { type: [String], default: [] },
   blockedAt: { type: Date, required: true },
@@ -179,6 +187,7 @@ const escalationReviewSchema = new mongoose.Schema({
   openedBy: { type: String, required: true },
   assistantPausedByReview: { type: Boolean, default: false },
   alarms: { type: [alarmSchema], default: [] },
+  urgencyReclassifications: { type: [urgencyReclassificationSchema], default: [] },
   updates: { type: [reviewUpdateSchema], default: [] },
   updatedSinceSeen: { type: Boolean, default: false },
   followUpCases: { type: [String], default: undefined },
@@ -228,6 +237,7 @@ module.exports = {
   INTERRUPTED_STATUSES,
   FOLLOWUP_STATUSES,
   RETURN_REASONS,
+  URGENCY_LEVELS,
   URGENCY_RANK,
   getEscalationReview,
   escalationReviewSchema,

package/lib/routes/index.js

@@ -136,6 +136,7 @@ const escalationReviewRouteDefinitions = {
   'POST /:id/patient-deliveries': 'sendEscalationReviewIndicationsController',
   'POST /:id/close': 'closeEscalationReviewController',
   'POST /:id/cancel': 'cancelEscalationReviewController',
+  'POST /:id/urgency-reclassifications': 'reclassifyEscalationReviewUrgencyController',
   'POST /:id/case-sync': 'syncEscalationReviewCaseController'
 };
 
@@ -312,6 +313,7 @@ const builtInControllers = {
   sendEscalationReviewIndicationsController: escalationReviewController.sendEscalationReviewIndicationsController,
   closeEscalationReviewController: escalationReviewController.closeEscalationReviewController,
   cancelEscalationReviewController: escalationReviewController.cancelEscalationReviewController,
+  reclassifyEscalationReviewUrgencyController: escalationReviewController.reclassifyEscalationReviewUrgencyController,
   syncEscalationReviewCaseController: escalationReviewController.syncEscalationReviewCaseController,
 
   // Office assistant controllers

package/lib/services/escalationReviewService.js

@@ -16,6 +16,7 @@ const {
   INTERRUPTED_STATUSES,
   FOLLOWUP_STATUSES,
   RETURN_REASONS,
+  URGENCY_LEVELS,
   URGENCY_RANK,
   getEscalationReview,
 } = require('../models/escalationReviewModel');
@@ -36,6 +37,7 @@ const { getPatientInformation, logPatientChange } = require('./patientService');
 const { MAX_NOTE_LENGTH, getPatientTasks, openCaseIds, updatePatientTask } = require('./patientTaskService');
 const { getEscalationApprover, listEscalationApprovers } = require('./physicianService');
 const { switchThreadStoppedStatus } = require('./threadService');
+const { effectiveUrgencyOf, responseDeadlineOf, responseDeadlinePolicy } = require('./reviewDeadlineService');
 
 const AUDIT_SOURCE = 'escalation_review';
 const RECENT_REVIEW_LIMIT = 20;
@@ -63,6 +65,9 @@ const ALERT_MARKS = { stat: '🔴', asap: '🟠' };
 const DEFAULT_STAT_REALERT_MINUTES = 15;
 const PRE_DECISION_STATUSES = ['open', 'documenting', 'draft_ready', 'handing_off', 'awaiting_doctor'];
 const ALERT_OPERATOR = 'bot:escalationAlert';
+const RECLASSIFIABLE_STATUSES = [...DOCUMENTING_STATUSES, 'awaiting_doctor'];
+const SAME_URGENCY = 'The review is already at that urgency';
+const RECLASSIFY_CHANGED = 'The review changed while you were reclassifying it; read it again before changing the urgency';
 const DIRECT_CHAT_STATUSES = ['open', 'documenting', 'draft_ready', 'returned', 'awaiting_doctor', 'approved', 'needs_intervention'];
 const APPROVALS = ['approved', 'edited_approved'];
 const STALE_DRAFT = 'New information reached the review after this draft; wait for the updated draft before approving';
@@ -687,7 +692,7 @@ async function getEscalationReviewById({ id, requestedBy } = {}) {
       .updateOne({ _id: review._id }, { $max: { approverViewedAt: readAt } }, { timestamps: false })
       .catch(warnUnmarked);
   }
-  return { review, isApprover };
+  return { review, isApprover, responseDeadline: responseDeadlineOf(review, responseDeadlinePolicy()) };
 }
 
 async function getReviewTimeline({ id } = {}) {
@@ -1745,6 +1750,32 @@ async function closeEscalationReview({
   return syncCase(await resumeAssistant(review, operator, requestId), operator, requestId);
 }
 
+async function reclassifyUrgency({ id, urgencyLevel, reason, reclassifiedBy, requestId = null } = {}) {
+  const reviewId = reviewIdOf(id);
+  const operator = requiredText(reclassifiedBy, 'reclassifiedBy');
+  if (!URGENCY_LEVELS.includes(urgencyLevel)) throw httpError(400, `urgencyLevel must be one of: ${URGENCY_LEVELS.join(', ')}`);
+  const why = requiredText(reason, 'reason');
+
+  const current = await loadReview(reviewId);
+  const fromLevel = effectiveUrgencyOf(current)?.urgency;
+  if (!fromLevel) throw httpError(409, STATUS_CONFLICT);
+  if (fromLevel === urgencyLevel) throw httpError(409, SAME_URGENCY);
+
+  const entry = { fromLevel, toLevel: urgencyLevel, reason: why, reclassifiedBy: operator, at: new Date() };
+  let review;
+  try {
+    review = await updateReview(reviewId, RECLASSIFIABLE_STATUSES, { $push: { urgencyReclassifications: entry } }, {
+      alarms: { $size: (current.alarms ?? []).length },
+      urgencyReclassifications: { $size: (current.urgencyReclassifications ?? []).length },
+    });
+  } catch (error) {
+    if (error?.statusCode === 409 && RECLASSIFIABLE_STATUSES.includes(current.status)) throw httpError(409, RECLASSIFY_CHANGED);
+    throw error;
+  }
+  await audit(review, operator, requestId, { action: 'urgency_reclassified', fromLevel, toLevel: urgencyLevel, reason: why });
+  return { review, responseDeadline: responseDeadlineOf(review, responseDeadlinePolicy()) };
+}
+
 async function cancelEscalationReview({ id, cancelledBy, reason = null, requestId = null } = {}) {
   const reviewId = reviewIdOf(id);
   const operator = requiredText(cancelledBy, 'cancelledBy');
@@ -1794,6 +1825,7 @@ module.exports = {
   handOffToDoctor,
   listEscalationReviews,
   openEscalationReview,
+  reclassifyUrgency,
   recordEscalationAlarm,
   recordDirectIndication,
   recordDoctorDecision,

package/lib/services/reviewBoardService.js

@@ -1,6 +1,8 @@
 const { httpError } = require('../utils/httpErrorUtils');
 const { FOLLOWUP_STATUSES, URGENCY_RANK, getEscalationReview } = require('../models/escalationReviewModel');
 
+const { effectiveUrgencyOf, responseDeadlineOf, responseDeadlinePolicy } = require('./reviewDeadlineService');
+
 const DONE_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
 const DONE_STATUSES = ['closed', 'cancelled'];
 const BOARD_BUCKETS = ['pending', 'followup', 'done'];
@@ -19,15 +21,9 @@ const bucketQuery = (bucket, now) => {
   }
 };
 
-const rankOf = (alarm) => URGENCY_RANK[alarm?.urgencyLevel] || 0;
-
-const leadingAlarm = (alarms) => alarms.reduce((lead, alarm) => (
-  !lead || rankOf(alarm) > rankOf(lead) || (rankOf(alarm) === rankOf(lead) && alarm.raisedAt > lead.raisedAt) ? alarm : lead
-), null);
-
-const boardRowOf = (review, bucket) => {
+const boardRowOf = (review, bucket, deadlinePolicy) => {
   const alarms = review.alarms || [];
-  const lead = leadingAlarm(alarms);
+  const lead = effectiveUrgencyOf(review);
   const raised = alarms.map((alarm) => alarm.raisedAt).filter(Boolean);
   const since = raised.length ? new Date(Math.min(...raised.map(Number))) : review.createdAt;
   return {
@@ -35,12 +31,13 @@ const boardRowOf = (review, bucket) => {
     patientCode: review.patientCode,
     bucket,
     status: review.status,
-    urgency: lead?.urgencyLevel || null,
+    urgency: lead?.urgency || null,
     symptom: lead?.symptom || null,
     alarmCount: alarms.length,
     since,
     closedAt: review.closedAt || null,
     updatedSinceSeen: review.updatedSinceSeen === true,
+    responseDeadline: responseDeadlineOf(review, deadlinePolicy),
   };
 };
 
@@ -53,9 +50,11 @@ async function listReviewBoard({ bucket, now = new Date() } = {}) {
   const reviews = await getEscalationReview()
     .find(bucketQuery(bucket, now), {
       patientCode: 1, status: 1, 'alarms.urgencyLevel': 1, 'alarms.symptom': 1, 'alarms.raisedAt': 1, createdAt: 1, closedAt: 1, updatedSinceSeen: 1,
+      'decisions.createdAt': 1, urgencyReclassifications: 1,
     })
     .lean();
-  const rows = reviews.map((review) => boardRowOf(review, bucket))
+  const deadlinePolicy = responseDeadlinePolicy();
+  const rows = reviews.map((review) => boardRowOf(review, bucket, deadlinePolicy))
     .sort(bucket === 'done' ? byMostRecentlyClosed : byUrgencyThenAge);
   const seen = new Set();
   return rows.filter((row) => !seen.has(row.patientCode) && seen.add(row.patientCode));

package/lib/services/reviewDeadlineService.js

@@ -0,0 +1,82 @@
+const runtimeConfig = require('../config/runtimeConfig');
+const { addWorkingMinutes } = require('../utils/dateUtils');
+const { FOLLOWUP_STATUSES, URGENCY_RANK } = require('../models/escalationReviewModel');
+
+const RESPONSE_MINUTES = { stat: 15, asap: 60, urgent: 240, routine: 720 };
+const MAX_RESPONSE_MINUTES = 7 * 24 * 60;
+const BUSINESS_HOURS_LEVELS = ['urgent', 'routine'];
+const TEAM_TIMEZONE = 'America/Mexico_City';
+const DEFAULT_TEAM_HOURS = { days: [1, 2, 3, 4, 5], startHour: 8, endHour: 20 };
+
+const rankOf = (level) => URGENCY_RANK[level] || 0;
+const timeOf = (value) => (value ? new Date(value).getTime() : NaN);
+
+const configuredMinutes = (level) => {
+  const minutes = Number(runtimeConfig.get(`ESCALATION_REVIEW_RESPONSE_MINUTES_${level.toUpperCase()}`, RESPONSE_MINUTES[level]));
+  return Number.isFinite(minutes) && minutes > 0 && minutes <= MAX_RESPONSE_MINUTES ? minutes : RESPONSE_MINUTES[level];
+};
+
+function configuredTeamHours() {
+  const entries = String(runtimeConfig.get('ESCALATION_REVIEW_TEAM_DAYS', '')).split(',').map((day) => day.trim()).filter(Boolean);
+  const days = entries.map(Number);
+  const isValidDays = days.length > 0 && days.every((day) => Number.isInteger(day) && day >= 1 && day <= 7);
+  const startHour = Number(runtimeConfig.get('ESCALATION_REVIEW_TEAM_START_HOUR', DEFAULT_TEAM_HOURS.startHour));
+  const endHour = Number(runtimeConfig.get('ESCALATION_REVIEW_TEAM_END_HOUR', DEFAULT_TEAM_HOURS.endHour));
+  const isValidSpan = Number.isInteger(startHour) && Number.isInteger(endHour) && startHour >= 0 && startHour < endHour && endHour <= 24;
+  return {
+    timeZone: TEAM_TIMEZONE,
+    days: isValidDays ? [...new Set(days)] : DEFAULT_TEAM_HOURS.days,
+    startHour: isValidSpan ? startHour : DEFAULT_TEAM_HOURS.startHour,
+    endHour: isValidSpan ? endHour : DEFAULT_TEAM_HOURS.endHour,
+  };
+}
+
+function responseDeadlinePolicy() {
+  return {
+    responseMinutes: Object.fromEntries(Object.keys(RESPONSE_MINUTES).map((level) => [level, configuredMinutes(level)])),
+    teamHours: configuredTeamHours(),
+  };
+}
+
+function alarmLevelsOf(review) {
+  const reclassifications = [...(review.urgencyReclassifications ?? [])].sort((a, b) => timeOf(a.at) - timeOf(b.at));
+  return (review.alarms ?? []).map((alarm) => reclassifications
+    .filter((change) => timeOf(alarm.raisedAt) <= timeOf(change.at))
+    .reduce((entry, change) => ({
+      alarm,
+      level: change.toLevel,
+      clockFrom: rankOf(change.toLevel) > rankOf(entry.level) ? change.at : entry.clockFrom,
+    }), { alarm, level: alarm.urgencyLevel, clockFrom: alarm.raisedAt }));
+}
+
+function effectiveUrgencyOf(review) {
+  const lead = alarmLevelsOf(review).reduce((top, entry) => (
+    !top || rankOf(entry.level) > rankOf(top.level)
+      || (rankOf(entry.level) === rankOf(top.level) && timeOf(entry.alarm.raisedAt) > timeOf(top.alarm.raisedAt)) ? entry : top
+  ), null);
+  return lead ? { urgency: lead.level, symptom: lead.alarm.symptom ?? null } : null;
+}
+
+function dueAtFor(from, level, policy) {
+  const minutes = policy.responseMinutes[level];
+  if (BUSINESS_HOURS_LEVELS.includes(level)) return addWorkingMinutes(new Date(from), minutes, policy.teamHours);
+  return new Date(timeOf(from) + minutes * 60 * 1000);
+}
+
+function responseDeadlineOf(review, policy) {
+  if (review.closedAt || FOLLOWUP_STATUSES.includes(review.status)) return null;
+  const decidedAt = timeOf((review.decisions ?? []).at(-1)?.createdAt);
+  const waiting = alarmLevelsOf(review)
+    .filter(({ alarm }) => Number.isNaN(decidedAt) || timeOf(alarm.raisedAt) > decidedAt)
+    .map(({ level, clockFrom }) => ({ urgency: level, dueAt: dueAtFor(clockFrom, level, policy) }))
+    .filter(({ dueAt }) => dueAt);
+  if (!waiting.length) return null;
+  const earliest = waiting.reduce((first, entry) => (entry.dueAt < first.dueAt ? entry : first));
+  return { ...earliest, isBusinessHoursOnly: BUSINESS_HOURS_LEVELS.includes(earliest.urgency) };
+}
+
+module.exports = {
+  effectiveUrgencyOf,
+  responseDeadlineOf,
+  responseDeadlinePolicy,
+};

package/lib/utils/dateUtils.js

@@ -58,7 +58,29 @@ const daysSince = (from, now = Date.now()) => {
   return Number.isNaN(at) ? null : Math.max(0, Math.floor((now - at) / 86400000));
 };
 
+const MAX_WORKING_DAY_STEPS = 400;
+
+const addWorkingMinutes = (start, minutes, { timeZone, days, startHour, endHour }) => {
+  let at = moment.tz(start, timeZone);
+  let remaining = minutes;
+  for (let step = 0; step < MAX_WORKING_DAY_STEPS; step += 1) {
+    const opens = at.clone().startOf('day').hour(startHour);
+    const closes = at.clone().startOf('day').hour(endHour);
+    if (!days.includes(at.isoWeekday()) || !at.isBefore(closes)) {
+      at = at.clone().add(1, 'day').startOf('day').hour(startHour);
+      continue;
+    }
+    if (at.isBefore(opens)) at = opens;
+    const available = closes.diff(at, 'minutes', true);
+    if (remaining <= available) return at.add(remaining, 'minutes').toDate();
+    remaining -= available;
+    at = closes;
+  }
+  return null;
+};
+
 module.exports = {
+  addWorkingMinutes,
   getCurrentMexicoDateTime,
   getMexicoDayLabels,
   parseDate,

package/package.json

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