@peopl-health/nexus 5.10.0-dev.1040 → 5.10.0-dev.1043

package/lib/clinical/tools/submitRecommendationPlanTool.js

@@ -0,0 +1,242 @@
+const { ZodError } = require('zod');
+
+const { storeRecommendationPlan, recommendationPlanExists } = require('../../fhir');
+const { RecommendationPlan, recommendationId } = require('../../shared/dtos/RecommendationPlan');
+const { logger } = require('../../utils/logger');
+
+const definition = {
+  name: 'submitRecommendationPlan',
+  description: '**Does:** Commits the symptom plan for THIS turn: ranked elements, each carrying its assessment fields AND its recommendation inline (rank/name/targets cannot diverge — one nested unit). Call ONCE per turn, AFTER submitSafetyGate on a triage turn (a chat turn may plan without a gate). Server-validated: contiguous ranks 1..N; denied symptoms excluded; main_recommendation 2-4 sentences; when_to_escalate ≤90 chars (auto-trimmed at a `;` boundary; required when the element escalates); every element delivers a patient-facing action (main_recommendation, otc_offer, or followup=team_referral); otc_offer only on chat turns and only complete (dose, frequency, duration, warnings) with non-null contraindications. Meds-need is carried solely by `recommendation.is_pharmacological_med_needed`; any element-level `are_meds_needed` is ignored. Repairs are disclosed in `auto_repairs`.\n\n**Required inputs:** `takeaways` (`safety_confirmation_needed`, `vital_risk_possible_now`, `summary_patient_facing`, `summary_internal`) and `elements[]` (each: `rank`, `type`, `name_short`, `targeted_ctcae_terms`, `why_relevant`, `escalation`, `recommendation`).\n\n**Returns:** `accepted`, `run_id`, `element_count`, `recommendation_ids` (rank order — reference these, never invent ids), `palliative_escalation`, `auto_repairs`.\n\n**Side effects:** persists the plan as a run-scoped FHIR ClinicalImpression + CarePlan + one Task per recommendation.',
+  strict: false,
+  parameters: {
+    type: 'object',
+    properties: {
+      takeaways: {
+        type: 'object',
+        description: '`{safety_confirmation_needed, safety_confirmation_question, vital_risk_possible_now, summary_patient_facing, summary_internal}`. `safety_confirmation_question` is exactly one closed yes/no question when needed; null otherwise.',
+      },
+      elements: {
+        type: 'array',
+        description: 'Ranked plan elements (contiguous ranks 1..N). Each: `{rank, type(cluster|individual), name_short, time_window, symptoms[{ctcae_term, grade, verification_status}], targeted_ctcae_terms[], why_relevant, qol_impact, improvement_capacity, escalation{urgent_under_24h, max_action_time_hours, routes[], clinical_criteria}, recommendation{symptoms_patient_facing[], is_pharmacological_med_needed, patient{main_recommendation, when_to_escalate, contraindications, expected_effectiveness}, otc_offer?, followup?, followup_urgency?}, grounded_in[]}`.',
+        items: { type: 'object' },
+      },
+    },
+    required: ['takeaways', 'elements'],
+  },
+};
+
+const str = (value) => (typeof value === 'string' ? value : '');
+const arr = (value) => (Array.isArray(value) ? value : []);
+const strList = (value) => arr(value).map(str).filter(Boolean);
+const num = (value) => (Number.isInteger(value) ? value : null);
+const nullableStr = (value) => str(value).trim() || null;
+const inEnum = (value, values) => (values.includes(str(value).trim()) ? str(value).trim() : null);
+
+const SENTENCE_END = /[.!?](?=\s|$)/g;
+const SENTENCE_PROTECT = /\b(?:\d+\.\d+|p\.\s?ej\.|Dr\.|Dra\.|etc\.)/gi;
+
+function sentenceCount(text) {
+  const protectedText = text.trim().replace(SENTENCE_PROTECT, (match) => match.replace(/\./g, '·'));
+  return (protectedText.match(SENTENCE_END) || []).length;
+}
+
+function trimEscalationText(text) {
+  if (text.length <= 90) return text;
+  let out = '';
+  for (const part of text.split(';').map((piece) => piece.trim()).filter(Boolean)) {
+    const candidate = out ? `${out}; ${part}` : part;
+    if (candidate.length > 90) break;
+    out = candidate;
+  }
+  return out || `${text.slice(0, 89).trimEnd()}…`;
+}
+
+function buildSymptom(raw) {
+  return {
+    ctcaeTerm: str(raw?.ctcae_term).trim(),
+    grade: num(raw?.grade),
+    verificationStatus: str(raw?.verification_status).trim() || 'suspected',
+  };
+}
+
+function buildOtcOffer(raw) {
+  if (!raw || typeof raw !== 'object') return null;
+  return {
+    label: str(raw?.label).trim(),
+    dose: nullableStr(raw?.dose),
+    frequency: nullableStr(raw?.frequency),
+    duration: nullableStr(raw?.duration),
+    warnings: nullableStr(raw?.warnings),
+  };
+}
+
+function buildElement(raw, repairs) {
+  const rawRec = raw?.recommendation || {};
+  const rawPatient = rawRec?.patient || {};
+  const patient = {
+    mainRecommendation: str(rawPatient?.main_recommendation).trim(),
+    whenToEscalate: nullableStr(rawPatient?.when_to_escalate),
+    contraindications: nullableStr(rawPatient?.contraindications),
+    expectedEffectiveness: inEnum(rawPatient?.expected_effectiveness, ['low', 'medium', 'high']),
+  };
+  if (patient.whenToEscalate && patient.whenToEscalate.length > 90) {
+    const trimmed = trimEscalationText(patient.whenToEscalate);
+    repairs.push(`when_to_escalate (rank ${raw?.rank ?? '?'}) recortado de ${patient.whenToEscalate.length} a ≤90 caracteres en límite de criterio`);
+    patient.whenToEscalate = trimmed;
+  }
+  const recommendation = {
+    symptomsPatientFacing: strList(rawRec?.symptoms_patient_facing),
+    isPharmacologicalMedNeeded: rawRec?.is_pharmacological_med_needed === true,
+    patient,
+    otcOffer: buildOtcOffer(rawRec?.otc_offer),
+    followup: inEnum(rawRec?.followup, ['checkin_48h', 'team_referral', 'none']),
+    followupUrgency: nullableStr(rawRec?.followup_urgency),
+  };
+  const rawEsc = raw?.escalation || {};
+  return {
+    rank: num(raw?.rank) || 0,
+    type: str(raw?.type).trim(),
+    nameShort: str(raw?.name_short).trim(),
+    timeWindow: nullableStr(raw?.time_window),
+    symptoms: arr(raw?.symptoms).map(buildSymptom),
+    targetedCtcaeTerms: strList(raw?.targeted_ctcae_terms),
+    whyRelevant: str(raw?.why_relevant).trim(),
+    qolImpact: inEnum(raw?.qol_impact, ['low', 'moderate', 'high']),
+    improvementCapacity: inEnum(raw?.improvement_capacity, ['low', 'moderate', 'high']),
+    escalation: {
+      urgentUnder24h: rawEsc?.urgent_under_24h === true,
+      maxActionTimeHours: num(rawEsc?.max_action_time_hours),
+      routes: strList(rawEsc?.routes),
+      clinicalCriteria: nullableStr(rawEsc?.clinical_criteria),
+    },
+    recommendation,
+    groundedIn: strList(raw?.grounded_in),
+  };
+}
+
+function validate(elements) {
+  const issues = [];
+  const ranks = elements.map((element) => element.rank).sort((a, b) => a - b);
+  const contiguous = ranks.every((rank, index) => rank === index + 1);
+  if (!contiguous) {
+    issues.push({ path: 'elements[].rank', problem: `ranks deben ser contiguos 1..${ranks.length}; recibidos ${ranks.join(', ')}` });
+  }
+  elements.forEach((element, index) => {
+    const path = `elements[${index}]`;
+    const { recommendation } = element;
+    const { patient } = recommendation;
+    for (const symptom of element.symptoms) {
+      if (symptom.verificationStatus === 'denied') {
+        issues.push({ path: `${path}.symptoms`, problem: `síntoma negado (${symptom.ctcaeTerm}) no se incluye` });
+      }
+    }
+    const count = patient.mainRecommendation ? sentenceCount(patient.mainRecommendation) : 0;
+    if (patient.mainRecommendation && !(count >= 2 && count <= 4)) {
+      issues.push({ path: `${path}.recommendation.patient.main_recommendation`, problem: `2-4 oraciones; detectadas: ${count}` });
+    }
+    if (element.escalation.urgentUnder24h && !patient.whenToEscalate) {
+      issues.push({ path: `${path}.recommendation.patient.when_to_escalate`, problem: 'elemento con escalamiento <24h ⇒ when_to_escalate no puede ser null' });
+    }
+    if (!patient.mainRecommendation && recommendation.otcOffer === null && recommendation.followup !== 'team_referral') {
+      issues.push({ path: `${path}.recommendation`, problem: 'sin main_recommendation, sin otc_offer y sin followup=team_referral — el paciente no recibe nada' });
+    }
+    if (recommendation.otcOffer !== null) {
+      for (const field of ['dose', 'frequency', 'duration', 'warnings']) {
+        if (!recommendation.otcOffer[field]) {
+          issues.push({ path: `${path}.recommendation.otc_offer.${field}`, problem: 'los 4 elementos del contrato OTC son obligatorios' });
+        }
+      }
+      if (!patient.contraindications) {
+        issues.push({ path: `${path}.recommendation.patient.contraindications`, problem: 'contraindications no puede ser null con una oferta OTC' });
+      }
+    }
+  });
+  return issues;
+}
+
+async function handler(args = {}, context = {}) {
+  try {
+    const runtime = context?.toolRuntimeContext || null;
+    if (!runtime?.turnId || !runtime?.patientCode) {
+      return JSON.stringify({ success: false, error: 'submitRecommendationPlan requires an active turn context (turnId, patientCode).', data: {} });
+    }
+    const takeaways = args?.takeaways;
+    if (!takeaways || typeof takeaways !== 'object') {
+      return JSON.stringify({ success: false, error: 'takeaways is required.', data: {} });
+    }
+    const rawElements = arr(args?.elements);
+    if (!rawElements.length) {
+      return JSON.stringify({ success: false, error: 'elements is required and must be non-empty.', data: {} });
+    }
+
+    // Nexus is chat-lane-only; the triage safety-gate precondition is Python-deferred.
+    const runId = `recrun-chat-${runtime.turnId}`;
+
+    if (await recommendationPlanExists({ runId })) {
+      return JSON.stringify({ success: false, error: 'plan_already_committed_for_turn', data: { run_id: runId } });
+    }
+
+    const repairs = [];
+    const elements = rawElements.map((raw) => buildElement(raw, repairs));
+    const issues = validate(elements);
+    if (issues.length) {
+      return JSON.stringify({ success: false, error: 'plan_invalid', data: { issues } });
+    }
+
+    const plan = new RecommendationPlan({
+      runId,
+      patientId: runtime.patientCode,
+      turnId: runtime.turnId,
+      takeaways: {
+        safetyConfirmationNeeded: takeaways.safety_confirmation_needed === true,
+        safetyConfirmationQuestion: nullableStr(takeaways.safety_confirmation_question),
+        vitalRiskPossibleNow: takeaways.vital_risk_possible_now === true,
+        summaryPatientFacing: str(takeaways.summary_patient_facing).trim(),
+        summaryInternal: str(takeaways.summary_internal).trim(),
+      },
+      elements,
+      createdAt: new Date().toISOString(),
+    });
+
+    await storeRecommendationPlan({ patientId: runtime.patientCode, plan });
+
+    const ranked = [...plan.elements].sort((a, b) => a.rank - b.rank);
+    const recommendationIds = ranked.map((element) => recommendationId(runId, element.rank));
+    const palliativeEscalation = plan.elements.some((element) => element.escalation.urgentUnder24h);
+
+    const trace = runtime.trace || null;
+    if (trace) {
+      trace.setSignals({
+        recommendationPlan: {
+          runId,
+          elementCount: plan.elements.length,
+          palliativeEscalation,
+        },
+      });
+    } else {
+      logger.warn('[submitRecommendationPlan] no trace on runtime context; plan signal not recorded', { turnId: runtime.turnId });
+    }
+
+    return JSON.stringify({
+      success: true,
+      data: {
+        accepted: true,
+        run_id: runId,
+        element_count: plan.elements.length,
+        recommendation_ids: recommendationIds,
+        palliative_escalation: palliativeEscalation,
+        auto_repairs: repairs,
+      },
+    });
+  } catch (err) {
+    if (err instanceof ZodError) {
+      return JSON.stringify({ success: false, error: 'plan_schema_invalid', data: { issues: err.issues.map((issue) => ({ path: issue.path.join('.'), problem: issue.message })) } });
+    }
+    return JSON.stringify({ success: false, error: err?.message || 'submitRecommendationPlan failed', data: {} });
+  }
+}
+
+module.exports = {
+  definition,
+  handler,
+};

package/lib/fhir/constants/projectionSlugs.js

@@ -10,6 +10,9 @@ const SYMPTOM_ASSESSMENT_SLUG = 'symptom-assessment';
 const SYMPTOM_GRADE_SLUG = 'symptom-grade';
 const PATIENT_RISK_SLUG = 'patient-risk-assessment';
 const SAFETY_GATE_SLUG = 'recommendation-safety';
+const RECOMMENDATION_PLAN_SLUG = 'recommendation-careplan';
+const RECOMMENDATION_ELEMENTS_SLUG = 'recommendation-palliative';
+const RECOMMENDATION_REC_SLUG = 'recommendation-rec';
 const CONTINGENCY_PLAN_SLUG = 'contingency-plan';
 const CONTINGENCY_STEP_SLUG = 'contingency-step';
 const INTERVENTION_SLUG = 'intervention';
@@ -35,6 +38,9 @@ module.exports = {
   SYMPTOM_GRADE_SLUG,
   PATIENT_RISK_SLUG,
   SAFETY_GATE_SLUG,
+  RECOMMENDATION_PLAN_SLUG,
+  RECOMMENDATION_ELEMENTS_SLUG,
+  RECOMMENDATION_REC_SLUG,
   CONTINGENCY_PLAN_SLUG,
   CONTINGENCY_STEP_SLUG,
   INTERVENTION_SLUG,

package/lib/fhir/index.js

@@ -3,6 +3,7 @@ const { storeClinicalMentions } = require('./services/clinicalMentionService');
 const { storeResultObservations } = require('./services/resultObservationService');
 const { storeSymptomCase, readSymptomCases } = require('./services/symptomCaseService');
 const { storePatientRisk, readPatientRisk, storeSafetyGate, safetyGateExists } = require('./services/riskService');
+const { storeRecommendationPlan, recommendationPlanExists } = require('./services/recommendationService');
 const { storeContingency, readContingencies } = require('./services/contingencyService');
 const { storeIntervention, readInterventions } = require('./services/interventionService');
 const { storeCluster, readClusters } = require('./services/clusterService');
@@ -33,6 +34,8 @@ module.exports = {
   readPatientRisk,
   storeSafetyGate,
   safetyGateExists,
+  storeRecommendationPlan,
+  recommendationPlanExists,
   storeContingency,
   readContingencies,
   storeIntervention,

package/lib/fhir/projections/recommendationPlanProjection.js

@@ -0,0 +1,25 @@
+const { ClinicalImpression } = require('../resources/ClinicalImpression');
+const { CarePlan } = require('../resources/CarePlan');
+const { Task } = require('../resources/Task');
+const { Provenance } = require('../resources/Provenance');
+const { recommendationId } = require('../../shared/dtos/RecommendationPlan');
+
+const PROJECTOR_NAME = 'recommendationPlan';
+
+function projectRecommendationPlan({ plan, hasSafetyGate }) {
+  const ranked = [...plan.elements].sort((a, b) => a.rank - b.rank);
+  const taskIds = ranked.map((element) => recommendationId(plan.runId, element.rank));
+  const impression = ClinicalImpression.fromRecommendationPlan({ plan });
+  const carePlan = CarePlan.fromRecommendationPlan({ plan, taskIds, hasSafetyGate });
+  const tasks = ranked.map((element, index) => Task.fromRecommendationPlan({ plan, element, taskId: taskIds[index] }));
+  const targetRefs = [impression, carePlan, ...tasks].map(
+    (resource) => ({ reference: `${resource.resourceType}/${resource.id}` }),
+  );
+  const provenance = Provenance.fromRecommendationPlan({ plan, targetRefs });
+  return [impression, carePlan, ...tasks, provenance];
+}
+
+module.exports = {
+  projectRecommendationPlan,
+  PROJECTOR_NAME,
+};

package/lib/fhir/projections/registerProjectors.js

@@ -5,6 +5,7 @@ const { projectReminder, PROJECTOR_NAME: REMINDER_PROJECTOR_NAME } = require('./
 const { projectSymptomCase, PROJECTOR_NAME: SYMPTOM_CASE_PROJECTOR_NAME } = require('./symptomCaseProjection');
 const { projectPatientRisk, PROJECTOR_NAME: RISK_PROJECTOR_NAME } = require('./riskProjection');
 const { projectSafetyGate, PROJECTOR_NAME: SAFETY_GATE_PROJECTOR_NAME } = require('./safetyGateProjection');
+const { projectRecommendationPlan, PROJECTOR_NAME: RECOMMENDATION_PLAN_PROJECTOR_NAME } = require('./recommendationPlanProjection');
 const { projectContingency, PROJECTOR_NAME: CONTINGENCY_PROJECTOR_NAME } = require('./contingencyProjection');
 const { projectIntervention, PROJECTOR_NAME: INTERVENTION_PROJECTOR_NAME } = require('./interventionProjection');
 const { projectCluster, PROJECTOR_NAME: CLUSTER_PROJECTOR_NAME } = require('./clusterProjection');
@@ -18,6 +19,7 @@ const PROJECTORS = [
   { name: SYMPTOM_CASE_PROJECTOR_NAME, project: projectSymptomCase },
   { name: RISK_PROJECTOR_NAME, project: projectPatientRisk },
   { name: SAFETY_GATE_PROJECTOR_NAME, project: projectSafetyGate },
+  { name: RECOMMENDATION_PLAN_PROJECTOR_NAME, project: projectRecommendationPlan },
   { name: CONTINGENCY_PROJECTOR_NAME, project: projectContingency },
   { name: INTERVENTION_PROJECTOR_NAME, project: projectIntervention },
   { name: CLUSTER_PROJECTOR_NAME, project: projectCluster },

package/lib/fhir/resources/CarePlan.js

@@ -7,7 +7,7 @@ const {
   extension,
   toIso,
 } = require('../helpers/elementHelper');
-const { CONTINGENCY_PLAN_SLUG, ROUTING_DISPOSITION_SLUG } = require('../constants/projectionSlugs');
+const { CONTINGENCY_PLAN_SLUG, ROUTING_DISPOSITION_SLUG, RECOMMENDATION_PLAN_SLUG } = require('../constants/projectionSlugs');
 
 const CONTINGENCY_STATUS_TO_FHIR = {
   armed: 'active',
@@ -45,6 +45,28 @@ class CarePlan {
     return new CarePlan(payload);
   }
 
+  static fromRecommendationPlan({ plan, taskIds, hasSafetyGate }) {
+    const payload = {
+      resourceType: 'CarePlan',
+      id: fhirId(`${plan.runId}-careplan`),
+      identifier: [identifier(RECOMMENDATION_PLAN_SLUG, `${plan.runId}-careplan`)],
+      status: 'active',
+      intent: 'plan',
+      category: [codeableConcept('symptom_management')],
+      subject: patientReference(plan.patientId),
+      created: toIso(plan.createdAt),
+      activity: taskIds.map((taskId) => ({
+        plannedActivityReference: reference('Task', taskId),
+      })),
+    };
+    if (hasSafetyGate) {
+      payload.supportingInfo = [reference('RiskAssessment', `${plan.runId}-safety`)];
+    }
+    if (plan.takeaways.summaryInternal) payload.description = plan.takeaways.summaryInternal;
+    if (plan.takeaways.summaryPatientFacing) payload.note = [{ text: plan.takeaways.summaryPatientFacing }];
+    return new CarePlan(payload);
+  }
+
   static fromRoutingDisposition({ disposition }) {
     const payload = {
       resourceType: 'CarePlan',

package/lib/fhir/resources/ClinicalImpression.js

@@ -1,6 +1,6 @@
 const { fhirId } = require('../helpers/fhirHelper');
 const { identifier, reference, patientReference, codeableConcept, extension, toIso } = require('../helpers/elementHelper');
-const { SYMPTOM_ASSESSMENT_SLUG, CLUSTER_IMPRESSION_SLUG, CLUSTER_LABEL_SLUG, ROUTING_ASSESSMENT_SLUG, PALLIATIVE_ASSESSMENT_SLUG } = require('../constants/projectionSlugs');
+const { SYMPTOM_ASSESSMENT_SLUG, CLUSTER_IMPRESSION_SLUG, CLUSTER_LABEL_SLUG, ROUTING_ASSESSMENT_SLUG, RECOMMENDATION_ELEMENTS_SLUG, PALLIATIVE_ASSESSMENT_SLUG } = require('../constants/projectionSlugs');
 
 const CLUSTER_STATUS_TO_FHIR = { active: 'in-progress', dissolved: 'completed' };
 const CLUSTER_LIST_SEPARATOR = '; ';
@@ -76,6 +76,30 @@ class ClinicalImpression {
     return new ClinicalImpression(payload);
   }
 
+  static fromRecommendationPlan({ plan }) {
+    const finding = [...plan.elements]
+      .sort((a, b) => a.rank - b.rank)
+      .map((element) => {
+        const basis = [`rank: ${element.rank}`, `tipo: ${element.type}`];
+        if (element.qolImpact) basis.push(`QoL: ${element.qolImpact}`);
+        if (element.whyRelevant) basis.push(`relevancia: ${element.whyRelevant}`);
+        const grounding = element.groundedIn.filter(Boolean).join('; ');
+        if (grounding) basis.push(`sustento: ${grounding}`);
+        return { item: { concept: codeableConcept(element.nameShort) }, basis: basis.join('; ') };
+      });
+    const payload = {
+      resourceType: 'ClinicalImpression',
+      id: fhirId(`${plan.runId}-palliative`),
+      identifier: [identifier(RECOMMENDATION_ELEMENTS_SLUG, `${plan.runId}-palliative`)],
+      status: 'completed',
+      subject: patientReference(plan.patientId),
+      effectiveDateTime: toIso(plan.createdAt),
+      finding,
+    };
+    if (plan.takeaways.summaryInternal) payload.summary = plan.takeaways.summaryInternal;
+    return new ClinicalImpression(payload);
+  }
+
   static fromRoutingAssessment({ assessment, decisionId, committedAt, deferredItems = [], primaryCaseId = null }) {
     const extensions = [
       extension('routing-turn-id', { valueString: assessment.turnId }),

package/lib/fhir/resources/Provenance.js

@@ -98,6 +98,17 @@ class Provenance {
     });
   }
 
+  static fromRecommendationPlan({ plan, targetRefs }) {
+    return new Provenance({
+      resourceType: 'Provenance',
+      id: fhirId(`${plan.runId}-careplan-prov`),
+      target: targetRefs,
+      recorded: toIso(plan.createdAt),
+      agent: [{ who: reference('Device', getDeviceId()), onBehalfOf: reference('Organization', getOrganizationId()) }],
+      activity: codeableConcept('recommendations-process'),
+    });
+  }
+
   static fromContingency({ planId, recipients, recordedAt, activityText }) {
     const targets = [{ reference: `CarePlan/${fhirId(planId)}` }];
     for (const recipient of recipients) {

package/lib/fhir/resources/Task.js

@@ -16,6 +16,7 @@ const {
   INTERVENTION_KIND_SLUG,
   INTERVENTION_OUTCOME_SLUG,
   ROUTING_DISPOSITION_SLUG,
+  RECOMMENDATION_REC_SLUG,
   PALLIATIVE_ESCALATION_SLUG,
 } = require('../constants/projectionSlugs');
 const { SEVERITY_TO_PRIORITY } = require('../constants/severityPriority');
@@ -84,6 +85,36 @@ class Task {
     return new Task(payload);
   }
 
+  static fromRecommendationPlan({ plan, element, taskId }) {
+    const { recommendation } = element;
+    const { patient } = recommendation;
+    const code = {
+      text: element.nameShort,
+      coding: element.targetedCtcaeTerms.map((term) => ({
+        system: codeSystemUrl('pro-ctcae'), code: term, display: term,
+      })),
+    };
+    const noteTexts = [];
+    if (patient.whenToEscalate) noteTexts.push(`cuándo escalar: ${patient.whenToEscalate}`);
+    if (patient.expectedEffectiveness) noteTexts.push(`efectividad esperada: ${patient.expectedEffectiveness}`);
+    if (patient.contraindications) noteTexts.push(`contraindicaciones: ${patient.contraindications}`);
+    noteTexts.push(`requiere coordinación farmacológica: ${recommendation.isPharmacologicalMedNeeded}`);
+    const payload = {
+      resourceType: 'Task',
+      id: fhirId(taskId),
+      identifier: [identifier(RECOMMENDATION_REC_SLUG, taskId)],
+      status: 'requested',
+      intent: 'plan',
+      code,
+      description: patient.mainRecommendation,
+      for: patientReference(plan.patientId),
+      authoredOn: toIso(plan.createdAt),
+      requester: reference('Device', getDeviceId()),
+      note: noteTexts.map((text) => ({ text })),
+    };
+    return new Task(payload);
+  }
+
   static fromPalliativeEscalation({ assessmentId, committedAt, finding, deviceId }) {
     const { escalation } = finding;
     const start = new Date(committedAt);

package/lib/fhir/services/recommendationService.js

@@ -0,0 +1,27 @@
+const { fhirId } = require('../helpers/fhirHelper');
+const { PROJECTOR_NAME } = require('../projections/recommendationPlanProjection');
+const { getFhirStore } = require('../stores/fhirStore');
+const { project, storeResources } = require('./fhirService');
+
+async function storeRecommendationPlan({ patientId, plan }) {
+  if (plan.patientId !== patientId) {
+    throw new Error(`storeRecommendationPlan patientId mismatch: expected ${patientId}`);
+  }
+  const store = getFhirStore();
+  const gate = await store.getByReference(`RiskAssessment/${fhirId(`${plan.runId}-safety`)}`);
+  const bundle = project([{ name: PROJECTOR_NAME, aggregate: { plan, hasSafetyGate: Boolean(gate) } }]);
+  const resources = bundle.entry.map((entry) => entry.resource);
+  const { stored } = await storeResources(resources);
+  return { count: stored.length, ids: stored };
+}
+
+async function recommendationPlanExists({ runId }) {
+  const store = getFhirStore();
+  const resource = await store.getByReference(`Provenance/${fhirId(`${runId}-careplan-prov`)}`);
+  return Boolean(resource);
+}
+
+module.exports = {
+  storeRecommendationPlan,
+  recommendationPlanExists,
+};

package/lib/shared/dtos/RecommendationPlan.js

@@ -0,0 +1,109 @@
+const { z } = require('zod');
+
+const { BaseDto } = require('./BaseDto');
+
+const dateTime = z.iso.datetime({ offset: true });
+
+const ELEMENT_TYPES = ['cluster', 'individual'];
+const SYMPTOM_STATUSES = ['confirmed', 'suspected', 'denied'];
+const PALLIATIVE_ROUTES = ['equipo_medico_tratante', 'abordaje_onco_nutricion', 'abordaje_psico_onco'];
+const QOL_CATEGORIES = ['low', 'moderate', 'high'];
+const EFFECTIVENESS = ['low', 'medium', 'high'];
+const FOLLOWUP_TYPES = ['checkin_48h', 'team_referral', 'none'];
+
+const symptomSchema = z.strictObject({
+  ctcaeTerm: z.string(),
+  grade: z.number().int().min(1).max(5).nullable().default(null),
+  verificationStatus: z.enum(SYMPTOM_STATUSES),
+});
+
+const escalationSchema = z.strictObject({
+  urgentUnder24h: z.boolean().default(false),
+  maxActionTimeHours: z.number().int().min(1).max(24).nullable().default(null),
+  routes: z.array(z.enum(PALLIATIVE_ROUTES)).default([]),
+  clinicalCriteria: z.string().nullable().default(null),
+});
+
+const otcOfferSchema = z.strictObject({
+  label: z.string(),
+  dose: z.string().nullable().default(null),
+  frequency: z.string().nullable().default(null),
+  duration: z.string().nullable().default(null),
+  warnings: z.string().nullable().default(null),
+});
+
+const patientSchema = z.strictObject({
+  mainRecommendation: z.string(),
+  whenToEscalate: z.string().nullable().default(null),
+  contraindications: z.string().nullable().default(null),
+  expectedEffectiveness: z.enum(EFFECTIVENESS),
+});
+
+const recommendationSchema = z.strictObject({
+  symptomsPatientFacing: z.array(z.string()).min(1).max(6),
+  isPharmacologicalMedNeeded: z.boolean(),
+  patient: patientSchema,
+  otcOffer: otcOfferSchema.nullable().default(null),
+  followup: z.enum(FOLLOWUP_TYPES).nullable().default(null),
+  followupUrgency: z.string().nullable().default(null),
+});
+
+const elementSchema = z.strictObject({
+  rank: z.number().int().min(1),
+  type: z.enum(ELEMENT_TYPES),
+  nameShort: z.string(),
+  timeWindow: z.string().nullable().default(null),
+  symptoms: z.array(symptomSchema).default([]),
+  targetedCtcaeTerms: z.array(z.string()).min(1),
+  whyRelevant: z.string(),
+  qolImpact: z.enum(QOL_CATEGORIES).nullable().default(null),
+  improvementCapacity: z.enum(QOL_CATEGORIES).nullable().default(null),
+  escalation: escalationSchema,
+  recommendation: recommendationSchema,
+  groundedIn: z.array(z.string()).default([]),
+});
+
+const takeawaysSchema = z.strictObject({
+  safetyConfirmationNeeded: z.boolean().default(false),
+  safetyConfirmationQuestion: z.string().nullable().default(null),
+  vitalRiskPossibleNow: z.boolean().default(false),
+  summaryPatientFacing: z.string(),
+  summaryInternal: z.string(),
+})
+  .refine(
+    (t) => !t.safetyConfirmationNeeded || Boolean(t.safetyConfirmationQuestion && t.safetyConfirmationQuestion.trim()),
+    { path: ['safetyConfirmationQuestion'], message: 'safetyConfirmationNeeded=true ⇒ exactamente 1 pregunta cerrada' },
+  )
+  .refine(
+    (t) => t.safetyConfirmationNeeded || !t.safetyConfirmationQuestion,
+    { path: ['safetyConfirmationQuestion'], message: 'safetyConfirmationNeeded=false ⇒ null' },
+  );
+
+const schema = z.strictObject({
+  schemaVersion: z.string().default('1'),
+  runId: z.string(),
+  patientId: z.string(),
+  origin: z.enum(['chat', 'triage']).default('chat'),
+  turnId: z.string(),
+  takeaways: takeawaysSchema,
+  elements: z.array(elementSchema).min(1),
+  createdAt: dateTime,
+});
+
+class RecommendationPlan extends BaseDto {}
+
+RecommendationPlan.schema = schema;
+
+const FHIR_ID_MAX = 64;
+
+const fhirSafe = (value) => String(value).replace(/[^A-Za-z0-9.-]/g, '-');
+
+const recommendationId = (runId, rank) => {
+  const suffix = `-rec${fhirSafe(rank)}`;
+  return `${fhirSafe(runId).slice(0, FHIR_ID_MAX - suffix.length)}${suffix}`;
+};
+
+module.exports = {
+  RecommendationPlan,
+  recommendationId,
+};

package/package.json

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