@peopl-health/nexus 5.44.0-dev.6832 → 5.44.0-dev.6850

package/lib/clinical/helpers/clinicalWorkflowGuard.js

@@ -72,7 +72,7 @@ function validateClinicalDelivery(trace, { enabledSkills = [], skillActivationIt
   if (signals.clinicalIntakeCompleted !== true) {
     return {
       error: REFUSAL.intakeBeforeDelivery,
-      recovery: 'Classify the complete patient message: call extractClinicalInfo with every supported tag it carries, or commit the workflow matching the clinical event it names. Do not file an administrative escalation for a turn that carries no pending request.',
+      recovery: 'Classify the complete patient message: call extractClinicalInfo with every supported tag it carries, or declare its non_clinical_request when it carries no clinical content and only asks for something you answer yourself, or commit the workflow matching the clinical event it names. Do not file an administrative escalation for a turn that carries no pending request, or for a request you answer yourself.',
       requiredToolIds: [
         'extractClinicalInfo', 'reportResultsReceived', 'reportCrisis',
         'reportMedicalEscalation',

package/lib/clinical/providers/BaseLLMProvider.js

@@ -554,6 +554,10 @@ class BaseLLMProvider {
       const value = calls.find(call => call.name === name)?.input?.[field];
       return typeof value === 'string' && value.trim() ? value : null;
     };
+    const extraction = calls.find(call => call.name === EXTRACTION_TOOL)?.input;
+    if (pick(EXTRACTION_TOOL, 'non_clinical_request') && pick(EXTRACTION_TOOL, 'raw_message') && extraction?.detected_tags?.length === 0) {
+      return { text: null, reasoning: null };
+    }
     const authored = pick(BRIDGE_TOOL, 'message_text');
     if (authored) return { text: authored, reasoning: pick(BRIDGE_TOOL, 'reasoning') };
     return { text: pick(EXTRACTION_TOOL, 'bridge_text'), reasoning: pick(EXTRACTION_TOOL, 'bridge_reasoning') };

package/lib/clinical/tools/extractClinicalInfoTool.js

@@ -12,11 +12,12 @@ const DETECTED_TAG_ENUM = [
   'symptom', 'indication', 'treatment', 'adherence', 'medication', 'appointment',
   'emotion', 'lab_value', 'diagnosis', 'allergy', 'comorbidity', 'performance_status',
 ];
+const NON_CLINICAL_REQUESTS = ['external_booking'];
 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`), `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 written to the patient record — they are held back until the patient confirms them.',
   strict: true,
   parameters: {
     type: 'object',
@@ -86,8 +87,18 @@ const definition = {
         anyOf: [{ type: 'string' }, { type: 'null' }],
         description: 'Una frase: en qué detalle del inbound anclaste `bridge_text` y por qué ese detalle. INTERNO; el paciente nunca lo ve. null cuando `bridge_text` es null.',
       },
+      non_clinical_request: {
+        anyOf: [{ type: 'string', enum: NON_CLINICAL_REQUESTS }, { type: 'null' }],
+        description: [
+          'Declara que el mensaje NO trae contenido clínico y solo pide algo que tú contestas directamente, sin el equipo.',
+          '- external_booking: agendar, reprogramar o cancelar una cita con un médico, una sesión de tratamiento (quimio, radio, infusión) o un estudio de laboratorio o imagen.',
+          'Va con `detected_tags` vacío. Si el mensaje también menciona un síntoma, emoción, medicamento, tratamiento o resultado, etiqueta esas variables y manda `null` aquí.',
+          'Manda `null` cuando la petición necesita que el equipo actúe (p. ej. una sesión del programa de acompañamiento de AUNA) y cuando el paciente solo cuenta que tiene una cita.',
+          'Con este campo, `bridge_text` va en `null`: la respuesta es un solo mensaje.',
+        ].join('\n'),
+      },
     },
-    required: ['raw_message', 'detected_tags', 'intake_source', 'response_format', 'context', 'bridge_text', 'bridge_reasoning'],
+    required: ['raw_message', 'detected_tags', 'intake_source', 'response_format', 'context', 'bridge_text', 'bridge_reasoning', 'non_clinical_request'],
     additionalProperties: false,
   },
 };
@@ -116,7 +127,12 @@ async function handler(args, context = {}) {
 
   if (!detectedTags.length) {
     const supported = [...SUPPORTED_TAGS].sort();
-    const safetyFlags = await scanSafetyFlags(rawMessage);
+    const declaredRequest = !detectedTagsRaw.length && NON_CLINICAL_REQUESTS.includes(args?.non_clinical_request) ? args.non_clinical_request : null;
+    if (declaredRequest && trace?.signals?.clinicalFactsExtracted) {
+      return JSON.stringify({ success: false, error: 'This turn already extracted clinical facts, so it cannot be declared a non-clinical request. Continue the clinical workflow those facts require.' });
+    }
+    const scannedFlags = await scanSafetyFlags(rawMessage);
+    const safetyFlags = scannedFlags || [];
     if (trace?.setSignals) trace.setSignals({ clinicalIntakeCompleted: false, clinicalMentions: [], safetyFlags });
 
     const providerDecision = trace?.signals?.clinicalIntakeDecisionRequired;
@@ -130,15 +146,25 @@ async function handler(args, context = {}) {
       }
       conversationalInbound = isPurelyConversational(rawMessage, conversationalTokens);
     }
-    if (!detectedTagsRaw.length && conversationalInbound) {
+    if (declaredRequest && scannedFlags?.length === 0) {
+      if (trace?.setSignals) trace.setSignals({ clinicalIntakeCompleted: true });
+      return JSON.stringify({
+        success: true,
+        data: { degraded: false, non_clinical_request: declaredRequest, clinical_facts: [] },
+      });
+    }
+    if (!declaredRequest && !detectedTagsRaw.length && conversationalInbound) {
       if (trace?.setSignals) trace.setSignals({ clinicalIntakeCompleted: true });
       return JSON.stringify({
         success: true,
         data: { degraded: false, conversational_inbound: true, clinical_facts: [] },
       });
     }
+    const emptyTagsError = declaredRequest
+      ? `The message matched a safety pattern or the safety scan was unavailable, so it cannot be declared a non-clinical request. Re-call with every applicable supported tag (${supported.join(', ')}).`
+      : `extractClinicalInfo was called with an empty \`detected_tags\` list and the inbound is not purely conversational. The intake decision is incomplete, so direct delivery remains blocked. Re-call with every applicable supported tag (${supported.join(', ')}). If the message carries no clinical content and only makes a request that \`non_clinical_request\` covers, re-call with empty tags and that field set. If it carries no clinical content but needs the team to act on a request, commit that workflow instead. Commit nothing when the turn carries neither.`;
     const error = !detectedTagsRaw.length
-      ? `extractClinicalInfo was called with an empty \`detected_tags\` list and the inbound is not purely conversational. The intake decision is incomplete, so direct delivery remains blocked. Re-call with every applicable supported tag (${supported.join(', ')}), or, if the message carries no clinical content but does carry an administrative or referral request, commit that workflow instead. Commit nothing when the turn carries neither.`
+      ? emptyTagsError
       : `extractClinicalInfo received detected_tags=${JSON.stringify(detectedTagsRaw)} but none are supported. Use only these exact strings (lowercase): ${supported.join(', ')}. Re-call with the corrected tags.`;
     return JSON.stringify({ success: false, error, supported_tags: supported, received_tags: detectedTagsRaw });
   }
@@ -167,6 +193,7 @@ async function handler(args, context = {}) {
       clinicalIntakeCompleted: intakeCompleted,
       clinicalMentions: [...clinicalMentions, ...pendingMentions],
       safetyFlags,
+      ...(clinicalMentions.length || pendingMentions.length ? { clinicalFactsExtracted: true } : {}),
     });
   } else {
     logger.warn('[extractClinicalInfo] no trace on runtime context; signals not recorded', { turnId: runtime?.turnId });
@@ -215,7 +242,7 @@ async function scanSafetyFlags(text) {
     return detectSafetyFlags(text, await getSafetyFlagPatterns());
   } catch (err) {
     logger.warn('[extractClinicalInfo] deterministic safety scan failed', { error: err?.message });
-    return [];
+    return null;
   }
 }
 

package/lib/clinical/tools/reportUnresolvedRequestv2Tool.js

@@ -4,14 +4,14 @@ const { logger } = require('../../utils/logger');
 
 const definition = {
   'name': 'reportUnresolvedRequestv2',
-  'description': '**Does:** Escalates ADMINISTRATIVE / OPERATIVE matters — and non-clinical referrals to other services (psico-oncología, paliativos, non-oncology medical) — to the appropriate team queue. Records what was left pending, why it needs the team, operational urgency, and what was already communicated to the patient. It carries NO clinical-escalation semantics for the patient\'s oncology condition — those go to `reportMedicalEscalation`.\n\n**Required inputs:** `unresolved_question`, `category` (operational routing — REQUIRED for the queue), `urgency` (`routine` | `soon` | `urgent`; default `routine`), `escalation_details`, `resolution_attempted` (bool).\n\n**When to call:**\n- Administrative matter (appointments / insurance / authorisations / letters / rescheduling / transport).\n- Patient request that needs human (non-clinical) intervention.\n- Outside the agent\'s scope or knowledge (non-clinical).\n- A routine referral (psico-oncología, paliativos).\n- Callback from a specific team member (`category=contact_team_member`), or enrollment in a program / workshop / support group (`category=program_enrollment`).\nAlways pair with a `DeliverPatientMessage` acknowledging the escalation.\n\n**When NOT to call (use the clinical tools instead):**\n- ANY medical escalation — confirmed emergency, same-day evaluation, OR an asynchronous clinical concern (a symptom persisting >72h, a worrying trend, a treatment concern, stale clinical context) — use `reportMedicalEscalation` (urgency_level stat | asap | urgent | routine).\n- Active mental-health crisis — use `reportCrisis`.\n- Patient SHARED results / values / files — use `reportResultsReceived`.\n- Questions answerable from the CTCAE catalog or skill protocols — answer directly.\n\n**Returns:** an ack ({} on the happy path). Out-of-enum `urgency`/`category` are coerced (to `routine`/`other`) and disclosed via `coerced_urgency`/`coerced_category`; inputs over 500 chars are truncated and disclosed via `truncated_fields`. If the escalation could not be queued to the team it comes back with `queued: false` — do NOT tell the patient the team was notified in that case; acknowledge and say you are still working on it.\n\n**Side effects:** Emits `OUT_OF_SCOPE_LOGGED` to the appropriate team queue.',
+  'description': '**Does:** Escalates ADMINISTRATIVE / OPERATIVE matters — and non-clinical referrals to other services (psico-oncología, paliativos, non-oncology medical) — to the appropriate team queue. Records what was left pending, why it needs the team, operational urgency, and what was already communicated to the patient. It carries NO clinical-escalation semantics for the patient\'s oncology condition — those go to `reportMedicalEscalation`.\n\n**Required inputs:** `unresolved_question`, `category` (operational routing — REQUIRED for the queue), `urgency` (`routine` | `soon` | `urgent`; default `routine`), `escalation_details`, `resolution_attempted` (bool).\n\n**When to call:**\n- Administrative matter the team has to act on (insurance / authorisations / letters / transport), including scheduling or rescheduling a session of the AUNA accompaniment program (psico-oncología, nutrición).\n- Patient request that needs human (non-clinical) intervention.\n- Outside the agent\'s scope or knowledge (non-clinical).\n- A routine referral (psico-oncología, paliativos).\n- Callback from a specific team member (`category=contact_team_member`), or enrollment in a program / workshop / support group (`category=program_enrollment`).\nAlways pair with a `DeliverPatientMessage` acknowledging the escalation.\n\n**When NOT to call:**\n- ANY medical escalation — confirmed emergency, same-day evaluation, OR an asynchronous clinical concern (a symptom persisting >72h, a worrying trend, a treatment concern, stale clinical context) — use `reportMedicalEscalation` (urgency_level stat | asap | urgent | routine).\n- Active mental-health crisis — use `reportCrisis`.\n- Patient SHARED results / values / files — use `reportResultsReceived`.\n- Booking, rescheduling or cancelling a doctor appointment, a treatment session (chemo / radiotherapy / infusion) or a lab / imaging study — these are not booked through this channel; answer the patient directly with where to book, as your instructions describe. When that turn carries no clinical content, declare it with `non_clinical_request` in `extractClinicalInfo`.\n- Questions answerable from the CTCAE catalog or skill protocols — answer directly.\n\n**Returns:** an ack ({} on the happy path). Out-of-enum `urgency`/`category` are coerced (to `routine`/`other`) and disclosed via `coerced_urgency`/`coerced_category`; inputs over 500 chars are truncated and disclosed via `truncated_fields`. If the escalation could not be queued to the team it comes back with `queued: false` — do NOT tell the patient the team was notified in that case; acknowledge and say you are still working on it.\n\n**Side effects:** Emits `OUT_OF_SCOPE_LOGGED` to the appropriate team queue.',
   'strict': true,
   'parameters': {
     'type': 'object',
     'properties': {
       'unresolved_question': {
         'type': 'string',
-        'description': 'El pendiente ADMINISTRATIVO / OPERATIVO o de DERIVACIÓN que requiere al equipo. Cubre: (1) administrativo — citas, seguros, autorizaciones, cartas, reprogramación, transporte; (2) solicitud que requiere intervención humana no clínica; (3) fuera de tus alcances o conocimientos; (4) derivación/referencia a otro servicio (psico-oncología, paliativos, médico no oncológico) — eso es COORDINACIÓN, no escalación clínica. NO uses esta herramienta para ESCALACIONES CLÍNICAS del cuadro oncológico — un síntoma que persiste, una tendencia preocupante, un treatment_concern o contexto clínico desactualizado van por `reportMedicalEscalation` (urgency_level `routine` para revisión asíncrona del equipo). Resultados ya realizados que compartió el paciente van por `reportResultsReceived`.'
+        'description': 'El pendiente ADMINISTRATIVO / OPERATIVO o de DERIVACIÓN que requiere al equipo. Cubre: (1) administrativo que el equipo tiene que resolver — seguros, autorizaciones, cartas, transporte, y agendar o reprogramar sesiones del programa de acompañamiento de AUNA (psico-oncología, nutrición); (2) solicitud que requiere intervención humana no clínica; (3) fuera de tus alcances o conocimientos; (4) derivación/referencia a otro servicio (psico-oncología, paliativos, médico no oncológico) — eso es COORDINACIÓN, no escalación clínica. NO uses esta herramienta para ESCALACIONES CLÍNICAS del cuadro oncológico — un síntoma que persiste, una tendencia preocupante, un treatment_concern o contexto clínico desactualizado van por `reportMedicalEscalation` (urgency_level `routine` para revisión asíncrona del equipo). Resultados ya realizados que compartió el paciente van por `reportResultsReceived`. Tampoco la uses para agendar, reprogramar o cancelar citas con médicos, sesiones de tratamiento (quimio, radio, infusión) o estudios de laboratorio o imagen: no se agendan por este medio y eso se le responde directamente al paciente.'
       },
       'escalation_details': {
         'type': 'string',
@@ -32,7 +32,7 @@ const definition = {
           'program_enrollment',
           'other'
         ],
-        'description': 'Categoría operativa/administrativa o de derivación del pendiente para ruteo. `contact_team_member` = el paciente quiere hablar con / pasar un mensaje a / que lo llame de vuelta un miembro del equipo. `program_enrollment` = inscribirse a charlas, talleres, grupos de apoyo o check-ups. Las categorías de ESCALACIÓN CLÍNICA (symptom_persistent, treatment_concern, stale_context) se retiraron — esas escalaciones van por `reportMedicalEscalation`.'
+        'description': 'Categoría operativa/administrativa o de derivación del pendiente para ruteo. `scheduling` = agendar o reprogramar sesiones del programa de acompañamiento de AUNA (no citas médicas, sesiones de tratamiento ni estudios). `contact_team_member` = el paciente quiere hablar con / pasar un mensaje a / que lo llame de vuelta un miembro del equipo. `program_enrollment` = inscribirse a charlas, talleres, grupos de apoyo o check-ups. Las categorías de ESCALACIÓN CLÍNICA (symptom_persistent, treatment_concern, stale_context) se retiraron — esas escalaciones van por `reportMedicalEscalation`.'
       },
       'resolution_attempted': {
         'anyOf': [
@@ -54,7 +54,7 @@ const definition = {
               'soon',
               'urgent'
             ],
-            'description': 'routine = sin plazo; soon = plazo en la semana; urgent = mismo día (transporte para hoy, conflicto de cita mañana).'
+            'description': 'routine = sin plazo; soon = plazo en la semana; urgent = mismo día (transporte para hoy, una sesión de programa que choca mañana).'
           },
           {
             'type': 'null'

package/package.json

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