@peopl-health/nexus 5.9.0-dev.921 → 6.0.0-dev.611

package/lib/clinical/tools/reportCrisisTool.js

@@ -1,211 +0,0 @@
-const { dispatcherService } = require('../services/dispatcherService');
-const { recordEmergency } = require('../services/clinicalAirtableService');
-const { logger } = require('../../utils/logger');
-
-const definition = {
-  'name': 'reportCrisis',
-  'description': '**Does:** Commits a confirmed mental-health crisis — emits `CRISIS_TRIGGERED` to the mental-health responder + SAPTEL coordination. One-way escalation: there is no un-commit. Symmetric with `reportMedicalEscalation` (the medical-event sibling).\n\n**Required inputs:** `crisis_level`, `patient_verbatim` (literal patient text), `action_given`, `signals`, `reasoning`.\n\n**Optional inputs (pass `null` when unknown — do NOT invent):** `with_someone`, `mentioned_method`, `protective_factors_observed`, `risk_trajectory`.\n\n**When to call:** confirmed suicidal ideation (direct or with plan), active or recent self-harm, or profound hopelessness with risk signals. The decision is yours and it is irreversible.\n\n**When NOT to call:**\n- Ambiguous suspicion — an existential phrase like "a veces ya no puedo más" without plan or intent. Instead, deliver `DeliverPatientMessage` with ONE clarifying question ("¿Estás teniendo pensamientos de hacerte daño ahora?") and end the turn; re-enter next turn with the new signal.\n- Sadness, grief, fear of treatment, frustration without ideation — not a crisis; use normal emotional-support flow, not `reportCrisis`.\n- Medical emergency / escalation — use `reportMedicalEscalation`.\n- Patient shared results/values — use `reportResultsReceived`.\n- Routine psycho-oncology referral — use `reportUnresolvedRequestv2` with `category=\'psicooncologia_referral\'`.\n- Already called once this turn — do not repeat.\n\n**After the commit:** deliver `DeliverPatientMessage` per the crisis branch template: ONE line of genuine acknowledgement, ONE line of concrete action (Línea de la Vida 800 911 2000 / SAPTEL 55 5259 8121 / stay where you are / move means of harm away), and the closing line "Ya avisé al equipo médico." No dose, no diagnosis, no jargon. The turn ends there.\n\n**Returns:** an ack ({}). Invalid `crisis_level` values are REJECTED with the valid bucket list — re-issue with the matching bucket.\n\n**Side effects:** Emits `CRISIS_TRIGGERED` to the mental-health responder + SAPTEL coordination.',
-  'strict': true,
-  'parameters': {
-    'type': 'object',
-    'properties': {
-      'crisis_level': {
-        'type': 'string',
-        'enum': [
-          'ideation',
-          'plan',
-          'means_accessible',
-          'action_taken'
-        ],
-        'description': 'Severity bucket for the crisis. Determines responder tempo. \'ideation\' = pensamientos sin plan ni medios. \'plan\' = mencionó método, tiempo o cómo lo haría, sin acceso inmediato. \'means_accessible\' = plan + acceso a los medios (pastillas a la mano, arma en casa). \'action_taken\' = ya inició la acción (tomó las pastillas, se cortó). El responder escala 911 / SAPTEL vs llamada del navegador según este campo — sé preciso.'
-      },
-      'patient_verbatim': {
-        'type': 'string',
-        'description': 'Lo que el paciente escribió, LITERAL, sin parafrasear ni corregir. El responder lee la señal cruda antes de llamar — la elección de palabras importa clínicamente.'
-      },
-      'action_given': {
-        'type': 'string',
-        'description': 'La acción concreta que le diste al paciente en `DeliverPatientMessage` este turno (e.g., \'Llamar a SAPTEL 55 5259 8121 ahora y quedarse en la conversación\', \'Alejar las pastillas y avisar a su hermana que está en la casa\'). El responder necesita saber qué dijimos para no contradecir.'
-      },
-      'signals': {
-        'type': 'array',
-        'items': {
-          'type': 'string'
-        },
-        'description': 'Señales catalogadas que identificaste (e.g., \'ideacion_suicida_directa\', \'plan_con_medios\', \'autolesion_activa\', \'desesperanza_profunda\'). Matchean contra el crisis_catalog para agregación estadística.'
-      },
-      'with_someone': {
-        'anyOf': [
-          {
-            'type': 'boolean',
-            'description': '¿El paciente mencionó estar acompañado en este momento? True si dijo que hay alguien (familia, pareja, amigo). False si dijo estar solo/a. Omitir (null) si no se sabe — NO inventes.'
-          },
-          {
-            'type': 'null'
-          }
-        ]
-      },
-      'mentioned_method': {
-        'anyOf': [
-          {
-            'type': 'string',
-            'description': 'Si el paciente nombró un método específico (pastillas, cuerda, arma, una altura, un corte), cópialo LITERAL aquí. Omitir si no se nombró — NO asumas.'
-          },
-          {
-            'type': 'null'
-          }
-        ]
-      },
-      'protective_factors_observed': {
-        'anyOf': [
-          {
-            'type': 'array',
-            'items': {
-              'type': 'string'
-            },
-            'description': 'Quotes u observaciones que atenúan el riesgo (red de apoyo mencionada, planes futuros, razones para vivir, disposición a seguir hablando, fe, hijos, responsabilidades activas). Lista vacía si no hay.'
-          },
-          {
-            'type': 'null'
-          }
-        ]
-      },
-      'risk_trajectory': {
-        'anyOf': [
-          {
-            'type': 'string',
-            'enum': [
-              'escalating',
-              'stable',
-              'passive_ideation',
-              'active_plan'
-            ],
-            'description': 'Trayectoria observada en este turno vs. turnos previos. Opcional — úsalo cuando el histórico del paciente aporte contexto (e.g. pasiva en turnos anteriores, ahora activa).'
-          },
-          {
-            'type': 'null'
-          }
-        ]
-      },
-      'reasoning': {
-        'type': 'object',
-        'description': 'Trazabilidad interna de la decisión (auditoría). NUNCA se muestra al paciente. Úsalo para dejar por qué llamaste esta herramienta AHORA, con evidencia y alternativas descartadas.',
-        'properties': {
-          'brief': {
-            'type': 'string',
-            'description': 'UNA oración explicando por qué esta llamada en este turno. Observacional, no justificación genérica. E.g. \'Constelación neuro: visión borrosa + no camina en <2 turnos\'.'
-          },
-          'evidence_quote': {
-            'type': 'string',
-            'description': 'Cita textual del paciente (o del contexto inyectado) que soporta la decisión. Vacío si la evidencia es derivada de una tool anterior (menciónala en brief).'
-          },
-          'alternatives_considered': {
-            'anyOf': [
-              {
-                'type': 'array',
-                'items': {
-                  'type': 'string'
-                },
-                'description': 'Opciones que sopesaste y descartaste este turno (e.g., \'esperar una caracterización más\', \'ofrecer OTC en vez de non-pharm\'). Lista vacía si no hubo tradeoff real.'
-              },
-              {
-                'type': 'null'
-              }
-            ]
-          }
-        },
-        'required': [
-          'brief',
-          'evidence_quote',
-          'alternatives_considered'
-        ],
-        'additionalProperties': false
-      }
-    },
-    'required': [
-      'crisis_level',
-      'patient_verbatim',
-      'action_given',
-      'signals',
-      'with_someone',
-      'mentioned_method',
-      'protective_factors_observed',
-      'risk_trajectory',
-      'reasoning'
-    ],
-    'additionalProperties': false
-  }
-};
-
-async function handler(args = {}, context = {}) {
-  try {
-    const runtime = context?.toolRuntimeContext || null;
-    const trace = runtime?.trace || null;
-    if (!trace) {
-      logger.error('[reportCrisis] Crisis escalation dropped — no active turn trace', { patientCode: runtime?.patientCode || null });
-      return JSON.stringify({ success: false, error: 'reportCrisis requires an active turn context (trace).' });
-    }
-    const levels = definition.parameters.properties.crisis_level.enum;
-    const crisisLevel = (args?.crisis_level || '').trim().toLowerCase();
-    if (!levels.includes(crisisLevel)) {
-      const validLevels = `[${levels.map((v) => `'${v}'`).join(', ')}]`;
-      return JSON.stringify({
-        success: false,
-        data: { valid_crisis_levels: [...levels] },
-        error: `invalid crisis_level: '${crisisLevel}'. Must be one of ${validLevels} — re-issue the call with the matching bucket.`,
-      });
-    }
-
-    trace.setSafetyDecision({ ...(trace.safetyDecision || {}), escalationKind: 'crisis' });
-    trace.setSignals({
-      crisis: {
-        crisisLevel,
-        patientVerbatim: args?.patient_verbatim || '',
-        actionGiven: args?.action_given || null,
-        signals: args?.signals || [],
-        withSomeone: args?.with_someone ?? null,
-        mentionedMethod: args?.mentioned_method ?? null,
-        protectiveFactorsObserved: args?.protective_factors_observed ?? null,
-        riskTrajectory: args?.risk_trajectory ?? null,
-        reasoning: args?.reasoning || null,
-      },
-    });
-
-    if (runtime.turnId && runtime.patientCode) {
-      try {
-        await dispatcherService.dispatch({
-          trace,
-          escalationKind: 'crisis',
-          turnId: runtime.turnId,
-          patientCode: runtime.patientCode,
-        });
-      } catch (dispatchErr) {
-        logger.warn('reportCrisis dispatch failed', { message: dispatchErr?.message });
-      }
-    }
-
-    if (runtime.patientCode) {
-      const crisisSignals = Array.isArray(args?.signals) ? args.signals.filter(Boolean) : [];
-      await recordEmergency({
-        code: runtime.patientCode,
-        trace,
-        symptom: `Crisis de salud mental (${crisisLevel})`,
-        recommendedAction: args?.action_given || '',
-        urgencyLevel: 'Alta',
-        documentation: [
-          args?.patient_verbatim || '',
-          crisisSignals.length ? `Señales: ${crisisSignals.join(', ')}` : '',
-        ].filter(Boolean).join('\n'),
-      });
-    }
-
-    return JSON.stringify({ success: true, data: {} });
-  } catch (err) {
-    return JSON.stringify({ success: false, error: err?.message || 'reportCrisis failed' });
-  }
-}
-
-module.exports = {
-  definition,
-  handler,
-};

package/lib/clinical/tools/reportMedicalEscalationTool.js

@@ -1,187 +0,0 @@
-const { dispatcherService } = require('../services/dispatcherService');
-const { recordEmergency, recordUnresolvedRequest } = require('../services/clinicalAirtableService');
-const { logger } = require('../../utils/logger');
-
-const definition = {
-  'name': 'reportMedicalEscalation',
-  'description': '**Does:** Escalates a MEDICAL situation to the oncology care team at a chosen urgency, with an explicit justification for the level. Covers the full medical-urgency spectrum — immediate emergencies through asynchronous team review. One-way commit; the payload is INTERNAL — the patient never sees it.\n\n**Required inputs:** `urgency_level` — the FHIR request-priority code (`stat` | `asap` | `urgent` | `routine`), `urgency_justification` (one or two sentences: why this level AND why not the tier above/below — the auditable decision record), `details` (object — `symptom` + `evidence_quote` required; pass `null` when unknown for `category`, `indicators`, `suspected_condition`, `recommended_action`).\n\n**Urgency levels:** FHIR request-priority, a RELATIVE order `routine` < `urgent` < `asap` < `stat` (priority/speed, not a fixed clock). The full per-tier rubric with clinical examples lives on the `urgency_level` input enum — read it there. Out-of-enum values are coerced to `urgent` and disclosed via `coerced_urgency` on the result.\n\n**Neurological constellation override:** TWO OR MORE of — visual change, dizziness/vertigo/loss of balance, inability to walk/stand, focal weakness/numbness, acute confusion, sudden severe headache — reported this turn or across the last 2–3 turns → escalate without a further clarifying question: `asap` by default, `stat` if there is an acute deficit (can\'t walk/stand, sphincter loss, bilateral leg weakness → possible cord compression) or any instability.\n\n**When NOT to call:**\n- Unconfirmed/unspecific symptom — ask ONE characterization question via `DeliverPatientMessage` first.\n- Active mental-health crisis — use `reportCrisis`.\n- Patient shared lab/imaging/values/files — use `reportResultsReceived`.\n- Administrative / operative matter (appointments, insurance, authorizations, letters, transport, scheduling, out-of-scope request) or a non-clinical referral (psico-oncología, paliativos, non-oncology medical) — use `reportUnresolvedRequestv2`.\n- Twice in the same turn — already committed.\n\n**After the commit:** deliver a brief `DeliverPatientMessage` matched to the level — `stat`: firm, no te muevas / 911 if alone or immobile, the team was notified; `asap`: wait 15 min for the team\'s word, then acude a urgencias (ve acompañada); `urgent`: \'es importante que te valoren hoy\' + the 15-min fallback; `routine`: warm acknowledgement that the team will review. Never confirm a diagnosis; avoid alarmist language; say the team was notified.\n\n**Returns:** an ack ({} on the happy path). When your `urgency_level` was out-of-enum it is coerced to `urgent` and disclosed via `{urgency_level, coerced_urgency, requested_urgency_level}`.\n\n**Side effects:** Emits `MEDICAL_ESCALATION_TRIGGERED`; the runtime routes it to the team by level (pages at `stat`/`asap`, ticket at `urgent`/`routine`).',
-  'strict': true,
-  'parameters': {
-    'type': 'object',
-    'properties': {
-      'urgency_level': {
-        'type': 'string',
-        'enum': [
-          'stat',
-          'asap',
-          'urgent',
-          'routine'
-        ],
-        'description': 'Tier of medical escalation — the FHIR request-priority code (RequestPriority), a RELATIVE urgency ordered routine < urgent < asap < stat. It encodes priority / speed-of-action, NOT a fixed time window — the per-case clock is safety_gate.max_action_time_hours. 1:1 with the gate route. In urgency_justification say why this level and not the one above or below.\n- `stat` (inmediato, gate emergencia) — acción inmediata, prioridad máxima, flujo de emergencia. Inestabilidad o amenaza vital: neutropenia febril CON inestabilidad, disnea severa, alteración del estado mental, sangrado mayor, compresión medular con déficit agudo.\n- `asap` (lo antes posible, gate urgencias) — máxima prioridad NO inmediata; revisión en la primera oportunidad posible porque la demora puede crear riesgo. Complicación seria sospechada pero aún no claramente inestable: dolor que empeora rápido, riesgo de infección / neutropenia febril ESTABLE, síntoma neurológico nuevo sin déficit agudo.\n- `urgent` (urgente, gate equipo_tratante_hoy) — revisión clínica acelerada, por encima de rutina porque la demora podría importar clínicamente. Mismo día, no presencial-ahora: síntoma nuevo moderado, anormalidad de laboratorio preocupante pero estable, toxicidad de tratamiento que necesita input oportuno.\n- `routine` (rutina, sin gate o verdict suavizado) — prioridad normal, vía de atención habitual. Sin riesgo por demora: seguimiento, aclaración de medicación, síntoma >72h sin empeorar, contexto clínico desactualizado.'
-      },
-      'urgency_justification': {
-        'type': 'string',
-        'description': 'Por qué ESTE nivel — y explícitamente por qué no el inmediato superior ni el inferior (qué dato objetivo define el tier). Es el registro auditable de la decisión. Una o dos frases. INTERNO; el paciente nunca lo ve.'
-      },
-      'details': {
-        'type': 'object',
-        'description': 'Structured clinical payload for the team. All fields are for INTERNAL review — never surfaced to the patient.',
-        'properties': {
-          'category': {
-            'anyOf': [
-              {
-                'type': 'string',
-                'description': 'Rama clínica que motiva la escalación (e.g. \'febrile_neutropenia\', \'neuro_constellation\', \'spinal_cord_compression\', \'treatment_concern\', \'persistent_symptom_72h\', \'stale_clinical_context\').'
-              },
-              {
-                'type': 'null'
-              }
-            ]
-          },
-          'symptom': {
-            'type': 'string',
-            'description': 'Síntoma o cluster principal, con temporalidad confirmada.'
-          },
-          'evidence_quote': {
-            'type': 'string',
-            'description': 'Cita textual del paciente que sustenta la escalación.'
-          },
-          'indicators': {
-            'anyOf': [
-              {
-                'type': 'array',
-                'items': {
-                  'type': 'string'
-                },
-                'description': 'Indicadores del catálogo (e.g. \'fever_on_chemo\', \'neuro_constellation\').'
-              },
-              {
-                'type': 'null'
-              }
-            ]
-          },
-          'suspected_condition': {
-            'anyOf': [
-              {
-                'type': 'string',
-                'description': 'Sospecha operativa interna para triage. NUNCA se menciona al paciente.'
-              },
-              {
-                'type': 'null'
-              }
-            ]
-          },
-          'recommended_action': {
-            'anyOf': [
-              {
-                'type': 'string',
-                'description': 'Acción recomendada para el equipo.'
-              },
-              {
-                'type': 'null'
-              }
-            ]
-          }
-        },
-        'required': [
-          'category',
-          'symptom',
-          'evidence_quote',
-          'indicators',
-          'suspected_condition',
-          'recommended_action'
-        ],
-        'additionalProperties': false
-      }
-    },
-    'required': [
-      'urgency_level',
-      'urgency_justification',
-      'details'
-    ],
-    'additionalProperties': false
-  }
-};
-
-async function handler(args, context = {}) {
-  try {
-    const runtime = context?.toolRuntimeContext || null;
-    const trace = runtime?.trace || null;
-    if (!trace) {
-      logger.error('[reportMedicalEscalation] Medical escalation dropped — no active turn trace', { patientCode: runtime?.patientCode || null });
-      return JSON.stringify({ success: false, error: 'reportMedicalEscalation requires an active turn context (trace).' });
-    }
-    const levels = definition.parameters.properties.urgency_level.enum;
-    const requested = (args?.urgency_level || '').trim().toLowerCase();
-    const coerced = !levels.includes(requested);
-    const urgencyLevel = coerced ? 'urgent' : requested;
-    const details = args?.details || {};
-
-    trace.setSafetyDecision({ ...(trace.safetyDecision || {}), escalationKind: 'medical_urgent' });
-    trace.setSignals({
-      medicalEscalation: {
-        urgencyLevel,
-        category: details.category ?? null,
-        symptom: details.symptom || null,
-        evidenceQuote: details.evidence_quote || null,
-        indicators: details.indicators ?? null,
-        suspectedCondition: details.suspected_condition ?? null,
-        recommendedAction: details.recommended_action ?? null,
-        urgencyJustification: args?.urgency_justification || null,
-        coercedUrgency: coerced,
-        requestedUrgencyLevel: requested,
-      },
-    });
-
-    if (runtime.turnId && runtime.patientCode) {
-      try {
-        await dispatcherService.dispatch({
-          trace,
-          escalationKind: 'medical_urgent',
-          turnId: runtime.turnId,
-          patientCode: runtime.patientCode,
-        });
-      } catch (dispatchErr) {
-        logger.warn('reportMedicalEscalation dispatch failed', { message: dispatchErr?.message });
-      }
-    }
-
-    if (runtime.patientCode) {
-      if (urgencyLevel === 'routine') {
-        await recordUnresolvedRequest({
-          code: runtime.patientCode,
-          trace,
-          question: details.symptom || '',
-          details: args?.urgency_justification || '',
-          category: 'medical_routine',
-          urgency: 'routine',
-        });
-      } else {
-        await recordEmergency({
-          code: runtime.patientCode,
-          trace,
-          symptom: details.symptom || '',
-          suspectedCondition: details.suspected_condition || '',
-          recommendedAction: details.recommended_action || '',
-          urgencyFhir: urgencyLevel,
-          documentation: [
-            args?.urgency_justification || '',
-            details.evidence_quote ? `Evidencia: «${details.evidence_quote}»` : '',
-          ].filter(Boolean).join('\n'),
-        });
-      }
-    }
-
-    const data = coerced
-      ? { urgency_level: urgencyLevel, coerced_urgency: true, requested_urgency_level: requested }
-      : {};
-    return JSON.stringify({ success: true, data });
-  } catch (err) {
-    return JSON.stringify({ success: false, error: err?.message || 'reportMedicalEscalation failed' });
-  }
-}
-
-module.exports = {
-  definition,
-  handler,
-};

package/lib/clinical/tools/reportResultsReceivedTool.js

@@ -1,153 +0,0 @@
-const { DEGRADED_NUMERIC_REASON, patientVerbatimHasNumericValues, slugify } = require('../helpers/resultsHelper');
-const { recordUnresolvedRequest } = require('../services/clinicalAirtableService');
-const { storeResultObservations } = require('../../fhir');
-const { logger } = require('../../utils/logger');
-
-const definition = {
-  'name': 'reportResultsReceived',
-  'description': '**Does:** Logs the receipt of patient-shared medical results (labs, imaging, pathology, numeric values, attachments) and records an oncologist-review intent on the turn trace (the team-queue notification is a downstream slice). Emits FHIR `Observation` + `Provenance` resources directly when `observations[]` is passed.\n\n**Required inputs:** `patient_verbatim` (LITERAL copy of the values and words the patient wrote — never interpreted), `result_type` (`lab` | `imaging` | `pathology` | `numeric_values` | `attachment` | `other`); optional `study_name`, `result_date`.\n\n**Required when `patient_verbatim` contains numeric values:** `observations` — flat list of items, NOT FHIR shapes. Each item: `{code: str, value: number|str, unit: str|None (e.g. "g/dL", "mmHg", "°C", "10^9/L"), effective: ISO8601 str|None}`. Without `observations[]` the audit lane stays empty and the system stamps the result `degraded` with reason `observations_should_have_been_passed_text_contains_numbers`.\n\n**Examples:**\n- Patient says *"hemoglobina 8.5 g/dL, neutrofilos 0.7"* → `observations=[{code: "hemoglobin", value: 8.5, unit: "g/dL"}, {code: "neutrophils", value: 0.7, unit: "10^9/L"}]`.\n- Patient says *"me tomaron la presión 140/90 y la temperatura 38.5"* → `observations=[{code: "systolic-blood-pressure", value: 140, unit: "mmHg"}, {code: "diastolic-blood-pressure", value: 90, unit: "mmHg"}, {code: "body-temperature", value: 38.5, unit: "°C"}]`.\n- Patient shares a PDF / image / prose WITHOUT numbers → omit `observations` (workflow notification only).\n\n**When to call:** the patient is SHARING raw data — values, attachments, study names with findings. Trigger phrases: "te mando los resultados", "aquí están mis análisis", "hemoglobina 9.1", "mi TAC salió…", PDF/photo of a study, any clinical number from the patient. Takes precedence over `extractClinicalInfo` when the primary event is "results shared".\n\n**When NOT to call:**\n- Patient is narrating news from the team WITHOUT sharing the data — use `extractClinicalInfo` with the matching `detected_tags` (e.g. `[\'lab_value\']` or `[\'diagnosis\']`).\n- Medical emergency / escalation, including a symptom that persists or worsens — use `reportMedicalEscalation`.\n- Mental-health crisis — use `reportCrisis`.\n- Administrative / operative request — use `reportUnresolvedRequestv2`.\n\n**Hard rule on the subsequent `DeliverPatientMessage`:** NEVER interpret values or findings; NEVER say "está bien / está mal / es normal / está bajo / está alto"; NEVER compare against reference ranges; NEVER repeat the values back to the patient. Confirm receipt only ("recibí tus resultados y quedaron registrados para tu equipo; te avisan en cuanto los revisen", `purpose=\'deliver_escalation\'`).\n\n**Returns:** `result_id` + `result_slug` (`result_type` is returned only when an out-of-enum value was coerced to `other`). With `observations[]`: also `fhir_observation_count` + `observation_ids` (the FHIR bodies live on the audit lane, not on this result), and `observation_rejected_count` when some items were dropped for a missing `code`. On the numeric-miss branch: `degraded=True`, `degraded_reasons` — re-issue with `observations[]`.\n\n**Side effects:** Records the result + oncologist-review intent on the turn trace (the team-queue notification is a downstream slice); writes one FHIR `Observation` per structured observation plus a single linking `Provenance`.',
-  'strict': false,
-  'parameters': {
-    'type': 'object',
-    'properties': {
-      'result_type': {
-        'type': 'string',
-        'enum': [
-          'lab',
-          'imaging',
-          'pathology',
-          'numeric_values',
-          'attachment',
-          'other'
-        ],
-        'description': 'What kind of results the patient shared.'
-      },
-      'study_name': {
-        'type': 'string',
-        'description': 'Study name if identified (e.g., \'BH\', \'QS\', \'TAC de tórax\', \'RM cerebral\', \'PET\', \'biopsia\', \'marcadores tumorales\'). Empty string if not identifiable.'
-      },
-      'patient_verbatim': {
-        'type': 'string',
-        'description': 'Patient\'s own words describing what they sent, verbatim. Include any numeric values they mentioned. DO NOT add interpretation, trends, or grading.'
-      },
-      'result_date': {
-        'type': 'string',
-        'description': 'Date of the study if mentioned (ISO or natural language). Empty string if not stated.'
-      },
-      'observations': {
-        'type': 'array',
-        'description': '**REQUIRED when the patient text contains ANY numeric values** (lab numbers, vital signs, weights, temperatures, scores). Pass one item per numeric value the patient shared — never leave them only in `patient_verbatim`. Each item has a flat shape: `{code: str (canonical term, e.g. \'hemoglobin\'), value: number|str, unit: str|null (e.g. \'g/dL\', \'10^9/L\', \'mmHg\', \'bpm\', \'°C\'), effective: ISO8601 str|null}`. The tool writes one FHIR `Observation` (category=laboratory) per item plus a single `Provenance` linking them to the audit lane, and returns `fhir_observation_count` + `observation_ids`.\n\n**Examples:**\n- Patient says "hemoglobina 8.5 g/dL, neutrofilos 0.7" → `observations: [{code: "hemoglobin", value: 8.5, unit: "g/dL"}, {code: "neutrophils", value: 0.7, unit: "10^9/L"}]`\n- Patient says "presión 140/90, fiebre 38.5" → `observations: [{code: "systolic-blood-pressure", value: 140, unit: "mmHg"}, {code: "diastolic-blood-pressure", value: 90, unit: "mmHg"}, {code: "body-temperature", value: 38.5, unit: "°C"}]`\n- Patient sends a PDF / image / pure narrative (no numbers) → omit `observations`. The tool still runs as a workflow notification; no FHIR Observation is emitted.',
-        'items': {
-          'type': 'object',
-          'properties': {
-            'code': {
-              'type': 'string'
-            },
-            'value': {},
-            'unit': {
-              'type': [
-                'string',
-                'null'
-              ]
-            },
-            'effective': {
-              'type': [
-                'string',
-                'null'
-              ]
-            }
-          },
-          'required': [
-            'code'
-          ]
-        }
-      }
-    },
-    'required': [
-      'result_type',
-      'patient_verbatim'
-    ]
-  }
-};
-
-const RESULT_TYPE_ENUM = definition.parameters.properties.result_type.enum;
-
-async function handler(args = {}, context = {}) {
-  try {
-    const runtime = context?.toolRuntimeContext || null;
-    if (!runtime?.turnId || !runtime?.patientCode) {
-      return JSON.stringify({ success: false, error: 'reportResultsReceived requires an active turn context (turnId, patientCode).', data: {} });
-    }
-    const trace = runtime.trace || null;
-    const str = (v) => (typeof v === 'string' ? v : '');
-
-    const patientVerbatim = str(args?.patient_verbatim).trim();
-    if (!patientVerbatim) {
-      return JSON.stringify({ success: false, error: 'reportResultsReceived requires `patient_verbatim`.', data: {} });
-    }
-
-    const rawType = (str(args?.result_type) || 'other').toLowerCase();
-    const resultType = RESULT_TYPE_ENUM.includes(rawType) ? rawType : 'other';
-    const studyName = str(args?.study_name).trim();
-    const resultDate = str(args?.result_date).trim();
-    const today = new Date().toISOString().slice(0, 10);
-    const dateForSlug = /^\d{4}-\d{2}-\d{2}/.test(resultDate) ? resultDate.slice(0, 10) : today;
-
-    const existing = Array.isArray(trace?.signals?.resultsReceived) ? trace.signals.resultsReceived : [];
-    const resultIndex = existing.length;
-    const resultId = `rr_${runtime.turnId}_${resultIndex}`;
-    const resultSlug = [resultType, studyName ? slugify(studyName, 20) : '', dateForSlug].filter(Boolean).join('-');
-
-    if (trace?.setSignals) {
-      trace.setSignals({
-        resultsReceived: [...existing, {
-          resultId,
-          resultType,
-          studyName,
-          patientVerbatim: patientVerbatim.slice(0, 500),
-          resultDate,
-          oncologistEscalation: { category: 'results_review', urgency: 'soon', linkedResultId: resultId },
-        }],
-      });
-    } else {
-      logger.warn('[reportResultsReceived] no trace on runtime context; results-received signal not recorded', { turnId: runtime.turnId });
-    }
-
-    await recordUnresolvedRequest({
-      code: runtime.patientCode,
-      trace,
-      question: ['Resultados recibidos:', resultType, studyName].filter(Boolean).join(' '),
-      details: patientVerbatim,
-      category: 'results_review',
-      urgency: 'soon',
-    });
-
-    const data = { result_id: resultId, result_slug: resultSlug };
-    if (resultType !== rawType) data.result_type = resultType;
-
-    const observations = Array.isArray(args?.observations) ? args.observations : [];
-    if (observations.length) {
-      const { count, ids } = await storeResultObservations({ patientId: runtime.patientCode, turnId: runtime.turnId, idBase: `${runtime.turnId}_${resultIndex}`, observations });
-      if (count) {
-        data.fhir_observation_count = count;
-        data.observation_ids = ids;
-        if (count < observations.length) data.observation_rejected_count = observations.length - count;
-        return JSON.stringify({ success: true, data });
-      }
-    }
-
-    if (patientVerbatimHasNumericValues(patientVerbatim)) {
-      data.degraded = true;
-      data.degraded_reasons = [DEGRADED_NUMERIC_REASON];
-      data.fhir_observation_count = 0;
-    }
-    return JSON.stringify({ success: true, data });
-  } catch (err) {
-    return JSON.stringify({ success: false, error: err?.message || 'reportResultsReceived failed' });
-  }
-}
-
-module.exports = {
-  definition,
-  handler,
-};