@peopl-health/nexus 5.44.0-dev.5437 → 5.44.0-dev.5439

package/lib/clinical/helpers/gradeEstimateHelper.js

@@ -120,12 +120,21 @@ function hasGradeSignal(raw) {
       .some((key) => raw[key] !== null && raw[key] !== undefined);
 }
 
+function malformedGradeEstimate(raw) {
+  if (raw === null || raw === undefined) return null;
+  if (typeof raw === 'object' && !Array.isArray(raw)) return null;
+  return `grade_estimate must be an object, not ${Array.isArray(raw) ? 'a list' : typeof raw}. `
+    + 'Send {best_estimate, confidence, possible_range, reasoning, functional_anchor, source, matched_grade} — '
+    + `a bare ${Array.isArray(raw) ? 'list' : typeof raw} carries no confidence or range and would be dropped.`;
+}
+
 function isCarriedForward(raw) {
   return !!raw && typeof raw === 'object' && raw.source === CARRIED_FORWARD;
 }
 
 module.exports = {
   gradeEstimateSchema,
+  malformedGradeEstimate,
   projectGradeEstimate,
   projectGradeRead,
   hasGradeSignal,

package/lib/clinical/services/conditionCloseService.js

@@ -0,0 +1,132 @@
+const { readContingencies, readClusters, storeCluster } = require('../../fhir');
+const { RESOLUTION_CLOSE_REASONS } = require('../../shared/dtos/ManagedSymptom');
+const { RESOLVED_REASONS } = require('../../shared/dtos/ContingencySafetyNet');
+const { ClusterImpression } = require('../../shared/dtos/ClusterImpression');
+const { ClusterHistoryRecord } = require('../../shared/dtos/ClusterHistoryRecord');
+const { autoResolveNets } = require('./contingencyDispatchService');
+
+const DEACTIVATE_CLOSE_REASONS = ['escalated_to_team', 'patient_transferred', 'stale_no_activity'];
+const CLUSTER_MEMBER_FLOOR = 2;
+const ALL_CLOSE_REASONS = [...RESOLUTION_CLOSE_REASONS, ...DEACTIVATE_CLOSE_REASONS];
+
+function isResolutionReason(reason) {
+  return RESOLUTION_CLOSE_REASONS.has((reason || '').trim().toLowerCase());
+}
+
+const INFER_HINT = 'A resolution reason records an observed end and stamps abatement_at; '
+  + 'a deactivation reason stops tracking without claiming one. Free text is not accepted for either.';
+
+const closeError = (error, data) => ({ error: { error, data } });
+
+function forResolve(closeReason, caseId) {
+  const reason = closeReason || 'resolved';
+  if (!RESOLUTION_CLOSE_REASONS.has(reason)) {
+    return closeError('invalid_close_reason_for_resolve', { case_id: caseId, valid_close_reasons: [...RESOLUTION_CLOSE_REASONS] });
+  }
+  return { closeReason: reason, resolving: true };
+}
+
+function forDeactivate(closeReason, caseId) {
+  if (!closeReason) return closeError('close_reason is required for deactivate', { valid_close_reasons: DEACTIVATE_CLOSE_REASONS });
+  if (!DEACTIVATE_CLOSE_REASONS.includes(closeReason)) {
+    return closeError('invalid_close_reason_for_deactivate', { case_id: caseId, valid_close_reasons: DEACTIVATE_CLOSE_REASONS });
+  }
+  return { closeReason, resolving: false };
+}
+
+function inferDirection(closeReason, caseId) {
+  if (!closeReason) return closeError('close_reason is required', { valid_close_reasons: ALL_CLOSE_REASONS });
+  if (isResolutionReason(closeReason)) return { closeReason, resolving: true };
+  if (!DEACTIVATE_CLOSE_REASONS.includes(closeReason)) {
+    return closeError('invalid_close_reason', { case_id: caseId, valid_close_reasons: ALL_CLOSE_REASONS, hint: INFER_HINT });
+  }
+  return { closeReason, resolving: false };
+}
+
+function resolveCloseReason(rawReason, { resolving = null, caseId = null } = {}) {
+  const closeReason = (typeof rawReason === 'string' ? rawReason : '').trim().toLowerCase();
+  if (resolving === null) return inferDirection(closeReason, caseId);
+  return resolving ? forResolve(closeReason, caseId) : forDeactivate(closeReason, caseId);
+}
+
+function closePatch({ closeReason, resolving, reasoning }) {
+  return {
+    clinicalStatus: 'closed',
+    abatementAt: resolving ? new Date().toISOString() : null,
+    closeReason,
+    ...(reasoning ? { lastTransitionReason: reasoning } : {}),
+  };
+}
+
+async function runCloseCascade(patientId, caseId, turnId, trace = null, sourceTool = 'updateConditionStatus') {
+  const autoResolvedPlans = [];
+  const prunedClusters = [];
+  const dissolvedClusters = [];
+  const cascadeErrors = [];
+  const now = new Date().toISOString();
+
+  try {
+    const nets = await readContingencies({ patientId, caseId });
+    const caseNets = await autoResolveNets({ patientCode: patientId, nets, resolvedReason: RESOLVED_REASONS.LINKED_CASE_CLOSED, trace });
+    autoResolvedPlans.push(...caseNets.autoResolvedPlans);
+    cascadeErrors.push(...caseNets.cascadeErrors);
+  } catch (error) {
+    cascadeErrors.push(`contingency_auto_resolve_failed: ${error?.message || error}`);
+  }
+
+  const clusters = await readClusters({ patientId, status: 'active' }).catch((error) => {
+    cascadeErrors.push(`cluster_cascade_failed: ${error?.message || error}`);
+    return [];
+  });
+  for (const cluster of clusters) {
+    if (!cluster.memberCaseIds.includes(caseId)) continue;
+    try {
+      const remaining = cluster.memberCaseIds.filter((id) => id !== caseId);
+      const isDissolving = remaining.length < CLUSTER_MEMBER_FLOOR;
+      const patch = { ...cluster, memberCaseIds: remaining.length ? remaining : cluster.memberCaseIds };
+      if (isDissolving) {
+        patch.status = 'dissolved';
+        patch.dissolvedAt = now;
+        patch.dissolveReason = `cascade: linked case ${caseId} closed`;
+        patch.dissolveCategory = 'linked_case_closed';
+      }
+      const action = isDissolving ? 'dissolved' : 'updated';
+      const changeItems = isDissolving
+        ? [`removed_members:${caseId}`, 'status:active→dissolved', 'dissolve_category:linked_case_closed']
+        : [`removed_members:${caseId}`];
+      const history = [new ClusterHistoryRecord({
+        clusterId: cluster.clusterId,
+        turnId: turnId || '',
+        action,
+        changes: { items: changeItems },
+        transitionReason: `cascade from ${sourceTool} on case ${caseId}`,
+        recordedAt: now,
+      })];
+      await storeCluster({ patientId, cluster: new ClusterImpression(patch), history });
+      (isDissolving ? dissolvedClusters : prunedClusters).push(cluster.clusterId);
+      if (isDissolving) {
+        try {
+          const clusterNets = await readContingencies({ patientId, clusterId: cluster.clusterId });
+          const dissolved = await autoResolveNets({ patientCode: patientId, nets: clusterNets, resolvedReason: RESOLVED_REASONS.LINKED_CLUSTER_DISSOLVED, trace });
+          autoResolvedPlans.push(...dissolved.autoResolvedPlans);
+          cascadeErrors.push(...dissolved.cascadeErrors);
+        } catch (error) {
+          cascadeErrors.push(`contingency_auto_resolve_failed: ${error?.message || error}`);
+        }
+      }
+    } catch (error) {
+      cascadeErrors.push(`cluster_cascade_failed: ${error?.message || error}`);
+    }
+  }
+
+  return { autoResolvedPlans, prunedClusters, dissolvedClusters, cascadeErrors };
+}
+
+module.exports = {
+  DEACTIVATE_CLOSE_REASONS,
+  CLUSTER_MEMBER_FLOOR,
+  isResolutionReason,
+  resolveCloseReason,
+  closePatch,
+  runCloseCascade,
+};

package/lib/clinical/tools/openConditionTool.js

@@ -1,19 +1,19 @@
 const crypto = require('node:crypto');
 
-const { GRADE_CONFIDENCE_LEVELS, GRADE_MIN, GRADE_MAX, gradeEstimateSchema, parseGradeEstimate, projectGradeEstimate, hasGradeSignal } = require('../helpers/gradeEstimateHelper');
+const { GRADE_CONFIDENCE_LEVELS, GRADE_MIN, GRADE_MAX, gradeEstimateSchema, parseGradeEstimate, projectGradeEstimate, hasGradeSignal, malformedGradeEstimate } = require('../helpers/gradeEstimateHelper');
 const { ceilingGapError } = require('../helpers/ceilingGapHelper');
 const { mentionProvenanceError } = require('../helpers/evidenceAnchorHelper');
 const { ctcaeTermError } = require('../services/ctcaeTermService');
 const { gradeClaimError } = require('../services/gradeClaimService');
 const { armOpenCeilingNet } = require('../services/contingencyDispatchService');
 const { readSymptomCases, storeSymptomCase } = require('../../fhir');
-const { ManagedSymptom, OPEN_STATUSES, FUNCTIONAL_ANCHORS } = require('../../shared/dtos/ManagedSymptom');
+const { ManagedSymptom, OPEN_STATUSES, CLOSED_STATUSES, FUNCTIONAL_ANCHORS } = require('../../shared/dtos/ManagedSymptom');
 const { logger } = require('../../utils/logger');
 const { isArmOnOpenCeilingLive } = require('../flags/contingencyFlags');
 
 const definition = {
   name: 'openCondition',
-  description: '**Does:** Opens a NEW agent-tracked symptom case (Condition + initial ClinicalImpression) for a symptom term with no open case — the longitudinal expediente that groups 1..N episodes of the same `ctcae_term`.\n\n**Required inputs:** `ctcae_term` (English snake_case catalog key — e.g. `fever`, `pain`, `dyspnea`; use `other` only when no catalog term fits), `episode_id` (the intake episode this case wraps), `mention_id` (the intake mention that opened the case), `verbatim_quote` (exact substring of the patient message). Optional `temporality`, `grade_estimate` (`{best_estimate, confidence, possible_range, reasoning}`).\n\n**When to call:** when the turn surfaces a symptom with no open case on this `ctcae_term`. Use `recordClinicalImpression` if a case is already open — do NOT call `openCondition` twice for the same symptom.\n\n**When NOT to call:** for a new episode or subsequent assessment of an EXISTING case — use `recordClinicalImpression`.\n\n**Returns:** `case_id`, `action_taken` (`opened`), `status`, `ctcae_term`, `episode_ids`, `current_episode_id`, `grade_estimate`, `temporality`, `trajectory`. Fails hard with `case_already_open_for_term` + `existing_case_id` when an open case already exists for the term — recover via `recordClinicalImpression`.\n\n**Side effects:** writes a FHIR `Condition` + head `ClinicalImpression` + `Provenance`.',
+  description: '**Does:** Opens a NEW agent-tracked symptom case (Condition + initial ClinicalImpression) for a symptom term with no open case — the longitudinal expediente that groups 1..N episodes of the same `ctcae_term`.\n\n**Required inputs:** `ctcae_term` (English snake_case catalog key — e.g. `fever`, `pain`, `dyspnea`; use `other` only when no catalog term fits), `episode_id` (the intake episode this case wraps), `mention_id` (the intake mention that opened the case), `verbatim_quote` (exact substring of the patient message). Optional `temporality`, `grade_estimate` (`{best_estimate, confidence, possible_range, reasoning}`).\n\n**When to call:** when the turn surfaces a symptom with no open case on this `ctcae_term`. Use `recordClinicalImpression` if a case is already open — do NOT call `openCondition` twice for the same symptom.\n\n**When NOT to call:**\n- For a new episode or subsequent assessment of an EXISTING open case — use `recordClinicalImpression`.\n- For a symptom that already has a case which was closed, resolved or deactivated — the same symptom returning is a recurrence of that case, not a new one. Reopen it with `updateConditionStatus(transition=\'reactivate\')`. This tool refuses the duplicate with `DORMANT_CASE_EXISTS` and names the case.\n\n**Returns:** `case_id`, `action_taken` (`opened`), `status`, `ctcae_term`, `episode_ids`, `current_episode_id`, `grade_estimate`, `temporality`, `trajectory`. Fails hard with `case_already_open_for_term` + `existing_case_id` when an open case already exists for the term — recover via `recordClinicalImpression`.\n\n**Side effects:** writes a FHIR `Condition` + head `ClinicalImpression` + `Provenance`.',
   strict: false,
   parameters: {
     type: 'object',
@@ -91,12 +91,30 @@ async function handler(args = {}, context = {}) {
       });
     }
 
+    const dormantCase = casesForTerm.find((symptomCase) => CLOSED_STATUSES.includes(symptomCase.condition.clinicalStatus));
+    if (dormantCase) {
+      const { condition } = dormantCase;
+      return JSON.stringify({
+        success: false,
+        error: 'DORMANT_CASE_EXISTS',
+        data: {
+          existing_case_id: condition.conditionId,
+          existing_status: condition.clinicalStatus,
+          close_reason: condition.closeReason,
+          dormant_since: condition.abatementAt || condition.lastUpdatedAt || null,
+          hint: `this symptom already has a case — reopen it instead of forking the record: updateConditionStatus(case_id='${condition.conditionId}', transition='reactivate', episode_id='${episodeId}', reasoning=…), then recordClinicalImpression on the same case_id`,
+        },
+      });
+    }
+
     const provenance = mentionProvenanceError(mentionId, { trace: runtime?.trace || null });
     if (provenance) return JSON.stringify({ success: false, error: provenance, data: {} });
 
     const now = new Date().toISOString();
     const caseId = uid('case');
     const temporality = typeof args?.temporality === 'string' ? args.temporality : null;
+    const malformedGrade = malformedGradeEstimate(args?.grade_estimate);
+    if (malformedGrade) return JSON.stringify({ success: false, error: malformedGrade, data: {} });
     const grade = parseGradeEstimate(args?.grade_estimate);
     if (grade.error) {
       const data = { invalid_grade_confidence: { allowed: GRADE_CONFIDENCE_LEVELS },

package/lib/clinical/tools/recordClinicalImpressionTool.js

@@ -1,21 +1,21 @@
 const crypto = require('node:crypto');
 
-const { CARRIED_FORWARD, GRADE_CONFIDENCE_LEVELS, GRADE_MIN, GRADE_MAX, gradeEstimateSchema, parseGradeEstimate, projectGradeEstimate, projectGradeRead, hasGradeSignal, isCarriedForward } = require('../helpers/gradeEstimateHelper');
+const { CARRIED_FORWARD, GRADE_CONFIDENCE_LEVELS, GRADE_MIN, GRADE_MAX, gradeEstimateSchema, parseGradeEstimate, projectGradeEstimate, projectGradeRead, hasGradeSignal, isCarriedForward, malformedGradeEstimate } = require('../helpers/gradeEstimateHelper');
 const { ceilingGapError } = require('../helpers/ceilingGapHelper');
 const { mentionProvenanceError } = require('../helpers/evidenceAnchorHelper');
 const { MEDICATION_NAMING_RULE } = require('../helpers/medicationNamingRule');
+const { resolveCloseReason, closePatch, runCloseCascade } = require('../services/conditionCloseService');
 const { gradeClaimError } = require('../services/gradeClaimService');
-const { autoResolveNets, armOpenCeilingNet } = require('../services/contingencyDispatchService');
+const { armOpenCeilingNet } = require('../services/contingencyDispatchService');
 const { inputConsistency, statedReasoning } = require('../services/impressionValidationService');
 const { isArmOnOpenCeilingLive } = require('../flags/contingencyFlags');
-const { readContingencies, readSymptomCases, storeSymptomCase } = require('../../fhir');
+const { readSymptomCases, storeSymptomCase } = require('../../fhir');
 const { ManagedSymptom, OPEN_STATUSES, FUNCTIONAL_ANCHORS } = require('../../shared/dtos/ManagedSymptom');
-const { RESOLVED_REASONS } = require('../../shared/dtos/ContingencySafetyNet');
 const { logger } = require('../../utils/logger');
 
 const definition = {
   name: 'recordClinicalImpression',
-  description: '**Does:** Evolves an existing symptom case by `event`. `add_evidence`: new mention on the current episode (requires `characterizing` + a grade or trajectory). `new_episode`: a new episode for the same `ctcae_term` — attaches it and returns the case to `characterizing`. `resolve_episode`: the current episode resolved — case goes to `monitoring`. `close`: terminal — status `closed`, requires `close_reason`.\n\nAn impression is a grading act plus the reasoning behind it: `grade_estimate` carries your most likely grade with its confidence and range, and `reasoning` names, in one or two sentences, what you think is going on. `reasoning` is REQUIRED on every call and is the canonical per-case rationale — it lands on the clinical record, and the routing trace references it rather than restating it. Omitting it does not fail the write, but the impression is then a grade with no clinical reasoning behind it and the envelope says so in `input_consistency`. Grade-specific justification (the matched `grade_scale` clause) belongs inside `grade_estimate.reasoning`.\n\n**Required inputs:** `case_id` (from `openCondition` or `getActiveSymptomLandscape`), `event`, `reasoning`. Per-event: `add_evidence`/`new_episode` require `mention_id`, `missing_for_higher_grade`, plus at least one of `grade_estimate` or `trajectory_direction`; `new_episode` also requires `episode_id`; `close` requires `close_reason`.\n\n**Returns:** `case_id`, `action_taken`, `status`, `ctcae_term`, `episode_ids`, `current_episode_id`, `mention_ids`, `grade_estimate`, `temporality`, `trajectory`, `decision_posture`, `close_reason`, `abatement_at`, plus `input_consistency` when the call under-specified something. Fails hard on status guards (e.g. `add_evidence` on a non-`characterizing` case), duplicate `mention_id`, or an already-attached `episode_id`.\n\n**Side effects:** appends a FHIR `ClinicalImpression` to the case chain and repoints the head; updates the `Condition` lifecycle. `close` also retires any contingency net guarding the case (returned as `auto_resolved_contingency_plans`) — a closed case never keeps writing to the patient.',
+  description: '**Does:** Evolves an existing symptom case by `event`. `add_evidence`: new mention on the current episode (requires `characterizing` + a grade or trajectory). `new_episode`: a new episode for the same `ctcae_term` — attaches it and returns the case to `characterizing`. `resolve_episode`: the current episode resolved — case goes to `monitoring`. `close`: terminal — status `closed`, requires `close_reason` from the closed vocabulary.\n\nAn impression is a grading act plus the reasoning behind it: `grade_estimate` carries your most likely grade with its confidence and range, and `reasoning` names, in one or two sentences, what you think is going on. `reasoning` is REQUIRED on every call and is the canonical per-case rationale — it lands on the clinical record, and the routing trace references it rather than restating it. Omitting it does not fail the write, but the impression is then a grade with no clinical reasoning behind it and the envelope says so in `input_consistency`. Grade-specific justification (the matched `grade_scale` clause) belongs inside `grade_estimate.reasoning`.\n\n**Required inputs:** `case_id` (from `openCondition` or `getActiveSymptomLandscape`), `event`, `reasoning`. Per-event: `add_evidence`/`new_episode` require `mention_id`, `missing_for_higher_grade`, plus at least one of `grade_estimate` or `trajectory_direction`; `new_episode` also requires `episode_id`; `close` requires `close_reason`, and it must be one of `resolved` | `team_resolved` | `resolved_spontaneously` | `resolved_by_intervention` (the symptom ENDED — this stamps `abatement_at`) or `escalated_to_team` | `patient_transferred` | `stale_no_activity` (stop tracking WITHOUT claiming an end — `abatement_at` stays null). Never claim a resolution nobody observed; free text is rejected.\n\n**Returns:** `case_id`, `action_taken`, `status`, `ctcae_term`, `episode_ids`, `current_episode_id`, `mention_ids`, `grade_estimate`, `temporality`, `trajectory`, `decision_posture`, `close_reason`, `abatement_at`, plus `input_consistency` when the call under-specified something. Fails hard on status guards (e.g. `add_evidence` on a non-`characterizing` case), duplicate `mention_id`, or an already-attached `episode_id`.\n\n**Side effects:** appends a FHIR `ClinicalImpression` to the case chain and repoints the head; updates the `Condition` lifecycle. `close` also retires any contingency net guarding the case (returned as `auto_resolved_contingency_plans`) — a closed case never keeps writing to the patient — and prunes the case from its active clusters, dissolving one that drops below 2 members (`pruned_clusters`, `dissolved_clusters`).',
   strict: false,
   parameters: {
     type: 'object',
@@ -84,6 +84,8 @@ const normalisedEvent = (args) => (typeof args?.event === 'string' ? args.event
 const uid = (prefix) => `${prefix}_${crypto.randomUUID().replace(/-/g, '').slice(0, 12)}`;
 
 function coerceGrade(raw, base, continuesEpisode = false) {
+  const malformed = malformedGradeEstimate(raw);
+  if (malformed) return { error: malformed };
   if (isCarriedForward(raw)) {
     const parsed = parseGradeEstimate(raw);
     if (parsed?.error) return parsed;
@@ -240,6 +242,8 @@ function applyNewEpisode(existing, args, runtime) {
 }
 
 function closingAssessment(existing, args, runtime, restatesPriorEvidence) {
+  const malformed = malformedGradeEstimate(args?.grade_estimate);
+  if (malformed) return { error: malformed };
   if (!hasGradeSignal(args?.grade_estimate) && !statesTrajectory(args)) return null;
   return buildAssessment(existing.condition, existing.latestAssessment, args, runtime, restatesPriorEvidence);
 }
@@ -270,11 +274,10 @@ function applyClose(existing, args, runtime) {
   if (!OPEN_STATUSES.includes(existing.condition.clinicalStatus)) {
     return fail('case_already_terminal', { case_id: existing.condition.conditionId, status: existing.condition.clinicalStatus, abatement_at: existing.condition.abatementAt, close_reason: existing.condition.closeReason });
   }
-  const closeReason = (typeof args?.close_reason === 'string' ? args.close_reason : '').trim();
-  if (!closeReason) return fail('close_reason is required');
-  const patch = { clinicalStatus: 'closed', abatementAt: new Date().toISOString(), closeReason };
+  const close = resolveCloseReason(args?.close_reason, { caseId: existing.condition.conditionId });
+  if (close.error) return fail(close.error.error, close.error.data);
   const reasoning = (typeof args?.reasoning === 'string' ? args.reasoning : '').trim();
-  if (reasoning) patch.lastTransitionReason = reasoning;
+  const patch = closePatch({ closeReason: close.closeReason, resolving: close.resolving, reasoning });
   const assessment = closingAssessment(existing, args, runtime, true);
   if (assessment?.error) return failAssessment(assessment.error, existing.condition.conditionId);
   return toManaged(existing, patch, assessment);
@@ -311,15 +314,16 @@ async function handler(args = {}, context = {}) {
     await storeSymptomCase({ patientId, managedSymptom: result });
 
     const autoResolvedPlans = [];
+    const prunedClusters = [];
+    const dissolvedClusters = [];
     if (event === 'close') {
       try {
-        const nets = await readContingencies({ patientId, caseId });
-        const cascade = await autoResolveNets({
-          patientCode: patientId, nets, resolvedReason: RESOLVED_REASONS.LINKED_CASE_CLOSED, trace: runtime.trace || null,
-        });
+        const cascade = await runCloseCascade(patientId, caseId, runtime.turnId, runtime.trace || null, 'recordClinicalImpression');
         autoResolvedPlans.push(...cascade.autoResolvedPlans);
+        prunedClusters.push(...cascade.prunedClusters);
+        dissolvedClusters.push(...cascade.dissolvedClusters);
         for (const failure of cascade.cascadeErrors) {
-          logger.warn('[recordClinicalImpression] net left armed on a closed case', { caseId, error: failure });
+          logger.warn('[recordClinicalImpression] close cascade incomplete', { caseId, error: failure });
         }
       } catch (error) {
         // The close already succeeded, so failing the tool here would only invite a useless retry.
@@ -352,6 +356,8 @@ async function handler(args = {}, context = {}) {
       data: {
         case_id: condition.conditionId,
         ...(autoResolvedPlans.length ? { auto_resolved_contingency_plans: autoResolvedPlans } : {}),
+        ...(prunedClusters.length ? { pruned_clusters: prunedClusters } : {}),
+        ...(dissolvedClusters.length ? { dissolved_clusters: dissolvedClusters } : {}),
         action_taken: event,
         status: condition.clinicalStatus,
         ctcae_term: condition.ctcaeTerm,

package/lib/clinical/tools/recordInterventionTool.js

@@ -8,7 +8,7 @@ const ACTIONS = ['create', 'record_outcome'];
 
 const definition = {
   name: 'recordIntervention',
-  description: '**Does:** Records an agent-delivered intervention against an open symptom case (`action:\'create\'`) or patches the outcome of one already recorded (`action:\'record_outcome\'`). One intervention = one clinical action (OTC advice, self-care, education, a team escalation task, or a follow-up check).\n\n**Create inputs:** `case_id` (an OPEN case from `openCondition`/`getActiveSymptomLandscape`), `intervention_label`, `intervention_kind` (`otc` | `self_care` | `other` | `education` | `team_escalation` | `follow_up_check`); optional `rationale`. Fails hard with `case_not_found_or_wrong_patient` or `case_is_dormant` (recover via `recordClinicalImpression` reactivation), or `invalid intervention_kind`.\n\n**Outcome inputs (`action:\'record_outcome\'`):** `intervention_id` (the handle create returned), `outcome` (`pending` | `improved` | `no_relief` | `side_effects` | `worsened` | `unknown`); optional `outcome_notes`. Single-write: fails with `outcome_already_recorded` if the outcome is already non-pending.\n\n**When to call:** create when you deliver an intervention; record_outcome once the patient reports how it went.\n\n**Returns:** create → `{intervention_id, delivered_at}`; record_outcome → `{intervention_id, outcome}`.\n\n**Side effects:** writes a FHIR Procedure/Communication/Task/CommunicationRequest (per kind) + Provenance.',
+  description: '**Does:** Records an agent-delivered intervention against an open symptom case (`action:\'create\'`) or patches the outcome of one already recorded (`action:\'record_outcome\'`). One intervention = one clinical action (OTC advice, self-care, education, a team escalation task, or a follow-up check).\n\n**Create inputs:** `case_id` (an OPEN case from `openCondition`/`getActiveSymptomLandscape`), `intervention_label`, `intervention_kind` (`otc` | `self_care` | `other` | `education` | `team_escalation` | `follow_up_check`); optional `rationale`. Fails hard with `case_not_found_or_wrong_patient` or `case_is_dormant` (recover via `updateConditionStatus(transition=\'reactivate\')`), or `invalid intervention_kind`.\n\n**Outcome inputs (`action:\'record_outcome\'`):** `intervention_id` (the handle create returned), `outcome` (`pending` | `improved` | `no_relief` | `side_effects` | `worsened` | `unknown`); optional `outcome_notes`. Single-write: fails with `outcome_already_recorded` if the outcome is already non-pending.\n\n**Record vs actuate — this tool only WRITES A RECORD.** `intervention_kind=\'team_escalation\'` dispatches nothing: escalate with `reportMedicalEscalation` FIRST, then record it here. `intervention_kind=\'follow_up_check\'` schedules nothing: schedule with `schedulePatientReminder` FIRST, then record it here. **Recording an escalation is not escalating** — a `success` here never means anyone was notified.\n\n**When to call:** create when you deliver an intervention; record_outcome once the patient reports how it went.\n\n**Returns:** create → `{intervention_id, delivered_at}`; record_outcome → `{intervention_id, outcome}`.\n\n**Side effects:** writes a FHIR Procedure/Communication/Task/CommunicationRequest (per kind) + Provenance.',
   strict: false,
   parameters: {
     type: 'object',
@@ -87,7 +87,7 @@ async function create(patientId, args) {
   const targetCase = (await readSymptomCases({ patientId })).find((c) => c.condition.conditionId === caseId);
   if (!targetCase) return fail('case_not_found_or_wrong_patient', { case_id: caseId });
   if (!OPEN_STATUSES.includes(targetCase.condition.clinicalStatus)) {
-    return fail('case_is_dormant — interventions attach to open cases; if the symptom recurred, reactivate the case via recordClinicalImpression first.', { case_id: caseId, status: targetCase.condition.clinicalStatus });
+    return fail('case_is_dormant — interventions attach to open cases; if the symptom recurred, reactivate the case with updateConditionStatus(transition=\'reactivate\') first.', { case_id: caseId, status: targetCase.condition.clinicalStatus });
   }
 
   const deliveredAt = new Date().toISOString();

package/lib/clinical/tools/updateConditionStatusTool.js

@@ -1,17 +1,13 @@
-const { autoResolveNets } = require('../services/contingencyDispatchService');
-const { readSymptomCases, storeSymptomCase, readContingencies, readClusters, storeCluster } = require('../../fhir');
-const { ManagedSymptom, OPEN_STATUSES, RESOLUTION_CLOSE_REASONS } = require('../../shared/dtos/ManagedSymptom');
-const { RESOLVED_REASONS } = require('../../shared/dtos/ContingencySafetyNet');
-const { ClusterImpression } = require('../../shared/dtos/ClusterImpression');
-const { ClusterHistoryRecord } = require('../../shared/dtos/ClusterHistoryRecord');
+const {
+  isResolutionReason, resolveCloseReason, closePatch, runCloseCascade,
+} = require('../services/conditionCloseService');
+const { readSymptomCases, storeSymptomCase } = require('../../fhir');
+const { ManagedSymptom } = require('../../shared/dtos/ManagedSymptom');
 const { logger } = require('../../utils/logger');
 
-const DEACTIVATE_CLOSE_REASONS = ['escalated_to_team', 'patient_transferred', 'stale_no_activity'];
-const CLUSTER_MEMBER_FLOOR = 2;
-
 const definition = {
   name: 'updateConditionStatus',
-  description: '**Does:** Transitions the lifecycle of a symptom `Condition` (FHIR `Condition.clinicalStatus`), selected via `transition`.\n\n**Required inputs:** `case_id`, `transition` (`new_episode` | `resolve_episode` | `resolve` | `deactivate` | `reactivate`), and `reasoning` (one short sentence justifying the transition — persisted to the Condition\'s audit record). Per transition:\n- `new_episode`: requires `episode_id` for a GENUINELY-NEW episode of the same term. Attaches it and returns the case to `characterizing`.\n- `resolve_episode`: no extra args. Current episode resolved; case → `monitoring`, current episode cleared.\n- `resolve`: the symptom ENDED (patient-confirmed or clinically established) → `resolved` + `abatement_at`.\n- `deactivate`: stop tracking WITHOUT asserting resolution. `close_reason` REQUIRED (`escalated_to_team` | `patient_transferred` | `stale_no_activity`) → `inactive`, no abatement.\n- `reactivate`: a dormant case\'s symptom RETURNED. Requires `episode_id`. Reopens the SAME Condition (→ `characterizing`; FHIR `recurrence` when it had been resolved).\n\n**Returns:** `case_id` + new `status`; `resolve`/`deactivate` add `abatement_at` (null on deactivate) and cascade outcomes — `auto_resolved_plans[]`, `pruned_clusters[]`, `dissolved_clusters[]`, `cascade_errors[]` (each present only when non-empty); `reactivate` adds `is_recurrence` + `recurrence_count`.\n\n**Side effects:** writes the lifecycle patch to the `Condition`. On `resolve`/`deactivate`, auto-resolves any active contingency safety net linked to the case and prunes the case from any active cluster (auto-dissolving a cluster that drops below 2 members, which also auto-resolves that cluster\'s own safety net).',
+  description: '**Does:** Transitions the lifecycle of a symptom `Condition` (FHIR `Condition.clinicalStatus`), selected via `transition`.\n\n**Required inputs:** `case_id`, `transition` (`resolve_episode` | `resolve` | `deactivate` | `reactivate`), and `reasoning` (one short sentence justifying the transition — persisted to the Condition\'s audit record). Per transition:\n- `resolve_episode`: no extra args. Current episode resolved; case → `monitoring`, current episode cleared.\n- `resolve`: the symptom ENDED (patient-confirmed or clinically established) → `resolved` + `abatement_at`.\n- `deactivate`: stop tracking WITHOUT asserting resolution. `close_reason` REQUIRED (`escalated_to_team` | `patient_transferred` | `stale_no_activity`) → `inactive`, no abatement.\n- `reactivate`: a dormant case\'s symptom RETURNED. Requires `episode_id`. Reopens the SAME Condition (→ `characterizing`; FHIR `recurrence` when it had been resolved).\n\n**When NOT to call:**\n- To start a new episode of the same term — that is `recordClinicalImpression` with `event=\'new_episode\'`, which gives the episode its own grade and arms its safety net. This tool refuses it.\n- To register a `ClinicalImpression` — that is `recordClinicalImpression`\'s job; call it separately, in an earlier round.\n- To open a case that does not exist yet — that is `openCondition`.\n\n**Parallelism with `recordClinicalImpression`:** `resolve_episode`, `resolve` and `deactivate` move the case out of `characterizing`, which is the status `recordClinicalImpression` requires. Record the impression carrying the closing read in an EARLIER round; a parallel impression in the same round will fail.\n\n**Returns:** `case_id` + new `status`; `resolve`/`deactivate` add `abatement_at` (null on deactivate) and cascade outcomes — `auto_resolved_plans[]`, `pruned_clusters[]`, `dissolved_clusters[]`, `cascade_errors[]` (each present only when non-empty); `reactivate` adds `is_recurrence` + `recurrence_count`.\n\n**Side effects:** writes the lifecycle patch to the `Condition`. On `resolve`/`deactivate`, auto-resolves any active contingency safety net linked to the case and prunes the case from any active cluster (auto-dissolving a cluster that drops below 2 members, which also auto-resolves that cluster\'s own safety net).',
   strict: false,
   parameters: {
     type: 'object',
@@ -22,8 +18,8 @@ const definition = {
       },
       transition: {
         type: 'string',
-        enum: ['new_episode', 'resolve_episode', 'resolve', 'deactivate', 'reactivate'],
-        description: '`new_episode`: attach a genuinely-new episode (→ characterizing). `resolve_episode`: current episode resolved (→ monitoring). `resolve`: symptom ended (→ resolved + abatement). `deactivate`: stop tracking without resolution (→ inactive, requires close_reason). `reactivate`: dormant case returned (→ characterizing).',
+        enum: ['resolve_episode', 'resolve', 'deactivate', 'reactivate'],
+        description: '`resolve_episode`: current episode resolved (→ monitoring). `resolve`: symptom ended (→ resolved + abatement). `deactivate`: stop tracking without resolution (→ inactive, requires close_reason). `reactivate`: dormant case returned (→ characterizing).',
       },
       reasoning: {
         type: 'string',
@@ -31,7 +27,7 @@ const definition = {
       },
       episode_id: {
         type: 'string',
-        description: 'Required for new_episode (a genuinely-new episode) and reactivate (the new bout\'s intake episode).',
+        description: 'Required for reactivate (the new bout\'s intake episode).',
       },
       close_reason: {
         type: 'string',
@@ -52,10 +48,6 @@ function fail(error, data = {}) {
   return JSON.stringify({ success: false, error, data });
 }
 
-function isResolutionReason(reason) {
-  return RESOLUTION_CLOSE_REASONS.has((reason || '').trim().toLowerCase());
-}
-
 function returnedStatus(condition) {
   const { clinicalStatus } = condition;
   if (clinicalStatus === 'closed') {
@@ -77,25 +69,6 @@ function toManaged(existing, conditionPatch) {
   });
 }
 
-function applyNewEpisode(existing, reasoning, args) {
-  if (!OPEN_STATUSES.includes(existing.condition.clinicalStatus)) {
-    return fail('new_episode requires an open case (characterizing or monitoring).', { case_id: existing.condition.conditionId, status: existing.condition.clinicalStatus });
-  }
-  const episodeId = (typeof args?.episode_id === 'string' ? args.episode_id : '').trim();
-  if (!episodeId) return fail('new_episode requires episode_id');
-  if (existing.condition.evidenceEpisodeIds.includes(episodeId)) {
-    return fail('episode_already_attached_to_case', { case_id: existing.condition.conditionId, episode_id: episodeId, current_episode_id: existing.condition.currentEpisodeId });
-  }
-  const patch = {
-    evidenceEpisodeIds: [...existing.condition.evidenceEpisodeIds, episodeId],
-    currentEpisodeId: episodeId,
-    clinicalStatus: 'characterizing',
-    lastTransitionReason: reasoning,
-  };
-  if (typeof args?.temporality === 'string') patch.temporality = args.temporality;
-  return toManaged(existing, patch);
-}
-
 function applyResolveEpisode(existing, reasoning, args) {
   if (existing.condition.clinicalStatus !== 'characterizing') {
     return fail('resolve_episode requires status=characterizing (there must be an active episode to resolve).', { case_id: existing.condition.conditionId, status: existing.condition.clinicalStatus });
@@ -109,31 +82,16 @@ function applyDormant(existing, reasoning, args, resolving) {
   if (isDormant(existing.condition)) {
     return fail('case_already_dormant', { case_id: existing.condition.conditionId, status: returnedStatus(existing.condition), close_reason: existing.condition.closeReason });
   }
-  let closeReason = (typeof args?.close_reason === 'string' ? args.close_reason : '').trim().toLowerCase();
-  if (resolving) {
-    closeReason = closeReason || 'resolved';
-    if (!RESOLUTION_CLOSE_REASONS.has(closeReason)) {
-      return fail('invalid_close_reason_for_resolve', { case_id: existing.condition.conditionId, valid_close_reasons: [...RESOLUTION_CLOSE_REASONS] });
-    }
-  } else {
-    if (!closeReason) return fail('close_reason is required for deactivate', { valid_close_reasons: DEACTIVATE_CLOSE_REASONS });
-    if (!DEACTIVATE_CLOSE_REASONS.includes(closeReason)) {
-      return fail('invalid_close_reason_for_deactivate', { case_id: existing.condition.conditionId, valid_close_reasons: DEACTIVATE_CLOSE_REASONS });
-    }
-  }
-  const patch = {
-    clinicalStatus: 'closed',
-    abatementAt: resolving ? new Date().toISOString() : null,
-    closeReason,
-    lastTransitionReason: reasoning,
-  };
+  const close = resolveCloseReason(args?.close_reason, { resolving, caseId: existing.condition.conditionId });
+  if (close.error) return fail(close.error.error, close.error.data);
+  const patch = closePatch({ closeReason: close.closeReason, resolving: close.resolving, reasoning });
   if (typeof args?.temporality === 'string') patch.temporality = args.temporality;
   return toManaged(existing, patch);
 }
 
 function applyReactivate(existing, reasoning, args) {
   if (!isDormant(existing.condition)) {
-    return fail('reactivate requires a dormant case (resolved/inactive). This case is already open — use transition=new_episode.', { case_id: existing.condition.conditionId, status: existing.condition.clinicalStatus });
+    return fail('reactivate requires a dormant case (resolved/inactive). This case is already open — record the new bout with recordClinicalImpression(event=\'new_episode\').', { case_id: existing.condition.conditionId, status: existing.condition.clinicalStatus });
   }
   const episodeId = (typeof args?.episode_id === 'string' ? args.episode_id : '').trim();
   if (!episodeId) return fail('reactivate requires episode_id');
@@ -156,70 +114,6 @@ function applyReactivate(existing, reasoning, args) {
   return { managed: toManaged(existing, patch), wasResolved: hasBeenResolved };
 }
 
-async function runCloseCascade(patientId, caseId, turnId, trace = null) {
-  const autoResolvedPlans = [];
-  const prunedClusters = [];
-  const dissolvedClusters = [];
-  const cascadeErrors = [];
-  const now = new Date().toISOString();
-
-  try {
-    const nets = await readContingencies({ patientId, caseId });
-    const caseNets = await autoResolveNets({ patientCode: patientId, nets, resolvedReason: RESOLVED_REASONS.LINKED_CASE_CLOSED, trace });
-    autoResolvedPlans.push(...caseNets.autoResolvedPlans);
-    cascadeErrors.push(...caseNets.cascadeErrors);
-  } catch (error) {
-    cascadeErrors.push(`contingency_auto_resolve_failed: ${error?.message || error}`);
-  }
-
-  const clusters = await readClusters({ patientId, status: 'active' }).catch((error) => {
-    cascadeErrors.push(`cluster_cascade_failed: ${error?.message || error}`);
-    return [];
-  });
-  for (const cluster of clusters) {
-    if (!cluster.memberCaseIds.includes(caseId)) continue;
-    try {
-      const remaining = cluster.memberCaseIds.filter((id) => id !== caseId);
-      const isDissolving = remaining.length < CLUSTER_MEMBER_FLOOR;
-      const patch = { ...cluster, memberCaseIds: remaining.length ? remaining : cluster.memberCaseIds };
-      if (isDissolving) {
-        patch.status = 'dissolved';
-        patch.dissolvedAt = now;
-        patch.dissolveReason = `cascade: linked case ${caseId} closed`;
-        patch.dissolveCategory = 'linked_case_closed';
-      }
-      const action = isDissolving ? 'dissolved' : 'updated';
-      const changeItems = isDissolving
-        ? [`removed_members:${caseId}`, 'status:active→dissolved', 'dissolve_category:linked_case_closed']
-        : [`removed_members:${caseId}`];
-      const history = [new ClusterHistoryRecord({
-        clusterId: cluster.clusterId,
-        turnId: turnId || '',
-        action,
-        changes: { items: changeItems },
-        transitionReason: `cascade from updateConditionStatus on case ${caseId}`,
-        recordedAt: now,
-      })];
-      await storeCluster({ patientId, cluster: new ClusterImpression(patch), history });
-      (isDissolving ? dissolvedClusters : prunedClusters).push(cluster.clusterId);
-      if (isDissolving) {
-        try {
-          const clusterNets = await readContingencies({ patientId, clusterId: cluster.clusterId });
-          const dissolved = await autoResolveNets({ patientCode: patientId, nets: clusterNets, resolvedReason: RESOLVED_REASONS.LINKED_CLUSTER_DISSOLVED, trace });
-          autoResolvedPlans.push(...dissolved.autoResolvedPlans);
-          cascadeErrors.push(...dissolved.cascadeErrors);
-        } catch (error) {
-          cascadeErrors.push(`contingency_auto_resolve_failed: ${error?.message || error}`);
-        }
-      }
-    } catch (error) {
-      cascadeErrors.push(`cluster_cascade_failed: ${error?.message || error}`);
-    }
-  }
-
-  return { autoResolvedPlans, prunedClusters, dissolvedClusters, cascadeErrors };
-}
-
 async function handler(args = {}, context = {}) {
   try {
     const runtime = context?.toolRuntimeContext || null;
@@ -230,6 +124,12 @@ async function handler(args = {}, context = {}) {
     const transition = (typeof args?.transition === 'string' ? args.transition : '').trim().toLowerCase();
     const reasoning = (typeof args?.reasoning === 'string' ? args.reasoning : '').trim();
     if (!caseId) return fail('case_id is required');
+    if (transition === 'new_episode') {
+      return fail('new_episode is not a status transition — use recordClinicalImpression', {
+        case_id: caseId,
+        recovery: 'call recordClinicalImpression with event=\'new_episode\', episode_id, mention_id, missing_for_higher_grade and a grade_estimate or trajectory_direction, so the new episode carries its own grade',
+      });
+    }
     if (!TRANSITIONS.includes(transition)) {
       return fail(`unknown transition: '${transition}'. Must be one of ${TRANSITIONS.join(' | ')}.`);
     }
@@ -240,13 +140,6 @@ async function handler(args = {}, context = {}) {
     const existing = cases.find((symptomCase) => symptomCase.condition.conditionId === caseId);
     if (!existing) return fail('case_not_found_or_wrong_patient', { case_id: caseId });
 
-    if (transition === 'new_episode') {
-      const result = applyNewEpisode(existing, reasoning, args);
-      if (typeof result === 'string') return result;
-      await storeSymptomCase({ patientId, managedSymptom: result });
-      return JSON.stringify({ success: true, data: { case_id: result.condition.conditionId, status: returnedStatus(result.condition) } });
-    }
-
     if (transition === 'resolve_episode') {
       const result = applyResolveEpisode(existing, reasoning, args);
       if (typeof result === 'string') return result;

package/package.json

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