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

package/lib/clinical/tools/deliverPatientMessageTool.js

@@ -1,202 +0,0 @@
-const { requireGatewayProvider } = require('../config/llmConfig');
-const { renderMessage } = require('../services/composerService');
-const { isComposerEnabled, isAgentSelfRenderEnabled } = require('../flags/composerFlags');
-
-const EMPTY_OUTBOUND_FALLBACK = 'Estoy revisando tu mensaje con detalle, te respondo en un momento.';
-
-const definition = {
-  name: 'DeliverPatientMessage',
-  description: '**Does:** Delivers the final, patient-facing message in Spanish — the only tool that produces text the patient sees. Call exactly ONCE as the last action of every CHAT turn.\n\n**Required inputs:** `message_text` (the message itself, in Spanish); `purpose` (the conversational purpose — e.g. `acknowledge`, `clarifying_question`, `deliver_escalation`, `deliver_recommendation`); `reasoning` (one short sentence, never shown to the patient, explaining why this is the right message for this turn).\n\n**When to call:** at the end of every chat turn — once. Pair it with any preceding tool calls; this is what surfaces their outcome to the patient.\n\n**When NOT to call:**\n- More than once per turn — only ONE patient-facing message per turn.\n- Mid-turn before clinical reads / commits complete — the message must reflect the final state of the turn.\n\n**Returns:** synthetic — the tool result carries the delivery envelope (no clinical data).\n\n**Side effects:** records the final patient-facing message on the turn trace; delivery to the patient is handled downstream.',
-  strict: false,
-  parameters: {
-    type: 'object',
-    properties: {
-      intent_payload: {
-        additionalProperties: false,
-        properties: {
-          schema_version: {
-            default: '2.3.0',
-            description: 'Bumped on any breaking schema change.',
-            type: 'string',
-          },
-          intent_type: {
-            enum: [
-              'casual_acknowledge',
-              'greet',
-              'close_loop',
-              'clarifying_probe',
-              'self_care_recommendation',
-              'otc_offer',
-              'follow_up_on_intervention',
-              'education',
-              'preparation_guidance',
-              'emotional_support',
-              'reassurance',
-              'escalation_team',
-              'escalation_emergency',
-              'prognostic_disclosure',
-              'out_of_scope_redirect',
-            ],
-            type: 'string',
-          },
-          urgency_level: {
-            enum: ['stat', 'asap', 'urgent', 'routine'],
-            type: 'string',
-          },
-          alarmism_target: {
-            description: 'Decoupled from urgency_level on purpose. Cauda equina is urgency_level=stat but alarmism_target=measured (calm urgency). Anaphylaxis is urgency_level=stat AND alarmism_target=high.',
-            enum: ['minimal', 'measured', 'high'],
-            type: 'string',
-          },
-          target_symptom: {
-            anyOf: [{ type: 'string' }, { type: 'null' }],
-            default: null,
-            description: 'Short patient-language name of the clinical anchor for this turn (e.g. \'náusea\', \'dolor de cabeza\', \'fiebre\'). Surfaces the symptom the composer is responding to without forcing it to be inferred from must_say / prior_interventions. Null when there is no clinical anchor (e.g. greet, casual_acknowledge, out_of_scope_redirect for an administrative request). PATIENT-LANGUAGE REQUIREMENT applies.',
-          },
-          probe_question: {
-            anyOf: [{ type: 'string' }, { type: 'null' }],
-            default: null,
-            description: 'Literal Spanish question text the composer renders verbatim when intent_type=clarifying_probe. The composer DOES NOT rewrite this — only micro-polish (punctuation, opening connector) is allowed. Provide when intent_type=\'clarifying_probe\'; null otherwise. Should end with \'?\' (or \'¿…?\' Spanish style) and be aligned with the decision_branches discriminator. Example: \'¿Has logrado retener líquidos o también vomitas?\' for branches {if_retains_liquids: ..., if_vomiting_or_no_retention: ...}.',
-          },
-          prior_intervention_ack_phrase: {
-            anyOf: [{ type: 'string' }, { type: 'null' }],
-            default: null,
-            description: 'Polished Spanish opener phrase the composer renders verbatim as the FIRST sentence of the message when prior interventions exist for the target symptom. Replaces the legacy \'must_say[0] is the opener\' convention. Examples: \'El ondansetron de ayer ayudó parcialmente\', \'Lo que tomaste ayer no te alivió\', \'El paño frío sigue ayudando\'. Provide when prior_interventions_for_target_symptom is non-empty AND intent_type is in {follow_up_on_intervention, otc_offer, self_care_recommendation, clarifying_probe}; should be null otherwise (do not use this field for free-form openers outside SR-01 territory). PATIENT-LANGUAGE REQUIREMENT applies.',
-          },
-          must_say: {
-            description: 'Clinical facts the message MUST transmit verbatim. Uniform list — no positional magic. The opener phrase for SR-01 cases lives in ``prior_intervention_ack_phrase``; the probe question for clarifying_probe lives in ``probe_question``. Items here are the remaining facts the composer must weave into the body of the message. PATIENT-LANGUAGE REQUIREMENT — every string must be a polished Spanish phrase the patient can read without medical training. NOT clinical notation, NOT audit-style summaries, NOT acronyms or abbreviations. The composer renders these strings verbatim, so jargon that lands here surfaces to the patient. Translate before writing: "37.9°C en ventana de nadir de AC-T" → "37.9°C siete días después de tu quimio, cuando tus defensas están más bajas"; "neutropenia febril probable" → "posible infección que necesita evaluación urgente"; "sospecha irAE de pneumonitis" → "posible reacción pulmonar a la inmunoterapia". Acronyms like AC-T, FOLFOX, R-CHOP are forbidden unless paired with a brief everyday translation in the same string ("tu quimio AC-T, el esquema con doxorrubicina").',
-            items: { type: 'string' },
-            type: 'array',
-          },
-          must_not_say: {
-            description: 'Things the message MUST NOT say (e.g. \'no diagnosis claim\').',
-            items: { type: 'string' },
-            type: 'array',
-          },
-          prior_interventions_for_target_symptom: {
-            description: 'Any prior intervention delivered for the same target_symptom. If non-empty, the composer must acknowledge the outcome before offering a new or repeated intervention (constitution principle 13).',
-            items: {
-              additionalProperties: false,
-              description: 'One past intervention for the same target_symptom.\n\nThe composer reads this list and (per Constitution principle 13) MUST\nacknowledge the outcome of any prior intervention BEFORE offering a\nnew one or repeating the same. Closes the bug observed in testing\nwhere the agent re-recommended Ondansetron without checking whether\nthe patient had already taken it.',
-              properties: {
-                intervention: {
-                  description: 'Short label of the intervention, e.g. \'ondansetron 8mg\'.',
-                  type: 'string',
-                },
-                delivered_in_turn: {
-                  anyOf: [{ type: 'string' }, { type: 'null' }],
-                  default: null,
-                  description: 'Human-friendly turn label, e.g. \'Turno 2\'.',
-                },
-                patient_outcome: {
-                  description: 'Outcome the patient reported (or \'pending\' / \'unknown\').',
-                  enum: ['pending', 'improved', 'no_relief', 'side_effects', 'worsened', 'unknown'],
-                  type: 'string',
-                },
-              },
-              required: ['intervention', 'patient_outcome'],
-              type: 'object',
-            },
-            type: 'array',
-          },
-          decision_branches: {
-            anyOf: [
-              { additionalProperties: { type: 'string' }, type: 'object' },
-              { type: 'null' },
-            ],
-            default: null,
-            description: 'Provide when intent_type=\'clarifying_probe\'. A mapping of branch labels to the actions the agent would take depending on the patient\'s answer. Branch keys are free-form and SHOULD be descriptive of what they discriminate (\'if_vomiting_frequent\' / \'if_no_vomiting_or_infrequent\') rather than generic labels. Should have at least 2 branches with distinct values — a probe whose branches collapse wastes the patient\'s turn (constitution principle 14).',
-          },
-          distress_signal: {
-            default: 'none',
-            enum: ['none', 'detected', 'high'],
-            type: 'string',
-          },
-          source_skill: {
-            description: 'Skill that emitted this payload (audit).',
-            type: 'string',
-          },
-          reasoning: {
-            description: 'One short sentence: why this intent for this turn.',
-            type: 'string',
-          },
-        },
-        required: ['intent_type', 'urgency_level', 'alarmism_target', 'source_skill', 'reasoning'],
-        type: 'object',
-        description: '[v1 composer mode] Structured intent payload that the Composer renders into Spanish prose. Use this mode when the skill prompt instructs you to. Schema is closed (additionalProperties: false) — only the listed fields are accepted.',
-      },
-      message_text: {
-        type: 'string',
-        description: '[legacy mode] The Spanish, warm message to send to the patient. Use when the skill prompt does not instruct you to emit an intent_payload.',
-      },
-      purpose: {
-        type: 'string',
-        enum: [
-          'greet',
-          'ask_clarifying_question',
-          'deliver_self_care',
-          'deliver_otc',
-          'deliver_emotional_support',
-          'deliver_reassurance',
-          'deliver_escalation',
-          'deliver_education',
-          'deliver_preparation',
-          'out_of_scope_ack',
-          'casual_acknowledge',
-          'close_loop',
-          'offer_followup',
-          'clarify_unclassifiable',
-        ],
-        description: 'The conversational purpose of this message.',
-      },
-      reasoning: {
-        type: 'string',
-        description: 'One short sentence explaining WHY this is the right message for this turn — what you\'re acting on, why now, and (if relevant) why this phrasing. Stays in the audit trace, never shown to the patient.',
-      },
-    },
-    required: ['reasoning', 'message_text', 'purpose'],
-  },
-};
-
-const PURPOSES = definition.parameters.properties.purpose.enum;
-
-function fail(error) {
-  return JSON.stringify({ success: false, error, data: {} });
-}
-
-async function handler(args = {}, context = {}) {
-  const runtime = context?.toolRuntimeContext || null;
-  const trace = runtime?.trace || null;
-  if (!runtime?.turnId || !runtime?.patientCode || !trace?.setOutbound) {
-    return fail('DeliverPatientMessage requires an active turn context (turnId, patientCode, trace).');
-  }
-
-  const rawPurpose = typeof args.purpose === 'string' ? args.purpose.trim() : '';
-  const purpose = PURPOSES.includes(rawPurpose) ? rawPurpose : 'ask_clarifying_question';
-  const messageText = typeof args.message_text === 'string' ? args.message_text : '';
-
-  let outbound = messageText;
-  if (isComposerEnabled() && !isAgentSelfRenderEnabled() && args.intent_payload) {
-    let provider = null;
-    try {
-      provider = requireGatewayProvider();
-    } catch {
-      provider = null;
-    }
-    const rendered = provider
-      ? await renderMessage({ intentPayload: args.intent_payload, provider })
-      : null;
-    if (rendered) outbound = rendered;
-  }
-  if (!(outbound || '').trim()) outbound = EMPTY_OUTBOUND_FALLBACK;
-
-  trace.setSignals({ outboundPurpose: purpose });
-  trace.setOutbound(outbound);
-
-  return JSON.stringify({ success: true, data: { queued: true, purpose } });
-}
-
-module.exports = {
-  definition,
-  handler,
-};

package/lib/clinical/tools/extractClinicalInfoTool.js

@@ -1,167 +0,0 @@
-const { requireGatewayProvider } = require('../config/llmConfig');
-const { getCtcaeCatalog } = require('../stores/CtcaeCatalog');
-const { getSafetyFlagPatterns } = require('../config/divergenceConfig');
-const { extractClinicalMentions, getConversationalTokens } = require('../services/clinicalExtractionService');
-const { detectSafetyFlags } = require('../helpers/safetyFlagsHelper');
-const { projectClinicalFacts, renderClinicalIntakeSummary } = require('../helpers/clinicalFactsHelper');
-const { recordClinicalIntake } = require('../services/clinicalAirtableService');
-const { logger } = require('../../utils/logger');
-
-const DETECTED_TAG_ENUM = [
-  'symptom', 'indication', 'treatment', 'adherence', 'medication', 'appointment',
-  'emotion', 'lab_value', 'diagnosis', 'allergy', 'comorbidity', 'performance_status',
-];
-const MAX_CONVERSATIONAL_TOKENS = 5;
-
-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), `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 sent   only while the symptom has no open case yet (once open,   `grade_scale_omitted_open_case` carries the case_id — use   `lookupCtcaeEntry` if you need the ladder again).\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**Side effects:** System emits a FHIR resource + `Provenance` per fact on the audit lane, except `allergy`/`comorbidity`/`performance_status` (aggregated).",
-  strict: true,
-  parameters: {
-    type: 'object',
-    properties: {
-      raw_message: {
-        type: 'string',
-        description: 'Mensaje VERBATIM del paciente para este turno (el mismo texto que recibiste; no lo parafrasees). El backend lo estructura.',
-      },
-      detected_tags: {
-        type: 'array',
-        items: { type: 'string', enum: DETECTED_TAG_ENUM },
-        description: [
-          'Lista de variables clínicas que el mensaje MENCIONA (explícita o implícitamente). Incluye TODAS las que apliquen en UNA sola llamada — el backend procesa múltiples categorías juntas. Guía rápida:',
-          '- symptom: síntoma nuevo, cambio, recurrente, o resuelto.',
-          '- indication: indicación del equipo (medicación, dieta, actividad, conducta).',
-          '- treatment: tratamiento oncológico (oral / IV / radio / cirugía) con cambio de estado (planeado/iniciado/pausado/completado).',
-          '- adherence: toma/omisión/ajuste de una indicación o medicación.',
-          '- medication: medicación no-oncológica o adyuvante. Etiqueta aunque solo la vaya a empezar, la tome ahora, o la haya tomado antes (el backend distingue planeada/actual/pasada y solo la actual entra a la lista de medicación vigente).',
-          '- appointment: cita o estudio confirmado/atendido/cancelado.',
-          '- emotion: estado emocional expresado (ansiedad, tristeza, miedo, etc.).',
-          '- lab_value: valor NUMÉRICO de laboratorio que el paciente comparte en el texto (ej: hemoglobina 9.2). Para solo mencionar que recibió resultados sin valores, usa reportResultsReceived.',
-          '- diagnosis: diagnóstico nuevo, confirmado, descartado, en progresión o remisión.',
-          '- allergy: alergia o reacción adversa a una sustancia.',
-          '- comorbidity: condición crónica NO oncológica (diabetes, hipertensión, etc.).',
-          '- performance_status: valor ECOG o Karnofsky reportado.',
-        ].join('\n'),
-      },
-      intake_source: {
-        type: 'string',
-        enum: ['self', 'caregiver', 'team_relay'],
-        description: "Quién reporta la información. 'self' = paciente directamente; 'caregiver' = familiar; 'team_relay' = el paciente transmite algo que le dijo un clínico (su equipo, un médico, especialista). Importa para la autoridad del dato: un juicio clínico (diagnosis, ECOG) transmitido como team_relay se registra como 'según médico'; si el paciente lo afirma por su cuenta queda 'sin confirmar'.",
-      },
-      response_format: {
-        anyOf: [
-          { type: 'string', enum: ['router', 'full'], description: "'router' (default) trims each clinical fact to the router's decision-critical fields — `id`, `interpretation` (negated/hedged/experiencer/temporal), `confidence`, `grade_scale` (the CTCAE grade RUBRIC), `value.observed` (the structured grading EVIDENCE, non-null entries only), `episode_id`, and `trend`. Use 'full' only when you need the complete verbose per-fact record in this turn." },
-          { type: 'null' },
-        ],
-      },
-    },
-    required: ['raw_message', 'detected_tags', 'intake_source', 'response_format'],
-    additionalProperties: false,
-  },
-};
-
-const SUPPORTED_TAGS = new Set(DETECTED_TAG_ENUM);
-
-async function handler(args, context = {}) {
-  const runtime = context?.toolRuntimeContext || null;
-  const trace = runtime?.trace || null;
-
-  const rawMessage = (args?.raw_message || '').trim();
-  const detectedTagsRaw = Array.isArray(args?.detected_tags) ? args.detected_tags : [];
-  const intakeSource = args?.intake_source || 'self';
-  const requestedFormat = typeof args?.response_format === 'string' ? args.response_format.toLowerCase() : 'router';
-  const responseFormat = ['router', 'full'].includes(requestedFormat) ? requestedFormat : 'router';
-
-  if (!rawMessage) {
-    if (trace?.setSignals) trace.setSignals({ clinicalMentions: [], safetyFlags: [] });
-    return JSON.stringify({ success: false, error: 'extractClinicalInfo requires `raw_message`.' });
-  }
-
-  const detectedTags = detectedTagsRaw
-    .filter((t) => typeof t === 'string' && SUPPORTED_TAGS.has(t.toLowerCase()))
-    .map((t) => t.toLowerCase());
-
-  if (!detectedTags.length) {
-    const supported = [...SUPPORTED_TAGS].sort();
-    const safetyFlags = await scanSafetyFlags(rawMessage);
-    if (trace?.setSignals) trace.setSignals({ clinicalMentions: [], safetyFlags });
-
-    let conversationalTokens = [];
-    try {
-      conversationalTokens = await getConversationalTokens();
-    } catch (err) {
-      logger.warn('[extractClinicalInfo] conversational token load failed; treating inbound as non-conversational', { turnId: runtime?.turnId, error: err?.message });
-    }
-    if (!detectedTagsRaw.length && isPurelyConversational(rawMessage, conversationalTokens)) {
-      return JSON.stringify({
-        success: true,
-        data: { degraded: false, conversational_inbound: true, clinical_facts: [] },
-      });
-    }
-    const error = !detectedTagsRaw.length
-      ? `extractClinicalInfo was called with an empty \`detected_tags\` list and the inbound is not purely conversational. Two recovery paths: (a) if the inbound has no clinical content, skip intake and respond with DeliverPatientMessage(intent_type=casual_acknowledge); (b) if you missed clinical content, re-call with at least one of: ${supported.join(', ')}.`
-      : `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 });
-  }
-
-  if (!runtime?.turnId || !runtime?.patientCode) {
-    return JSON.stringify({ success: false, error: 'extractClinicalInfo requires an active turn context (turnId, patientCode).' });
-  }
-
-  const { clinicalMentions, safetyFlags } = await extractClinicalMentions({
-    text: rawMessage,
-    detectedTags,
-    intakeSource,
-    responseFormat,
-    turnId: runtime.turnId,
-    code: runtime.patientCode,
-    provider: requireGatewayProvider(),
-  });
-
-  if (trace?.setSignals) {
-    trace.setSignals({ clinicalMentions, safetyFlags });
-  } else {
-    logger.warn('[extractClinicalInfo] no trace on runtime context; signals not recorded', { turnId: runtime?.turnId });
-  }
-
-  const intakeSummary = renderClinicalIntakeSummary({ clinicalMentions, safetyFlags });
-  if (intakeSummary) {
-    await recordClinicalIntake({
-      code: runtime.patientCode,
-      trace,
-      messageRaw: intakeSummary,
-      source: intakeSource,
-    });
-  }
-
-  const terms = [...new Set(clinicalMentions.map((m) => m?.fact?.ctcaeTerm).filter(Boolean))];
-  const catalog = getCtcaeCatalog();
-  const gradeScales = {};
-  for (const term of terms) gradeScales[term] = catalog.getGradeScale(term);
-  const envelope = projectClinicalFacts({ clinicalMentions, safetyFlags, gradeScales });
-  return JSON.stringify(envelope);
-}
-
-async function scanSafetyFlags(text) {
-  try {
-    return detectSafetyFlags(text, await getSafetyFlagPatterns());
-  } catch (err) {
-    logger.warn('[extractClinicalInfo] deterministic safety scan failed', { error: err?.message });
-    return [];
-  }
-}
-
-function isPurelyConversational(text, tokens) {
-  if (!text) return true;
-  const cleaned = text.toLowerCase().replace(/[^\p{L}\p{N}\s]/gu, ' ');
-  const found = cleaned.split(/\s+/).filter(Boolean);
-  if (!found.length) return true;
-  if (found.length > MAX_CONVERSATIONAL_TOKENS) return false;
-  const allowed = tokens instanceof Set ? tokens : new Set(tokens || []);
-  return found.every((tok) => allowed.has(tok));
-}
-
-module.exports = {
-  definition,
-  handler,
-};

package/lib/clinical/tools/getActiveSymptomLandscapeTool.js

@@ -1,141 +0,0 @@
-const { readSymptomCases, readClusters } = require('../../fhir');
-
-const definition = {
-  name: 'getActiveSymptomLandscape',
-  description: '**Does:** Returns a snapshot of ALL the patient\'s open symptom cases (`characterizing` | `monitoring`), each fusing the Condition with its head impression, plus active clusters. Read-only.\n\n**Required inputs:** none. Optional `minimum_priority` (`low` (default) returns everything; `medium` returns high+medium; `high` returns only high).\n\n**When to call:** before routing, to see which cases are open, avoid abandoning a case the patient did not mention this turn, or prioritise across concurrent concerns.\n\n**When NOT to call:** for the current turn\'s observations (use `extractClinicalInfo`) or closed-case history.\n\n**Returns:** `active_cases[]` (each: `case_id`, `ctcae_term`, `status`, `opened_at`, `current_episode_id`, `grade_estimate`, `decision_posture`, `trajectory`, derived `priority` + `attention_flags`) sorted priority desc then most-recently-opened; `active_clusters[]` (each: `cluster_id`, `label`, `hypothesis_type`, `status`, `confidence`, `clinical_significance`, `member_case_ids`, `relationship_model`).',
-  strict: false,
-  parameters: {
-    type: 'object',
-    properties: {
-      minimum_priority: {
-        type: 'string',
-        enum: ['low', 'medium', 'high'],
-        description: 'Filter by priority floor. \'low\' (default) returns everything; \'medium\' returns high+medium; \'high\' returns only high.',
-      },
-    },
-    required: [],
-  },
-};
-
-const PRIORITY_LEVEL = { low: 0, medium: 1, high: 2 };
-const OPEN_STATUSES = ['characterizing', 'monitoring'];
-
-function priorityAndFlags(managedSymptom, clusterMemberships) {
-  const flags = [];
-  const grade = managedSymptom.latestAssessment.grade;
-  const topGrade = Array.isArray(grade.possibleRange) ? grade.possibleRange[1] : null;
-  if (topGrade !== null && topGrade >= 3) flags.push('high_grade_possible');
-
-  const status = managedSymptom.condition.clinicalStatus;
-  if (status === 'monitoring') flags.push('no_active_episode');
-  if (managedSymptom.condition.evidenceEpisodeIds.length > 1) flags.push('multi_episode');
-  if (managedSymptom.latestAssessment.trajectory === 'worsening') flags.push('trajectory_worsening');
-  if (clusterMemberships.length) flags.push('in_cluster');
-
-  let priority;
-  if (topGrade !== null && topGrade >= 3) priority = 'high';
-  else if (status === 'characterizing' && grade.confidence === 'low') priority = 'medium';
-  else priority = 'low';
-  return { priority, flags };
-}
-
-function projectCase(managedSymptom, priority, flags) {
-  const { condition, latestAssessment } = managedSymptom;
-  const out = {
-    case_id: condition.conditionId,
-    ctcae_term: condition.ctcaeTerm,
-    status: condition.clinicalStatus,
-    opened_at: condition.onsetAt || null,
-    current_episode_id: condition.currentEpisodeId,
-    grade_estimate: {
-      best_estimate: latestAssessment.grade.bestEstimate,
-      confidence: latestAssessment.grade.confidence,
-      possible_range: latestAssessment.grade.possibleRange,
-    },
-    decision_posture: latestAssessment.decisionPosture,
-    trajectory: latestAssessment.trajectory,
-  };
-  if (latestAssessment.problemRepresentation) out.problem_representation = latestAssessment.problemRepresentation;
-  out.priority = priority;
-  out.attention_flags = flags;
-  return out;
-}
-
-function openedEpoch(openedAt) {
-  const parsed = openedAt ? Date.parse(openedAt) : NaN;
-  return Number.isNaN(parsed) ? 0 : parsed;
-}
-
-async function assembleLandscape(patientId, minimumPriorityArg) {
-  const minimumPriority = (typeof minimumPriorityArg === 'string' ? minimumPriorityArg : 'low').toLowerCase();
-  if (!(minimumPriority in PRIORITY_LEVEL)) {
-    throw new Error(`unknown minimum_priority: '${minimumPriority}'. Must be low | medium | high.`);
-  }
-  const minLevel = PRIORITY_LEVEL[minimumPriority];
-
-  const cases = (await readSymptomCases({ patientId }))
-    .filter((managedSymptom) => OPEN_STATUSES.includes(managedSymptom.condition.clinicalStatus));
-  let clusters = [];
-  let clustersDegraded = false;
-  try {
-    clusters = await readClusters({ patientId, status: 'active' });
-  } catch {
-    clustersDegraded = true;
-  }
-
-  const caseToClusters = new Map();
-  for (const cluster of clusters) {
-    for (const memberCaseId of cluster.memberCaseIds) {
-      if (!caseToClusters.has(memberCaseId)) caseToClusters.set(memberCaseId, []);
-      caseToClusters.get(memberCaseId).push(cluster.clusterId);
-    }
-  }
-
-  const projected = [];
-  for (const managedSymptom of cases) {
-    const memberships = caseToClusters.get(managedSymptom.condition.conditionId) || [];
-    const { priority, flags } = priorityAndFlags(managedSymptom, memberships);
-    if (PRIORITY_LEVEL[priority] < minLevel) continue;
-    projected.push(projectCase(managedSymptom, priority, flags));
-  }
-  projected.sort((a, b) => (PRIORITY_LEVEL[b.priority] - PRIORITY_LEVEL[a.priority])
-    || (openedEpoch(b.opened_at) - openedEpoch(a.opened_at)));
-
-  const result = {
-    active_cases: projected,
-    active_clusters: clusters.map((cluster) => ({
-      cluster_id: cluster.clusterId,
-      label: cluster.label,
-      hypothesis_type: cluster.hypothesisType,
-      status: cluster.status,
-      confidence: cluster.confidence,
-      clinical_significance: cluster.clinicalSignificance,
-      member_case_ids: [...cluster.memberCaseIds],
-      relationship_model: cluster.relationshipModel,
-    })),
-  };
-  if (clustersDegraded) {
-    result.clusters_degraded = true;
-    result.degraded_reasons = ['cluster_read_failed'];
-  }
-  return result;
-}
-
-async function handler(args = {}, context = {}) {
-  try {
-    const runtime = context?.toolRuntimeContext || null;
-    if (!runtime?.turnId || !runtime?.patientCode) {
-      return JSON.stringify({ success: false, error: 'getActiveSymptomLandscape requires an active turn context (turnId, patientCode).', data: {} });
-    }
-    const data = await assembleLandscape(runtime.patientCode, args?.minimum_priority);
-    return JSON.stringify({ success: true, data });
-  } catch (err) {
-    return JSON.stringify({ success: false, error: err?.message || 'getActiveSymptomLandscape failed', data: {} });
-  }
-}
-
-module.exports = {
-  definition,
-  handler,
-  assembleLandscape,
-};