@peopl-health/nexus 5.68.4 → 5.68.6

package/lib/clinical/services/clinicalExtractionService.js

@@ -19,6 +19,7 @@ const { logger } = require('../../utils/logger');
 const CONFIG_TABLE = 'registry';
 const CACHE_TTL = 5 * 60 * 1000;
 const CONFIG_CACHE_KEY = 'clinicalExtractorConfig';
+const ENDING_STATUSES = new Set(['paused', 'completed']);
 
 const extractorConfigCache = new MapCache({ maxSize: 1, ttl: CACHE_TTL });
 
@@ -37,6 +38,12 @@ function namesNothingSpecific(canonicalTerm, vagueWords) {
   return tokens.length > 0 && tokens.every((token) => vagueWords.has(token));
 }
 
+function endsNamedLine(raw, fact) {
+  return fact.category === 'treatment'
+    && Boolean(raw.treatment_line)
+    && ENDING_STATUSES.has(fact.observedFields?.status);
+}
+
 async function loadPatientContext(code) {
   try {
     const { clinicalContext, contextAsk } = await getClinicalContext(code);
@@ -115,7 +122,8 @@ async function extractClinicalMentions({ text, turnId, code, provider, detectedT
         unanchored += 1;
         return;
       }
-      if (!mention.provenance.needsConfirmation && namesNothingSpecific(mention.fact.canonicalTerm, vagueWords)) {
+      if (!mention.provenance.needsConfirmation && !endsNamedLine(raw, mention.fact)
+        && namesNothingSpecific(mention.fact.canonicalTerm, vagueWords)) {
         forcedPending += 1;
         mention = toClinicalMention(
           { ...raw, needs_confirmation: true, missing: raw.missing?.length ? raw.missing : ['name'] },

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/package.json

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