@peopl-health/nexus 5.69.0-dev.12577 → 5.69.0-dev.12578

package/lib/clinical/flags/emergencyConsultFlags.js

@@ -0,0 +1,16 @@
+const runtimeConfig = require('../../config/runtimeConfig');
+
+const MODES = ['off', 'shadow'];
+const DEFAULT_SAMPLE_RATE = 0.1;
+
+function emergencyConsultMode() {
+  const value = String(runtimeConfig.get('EMERGENCY_CONSULT_MODE', 'off')).trim().toLowerCase();
+  return MODES.includes(value) ? value : 'off';
+}
+
+function emergencyConsultSampleRate() {
+  const value = Number(runtimeConfig.get('EMERGENCY_CONSULT_SAMPLE_RATE', DEFAULT_SAMPLE_RATE));
+  return Number.isFinite(value) && value >= 0 && value <= 1 ? value : DEFAULT_SAMPLE_RATE;
+}
+
+module.exports = { emergencyConsultMode, emergencyConsultSampleRate };

package/lib/clinical/monitoring/LlmMonitorService.js

@@ -230,7 +230,7 @@ class LlmMonitorService {
     if (!evaluation) return Evaluations.findOne(key);
 
     try {
-      const evidence = spec.buildEvidence(trace);
+      const evidence = await spec.buildEvidence(trace);
       let judge = null;
       let result = null;
       let judgePrompt = null;
@@ -248,12 +248,19 @@ class LlmMonitorService {
           text: { format: { type: 'json_schema', name: `${spec.id}_verdict`, schema: spec.schema, strict: true } },
           metadata: { source: 'llm_monitor', turn_id: trace.turnId, monitor_id: spec.id, monitor_version: String(spec.version) },
         });
-        judge = parseJudge(result);
-        spec.validateJudge?.(judge);
+        // A refusal repeats on retry, so a spec that can record it does not pay for it again.
+        const isFinalRefusal = result?.status === 'refused' && spec.refusalIsFinal === true;
+        if (result?.status && result.status !== 'completed' && !isFinalRefusal) {
+          throw new Error(`monitor judge did not complete: ${result.stop_reason || result.status}`);
+        }
+        if (!isFinalRefusal) {
+          judge = parseJudge(result);
+          spec.validateJudge?.(judge);
+        }
       }
       let findings = spec.interpret({ trace, evidence, judge });
       const evalKey = `${spec.id}:${spec.version}:${trace.turnId}`;
-      const passSampled = findings.length === 0 && stableFraction(evalKey) < this.passSampleRate;
+      const passSampled = findings.length === 0 && judge !== null && stableFraction(evalKey) < this.passSampleRate;
       if (passSampled) findings = [passFinding(judge)];
       findings = findings.map((finding, index) => ({
         ...finding,
@@ -552,6 +559,7 @@ class LlmMonitorService {
 
 module.exports = {
   LlmMonitorService,
+  stableFraction,
   EVALUATE_QUEUE,
   RECONCILE_QUEUE,
   _test: { stableFraction, findingId, needsSync, syncBacklogFilter, RECONCILE_BATCH_SIZE, MAX_EVALUATION_ATTEMPTS },

package/lib/clinical/monitoring/emergencyConsultMonitorSpec.js

@@ -0,0 +1,215 @@
+const { patientMessageFromTrace } = require('../helpers/evidenceAnchorHelper');
+const { buildConsultContext } = require('../services/emergencyConsultService');
+const { emergencyConsultSampleRate } = require('../flags/emergencyConsultFlags');
+const { URGENCY_RANK } = require('../../models/escalationReviewModel');
+const { isPlainObject } = require('../../utils/jsonUtils');
+
+const { stableFraction } = require('./LlmMonitorService');
+
+const MONITOR_ID = 'emergency_consult';
+const MONITOR_VERSION = '1';
+const PRESET_ID = 'sa_emergency_consult';
+const LEVELS = ['stat', 'asap', 'urgent', 'routine'];
+const IMMEDIATE_LEVELS = ['stat', 'asap'];
+const DISPOSITIONS = ['escalate_now', 'ask_first', 'no_escalation'];
+const STALE_AFTER_MS = 15 * 60 * 1000;
+const UNREADABLE_PATIENT = [400, 404];
+
+const strings = { type: 'array', items: { type: 'string' } };
+const nullableLevel = { anyOf: [{ type: 'string', enum: LEVELS }, { type: 'null' }] };
+
+const CONSULT_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['disposition', 'urgency_level', 'confidence', 'clinical_reasoning', 'serious_differential', 'red_flags_present',
+    'red_flags_ruled_out', 'missing_information', 'level_if_unanswered', 'context_gaps', 'recommended_action', 'what_to_tell_patient'],
+  properties: {
+    disposition: { type: 'string', enum: DISPOSITIONS },
+    urgency_level: nullableLevel,
+    confidence: { type: 'string', enum: ['low', 'moderate', 'high'] },
+    clinical_reasoning: { type: 'string' },
+    serious_differential: {
+      type: 'array',
+      items: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['condition', 'status', 'features'],
+        properties: {
+          condition: { type: 'string' },
+          status: { type: 'string', enum: ['supported', 'not_excluded', 'unlikely'] },
+          features: strings,
+        },
+      },
+    },
+    red_flags_present: strings,
+    red_flags_ruled_out: strings,
+    missing_information: {
+      type: 'array',
+      items: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['question_for_patient', 'why', 'level_if_positive'],
+        properties: {
+          question_for_patient: { type: 'string' },
+          why: { type: 'string' },
+          level_if_positive: { type: 'string', enum: LEVELS },
+        },
+      },
+    },
+    level_if_unanswered: nullableLevel,
+    context_gaps: strings,
+    recommended_action: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['now', 'notify'],
+      properties: {
+        now: { type: 'string' },
+        notify: { type: 'string', enum: ['none', 'team_review', 'treating_team_today', 'oncologist_now', 'emergency_services'] },
+      },
+    },
+    what_to_tell_patient: { type: 'string' },
+  },
+};
+
+const asArray = (value) => (Array.isArray(value) ? value : []);
+
+function triggers(trace) {
+  const signals = trace?.signals || {};
+  const found = [];
+  if (signals.medicalEscalation) found.push('medical_escalation');
+  if (asArray(signals.safetyFlags).length) found.push('safety_flags');
+  if (asArray(signals.activatedSkills).includes('emergency')) found.push('emergency_skill');
+  if (!found.length && asArray(signals.clinicalMentions).length
+    && stableFraction(`${MONITOR_ID}:${trace.turnId}`) < emergencyConsultSampleRate()) found.push('mention_sample');
+  return found;
+}
+
+function isEligible(trace) {
+  return trace?.status === 'completed'
+    && trace?.shadow !== true
+    && triggers(trace).length > 0;
+}
+
+function agentDecision(trace) {
+  const escalation = trace.signals?.medicalEscalation;
+  if (!escalation) return { escalated: false, level: null, requestedLevel: null, patternFloor: null };
+  return {
+    escalated: true,
+    level: escalation.urgencyLevel || null,
+    requestedLevel: escalation.requestedUrgencyLevel || null,
+    patternFloor: escalation.clinicalPatternFloor || null,
+  };
+}
+
+const mentionFacts = (trace) => asArray(trace.signals?.clinicalMentions)
+  .map(({ fact }) => {
+    if (!isPlainObject(fact)) return null;
+    const { patientId: _patientId, mentionId: _mentionId, ...rest } = fact;
+    return rest;
+  })
+  .filter(Boolean);
+
+async function buildEvidence(trace, now = Date.now()) {
+  // The trace is saved once the turn ends, so the turn started predictionTimeMs before createdAt.
+  const turnStart = new Date(trace.createdAt).getTime() - (trace.timings?.predictionTimeMs || 0);
+  const base = { triggers: triggers(trace), agent: agentDecision(trace), lag_ms: now - turnStart };
+  if (base.lag_ms > STALE_AFTER_MS) return { ...base, extraction_succeeded: false, degraded: 'stale' };
+  try {
+    const { input, degradedSections, hasCoreContext } = await buildConsultContext({
+      code: trace.patientCode,
+      turnStart,
+      patientMessage: patientMessageFromTrace(trace),
+      mentions: mentionFacts(trace),
+    });
+    if (!hasCoreContext) return { ...base, extraction_succeeded: false, degraded: 'core_context_missing', degraded_sections: degradedSections };
+    return { ...base, extraction_succeeded: true, input, degraded_sections: degradedSections };
+  } catch (error) {
+    if (!UNREADABLE_PATIENT.includes(error?.statusCode)) throw error;
+    return { ...base, extraction_succeeded: false, degraded: 'patient_unreadable', error: error.message };
+  }
+}
+
+function buildJudgeInput(evidence) {
+  return [{ role: 'user', content: evidence.input }];
+}
+
+function validateJudge(judge) {
+  if (!isPlainObject(judge) || !DISPOSITIONS.includes(judge.disposition)) {
+    throw new Error('emergency consult returned no valid disposition');
+  }
+}
+
+function invariantViolations(judge) {
+  const violations = [];
+  const askFirst = judge.disposition === 'ask_first';
+  if (judge.disposition === 'escalate_now' && !judge.urgency_level) violations.push('escalate_now_without_level');
+  if (askFirst && !asArray(judge.missing_information).length) violations.push('ask_first_without_questions');
+  if (askFirst && !judge.level_if_unanswered) violations.push('ask_first_without_level_if_unanswered');
+  if (askFirst && [judge.urgency_level, judge.level_if_unanswered].some((level) => IMMEDIATE_LEVELS.includes(level))) {
+    violations.push('ask_first_on_immediate_level');
+  }
+  if (judge.disposition !== 'escalate_now' && asArray(judge.red_flags_present).length) violations.push('red_flags_without_escalation');
+  return violations;
+}
+
+const rank = (level) => URGENCY_RANK[level] || 0;
+
+function consultFinding(fields) {
+  return {
+    type: 'emergency_consult',
+    severity: 'normal',
+    confidence: 'high',
+    opsReviewRequired: false,
+    targetId: null,
+    observedCallIndex: null,
+    ...fields,
+  };
+}
+
+function interpret({ evidence, judge }) {
+  if (!evidence.extraction_succeeded || !judge) {
+    return [consultFinding({
+      expectedAction: null,
+      observedAction: evidence.agent?.level || null,
+      criteria: { degraded: evidence.extraction_succeeded ? 'judge_refused' : evidence.degraded },
+      summary: 'El especialista no evaluó el turno.',
+      evidence: evidence.error || 'Sin detalle.',
+    })];
+  }
+  const specialistLevel = judge.disposition === 'ask_first' ? judge.level_if_unanswered : judge.urgency_level;
+  const agentLevel = evidence.agent?.level || null;
+  return [consultFinding({
+    expectedAction: specialistLevel || null,
+    observedAction: agentLevel,
+    criteria: {
+      disposition: judge.disposition,
+      agent_below_specialist: rank(agentLevel) < rank(specialistLevel),
+      invariant_violations: invariantViolations(judge),
+    },
+    summary: `Especialista: ${judge.disposition} ${specialistLevel || 'sin nivel'}; agente: ${agentLevel || 'sin escalamiento'}.`,
+    evidence: judge.clinical_reasoning || 'Sin razonamiento.',
+  })];
+}
+
+const emergencyConsultMonitorSpec = {
+  id: MONITOR_ID,
+  version: MONITOR_VERSION,
+  presetId: PRESET_ID,
+  schema: CONSULT_SCHEMA,
+  refusalIsFinal: true,
+  reconcileQuery: {
+    $or: [
+      { 'signals.medicalEscalation': { $exists: true } },
+      { 'signals.safetyFlags.0': { $exists: true } },
+      { 'signals.activatedSkills': 'emergency' },
+      { 'signals.clinicalMentions.0': { $exists: true } },
+    ],
+  },
+  isEligible,
+  buildEvidence,
+  buildJudgeInput,
+  validateJudge,
+  interpret,
+};
+
+module.exports = { emergencyConsultMonitorSpec };

package/lib/clinical/services/emergencyConsultService.js

@@ -0,0 +1,76 @@
+const { readClinicalProfile } = require('../helpers/clinicalProfileHelper');
+const { buildExposureBlock } = require('../helpers/triageCaseBaseHelper');
+const { readDispatchedEscalations } = require('../../fhir');
+const { getEscalationContext } = require('../../services/escalationContextService');
+const { redactDirectIdentifiers } = require('../../utils/sanitizerUtils');
+const { assembleRiskProfile } = require('./riskAssessmentService');
+const { escalationLookbackSince } = require('./turnRiskBriefService');
+
+const CONTEXT_SECTIONS = ['agentContext', 'conversation', 'history'];
+const MAX_INPUT_CHARS = 120000;
+
+const optional = (promise) => promise.catch(() => undefined);
+
+// The conversation ends with this turn's own reply; the consult must not read the decision it is judging.
+function conversationBeforeReply(conversation) {
+  const messages = Array.isArray(conversation) ? [...conversation] : [];
+  while (messages.length && messages[messages.length - 1].role === 'assistant') messages.pop();
+  return messages;
+}
+
+function clinicalProfile(profile) {
+  if (!profile) return undefined;
+  const { edad = null, sexo = null } = profile.demografia || {};
+  return { demografia: { edad, sexo }, datos_clinicos: profile.datos_clinicos ?? null };
+}
+
+const section = (title, value) => [`## ${title}`, value === undefined ? 'no disponible' : JSON.stringify(value), ''];
+
+function fitConversation(head, conversation) {
+  const messages = [...conversation];
+  let text = section('Conversación', messages).join('\n');
+  while (messages.length && head.length + text.length > MAX_INPUT_CHARS) {
+    messages.shift();
+    text = section('Conversación', messages).join('\n');
+  }
+  return { text, truncated: messages.length < conversation.length };
+}
+
+async function buildConsultContext({ code, turnStart, patientMessage = null, mentions = [] }) {
+  const asOf = new Date(turnStart);
+  const [context, profile, risk, escalations] = await Promise.all([
+    getEscalationContext({ code, sections: CONTEXT_SECTIONS }),
+    readClinicalProfile(code),
+    optional(assembleRiskProfile(code)),
+    optional(readDispatchedEscalations({ patientId: code, since: escalationLookbackSince(asOf.getTime()) })),
+  ]);
+  const exposure = buildExposureBlock(profile);
+  const degradedSections = [...context.degradedSections];
+  if (!profile) degradedSections.push('clinicalProfile');
+  if (risk === undefined) degradedSections.push('risk');
+  if (escalations === undefined) degradedSections.push('escalations');
+
+  const head = [
+    `Fecha de hoy: ${asOf.toISOString().slice(0, 10)}`,
+    '',
+    '## Mensaje del paciente en este turno',
+    patientMessage || 'no capturado',
+    '',
+    ...section('Menciones clínicas extraídas en este turno', mentions),
+    ...section('Contexto clínico que ve la enfermera', context.agentContext ?? undefined),
+    '## Exposición antineoplásica y medicación documentadas',
+    exposure || 'no documentada',
+    '',
+    ...section('Perfil clínico', clinicalProfile(profile)),
+    ...section('Perfil de riesgo', risk?.profile ?? undefined),
+    ...section('Escalamientos de los últimos 14 días', escalations?.filter((event) => Date.parse(event.escalatedAt) < asOf.getTime())),
+    ...section('Historia clínica reciente', context.history ?? undefined),
+  ].join('\n');
+  const conversation = fitConversation(head, conversationBeforeReply(context.conversation));
+  if (conversation.truncated) degradedSections.push('conversation_truncated');
+  const input = `${head}\n${conversation.text}`;
+
+  return { input: redactDirectIdentifiers(input), degradedSections, hasCoreContext: Boolean(context.agentContext || profile) };
+}
+
+module.exports = { buildConsultContext };

package/lib/core/NexusMessaging.js

@@ -77,7 +77,11 @@ const unbatchedRoutes = {
 function loadDefaultLlmMonitor() {
   const { LlmMonitorService } = require('../clinical/monitoring/LlmMonitorService');
   const { contingencyMonitorSpec } = require('../clinical/monitoring/contingencyMonitorSpec');
-  return { LlmMonitorService, contingencyMonitorSpec };
+  const { emergencyConsultMonitorSpec } = require('../clinical/monitoring/emergencyConsultMonitorSpec');
+  const { emergencyConsultMode } = require('../clinical/flags/emergencyConsultFlags');
+  const specs = [contingencyMonitorSpec];
+  if (emergencyConsultMode() !== 'off') specs.push(emergencyConsultMonitorSpec);
+  return { LlmMonitorService, specs };
 }
 
 function normalizeLlmMonitorConfig(value) {
@@ -88,8 +92,8 @@ function normalizeLlmMonitorConfig(value) {
 function createDefaultLlmMonitor(options, loader = loadDefaultLlmMonitor) {
   if (!options.enabled) return null;
   try {
-    const { LlmMonitorService, contingencyMonitorSpec } = loader();
-    return new LlmMonitorService({ ...options, specs: [contingencyMonitorSpec] });
+    const { LlmMonitorService, specs } = loader();
+    return new LlmMonitorService({ ...options, specs });
   } catch (error) {
     logger.warn('[llmMonitor] construction failed; patient messaging remains available', {
       error: error?.message || String(error),

package/package.json

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