@peopl-health/nexus 5.10.0-dev.1064 → 5.10.0-dev.1066

package/lib/clinical/tools/registerClinicalTools.js

@@ -16,6 +16,7 @@ const TOOLS = [
   require('./submitRoutingDecisionTool'),
   require('./openConditionTool'),
   require('./recordClinicalImpressionTool'),
+  require('./updateConditionStatusTool'),
   require('./getActiveSymptomLandscapeTool'),
   require('./recordInterventionTool'),
   require('./setContingencyPlanTool'),

package/lib/clinical/tools/updateConditionStatusTool.js

@@ -0,0 +1,294 @@
+const { readSymptomCases, storeSymptomCase, readContingencies, storeContingency, readClusters, storeCluster } = require('../../fhir');
+const { ManagedSymptom } = require('../../shared/dtos/ManagedSymptom');
+const { RESOLUTION_CLOSE_REASONS } = require('../../fhir/resources/Condition');
+const { ContingencySafetyNet, ACTIVE_CARE_PLAN_STATUSES } = require('../../shared/dtos/ContingencySafetyNet');
+const { ClusterImpression } = require('../../shared/dtos/ClusterImpression');
+const { ClusterHistoryRecord } = require('../../shared/dtos/ClusterHistoryRecord');
+const { logger } = require('../../utils/logger');
+
+const DEACTIVATE_CLOSE_REASONS = ['escalated_to_team', 'patient_transferred', 'stale_no_activity'];
+const OPEN_STATUSES = ['characterizing', 'monitoring'];
+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).',
+  strict: false,
+  parameters: {
+    type: 'object',
+    properties: {
+      case_id: {
+        type: 'string',
+        description: 'The case_id whose Condition lifecycle changes (from openCondition or getActiveSymptomLandscape).',
+      },
+      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).',
+      },
+      reasoning: {
+        type: 'string',
+        description: 'Required. One short sentence justifying this lifecycle transition — persisted to the Condition\'s audit record.',
+      },
+      episode_id: {
+        type: 'string',
+        description: 'Required for new_episode (a genuinely-new episode) and reactivate (the new bout\'s intake episode).',
+      },
+      close_reason: {
+        type: 'string',
+        description: 'Required for deactivate. One of escalated_to_team | patient_transferred | stale_no_activity.',
+      },
+      temporality: {
+        type: 'string',
+        description: 'Optional. Pass only when temporality changed with this transition.',
+      },
+    },
+    required: ['case_id', 'transition', 'reasoning'],
+  },
+};
+
+const TRANSITIONS = definition.parameters.properties.transition.enum;
+
+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') {
+    return isResolutionReason(condition.closeReason) ? 'resolved' : 'inactive';
+  }
+  return clinicalStatus;
+}
+
+function isDormant(condition) {
+  return ['closed', 'resolved', 'inactive'].includes(condition.clinicalStatus);
+}
+
+function toManaged(existing, conditionPatch) {
+  const condition = { ...existing.condition, ...conditionPatch };
+  return new ManagedSymptom({
+    condition,
+    latestAssessment: existing.latestAssessment,
+    priorAssessments: existing.priorAssessments,
+  });
+}
+
+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 });
+  }
+  const patch = { clinicalStatus: 'monitoring', currentEpisodeId: null, lastTransitionReason: reasoning };
+  if (typeof args?.temporality === 'string') patch.temporality = args.temporality;
+  return toManaged(existing, patch);
+}
+
+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,
+  };
+  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 });
+  }
+  const episodeId = (typeof args?.episode_id === 'string' ? args.episode_id : '').trim();
+  if (!episodeId) return fail('reactivate requires episode_id');
+  const wasResolved = existing.condition.clinicalStatus === 'resolved'
+    || (existing.condition.clinicalStatus === 'closed' && isResolutionReason(existing.condition.closeReason));
+  const evidenceEpisodeIds = existing.condition.evidenceEpisodeIds.includes(episodeId)
+    ? [...existing.condition.evidenceEpisodeIds]
+    : [...existing.condition.evidenceEpisodeIds, episodeId];
+  const patch = {
+    clinicalStatus: 'characterizing',
+    abatementAt: null,
+    closeReason: null,
+    currentEpisodeId: episodeId,
+    evidenceEpisodeIds,
+    reactivatedAt: new Date().toISOString(),
+    lastTransitionReason: reasoning,
+  };
+  if (wasResolved) patch.recurrenceCount = (existing.condition.recurrenceCount || 0) + 1;
+  if (typeof args?.temporality === 'string') patch.temporality = args.temporality;
+  return { managed: toManaged(existing, patch), wasResolved };
+}
+
+async function runCloseCascade(patientId, caseId, turnId) {
+  const autoResolvedPlans = [];
+  const prunedClusters = [];
+  const dissolvedClusters = [];
+  const cascadeErrors = [];
+  const now = new Date().toISOString();
+
+  try {
+    const nets = await readContingencies({ patientId, caseId });
+    const active = nets.find((net) => ACTIVE_CARE_PLAN_STATUSES.includes(net.carePlan.status));
+    if (active) {
+      const contingency = new ContingencySafetyNet({
+        ...active,
+        carePlan: { ...active.carePlan, status: 'auto_resolved', resolvedAt: now, resolvedReason: 'linked_case_closed' },
+      });
+      await storeContingency({ patientId, contingency });
+      autoResolvedPlans.push(active.carePlan.planId);
+    }
+  } 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 dissolving = remaining.length < CLUSTER_MEMBER_FLOOR;
+      const patch = { ...cluster, memberCaseIds: remaining.length ? remaining : cluster.memberCaseIds };
+      if (dissolving) {
+        patch.status = 'dissolved';
+        patch.dissolvedAt = now;
+        patch.dissolveReason = `cascade: linked case ${caseId} closed`;
+        patch.dissolveCategory = 'linked_case_closed';
+      }
+      const action = dissolving ? 'dissolved' : 'updated';
+      const changeItems = dissolving
+        ? [`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 });
+      (dissolving ? dissolvedClusters : prunedClusters).push(cluster.clusterId);
+    } 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;
+    if (!runtime?.turnId || !runtime?.patientCode) {
+      return JSON.stringify({ success: false, error: 'updateConditionStatus requires an active turn context (turnId, patientCode).', data: {} });
+    }
+    const caseId = (typeof args?.case_id === 'string' ? args.case_id : '').trim();
+    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 (!TRANSITIONS.includes(transition)) {
+      return fail(`unknown transition: '${transition}'. Must be one of ${TRANSITIONS.join(' | ')}.`);
+    }
+    if (!reasoning) return fail('reasoning is required — one short sentence justifying this lifecycle transition.');
+
+    const patientId = runtime.patientCode;
+    const cases = await readSymptomCases({ patientId });
+    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;
+      await storeSymptomCase({ patientId, managedSymptom: result });
+      return JSON.stringify({ success: true, data: { case_id: result.condition.conditionId, status: returnedStatus(result.condition) } });
+    }
+
+    if (transition === 'reactivate') {
+      const result = applyReactivate(existing, reasoning, args);
+      if (typeof result === 'string') return result;
+      await storeSymptomCase({ patientId, managedSymptom: result.managed });
+      return JSON.stringify({
+        success: true,
+        data: {
+          case_id: result.managed.condition.conditionId,
+          status: returnedStatus(result.managed.condition),
+          is_recurrence: result.wasResolved,
+          recurrence_count: result.managed.condition.recurrenceCount || 0,
+        },
+      });
+    }
+
+    const result = applyDormant(existing, reasoning, args, transition === 'resolve');
+    if (typeof result === 'string') return result;
+    await storeSymptomCase({ patientId, managedSymptom: result });
+    const cascade = await runCloseCascade(patientId, result.condition.conditionId, runtime.turnId);
+    const data = {
+      case_id: result.condition.conditionId,
+      status: returnedStatus(result.condition),
+      abatement_at: result.condition.abatementAt,
+    };
+    if (cascade.autoResolvedPlans.length) data.auto_resolved_plans = cascade.autoResolvedPlans;
+    if (cascade.prunedClusters.length) data.pruned_clusters = cascade.prunedClusters;
+    if (cascade.dissolvedClusters.length) data.dissolved_clusters = cascade.dissolvedClusters;
+    if (cascade.cascadeErrors.length) {
+      data.cascade_errors = cascade.cascadeErrors;
+      logger.warn({ caseId: result.condition.conditionId, cascadeErrors: cascade.cascadeErrors }, 'updateConditionStatus close cascade errors');
+    }
+    return JSON.stringify({ success: true, data });
+  } catch (err) {
+    return JSON.stringify({ success: false, error: err?.message || 'updateConditionStatus failed', data: {} });
+  }
+}
+
+module.exports = {
+  definition,
+  handler,
+};

package/lib/fhir/resources/Condition.js

@@ -136,4 +136,4 @@ class Condition {
   }
 }
 
-module.exports = { Condition };
+module.exports = { Condition, RESOLUTION_CLOSE_REASONS };

package/lib/shared/dtos/ManagedSymptom.js

@@ -35,14 +35,14 @@ const symptomConditionSchema = z.strictObject({
   recurrenceCount: z.number().int().nonnegative().default(0),
   reactivatedAt: dateTime.nullable().default(null),
 })
-  .refine((c) => !c.closeReason || c.abatementAt !== null, {
-    message: 'closeReason requires abatementAt',
-  })
   .refine((c) => c.abatementAt === null || ['resolved', 'inactive', 'closed'].includes(c.clinicalStatus), {
     message: 'abatementAt requires a terminal clinicalStatus (resolved/inactive/closed)',
   })
   .refine((c) => c.abatementAt === null || new Date(c.abatementAt) >= new Date(c.onsetAt), {
     message: 'abatementAt must be >= onsetAt',
+  })
+  .refine((c) => !c.closeReason || c.clinicalStatus === 'closed', {
+    message: 'closeReason requires clinicalStatus=closed',
   });
 
 const symptomAssessmentSchema = z.strictObject({

package/package.json

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