@peopl-health/nexus 5.10.0-dev.1092 → 5.10.0-dev.1093

package/lib/clinical/tools/submitRoutingDecisionTool.js

@@ -79,14 +79,14 @@ const _DOWNSTREAM_SKILL = {
 
 const definition = {
   name: 'submitRoutingDecision',
-  description: '**Does:** The terminal routing checkpoint — call ONCE per turn to commit the turn plan. Decomposes `trace` (the per-mention evaluation record) and `turn_plan` (the primary action + optional secondary/deferred) into a persisted RoutingDecision (assessment + disposition + provenance), sets the turn\'s outbound signals, and hands the agent the next skill to invoke.\n\n**Required inputs:** `trace.mentions_evaluated[]` — one entry per clinical mention: `case_id_opened_or_updated`, `clinical_reasoning`, `decision.action`, plus `safety_flag_disposition` when `safety_flags_received` is non-empty. `turn_plan.primary` — exactly one `{action, reason, case_id?}`; `turn_plan.secondary[]` — up to 2 `{action, compose_as}`; `turn_plan.deferred[]` — optional `{item?, defer_reason}`.\n\n**Enum coercion:** primary/secondary `action` and secondary `compose_as` are folded (case/accent/separator) and synonym-mapped to canonical values; each repair is disclosed via `auto_repairs`. A genuinely unknown action is rejected.\n\n**Returns:** `decision_id`, `downstream_skill_to_invoke` (emergency | accompaniment | symptom_management | patient_education | null, derived from `primary.action`), and `auto_repairs` (only when non-empty). Fails hard with `decision_already_committed_for_turn` if called twice in one turn.\n\n**Side effects:** persists the RoutingDecision; sets `branch_taken=ai_agent` on the turn trace.',
+  description: '**Does:** The terminal routing checkpoint — call ONCE per turn to commit the turn plan. Decomposes `trace` (the per-mention evaluation record) and `turn_plan` (the primary action + optional secondary/deferred) into a persisted RoutingDecision (assessment + disposition + provenance), sets the turn\'s outbound signals, and hands the agent the next skill to invoke.\n\n**Required inputs:** `trace.mentions_evaluated[]` — one entry per clinical mention: `clinical_reasoning`, `decision.action`, `case_id_opened_or_updated` (null when the mention opened no case), plus `safety_flag_disposition` (string or object) when `safety_flags_received` is non-empty. `turn_plan.primary` — exactly one `{action, reason, case_id?}`; `turn_plan.secondary[]` — up to 2 `{action, compose_as}`; `turn_plan.deferred[]` — optional `{item?, defer_reason}`.\n\n**Enum coercion:** primary/secondary `action` and secondary `compose_as` are folded (case/accent/separator) and synonym-mapped to canonical values; each repair is disclosed via `auto_repairs`. A genuinely unknown action is rejected.\n\n**Returns:** `decision_id`, `downstream_skill_to_invoke` (emergency | accompaniment | symptom_management | patient_education | null, derived from `primary.action`), and `auto_repairs` (only when non-empty). Fails hard with `decision_already_committed_for_turn` if called twice in one turn.\n\n**Side effects:** persists the RoutingDecision; sets `branch_taken=ai_agent` on the turn trace.',
   strict: false,
   parameters: {
     type: 'object',
     properties: {
       trace: {
         type: 'object',
-        description: 'Per-mention evaluation record. `mentions_evaluated[]`: each `{case_id_opened_or_updated, clinical_reasoning, decision:{action}, safety_flags_received?, safety_flag_disposition?}`. A safety_flag_disposition is required for any mention with a non-empty safety_flags_received.',
+        description: 'Per-mention evaluation record. `mentions_evaluated[]`: each `{case_id_opened_or_updated?, clinical_reasoning, decision:{action}, safety_flags_received?, safety_flag_disposition?}`. `case_id_opened_or_updated` is null/omitted when the mention opened or updated no case (e.g. a medication, appointment, allergy or emotion mention). `safety_flag_disposition` is required for any mention with a non-empty `safety_flags_received`, and may be a short string (e.g. `acknowledged`, `escalated`) or an object.',
       },
       turn_plan: {
         type: 'object',
@@ -184,8 +184,8 @@ function validateTrace(trace) {
   for (let i = 0; i < mentionsRaw.length; i += 1) {
     const mention = mentionsRaw[i];
     if (!mention || typeof mention !== 'object' || Array.isArray(mention)) return { error: fail('trace.mentions_evaluated[*] must be objects', { index: i }) };
-    const caseId = (typeof mention.case_id_opened_or_updated === 'string' ? mention.case_id_opened_or_updated.trim() : '');
-    if (!caseId) return { error: fail(`mentions_evaluated[${i}].case_id_opened_or_updated is required`, { index: i }) };
+    // A non-symptom mention (medication, appointment, allergy, emotion) opens no case, so case_id is optional; null records the absence.
+    const caseId = (typeof mention.case_id_opened_or_updated === 'string' ? mention.case_id_opened_or_updated.trim() : '') || null;
     const reasoning = typeof mention.clinical_reasoning === 'string' ? mention.clinical_reasoning.trim() : '';
     if (!reasoning) return { error: fail(`mentions_evaluated[${i}].clinical_reasoning is required`, { index: i }) };
     let decision = mention.decision;
@@ -200,8 +200,14 @@ function validateTrace(trace) {
       return { error: fail(`mentions_evaluated[${i}].safety_flags_received must be a list`, { index: i }) };
     }
     if (Array.isArray(flags) && flags.length) {
-      const disposition = mention.safety_flag_disposition;
-      if (!disposition || typeof disposition !== 'object' || Array.isArray(disposition)) {
+      // Accept the model's most common shape — a plain string ('acknowledged', 'escalated') — as well as an object.
+      const disposition = typeof mention.safety_flag_disposition === 'string'
+        ? mention.safety_flag_disposition.trim()
+        : mention.safety_flag_disposition;
+      const dispositionGiven = typeof disposition === 'string'
+        ? disposition.length > 0
+        : (disposition && typeof disposition === 'object' && !Array.isArray(disposition));
+      if (!dispositionGiven) {
         return { error: fail(`mentions_evaluated[${i}].safety_flag_disposition is required when safety_flags_received is non-empty`, { index: i, mention_id: mention.mention_id }) };
       }
     }

package/lib/fhir/resources/ClinicalImpression.js

@@ -118,14 +118,21 @@ class ClinicalImpression {
       status: 'completed',
       subject: patientReference(assessment.patientId),
       effectiveDateTime: toIso(assessment.performedAt),
-      finding: assessment.findings.map((finding) => ({
-        item: reference('Condition', finding.caseId),
-        extension: [
-          extension('routing-finding-case-id', { valueString: finding.caseId }),
+      finding: assessment.findings.map((finding) => {
+        const findingExts = [];
+        const projected = {};
+        // A caseless mention (caseId null) has no case to point at: no Condition item and no case-id extension, so absence stays absence in the FHIR.
+        if (finding.caseId) {
+          projected.item = reference('Condition', finding.caseId);
+          findingExts.push(extension('routing-finding-case-id', { valueString: finding.caseId }));
+        }
+        findingExts.push(
           extension('routing-finding-reasoning', { valueString: finding.clinicalReasoning }),
           extension('routing-finding-action', { valueString: finding.decisionAction }),
-        ],
-      })),
+        );
+        projected.extension = findingExts;
+        return projected;
+      }),
       extension: extensions,
     };
     if (assessment.summary) payload.summary = assessment.summary;

package/lib/shared/dtos/RoutingDecision.js

@@ -5,7 +5,8 @@ const { BaseDto } = require('./BaseDto');
 const dateTime = z.iso.datetime({ offset: true });
 
 const mentionFindingSchema = z.strictObject({
-  caseId: z.string(),
+  // null when the mention opened/updated no case (medication, appointment, allergy, emotion); absence is stored as absence, not a sentinel.
+  caseId: z.string().nullable().default(null),
   clinicalReasoning: z.string(),
   decisionAction: z.string(),
 });

package/package.json

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