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

package/lib/clinical/tools/getPatientHistoryTool.js

@@ -1,235 +0,0 @@
-const { readSymptomCases, readInterventions, patientSnapshot } = require('../../fhir');
-const { fhirId } = require('../../fhir/helpers/fhirHelper');
-const { identifierValue } = require('../../fhir/helpers/fhirReadHelper');
-const { INTERVENTION_SLUG } = require('../../fhir/constants/projectionSlugs');
-
-const SUPPORTED_SCOPES = new Set([
-  'closed_cases_30d',
-  'closed_cases_90d',
-  'closed_cases_all',
-  'interventions_with_effectiveness',
-  'recurrence_patterns',
-  'recent_medications',
-  'appointment_mentions',
-  'patient_reported_procedures',
-]);
-
-const DEFAULT_SCOPE = ['closed_cases_30d', 'recurrence_patterns'];
-const TIMEFRAME_DAYS = { last_7_days: 7, last_30_days: 30, last_90_days: 90 };
-const CLOSED_STATUSES = ['resolved', 'inactive', 'closed'];
-const POSITION_E_DEFAULT_WINDOW_DAYS = 30;
-const POSITION_E_SCOPES = ['recent_medications', 'appointment_mentions', 'patient_reported_procedures'];
-
-const definition = {
-  name: 'getPatientHistory',
-  description: '**Does:** Longitudinal lookback across the patient\'s closed symptom cases, delivered interventions, recurrence patterns, and patient-reported medications/appointment-mentions/procedures. Read-only.\n\n**Required inputs:** none. Optional `scope` (list; default `["closed_cases_30d","recurrence_patterns"]`) selects sections; optional `filter` (`ctcae_term`, `timeframe` (`last_7_days`|`last_30_days`|`last_90_days`), `case_id`).\n\n**When to call:** before routing, to reason about prior episodes, what was tried and whether it helped, or repeated concerns.\n\n**Returns:** only the requested sections — `closed_cases[]`, `interventions_with_effectiveness[]`, `recurrence_patterns[]`, `recent_medications[]`, `appointment_mentions[]`, `patient_reported_procedures[]`. `appointment_mentions` are patient-reported appointment references (neither a scheduled time nor a mention time is captured upstream), so each row has `last_mentioned_at: null` and the list is returned unwindowed in store-recency order — not a future schedule and not timeframe-bounded. `recurrence_patterns` is computed over all closed cases regardless of `timeframe`/`scope` window. `filter.case_id` on `interventions_with_effectiveness` is matched after fhirId normalization (interim, until the intervention lane carries the raw case id).',
-  strict: false,
-  parameters: {
-    type: 'object',
-    properties: {
-      scope: {
-        type: 'array',
-        items: { type: 'string', enum: [...SUPPORTED_SCOPES] },
-        description: 'Sections to return. Omit for the default (closed_cases_30d + recurrence_patterns).',
-      },
-      filter: {
-        type: 'object',
-        properties: {
-          ctcae_term: { type: 'string' },
-          timeframe: { type: 'string', enum: Object.keys(TIMEFRAME_DAYS) },
-          case_id: { type: 'string' },
-        },
-      },
-    },
-    required: [],
-  },
-};
-
-function projectClosedCase(managedSymptom) {
-  const { condition, latestAssessment } = managedSymptom;
-  const grade = latestAssessment.grade;
-  return {
-    case_id: condition.conditionId,
-    ctcae_term: condition.ctcaeTerm,
-    opened_at: condition.onsetAt || null,
-    closed_at: condition.abatementAt || null,
-    close_reason: condition.closeReason,
-    final_grade: {
-      best_estimate: grade.bestEstimate,
-      confidence: grade.confidence,
-      possible_range: grade.possibleRange,
-    },
-    trajectory: latestAssessment.trajectory,
-  };
-}
-
-function projectInterventionHistory(intervention) {
-  return {
-    intervention_id: intervention.interventionId,
-    case_id: intervention.caseId,
-    intervention_label: intervention.interventionLabel,
-    intervention_kind: intervention.kind,
-    rationale: intervention.rationale,
-    delivered_at: intervention.deliveredAt || null,
-    outcome: intervention.outcome,
-    outcome_notes: intervention.outcomeNotes,
-  };
-}
-
-function computeRecurrencePatterns(closedCases) {
-  const byTerm = new Map();
-  for (const closedCase of closedCases) {
-    const term = (closedCase.ctcae_term || '').trim().toLowerCase();
-    if (!term) continue;
-    if (!byTerm.has(term)) byTerm.set(term, []);
-    byTerm.get(term).push(closedCase);
-  }
-  const out = [];
-  for (const [term, cases] of byTerm) {
-    if (cases.length < 2) continue;
-    out.push({
-      ctcae_term: term,
-      occurrence_count: cases.length,
-      most_recent_case_id: cases[0].case_id,
-      first_case_id: cases[cases.length - 1].case_id,
-    });
-  }
-  out.sort((a, b) => b.occurrence_count - a.occurrence_count);
-  return out;
-}
-
-function reportedEpoch(iso) {
-  const parsed = iso ? Date.parse(iso) : NaN;
-  return Number.isNaN(parsed) ? 0 : parsed;
-}
-
-const NEGATED_STATUSES = new Set(['cancelled', 'not-done', 'entered-in-error']);
-
-function projectSnapshotFacts(resources, timeField, ascending = false) {
-  return (resources || [])
-    .map((resource) => ({
-      resource_id: resource.id || null,
-      code: codeText(resource),
-      last_mentioned_at: resource[timeField] || null,
-      negated: NEGATED_STATUSES.has(resource.status),
-    }))
-    .sort((a, b) => (ascending
-      ? reportedEpoch(a.last_mentioned_at) - reportedEpoch(b.last_mentioned_at)
-      : reportedEpoch(b.last_mentioned_at) - reportedEpoch(a.last_mentioned_at)));
-}
-
-function codeText(resource) {
-  if (typeof resource.description === 'string') return resource.description;
-  const code = resource.code || (resource.medication && resource.medication.concept);
-  if (code && typeof code.text === 'string') return code.text;
-  const coding = code && code.coding && code.coding[0];
-  return (coding && (coding.display || coding.code)) || null;
-}
-
-async function assembleHistory(patientId, args = {}) {
-  const scopeRaw = args?.scope;
-  let scope;
-  if (scopeRaw == null) {
-    scope = [...DEFAULT_SCOPE];
-  } else if (Array.isArray(scopeRaw) && scopeRaw.length) {
-    scope = scopeRaw.map((entry) => (typeof entry === 'string' ? entry.trim() : entry));
-    if (scope.some((entry) => typeof entry !== 'string' || !entry.length)) {
-      throw new Error('scope must be a non-empty list of strings (omit for default)');
-    }
-  } else {
-    throw new Error('scope must be a non-empty list of strings (omit for default)');
-  }
-  const unknown = scope.filter((scopeName) => !SUPPORTED_SCOPES.has(scopeName));
-  if (unknown.length) {
-    throw new Error(`unknown scope(s): ${JSON.stringify(unknown)}. Valid: ${JSON.stringify([...SUPPORTED_SCOPES].sort())}`);
-  }
-
-  const filter = args?.filter || {};
-  if (typeof filter !== 'object' || Array.isArray(filter)) throw new Error('filter must be an object or omitted');
-  const ctcaeFilter = (filter.ctcae_term || '').trim().toLowerCase() || null;
-  const caseIdFilter = (filter.case_id || '').trim() || null;
-  const timeframe = filter.timeframe;
-  if (timeframe != null && !(timeframe in TIMEFRAME_DAYS)) {
-    throw new Error(`timeframe must be one of ${JSON.stringify(Object.keys(TIMEFRAME_DAYS))} or omitted`);
-  }
-
-  const now = Date.now();
-  let since = null;
-  if (timeframe != null) since = now - TIMEFRAME_DAYS[timeframe] * 86400000;
-  else if (scope.includes('closed_cases_30d')) since = now - 30 * 86400000;
-  else if (scope.includes('closed_cases_90d')) since = now - 90 * 86400000;
-
-  const needsWindowedClosed = scope.some((scopeName) => ['closed_cases_30d', 'closed_cases_90d', 'closed_cases_all'].includes(scopeName));
-  const needsRecurrence = scope.includes('recurrence_patterns');
-  let allClosed = [];
-  if (needsWindowedClosed || needsRecurrence) {
-    allClosed = (await readSymptomCases({ patientId, ctcaeTerm: ctcaeFilter }))
-      .filter((managedSymptom) => CLOSED_STATUSES.includes(managedSymptom.condition.clinicalStatus))
-      .sort((a, b) => reportedEpoch(b.condition.abatementAt) - reportedEpoch(a.condition.abatementAt));
-  }
-  const windowedClosed = allClosed.filter((managedSymptom) => {
-    if (since != null && (!managedSymptom.condition.abatementAt || reportedEpoch(managedSymptom.condition.abatementAt) < since)) return false;
-    if (caseIdFilter && managedSymptom.condition.conditionId !== caseIdFilter) return false;
-    return true;
-  });
-
-  const result = {};
-
-  if (needsWindowedClosed) {
-    result.closed_cases = windowedClosed.map(projectClosedCase);
-  }
-
-  if (scope.includes('interventions_with_effectiveness')) {
-    const interventions = await readInterventions({ patientId });
-    const caseIdMatch = caseIdFilter ? fhirId(caseIdFilter) : null;
-    result.interventions_with_effectiveness = interventions
-      .filter((intervention) => (!caseIdMatch || fhirId(intervention.caseId) === caseIdMatch)
-        && (since == null || reportedEpoch(intervention.deliveredAt) >= since))
-      .map(projectInterventionHistory);
-  }
-
-  if (needsRecurrence) {
-    result.recurrence_patterns = computeRecurrencePatterns(allClosed.map(projectClosedCase));
-  }
-
-  if (scope.some((scopeName) => POSITION_E_SCOPES.includes(scopeName))) {
-    const windowSince = since != null ? since : now - POSITION_E_DEFAULT_WINDOW_DAYS * 86400000;
-    const snapshot = await patientSnapshot(patientId, { resourceTypes: ['MedicationStatement', 'Appointment', 'Procedure'] });
-    if (scope.includes('recent_medications')) {
-      result.recent_medications = projectSnapshotFacts(snapshot.MedicationStatement, 'effectiveDateTime')
-        .filter((fact) => reportedEpoch(fact.last_mentioned_at) >= windowSince);
-    }
-    if (scope.includes('appointment_mentions')) {
-      result.appointment_mentions = projectSnapshotFacts(snapshot.Appointment, 'occurrenceDateTime');
-    }
-    if (scope.includes('patient_reported_procedures')) {
-      const mentionProcedures = (snapshot.Procedure || [])
-        .filter((resource) => !identifierValue(resource, INTERVENTION_SLUG));
-      result.patient_reported_procedures = projectSnapshotFacts(mentionProcedures, 'occurrenceDateTime')
-        .filter((fact) => reportedEpoch(fact.last_mentioned_at) >= windowSince);
-    }
-  }
-
-  return result;
-}
-
-async function handler(args = {}, context = {}) {
-  try {
-    const runtime = context?.toolRuntimeContext || null;
-    if (!runtime?.turnId || !runtime?.patientCode) {
-      return JSON.stringify({ success: false, error: 'getPatientHistory requires an active turn context (turnId, patientCode).', data: {} });
-    }
-    const data = await assembleHistory(runtime.patientCode, args);
-    return JSON.stringify({ success: true, data });
-  } catch (err) {
-    return JSON.stringify({ success: false, error: err?.message || 'getPatientHistory failed', data: {} });
-  }
-}
-
-module.exports = {
-  definition,
-  handler,
-  assembleHistory,
-  SUPPORTED_SCOPES,
-  TIMEFRAME_DAYS,
-};

package/lib/clinical/tools/getPatientRiskProfileTool.js

@@ -1,71 +0,0 @@
-const { readPatientRisk } = require('../../fhir');
-
-const definition = {
-  name: 'getPatientRiskProfile',
-  description: '**Does:** Returns the patient\'s persistent risk profile — predicted adverse events, disease risks, and comorbidity amplifiers derived from their regimen. Read-only.\n\n**Required inputs:** none.\n\n**When to call:** before routing, to anticipate which adverse events or complications the current regimen makes plausible.\n\n**Returns:** `status` (`final` when a profile exists, `not_generated` otherwise) and `profile` (`assessment_id`, `source_regimen`, `source_diagnosis`, `source_phase`, `predicted_aes[]`, `disease_risks[]`, `comorbidity_amplifiers[]`, `assessed_at`, `assessed_by_model`) — `null` when not yet generated.',
-  strict: false,
-  parameters: {
-    type: 'object',
-    properties: {},
-    required: [],
-  },
-};
-
-function projectRisk(assessment) {
-  return {
-    assessment_id: assessment.assessmentId,
-    source_regimen: assessment.sourceRegimen,
-    source_diagnosis: assessment.sourceDiagnosis,
-    source_phase: assessment.sourcePhase,
-    predicted_aes: assessment.predictedAes.map((predictedAe) => ({
-      ae_name: predictedAe.aeName,
-      severity_if_confirmed: predictedAe.severityIfConfirmed,
-      minimum_symptom_set: predictedAe.minimumSymptomSet,
-      why: predictedAe.why,
-    })),
-    disease_risks: assessment.diseaseRisks.map((diseaseRisk) => ({
-      body_site: diseaseRisk.bodySite,
-      complications: diseaseRisk.complications,
-      warning_symptoms: diseaseRisk.warningSymptoms,
-      amplifier_comorbidities: diseaseRisk.amplifierComorbidities,
-    })),
-    comorbidity_amplifiers: assessment.comorbidityAmplifiers.map((amplifier) => ({
-      comorbidity: amplifier.comorbidity,
-      interaction: amplifier.interaction,
-      clinical_note: amplifier.clinicalNote,
-    })),
-    assessed_at: assessment.assessedAt,
-    assessed_by_model: assessment.assessedByModel,
-  };
-}
-
-async function assembleRiskProfile(patientId) {
-  const assessment = await readPatientRisk({ patientId });
-  if (!assessment) {
-    return {
-      status: 'not_generated',
-      profile: null,
-      hint: 'No risk assessment exists yet for this patient; the runtime warms it on a background thread and it should be available on a subsequent turn.',
-    };
-  }
-  return { status: assessment.status, profile: projectRisk(assessment) };
-}
-
-async function handler(_args = {}, context = {}) {
-  try {
-    const runtime = context?.toolRuntimeContext || null;
-    if (!runtime?.turnId || !runtime?.patientCode) {
-      return JSON.stringify({ success: false, error: 'getPatientRiskProfile requires an active turn context (turnId, patientCode).', data: {} });
-    }
-    const data = await assembleRiskProfile(runtime.patientCode);
-    return JSON.stringify({ success: true, data });
-  } catch (err) {
-    return JSON.stringify({ success: false, error: err?.message || 'getPatientRiskProfile failed', data: {} });
-  }
-}
-
-module.exports = {
-  definition,
-  handler,
-  assembleRiskProfile,
-};

package/lib/clinical/tools/getRouterContextBundleTool.js

@@ -1,93 +0,0 @@
-const { assembleLandscape } = require('./getActiveSymptomLandscapeTool');
-const { assembleHistory, SUPPORTED_SCOPES, TIMEFRAME_DAYS } = require('./getPatientHistoryTool');
-const { assembleRiskProfile } = require('./getPatientRiskProfileTool');
-
-const ALLOWED_SECTIONS = ['landscape', 'history', 'risk'];
-
-const definition = {
-  name: 'getRouterContextBundle',
-  description: '**Does:** Batched router-context fetch — returns any subset of `landscape`, `history`, and `risk` in a single call. Read-only.\n\n**Required inputs:** none. Optional `include` (list; default all three), `landscape_min_priority`, `history_scope`, `history_filter`.\n\n**When to call:** at the start of routing, to load the patient context in one round-trip instead of three separate reads.\n\n**Returns:** `patient_id`, `sections_requested[]`, `sections_returned[]` (only sections that succeeded), and the requested `landscape` / `history` / `risk` sections. A section that errors is omitted and its error reported under `_diagnostics`.',
-  strict: false,
-  parameters: {
-    type: 'object',
-    properties: {
-      include: {
-        type: 'array',
-        items: { type: 'string', enum: ALLOWED_SECTIONS },
-        description: 'Sections to fetch. Omit for all three.',
-      },
-      landscape_min_priority: { type: 'string', enum: ['low', 'medium', 'high'] },
-      history_scope: { type: 'array', items: { type: 'string', enum: [...SUPPORTED_SCOPES] } },
-      history_filter: {
-        type: 'object',
-        properties: {
-          ctcae_term: { type: 'string' },
-          timeframe: { type: 'string', enum: Object.keys(TIMEFRAME_DAYS) },
-          case_id: { type: 'string' },
-        },
-      },
-    },
-    required: [],
-  },
-};
-
-async function handler(args = {}, context = {}) {
-  try {
-    const runtime = context?.toolRuntimeContext || null;
-    if (!runtime?.turnId || !runtime?.patientCode) {
-      return JSON.stringify({ success: false, error: 'getRouterContextBundle requires an active turn context (turnId, patientCode).', data: {} });
-    }
-
-    let include;
-    if ('include' in args) {
-      include = args.include;
-      if (!Array.isArray(include) || !include.length) {
-        return JSON.stringify({ success: false, error: `include must be a non-empty list of ${JSON.stringify(ALLOWED_SECTIONS)}.`, data: {} });
-      }
-    } else {
-      include = [...ALLOWED_SECTIONS];
-    }
-    const unknown = include.filter((section) => !ALLOWED_SECTIONS.includes(section));
-    if (unknown.length) {
-      return JSON.stringify({ success: false, error: `unknown include section(s): ${JSON.stringify(unknown)}. Allowed: ['landscape','history','risk'].`, data: {} });
-    }
-
-    const sections = [...new Set(include)];
-
-    const patientId = runtime.patientCode;
-    const historyArgs = {};
-    if (args.history_scope != null) historyArgs.scope = args.history_scope;
-    if (args.history_filter != null) historyArgs.filter = args.history_filter;
-
-    const readers = {
-      landscape: () => assembleLandscape(patientId, args.landscape_min_priority || 'low'),
-      history: () => assembleHistory(patientId, historyArgs),
-      risk: () => assembleRiskProfile(patientId),
-    };
-
-    const outcomes = await Promise.allSettled(sections.map((section) => readers[section]()));
-
-    const bundle = { patient_id: patientId, sections_requested: sections, sections_returned: [] };
-    const diagnostics = {};
-
-    sections.forEach((section, index) => {
-      const outcome = outcomes[index];
-      if (outcome.status === 'fulfilled') {
-        bundle[section] = outcome.value;
-        bundle.sections_returned.push(section);
-      } else {
-        diagnostics[`${section}_error`] = outcome.reason?.message || `${section} failed`;
-      }
-    });
-
-    if (Object.keys(diagnostics).length) bundle._diagnostics = diagnostics;
-    return JSON.stringify({ success: true, data: bundle });
-  } catch (err) {
-    return JSON.stringify({ success: false, error: err?.message || 'getRouterContextBundle failed', data: {} });
-  }
-}
-
-module.exports = {
-  definition,
-  handler,
-};

package/lib/clinical/tools/lookupCtcaeEntryTool.js

@@ -1,35 +0,0 @@
-const { getCtcaeCatalog } = require('../stores/CtcaeCatalog');
-
-const definition = {
-  name: 'lookupCtcaeEntry',
-  description: '**Does:** Looks up the CTCAE entry for a canonical symptom term (e.g. `nausea`, `diarrhea`, `fatigue`). Returns grade-by-grade severity definitions and validated PRO-CTCAE patient-language anchors (when present).\n\n**Required inputs:** `term` (canonical CTCAE symptom term in English snake_case, e.g. `nausea`, `diarrhea`; use `other` only when no catalog term fits).\n\n**When to call:** when the curated grade rubric already on intake (`extractClinicalInfo.clinical_facts[i].grade_scale`) is missing or insufficient — PRO-CTCAE patient-language disambiguation, or a boundary case needing the validated PRO-CTCAE anchors. Read-only; parallelisable with other router-side reads.\n\n**When NOT to call:**\n- When `grade_scale` on the clinical fact is already sufficient — grading from that avoids a wasted lookup.\n- Non-symptom turns (pure educational questions, emotional-only, out-of-scope admin, casual chat) — no concrete symptom to grade.\n\n**Returns:** `entry` (with `found: true`) — the CTCAE record carrying `grades` (grade-by-grade severity definitions; may be `null` for a curated term without a defined ladder) and `patient_phrases_validated` (validated patient-language anchors, when present). Unknown term → `{found: false, nearest_terms[]}` — pick the right key and re-issue. The grading workflow (Grade 0–4 mapping, ≥ 3 → escalate via `reportMedicalEscalation`, etc.) lives in the `clinical_routing` `SKILL.md` — read the returned entry against those rules.\n\n**Side effects:** none — read-only catalog lookup.',
-  strict: true,
-  parameters: {
-    type: 'object',
-    properties: {
-      term: {
-        type: 'string',
-        description: 'Canonical CTCAE term to look up severity grading for.',
-      },
-    },
-    required: ['term'],
-    additionalProperties: false,
-  },
-};
-
-async function handler(args) {
-  const term = args?.term;
-  if (typeof term !== 'string' || !term.trim()) {
-    return JSON.stringify({ success: false, error: 'lookupCtcaeEntry requires `term`.' });
-  }
-  try {
-    return JSON.stringify({ success: true, data: getCtcaeCatalog().lookupEntry(term) });
-  } catch (err) {
-    return JSON.stringify({ success: false, error: err?.message || 'lookupCtcaeEntry failed' });
-  }
-}
-
-module.exports = {
-  definition,
-  handler,
-};

package/lib/clinical/tools/openClusterHypothesisTool.js

@@ -1,160 +0,0 @@
-const crypto = require('node:crypto');
-
-const { readSymptomCases, readClusters, storeCluster } = require('../../fhir');
-const { ClusterImpression } = require('../../shared/dtos/ClusterImpression');
-const { ClusterHistoryRecord } = require('../../shared/dtos/ClusterHistoryRecord');
-
-const HYPOTHESIS_TYPES = ['ae_profile', 'symptom_syndrome', 'disease_complication', 'relational_causal'];
-const CONFIDENCE_LEVELS = ['speculative', 'moderate', 'strong'];
-const CLINICAL_SIGNIFICANCE = ['benign', 'moderate', 'safety_relevant', 'emergency'];
-const OPEN_CASE_STATUSES = ['characterizing', 'monitoring'];
-
-const definition = {
-  name: 'openClusterHypothesis',
-  description: '**Does:** Opens a NEW cluster hypothesis (ClusterImpression) grouping 2+ open symptom cases the agent believes are one clinical pattern (an AE profile, a syndrome, a disease complication, or a causal chain).\n\n**Required inputs:** `label` (short human name, unique among active clusters), `hypothesis_type` (`ae_profile` | `symptom_syndrome` | `disease_complication` | `relational_causal`), `member_case_ids` (2+ open case_ids), `relationship_model` (how the members relate), `initial_confidence` (`speculative` | `moderate` | `strong`), `clinical_significance` (`benign` | `moderate` | `safety_relevant` | `emergency`), `opening_reasoning`. Optional `strengthens_if`, `weakens_if`, `consultation_id`.\n\n**When to call:** when 2+ open cases co-occur as a coherent pattern with routing implications.\n\n**When NOT to call:** for a single case, or when an active cluster already carries this `label` — use `updateClusterHypothesis` instead.\n\n**Returns:** `cluster_id`, and `member_case_ids` ONLY when input dedup changed the list you sent. Fails hard with `cluster_already_open_with_label` (+`existing_cluster_id`), fewer than 2 unique members, an unknown/non-open/wrong-patient member, or an invalid vocab value.\n\n**Side effects:** writes a FHIR ClusterImpression + an \'opened\' Provenance.',
-  strict: false,
-  parameters: {
-    type: 'object',
-    properties: {
-      label: {
-        type: 'string',
-        description: 'Short human name for the cluster. Must be unique among the patient\'s active clusters.',
-      },
-      hypothesis_type: {
-        type: 'string',
-        enum: HYPOTHESIS_TYPES,
-        description: 'The kind of pattern: `ae_profile`, `symptom_syndrome`, `disease_complication`, or `relational_causal`.',
-      },
-      member_case_ids: {
-        type: 'array',
-        items: { type: 'string' },
-        description: 'At least 2 open case_ids (NCI symptom-cluster definition). Duplicates are silently deduped.',
-      },
-      relationship_model: {
-        type: 'string',
-        description: 'How the member cases relate (the clinical model behind the cluster).',
-      },
-      initial_confidence: {
-        type: 'string',
-        enum: CONFIDENCE_LEVELS,
-        description: '`speculative`, `moderate`, or `strong`.',
-      },
-      clinical_significance: {
-        type: 'string',
-        enum: CLINICAL_SIGNIFICANCE,
-        description: '`benign`, `moderate`, `safety_relevant`, or `emergency`.',
-      },
-      opening_reasoning: {
-        type: 'string',
-        description: 'Why this cluster is being opened now.',
-      },
-      strengthens_if: {
-        type: 'array',
-        items: { type: 'string' },
-        description: 'Optional. Observations that would raise confidence in this hypothesis.',
-      },
-      weakens_if: {
-        type: 'array',
-        items: { type: 'string' },
-        description: 'Optional. Observations that would lower confidence in this hypothesis.',
-      },
-      consultation_id: {
-        type: 'string',
-        description: 'Optional. The pattern-consult id that anchors this hypothesis, if any.',
-      },
-    },
-    required: ['label', 'hypothesis_type', 'member_case_ids', 'relationship_model', 'initial_confidence', 'clinical_significance', 'opening_reasoning'],
-  },
-};
-
-function fail(error, data = {}) {
-  return JSON.stringify({ success: false, error, data });
-}
-
-async function handler(args = {}, context = {}) {
-  try {
-    const runtime = context?.toolRuntimeContext || null;
-    if (!runtime?.turnId || !runtime?.patientCode) {
-      return fail('openClusterHypothesis requires an active turn context (turnId, patientCode).');
-    }
-    const str = (v) => (typeof v === 'string' ? v : '');
-    const label = str(args?.label).trim();
-    const hypothesisType = str(args?.hypothesis_type).trim().toLowerCase();
-    const relationshipModel = str(args?.relationship_model).trim();
-    const initialConfidence = str(args?.initial_confidence).trim().toLowerCase();
-    const clinicalSignificance = str(args?.clinical_significance).trim().toLowerCase();
-    const openingReasoning = str(args?.opening_reasoning).trim();
-    const strList = (raw) => (Array.isArray(raw) ? raw.filter((item) => typeof item === 'string') : []);
-    const requested = strList(args?.member_case_ids);
-
-    const missing = [['label', label], ['hypothesis_type', hypothesisType], ['member_case_ids', Array.isArray(args?.member_case_ids) ? args.member_case_ids : ''], ['relationship_model', relationshipModel], ['initial_confidence', initialConfidence], ['clinical_significance', clinicalSignificance], ['opening_reasoning', openingReasoning]]
-      .filter(([, v]) => !v).map(([n]) => n);
-    if (missing.length) return fail(`missing required field(s): ${missing.join(', ')}`);
-
-    if (!HYPOTHESIS_TYPES.includes(hypothesisType)) return fail(`invalid hypothesis_type: '${hypothesisType}'. Must be one of ${HYPOTHESIS_TYPES.join(' | ')}.`, { hypothesis_type: hypothesisType });
-    if (!CONFIDENCE_LEVELS.includes(initialConfidence)) return fail(`invalid initial_confidence: '${initialConfidence}'. Must be one of ${CONFIDENCE_LEVELS.join(' | ')}.`, { initial_confidence: initialConfidence });
-    if (!CLINICAL_SIGNIFICANCE.includes(clinicalSignificance)) return fail(`invalid clinical_significance: '${clinicalSignificance}'. Must be one of ${CLINICAL_SIGNIFICANCE.join(' | ')}.`, { clinical_significance: clinicalSignificance });
-
-    if (requested.length < 2) return fail('cluster requires at least 2 member_case_ids (NCI symptom-cluster definition).', { member_case_ids: requested });
-    const memberCaseIds = [...new Set(requested)];
-    if (memberCaseIds.length < 2) return fail('after dedup, fewer than 2 unique member_case_ids remain');
-
-    const patientId = runtime.patientCode;
-    const active = await readClusters({ patientId, label });
-    const existing = active.find((c) => c.status === 'active');
-    if (existing) {
-      return fail('cluster_already_open_with_label', {
-        existing_cluster_id: existing.clusterId,
-        existing_status: existing.status,
-        hint: 'call updateClusterHypothesis on the existing cluster instead of opening a duplicate',
-      });
-    }
-
-    const cases = await readSymptomCases({ patientId });
-    for (const caseId of memberCaseIds) {
-      const managedSymptom = cases.find((c) => c.condition.conditionId === caseId);
-      if (!managedSymptom) return fail('member_case_not_found_or_wrong_patient', { member_case_id: caseId });
-      if (!OPEN_CASE_STATUSES.includes(managedSymptom.condition.clinicalStatus)) return fail('member_case_not_open', { case_id: caseId, status: managedSymptom.condition.clinicalStatus });
-    }
-
-    const now = new Date().toISOString();
-    const clusterId = `cluster_${crypto.randomUUID().replace(/-/g, '').slice(0, 12)}`;
-    const consultationId = str(args?.consultation_id).trim() || null;
-    const cluster = new ClusterImpression({
-      clusterId,
-      patientId,
-      label,
-      hypothesisType,
-      status: 'active',
-      confidence: initialConfidence,
-      clinicalSignificance,
-      memberCaseIds,
-      consultationId,
-      relationshipModel,
-      strengthensIf: strList(args?.strengthens_if),
-      weakensIf: strList(args?.weakens_if),
-      openingReasoning,
-      openedAt: now,
-    });
-    const history = [new ClusterHistoryRecord({
-      clusterId,
-      turnId: runtime.turnId,
-      action: 'opened',
-      transitionReason: openingReasoning,
-      recordedAt: now,
-    })];
-
-    await storeCluster({ patientId, cluster, history });
-
-    const out = { cluster_id: clusterId };
-    if (memberCaseIds.length !== requested.length) out.member_case_ids = [...memberCaseIds];
-    return JSON.stringify({ success: true, data: out });
-  } catch (err) {
-    return fail(err?.message || 'openClusterHypothesis failed');
-  }
-}
-
-module.exports = {
-  definition,
-  handler,
-};