@peopl-health/nexus 5.68.5 → 5.68.7

package/lib/clinical/tools/extractClinicalInfoTool.js

@@ -40,7 +40,7 @@ const MAX_CONTEXT_TURNS = 6;
 
 const definition = {
   name: 'extractClinicalInfo',
-  description: '**Does:** Extracts ALL structured clinical facts from the current patient message — symptoms, labs, medications, diagnoses, appointments, treatments — and returns them as a discriminated-union `clinical_facts[]` list keyed by `kind`. Call ONCE per turn with ALL detected tags in a single call — one call covers every category.\n\n**Required inputs:** `raw_message` (the patient\'s current turn text, VERBATIM — the full contents of `<patient_message>`, every line of it when the turn carries more than one), `detected_tags` (list, at least one of: `symptom`, `indication`, `treatment`, `adherence`, `medication`, `appointment`, `emotion`, `lab_value`, `diagnosis`, `allergy`, `comorbidity`, `performance_status`; empty only for a purely conversational message or when declaring `non_clinical_request`), `intake_source` (`self` | `caregiver` | `team_relay`).\n\n**When to call:** at the start of any turn where the patient message mentions, explicitly or implicitly, any of the 12 supported categories. The result drives every downstream router-side read (landscape / history / risk / patterns).\n\n**When NOT to call:**\n- When the patient SHARED raw numeric results / lab values / files — use `reportResultsReceived` instead (it both logs the share AND emits FHIR Observations directly).\n- More than once per turn — a single call covers every category.\n\n**Returns:** `data.clinical_facts[]` — a discriminated-union list where each record has `kind` (observation | medication | condition | procedure | appointment | allergy) plus common fields `{id, code, effective, notes}` (null/default fields are OMITTED — e.g. `interpretation` appears only when non-default) and kind-specific fields:\n- `kind=observation`: `code_ctcae`, `value`, `grade_scale`,   `episode_id`, `trend`. Read `grade_scale` to anchor the   grade assigned in `recordClinicalImpression`. It is present   whenever the term has a curated CTCAE ladder, and ABSENT   when it does not — an absent `grade_scale` means there is no   rubric for this term, not that one was withheld. An absent   `grade_scale` means the term has no curated rubric, not   that one was withheld — so there is nothing to grade   against from memory. Call `lookupCtcaeEntry` when you   suspect the term itself is wrong; otherwise say where the   grade came from in `grade_estimate.source`.\n- `kind=medication`: `adherence_status` (`started` |   `ongoing` | `non_adherent` | …).\n- `kind=condition`: `clinical_status` (`active` | `resolved`   | …) — patient self-report of an existing diagnosis   (distinct from `openCondition` which commits a new   agent-tracked case).\n- `kind=procedure`: patient-reported procedure done   elsewhere (distinct from `recordIntervention` which is   agent-authored); `venue`/`outcome` may be null in the   current extraction phase.\n- `kind=appointment`: `scheduled_for`, `purpose` (may be   null in the current extraction phase).\nThe system writes the matching FHIR resource (Observation / MedicationStatement / Condition / Procedure / Appointment) + `Provenance` per fact on the audit lane; `allergy`, `comorbidity`, and `performance_status` are captured in a dedicated aggregate, not as a per-fact resource.\n\n**When the result asks you to confirm:** `data.pending_confirmation[]` means the patient reported a REAL clinical event but named it only generically («me suspendieron el tratamiento»), so it was deliberately NOT recorded. Each entry carries `{term, category, missing, quote}`; the list holds EVERY fact withheld this turn, but ask about the FIRST one only. Ask the patient for exactly what its `missing` names, in ONE short natural question, and never state or imply that anything was recorded. When they answer, call `extractClinicalInfo` again on their reply and it will be recorded then. `data.context_gaps[]` — only ever sent when there is nothing to confirm — names ONE stored variable that is stale or incomplete; raise it only if the conversation allows it naturally. Both lists are empty whenever the turn carries a safety flag: never ask housekeeping questions during a safety event.\n\n**Side effects:** System emits a FHIR resource + `Provenance` per fact on the audit lane, except `allergy`/`comorbidity`/`performance_status` (aggregated). Facts listed in `pending_confirmation` are NOT written to the patient record — they are held back until the patient confirms them.',
+  description: '**Does:** Extracts ALL structured clinical facts from the current patient message — symptoms, labs, medications, diagnoses, appointments, treatments — and returns them as a discriminated-union `clinical_facts[]` list keyed by `kind`. Call ONCE per turn with ALL detected tags in a single call — one call covers every category.\n\n**Required inputs:** `raw_message` (the patient\'s current turn text, VERBATIM — the full contents of `<patient_message>`, every line of it when the turn carries more than one), `detected_tags` (list, at least one of: `symptom`, `indication`, `treatment`, `adherence`, `medication`, `appointment`, `emotion`, `lab_value`, `diagnosis`, `allergy`, `comorbidity`, `performance_status`; empty only for a purely conversational message or when declaring `non_clinical_request`), `intake_source` (`self` | `caregiver` | `team_relay`).\n\n**When to call:** at the start of any turn where the patient message mentions, explicitly or implicitly, any of the 12 supported categories. The result drives every downstream router-side read (landscape / history / risk / patterns).\n\n**When NOT to call:**\n- When the patient SHARED raw numeric results / lab values / files — use `reportResultsReceived` instead (it both logs the share AND emits FHIR Observations directly).\n- More than once per turn — a single call covers every category.\n\n**Returns:** `data.clinical_facts[]` — a discriminated-union list where each record has `kind` (observation | medication | condition | procedure | appointment | allergy) plus common fields `{id, code, effective, notes}` (null/default fields are OMITTED — e.g. `interpretation` appears only when non-default) and kind-specific fields:\n- `kind=observation`: `code_ctcae`, `value`, `grade_scale`,   `episode_id`, `trend`. Read `grade_scale` to anchor the   grade assigned in `recordClinicalImpression`. It is present   whenever the term has a curated CTCAE ladder, and ABSENT   when it does not — an absent `grade_scale` means there is no   rubric for this term, not that one was withheld. An absent   `grade_scale` means the term has no curated rubric, not   that one was withheld — so there is nothing to grade   against from memory. Call `lookupCtcaeEntry` when you   suspect the term itself is wrong; otherwise say where the   grade came from in `grade_estimate.source`.\n- `kind=medication`: `adherence_status` (`started` |   `ongoing` | `non_adherent` | …).\n- `kind=condition`: `clinical_status` (`active` | `resolved`   | …) — patient self-report of an existing diagnosis   (distinct from `openCondition` which commits a new   agent-tracked case).\n- `kind=procedure`: patient-reported procedure done   elsewhere (distinct from `recordIntervention` which is   agent-authored); `venue`/`outcome` may be null in the   current extraction phase.\n- `kind=appointment`: `scheduled_for`, `purpose` (may be   null in the current extraction phase).\nThe system writes the matching FHIR resource (Observation / MedicationStatement / Condition / Procedure / Appointment) + `Provenance` per fact on the audit lane; `allergy`, `comorbidity`, and `performance_status` are captured in a dedicated aggregate, not as a per-fact resource.\n\n**When the result asks you to confirm:** `data.pending_confirmation[]` means the patient reported a REAL clinical event but named it only generically («me suspendieron el tratamiento»), so it was deliberately NOT recorded. Each entry carries `{term, category, missing, quote}`; the list holds EVERY fact withheld this turn, but ask about the FIRST one only. Ask the patient for exactly what its `missing` names, in ONE short natural question, and never state or imply that anything was recorded. When they answer, call `extractClinicalInfo` again on their reply and it will be recorded then. `data.context_gaps[]` — only ever sent when there is nothing to confirm — names ONE stored variable that is stale or incomplete; raise it only if the conversation allows it naturally. Both lists are empty whenever the turn carries a safety flag: never ask housekeeping questions during a safety event.\n\n**Side effects:** System emits a FHIR resource + `Provenance` per fact on the audit lane, except `allergy`/`comorbidity`/`performance_status` (aggregated). Facts listed in `pending_confirmation` are NOT recorded as facts — they never reach the clinical intake or the patient\'s chart; FHIR keeps them only as unconfirmed drafts until the patient confirms them.',
   strict: true,
   parameters: {
     type: 'object',

package/lib/fhir/projections/clinicalMentionProjection.js

@@ -5,6 +5,7 @@ const { reference, patientReference, codeableConcept, extension, toInstant } = r
 const { baseResource, problemListCategory, observationCategory } = require('../helpers/resourceHelper');
 const { MENTION_SLUG } = require('../constants/projectionSlugs');
 const { MENTION_EXT } = require('../constants/extensionSlugs');
+const { PROCEDURE_STATUS, statusFrom } = require('./contextFactProjection');
 
 const ACTIVITY_TEXT = 'clinical-mention-extraction';
 const OBSERVED_FIELD_SYSTEM_KEY = 'observedField';
@@ -137,7 +138,8 @@ function adherenceFor(assertion) {
 
 function procedureStatus(fact, provenance) {
   if (fact.assertion.negated) return 'not-done';
-  return provenance.needsConfirmation ? 'unknown' : 'completed';
+  if (provenance.needsConfirmation) return 'unknown';
+  return statusFrom(PROCEDURE_STATUS, fact.observedFields?.status, { absent: 'completed', unrecognised: 'completed' });
 }
 
 function procedureResource({ fact, provenance }) {

package/lib/fhir/projections/contextFactProjection.js

@@ -33,7 +33,7 @@ const PROCEDURE_STATUS = {
   ended: 'completed', realizada: 'completed', realizado: 'completed',
   stopped: 'stopped', suspendido: 'stopped', suspendida: 'stopped',
   suspended: 'stopped', discontinued: 'stopped', not_active: 'stopped',
-  paused: 'on-hold',
+  paused: 'on-hold', started: 'in-progress',
   finalizado: 'completed', end: 'completed', past: 'completed', previous: 'completed',
   historical: 'completed', historico: 'completed',
   cancelled: 'not-done', cancelado: 'not-done', cancelada: 'not-done',
@@ -363,6 +363,8 @@ function fromFhir(resources) {
 
 module.exports = {
   CONTEXT_RESOURCE_TYPES,
+  PROCEDURE_STATUS,
+  statusFrom,
   toFhir,
   fromFhir,
   conceptKeyOf,

package/lib/services/escalationReviewService.js

@@ -507,6 +507,25 @@ async function recordReviewUpdate({ code, update, now = new Date(), settleInBack
   }
 }
 
+const STALE_INTERRUPTION_NOTES = 'Cerrada automáticamente al llegar una alarma nueva; nadie verificó si la operación interrumpida se completó';
+
+async function closeStaleInterruption(EscalationReview, patientCode, now) {
+  try {
+    const stale = await EscalationReview.findOne({
+      patientCode,
+      closedAt: null,
+      status: { $in: INTERRUPTED_STATUSES },
+      updatedAt: { $lte: new Date(now.getTime() - INTERRUPTION_GRACE_MS) },
+    }, { updatedAt: 1 }).lean();
+    if (!stale) return;
+    await closeEscalationReview({
+      id: String(stale._id), closedBy: BOT_OPERATOR, interruptionNotes: STALE_INTERRUPTION_NOTES, expectedUpdatedAt: stale.updatedAt,
+    });
+  } catch (error) {
+    logger[error?.statusCode === 409 ? 'warn' : 'error']('[EscalationReview] The interrupted review was not closed before the new alarm', { error: redactedError(error) });
+  }
+}
+
 async function recordEscalationAlarm({ code, alarm, now = new Date() } = {}) {
   try {
     const patientCode = patientCodeOf(code);
@@ -518,6 +537,7 @@ async function recordEscalationAlarm({ code, alarm, now = new Date() } = {}) {
       .lean();
 
     await ensureActiveReviewIndex(EscalationReview);
+    await closeStaleInterruption(EscalationReview, patientCode, now);
     const joined = await join();
     if (joined) {
       await scheduleDoctorAlert(joined, entry, now);

package/package.json

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