@peopl-health/nexus 5.67.0-dev.11849 → 5.67.0-dev.11929

package/lib/clinical/providers/BaseLLMProvider.js

@@ -125,13 +125,13 @@ class BaseLLMProvider {
       assistant.toolRuntimeContext.enabledSkills = enabledSkills;
     }
 
-    const resolvedSchemas = this._resolveToolSchemas({
+    const resolvedSchemas = this._scopeOutreachDecisionTool(this._resolveToolSchemas({
       assistant, toolIds: resolvedToolIds, filtered, toolDescriptions,
-    });
+    }), isOutreach);
     const { toolChoice: flooredToolChoice, toolSchemas, narrowed } = this._applyDeliveryFloor(
       toolChoice, resolvedSchemas, Boolean(assistant?.toolRuntimeContext), turnKind);
     const effectiveToolIds = toolSchemas.map(s => s.function?.name).filter(Boolean);
-    const instructionToolIds = narrowed ? effectiveToolIds : resolvedToolIds;
+    const instructionToolIds = narrowed || isOutreach ? effectiveToolIds : resolvedToolIds;
     const requestedToolChoice = prePromptResult?.toolChoice;
     const requestedToolName = requestedToolChoice?.name || requestedToolChoice?.function?.name || null;
     const supportedGenericChoices = new Set(['auto', 'none', 'required', 'any']);
@@ -234,6 +234,17 @@ class BaseLLMProvider {
     };
   }
 
+  // The decision tool belongs to the turn kind, not to a preset: without it an outreach turn cannot
+  // close and the brief is dropped, and on any other turn it would invite a decision nobody asked for.
+  _scopeOutreachDecisionTool(schemas, isOutreach) {
+    const others = schemas.filter(s => s.function?.name !== OUTREACH_DECISION_TOOL);
+    if (!isOutreach) return others;
+    const decision = schemas.find(s => s.function?.name === OUTREACH_DECISION_TOOL)
+      || getRegistrySchemas([OUTREACH_DECISION_TOOL])[0];
+    if (!decision) throw new Error('OUTREACH_DECISION_TOOL_UNAVAILABLE');
+    return [...others, decision];
+  }
+
   _resolveToolSchemas({ assistant, toolIds, filtered, toolDescriptions }) {
     const assistantSchemas = assistant?.getToolSchemas?.() || [];
     const registrySchemas = getRegistrySchemas();

package/lib/clinical/services/nutritionPlanService.js

@@ -7,6 +7,7 @@ const NUTRITION_GUIDE_PROMPT_ID = 'nutrition_plan_guide';
 const PLAN_MAX_CHARS = 1500;
 const GUIDE_MAX_CHARS = 2000;
 const ISO_DATE_RX = /^\d{4}-\d{2}-\d{2}$/;
+const GUIDE_TIMEOUT_MS = 3000;
 
 // Each line of a plan or guide is one kind of indication, so the breaks survive and only each line is flattened.
 function keepLines(text, maxChars) {
@@ -30,14 +31,44 @@ function readPlanSection(section) {
   return { text: typeof text === 'string' ? text : '', reviewBy };
 }
 
+let lastGuide = '';
+let guideRead = null;
+let readSeq = 0;
+let appliedSeq = 0;
+
+function readGuide() {
+  if (guideRead) return guideRead;
+  const seq = ++readSeq;
+  const read = composePrompt({ promptId: NUTRITION_GUIDE_PROMPT_ID })
+    .then(({ resolvedPrompt }) => {
+      // 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(() => { 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,
+// and a read that never settles must not hold every later turn either.
 async function loadNutritionGuide() {
-  try {
-    const { resolvedPrompt } = await composePrompt({ promptId: NUTRITION_GUIDE_PROMPT_ID });
-    return keepLines(resolvedPrompt || '', GUIDE_MAX_CHARS);
-  } catch (error) {
-    logger.warn('[nutritionPlanService] nutrition guide unavailable; plan sent without it', { error: error.message });
-    return '';
-  }
+  let timer;
+  const read = readGuide();
+  const timedOut = new Promise((resolve) => { timer = setTimeout(() => resolve(null), GUIDE_TIMEOUT_MS); });
+  const guide = await Promise.race([read, timedOut]);
+  clearTimeout(timer);
+  if (guide !== null) return guide;
+  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() } = {}) {
@@ -55,5 +86,7 @@ async function resolveNutritionPlan(section, { now = new Date() } = {}) {
 
 module.exports = {
   NUTRITION_GUIDE_PROMPT_ID,
+  GUIDE_TIMEOUT_MS,
   resolveNutritionPlan,
+  _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.
@@ -75,7 +76,7 @@ class EvalProvider {
       const { messages, promptVariables, lastUserMessage, contextSource } = await this._buildContext(numero, beforeCheckpoint);
 
       const {
-        devContent, assistant, toolSchemas, resolvedPromptId, presetModelConfig, resolvedPresetId,
+        devContent, assistant, toolSchemas, resolvedPromptId, presetModelConfig, resolvedPresetId, interpolatedVariables,
       } = await this._resolvePrompt(prompt, assistantId, thread, promptVariables);
 
       const request = this._buildRequest({
@@ -83,6 +84,7 @@ class EvalProvider {
         assistantId: resolvedPromptId || assistantId,
         presetId: resolvedPresetId,
         presetModelConfig,
+        interpolatedVariables,
       });
 
       const startTime = Date.now();
@@ -133,6 +135,7 @@ class EvalProvider {
 
   async _resolvePrompt(fallbackPrompt, assistantId, thread, promptVariables) {
     let devContent;
+    let interpolatedVariables = [];
     let resolvedPromptId = assistantId;
     let presetToolIds = null;
     let presetModelConfig = null;
@@ -143,18 +146,21 @@ class EvalProvider {
     if (this.promptSource === 'airtable' && (presetId || assistantId)) {
       const {
         resolvedPrompt, promptId, presetToolIds: toolIds, modelConfig, presetId: composedPresetId,
+        interpolatedVariables: interpolated,
       } = await composePrompt({
         presetId,
         promptId: assistantId,
         variables: promptVariables,
       });
       devContent = resolvedPrompt;
+      interpolatedVariables = interpolated || [];
       resolvedPromptId = promptId || assistantId;
       presetToolIds = toolIds;
       presetModelConfig = modelConfig || null;
       resolvedPresetId = composedPresetId || resolvedPresetId;
     } else {
       devContent = fallbackPrompt;
+      interpolatedVariables = variablesReferencedIn(devContent);
       devContent = devContent.replace(/\{\{(\w+)\}\}/g, (_, key) => promptVariables[key] ?? '');
     }
 
@@ -191,7 +197,7 @@ class EvalProvider {
       }
     }
 
-    return { devContent, assistant, toolSchemas, resolvedPromptId, presetModelConfig, resolvedPresetId };
+    return { devContent, assistant, toolSchemas, resolvedPromptId, presetModelConfig, resolvedPresetId, interpolatedVariables };
   }
 
   _modelConfig(presetModelConfig) {
@@ -204,7 +210,7 @@ class EvalProvider {
 
   _buildRequest({
     devContent, messages, promptVariables, toolSchemas, assistant, assistantId, presetId,
-    presetModelConfig = null,
+    presetModelConfig = null, interpolatedVariables = [],
   }) {
     const convertedMessages = this.provider._convertItemsToApiFormat(messages);
 
@@ -215,7 +221,11 @@ class EvalProvider {
       ? [{ role: 'developer', content: `Usa la siguiente información que conoces del paciente para personalizar tu respuesta. Adapta tu tono, contenido o recomendaciones según estas preferencias y contexto cuando sea relevante. No menciones que tienes esta información almacenada.\n\n${memoryParts.join('\n\n')}` }]
       : [];
 
-    const input = this.provider._sanitizeInput([...memoryMessage, ...convertedMessages]);
+    // The same runtime clinical block a live turn gets (context, symptoms, nutrition plan), unless the prompt interpolates it.
+    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;

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.11849",
+  "version": "5.67.0-dev.11929",
   "description": "Core messaging and assistant library for WhatsApp communication platforms",
   "keywords": [
     "whatsapp",