@peopl-health/nexus 6.3.1 → 6.4.0-dev.18676

package/lib/clinical/helpers/doctorPlanHelper.js

@@ -0,0 +1,193 @@
+const { httpError } = require('../../utils/httpErrorUtils');
+const { oneLineOf } = require('../../utils/coercionUtils');
+const { PLAN_FOLLOW_UPS } = require('../../models/escalationReviewModel');
+
+const DEFAULT_FOLLOW_UP_HOURS = { check_in: 24, vigilancia: 48 };
+const FIRST_LINE = '1L';
+const MAX_ENTRIES = 10;
+const MAX_FIELD_LENGTH = 300;
+const MAX_NOTE_LENGTH = 1000;
+const MAX_INSTRUCTIONS_LENGTH = 4000;
+const MAX_DAYS = 90;
+const MAX_FOLLOW_UP_HOURS = 168;
+// A route is not a dose: the doctor still says how many tablets.
+const ROUTE_ONLY = /^(vo|v[ií]a oral|oral)$/i;
+
+const textOf = (value, name, max = MAX_FIELD_LENGTH) => {
+  if (value != null && typeof value !== 'string') throw httpError(400, `${name} must be text`);
+  const text = oneLineOf(value);
+  if (text.length > max) throw httpError(400, `${name} exceeds ${max} characters`);
+  return text || null;
+};
+
+const neededText = (value, name) => {
+  const text = textOf(value, name);
+  if (!text) throw httpError(400, `${name} is required`);
+  return text;
+};
+
+const isPlainObject = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+
+// Only a number or a string of digits: `true`, `[5]` and `'1e1'` are not days.
+const wholeNumber = (value, name, max) => {
+  const number = typeof value === 'number' || (typeof value === 'string' && /^\d+$/.test(value.trim())) ? Number(value) : NaN;
+  if (!Number.isInteger(number) || number < 1 || number > max) throw httpError(400, `${name} must be a whole number from 1 to ${max}`);
+  return number;
+};
+
+const listOf = (value, name) => {
+  if (value == null) return [];
+  if (!Array.isArray(value)) throw httpError(400, `${name} must be a list`);
+  if (value.length > MAX_ENTRIES) throw httpError(400, `${name} allows at most ${MAX_ENTRIES} entries`);
+  return value;
+};
+
+function itemOf(item, index) {
+  const name = `plan.items[${index}]`;
+  const position = textOf(item?.position, `${name}.position`);
+  const reason = textOf(item?.reason, `${name}.reason`);
+  // An alternative to the first line has to say why the first line does not fit.
+  if (position && position !== FIRST_LINE && !reason) throw httpError(400, `${name}.reason is required for a drug that is not first line`);
+  return {
+    drug: neededText(item?.drug, `${name}.drug`),
+    strength: textOf(item?.strength, `${name}.strength`),
+    dose: neededText(item?.dose, `${name}.dose`),
+    frequency: neededText(item?.frequency, `${name}.frequency`),
+    days: wholeNumber(item?.days, `${name}.days`, MAX_DAYS),
+    position,
+    reason,
+    formularyKey: textOf(item?.formularyKey, `${name}.formularyKey`),
+  };
+}
+
+function followUpOf(value) {
+  if (value != null && !isPlainObject(value)) throw httpError(400, 'plan.followUp must be an object with a kind');
+  const kind = value?.kind ?? 'none';
+  if (!PLAN_FOLLOW_UPS.includes(kind)) throw httpError(400, `plan.followUp.kind must be one of: ${PLAN_FOLLOW_UPS.join(', ')}`);
+  if (kind === 'none') return { kind, hours: null };
+  return { kind, hours: wholeNumber(value?.hours ?? DEFAULT_FOLLOW_UP_HOURS[kind], 'plan.followUp.hours', MAX_FOLLOW_UP_HOURS) };
+}
+
+// The plan as the doctor approved it, refused whole when any line is incomplete.
+function planOf(input) {
+  if (!isPlainObject(input)) throw httpError(400, 'plan is required');
+  const plan = {
+    items: listOf(input.items, 'plan.items').map((item, index) => {
+      if (!isPlainObject(item)) throw httpError(400, `plan.items[${index}] must be an object`);
+      return itemOf(item, index);
+    }),
+    studies: listOf(input.studies, 'plan.studies').map((study, index) => ({
+      name: neededText(study?.name, `plan.studies[${index}].name`),
+      instructions: textOf(study?.instructions, `plan.studies[${index}].instructions`),
+    })),
+    homeCare: listOf(input.homeCare, 'plan.homeCare').map((entry, index) => neededText(entry, `plan.homeCare[${index}]`)),
+    note: textOf(input.note, 'plan.note', MAX_NOTE_LENGTH),
+    followUp: followUpOf(input.followUp),
+  };
+  if (!plan.items.length && !plan.studies.length && !plan.homeCare.length && !plan.note) {
+    throw httpError(400, 'plan needs a drug, a study, a home care measure or a note');
+  }
+  return plan;
+}
+
+const needsPrescriber = (plan) => plan.items.length > 0 || plan.studies.length > 0;
+
+const daysText = (days) => (days === 1 ? '1 día' : `${days} días`);
+const itemLine = (item) => `${[item.drug, item.strength].filter(Boolean).join(' ')}: ${item.dose} ${item.frequency} por ${daysText(item.days)}.`;
+const studyLine = (study) => `${study.name}${study.instructions ? `: ${study.instructions}` : ''}.`;
+const PRESCRIPTION_LINE = 'Justo después de tu mensaje le llega aparte la receta del médico en PDF; dile que la va a recibir.';
+
+const FOLLOW_UP_LINES = {
+  check_in: (hours) => `Seguimiento: le escribiremos en unas ${hours} horas para ver cómo va.`,
+  vigilancia: (hours) => `Seguimiento: queda en vigilancia las próximas ${hours} horas; le escribiremos para ver cómo va.`,
+};
+
+// What the assistant is told to pass on; it writes the patient message itself.
+function planInstructions(plan) {
+  const lines = ['Transmítele al paciente lo que indicó el médico, con tus palabras: no cambies dosis, frecuencia ni días, y no agregues otros medicamentos ni estudios.'];
+  if (plan.items.length) {
+    lines.push('Medicamentos:', ...plan.items.map((item) => `- ${itemLine(item)}`));
+  }
+  if (plan.studies.length) {
+    lines.push('Estudios:', ...plan.studies.map((study) => `- ${studyLine(study)}`));
+  }
+  if (plan.homeCare.length) lines.push('Cuidados en casa:', ...plan.homeCare.map((entry) => `- ${entry}`));
+  if (plan.note) lines.push(`Nota del médico: «${plan.note}».`);
+  if (plan.followUp.kind !== 'none') lines.push(FOLLOW_UP_LINES[plan.followUp.kind](plan.followUp.hours));
+  if (needsPrescriber(plan)) lines.push(PRESCRIPTION_LINE);
+  return lines.join('\n');
+}
+
+// An edit can drop the receta line; the PDF goes out anyway, so the assistant is still told.
+function assistantInstructionsOf(plan) {
+  if (!needsPrescriber(plan) || plan.instructions.includes(PRESCRIPTION_LINE)) return plan.instructions;
+  return `${plan.instructions}\n${PRESCRIPTION_LINE}`;
+}
+
+// What the team's case shows as the indication, in the doctor's terms rather than the assistant's.
+function planSummary(plan) {
+  const lines = [...plan.items.map(itemLine), ...plan.studies.map((study) => `Estudio: ${studyLine(study)}`)];
+  if (plan.homeCare.length) lines.push(`Cuidados en casa: ${plan.homeCare.join('; ')}.`);
+  if (plan.note) lines.push(`Nota: ${plan.note}`);
+  return lines.join('\n');
+}
+
+// The receta the Airtable automations turn into the doctor's PDF.
+function prescriptionText(plan) {
+  const lines = plan.items.map(itemLine);
+  if (plan.studies.length) lines.push('Estudios:', ...plan.studies.map(studyLine));
+  return lines.join('\n');
+}
+
+// The doctor's edit wins; with none, the instructions follow the plan.
+function approvedInstructions(plan, edited) {
+  if (edited != null && typeof edited !== 'string') throw httpError(400, 'instructions must be text');
+  if (!edited?.trim()) return { instructions: planInstructions(plan), instructionsEdited: false };
+  const instructions = edited.trim();
+  if (instructions.length > MAX_INSTRUCTIONS_LENGTH) throw httpError(400, `instructions exceed ${MAX_INSTRUCTIONS_LENGTH} characters`);
+  return { instructions, instructionsEdited: instructions !== planInstructions(plan) };
+}
+
+// «1 tableta cada 24 horas por 5 días; además, …» → dose, frequency, days and the rest; what does not match is left for the doctor.
+function dosingOf(instructions) {
+  const text = oneLineOf(instructions);
+  const match = text.match(/^(.*?)\s+(cada [^,;]+?)(?:\s+por\s+(\d+)\s+d[ií]as?)?(?:\s*[,;]\s*(.*))?$/i);
+  if (!match) return { dose: text || null, frequency: null, days: null, rest: null };
+  const [, dose, frequency, days, rest] = match;
+  // A duration said after other directions («…, y tragar, por 7 días») is still the days.
+  const lateDays = !days && rest?.match(/(?:^|[,;]\s*|\s)por\s+(\d+)\s+d[ií]as?\s*$/i);
+  return {
+    dose: ROUTE_ONLY.test(dose) ? null : dose,
+    frequency,
+    days: Number(days ?? lateDays?.[1]) || null,
+    rest: (lateDays ? rest.slice(0, lateDays.index).replace(/[,;\s]+$/, '') : rest) || null,
+  };
+}
+
+// The doctor's starting point: the drugs the bot proposed and confirmed, once each, and a 24 h check-in.
+// What the formulary adds after the dosing («además, valoración por oftalmología») goes to the note.
+function proposedPlanOf(draft) {
+  const seen = new Set();
+  const rests = [];
+  const items = (draft?.symptoms ?? [])
+    .filter((entry) => entry?.proposal?.confirmed)
+    .flatMap((entry) => (entry.proposal.items ?? []).map((item) => ({ item, formularyKey: entry.proposal.formularyKey })))
+    .filter(({ item }) => !seen.has(oneLineOf(item.drug).toLowerCase()) && seen.add(oneLineOf(item.drug).toLowerCase()))
+    .map(({ item, formularyKey }) => {
+      const { rest, ...dosing } = dosingOf(item.instructions);
+      if (rest) rests.push(`${item.drug}: ${rest}`);
+      return { drug: item.drug, strength: item.strength ?? null, ...dosing, position: item.position ?? null, reason: null, formularyKey };
+    });
+  return { items, studies: [], homeCare: [], note: rests.join('. ') || null, followUp: { kind: 'check_in', hours: DEFAULT_FOLLOW_UP_HOURS.check_in } };
+}
+
+module.exports = {
+  approvedInstructions,
+  assistantInstructionsOf,
+  needsPrescriber,
+  planInstructions,
+  planOf,
+  planSummary,
+  prescriptionText,
+  proposedPlanOf,
+};

package/lib/clinical/tools/getPatientRiskAssessmentTool.js

@@ -5,7 +5,7 @@ const { logger } = require('../../utils/logger');
 
 const definition = {
   name: 'getPatientRiskAssessment',
-  description: '**Does:** Returns the patient\'s latest full risk assessment and a deterministic `turn_focus` for the symptoms extracted in this turn. Read-only; no model call.\n\n**Required inputs:** none.\n\n**When to call:** immediately before `submitRoutingDecision` only when `getRouterContextBundle.sections_returned` does not contain `risk`, including a bundle result with `_diagnostics.risk_error`. The routine load is the bundle\'s mandatory `risk` section, which resolves the same assessment through the same code path.\n\n**When NOT to call:** when `getRouterContextBundle` already returned `risk` this turn — it is the same assessment, and a second read cannot change it. Nor again in the same turn after a `not_generated` result — generation runs between turns and the result cannot change mid-turn.\n\n**`turn_focus.recent_escalations` — what you already sent the team.** Every escalation dispatched for this patient in the last 14 days, newest first, with `escalated_at`, `days_since`, `urgency`, `reason` and the `channels` used. Read it before `reportMedicalEscalation`. It records only what was SENT; where the team is with it is in `team_cases`. A complaint unchanged since an escalation a day ago rarely needs a second dispatch; one still uncontrolled days after its escalation needs one at a HIGHER urgency, and `urgency_justification` should say which of the two this is. Empty means nothing was escalated in the window.\n\n**`turn_focus.team_cases` — where the care team is with each case.** Every case the team still holds, and those it closed in the last 14 days, newest first: `status`, `is_open`, `level`, `opened_at`, `days_since`, `doctor_decision` and `case_ids` (the symptom cases it covers).\n- `Por revisar`, `En evaluación`, `Con el médico`, `Indicación por enviar`, `Requiere valoración`: the team has it and has not answered yet. Tell the patient it is with the team, without promising a time. A new escalation is for a new symptom, a higher grade, a new red flag, or a symptom that persists or worsens while it waits (send it as an update).\n- `Esperando paciente`, `Indicaciones dadas`, `En vigilancia`: the team already answered (an indication on its way to the patient, given, or under watch). This comes first: ask how the indication is going before escalating again.\n- `Cerrado`, `No requiere`: the team closed it. A new complaint is a new decision.\n`doctor_decision` is internal (`approved`, `edited_approved`, `monitor`, `needs_intervention` = the doctor asked for an in-person evaluation, `returned`, `direct_chat`): use it to understand the case, never quote it. `team_cases` never says whether the problem resolved; ask the patient. An escalation in `recent_escalations` with no case here has an unknown team status, not an absent one.\n\n**Use `turn_focus.symptom_history` before grading or escalating.** It carries what no other section does: how this patient compares to their own past. `worst_grade` and `worst_reported_at` are the worst they have ever been recorded, `at_personal_worst` says whether they are back at it, and `days_since_last_report` says how stale `last_grade` is. (The current grade and trajectory are already in `landscape.active_cases` — do not expect them repeated here.) Escalate on the comparison, not on severity alone: a patient at their personal worst is a different decision from one below it, and a grade unchanged for weeks is different from the same grade reported yesterday. When you ask about it, anchor the question in the value and the date so the patient can compare. Empty means no graded case on record. \n\n**How to use:** read `turn_focus.current_concerns`, then each `relevant_risks[].checks_now` and `escalation_threshold`. It preserves concurrent symptoms. Any `selection` containing `fallback` marks a precaution to check, not a confirmed explanation. When `selection` is `no_current_concerns` the patient reported no current symptom this turn. Use `profile` only for supporting detail.\n\n**`profile` is a forecast, not history:** `predicted_aes[].minimum_symptom_set`, `disease_risks[].warning_symptoms` and every other profile list name symptoms to watch for, none of which the patient has reported. Never tell the patient a profile symptom appears in their report, and never attach a CTCAE grade to one. Reported symptoms come only from `turn_focus.current_concerns`.\n\n**Returns:** `status` — `final` when an assessment exists and carries findings, `no_signal` when one exists but the synthesis found nothing usable, or `not_generated`; `turn_focus`, always present; and the full `profile` (`predicted_aes[]`, `disease_risks[]`, `comorbidity_amplifiers[]`, lifecycle and missing-information fields). `profile` is null when not yet generated.',
+  description: '**Does:** Returns the patient\'s latest full risk assessment and a deterministic `turn_focus` for the symptoms extracted in this turn. Read-only; no model call.\n\n**Required inputs:** none.\n\n**When to call:** immediately before `submitRoutingDecision` only when `getRouterContextBundle.sections_returned` does not contain `risk`, including a bundle result with `_diagnostics.risk_error`. The routine load is the bundle\'s mandatory `risk` section, which resolves the same assessment through the same code path.\n\n**When NOT to call:** when `getRouterContextBundle` already returned `risk` this turn — it is the same assessment, and a second read cannot change it. Nor again in the same turn after a `not_generated` result — generation runs between turns and the result cannot change mid-turn.\n\n**`turn_focus.recent_escalations` — what you already sent the team.** Every escalation dispatched for this patient in the last 14 days, newest first, with `escalated_at`, `days_since`, `urgency`, `reason` and the `channels` used. Read it before `reportMedicalEscalation`. It records only what was SENT; where the team is with it is in `team_cases`. A complaint unchanged since an escalation a day ago rarely needs a second dispatch; one still uncontrolled days after its escalation needs one at a HIGHER urgency, and `urgency_justification` should say which of the two this is. Empty means nothing was escalated in the window.\n\n**`turn_focus.team_cases` — where the care team is with each case.** Every case the team still holds, and those it closed in the last 14 days, newest first: `status`, `is_open`, `level`, `opened_at`, `days_since`, `doctor_decision` and `case_ids` (the symptom cases it covers).\n- `Por revisar`, `En evaluación`, `Con el médico`, `Indicación por enviar`, `Requiere valoración`: the team has it and has not answered yet. Tell the patient it is with the team, without promising a time. A new escalation is for a new symptom, a higher grade, a new red flag, or a symptom that persists or worsens while it waits (send it as an update).\n- `Esperando paciente`, `Indicaciones dadas`, `En vigilancia`: the team already answered (an indication on its way to the patient, given, or under watch). This comes first: ask how the indication is going before escalating again.\n- `Cerrado`, `No requiere`: the team closed it. A new complaint is a new decision.\n`doctor_decision` is internal (`approved`, `edited_approved`, `plan_approved` = the doctor gave a structured plan, `monitor`, `needs_intervention` = the doctor asked for an in-person evaluation, `returned`, `direct_chat`): use it to understand the case, never quote it. `team_cases` never says whether the problem resolved; ask the patient. An escalation in `recent_escalations` with no case here has an unknown team status, not an absent one.\n\n**Use `turn_focus.symptom_history` before grading or escalating.** It carries what no other section does: how this patient compares to their own past. `worst_grade` and `worst_reported_at` are the worst they have ever been recorded, `at_personal_worst` says whether they are back at it, and `days_since_last_report` says how stale `last_grade` is. (The current grade and trajectory are already in `landscape.active_cases` — do not expect them repeated here.) Escalate on the comparison, not on severity alone: a patient at their personal worst is a different decision from one below it, and a grade unchanged for weeks is different from the same grade reported yesterday. When you ask about it, anchor the question in the value and the date so the patient can compare. Empty means no graded case on record. \n\n**How to use:** read `turn_focus.current_concerns`, then each `relevant_risks[].checks_now` and `escalation_threshold`. It preserves concurrent symptoms. Any `selection` containing `fallback` marks a precaution to check, not a confirmed explanation. When `selection` is `no_current_concerns` the patient reported no current symptom this turn. Use `profile` only for supporting detail.\n\n**`profile` is a forecast, not history:** `predicted_aes[].minimum_symptom_set`, `disease_risks[].warning_symptoms` and every other profile list name symptoms to watch for, none of which the patient has reported. Never tell the patient a profile symptom appears in their report, and never attach a CTCAE grade to one. Reported symptoms come only from `turn_focus.current_concerns`.\n\n**Returns:** `status` — `final` when an assessment exists and carries findings, `no_signal` when one exists but the synthesis found nothing usable, or `not_generated`; `turn_focus`, always present; and the full `profile` (`predicted_aes[]`, `disease_risks[]`, `comorbidity_amplifiers[]`, lifecycle and missing-information fields). `profile` is null when not yet generated.',
   strict: false,
   replayScope: 'turn',
   parameters: {

package/lib/controllers/escalationReviewController.js

@@ -11,6 +11,7 @@ const {
   handOffToDoctor,
   listEscalationReviews,
   openEscalationReview,
+  previewPlanInstructions,
   reclassifyUrgency,
   recordDoctorDecision,
   requestBotDraft,
@@ -53,13 +54,22 @@ const openEscalationReviewController = async (req, res) => {
 
 const getEscalationReviewController = async (req, res) => {
   try {
-    const { review, isApprover, responseDeadline } = await getEscalationReviewById({ id: req.params.id, requestedBy: req.query.requestedBy });
-    res.status(200).json({ success: true, review: withCaseStatus(review), isApprover, responseDeadline });
+    const { review, isApprover, responseDeadline, proposedPlan } = await getEscalationReviewById({ id: req.params.id, requestedBy: req.query.requestedBy });
+    res.status(200).json({ success: true, review: withCaseStatus(review), isApprover, responseDeadline, proposedPlan });
   } catch (error) {
     respondWithError(res, error, 'reading escalation review', { reviewId: req.params?.id });
   }
 };
 
+const previewEscalationReviewPlanController = async (req, res) => {
+  try {
+    const instructions = previewPlanInstructions({ id: req.params.id, plan: req.body?.plan });
+    res.status(200).json({ success: true, instructions });
+  } catch (error) {
+    respondWithError(res, error, 'previewing the plan instructions', { reviewId: req.params?.id });
+  }
+};
+
 const getReviewTimelineController = async (req, res) => {
   try {
     const timeline = await getReviewTimeline({ id: req.params.id });
@@ -175,6 +185,8 @@ const recordEscalationReviewDecisionController = async (req, res) => {
       source,
       decision,
       finalText = null,
+      plan = null,
+      instructions = null,
       comment = null,
       doctorName = null,
       doctorReply = null,
@@ -188,6 +200,8 @@ const recordEscalationReviewDecisionController = async (req, res) => {
       source,
       decision,
       finalText,
+      plan,
+      instructions,
       comment,
       doctorName,
       doctorReply,
@@ -284,6 +298,7 @@ module.exports = {
   closeEscalationReviewController,
   getEscalationReviewController,
   getReviewTimelineController,
+  previewEscalationReviewPlanController,
   requestEscalationReviewDraftController,
   handOffEscalationReviewController,
   listEscalationReviewsController,

package/lib/controllers/prescriptionController.js

@@ -1,17 +1,11 @@
-const { Monitoreo_ID } = require('../config/airtableConfig');
-
 const { logger } = require('../utils/logger');
 
-const { ensureWhatsAppFormat } = require('../helpers/twilioHelper');
-
-const { addLinkedRecord } = require('../services/airtableService');
+const { createPrescription } = require('../services/prescriptionService');
 
 const RECORD_ID_RX = /^rec[A-Za-z0-9]{14}$/;
 
-// physicianId links the receta to a physicians row; the Airtable automation picks the PDF template from that physician's specialty.
 const createPrescriptionController = async (req, res) => {
-  const { prescription, triggeredBy, creationSource = 'other', physicianId } = req.body;
-  let code = req.body.code;
+  const { code, prescription, triggeredBy, creationSource = 'other', physicianId } = req.body;
 
   if (!code) return res.status(400).json({ success: false, error: 'Code is required' });
   if (!prescription) return res.status(400).json({ success: false, error: 'Prescription is required' });
@@ -21,28 +15,10 @@ const createPrescriptionController = async (req, res) => {
   }
 
   try {
-    code = ensureWhatsAppFormat(code);
-
-    const record = await addLinkedRecord(
-      Monitoreo_ID,
-      'patient_prescriptions',
-      {
-        prescription,
-        author_email: triggeredBy,
-        creation_source: creationSource,
-        created: new Date().toISOString(),
-        ...(physicianId && { physician: [physicianId] })
-      },
-      {
-        referenceTable: 'estado_general',
-        referenceFilter: `{whatsapp_id}='${code}'`,
-        linkFieldName: 'patient_id'
-      },
-      code
-    );
+    const recordId = await createPrescription({ code, prescription, authorEmail: triggeredBy, creationSource, physicianId });
 
     logger.info('[PrescriptionController] Prescription created', { code, physicianId });
-    res.status(201).json({ success: true, message: 'Prescription created', recordId: record?.id || null });
+    res.status(201).json({ success: true, message: 'Prescription created', recordId });
   } catch (error) {
     logger.error('[PrescriptionController] Error creating prescription', { error: error.message, code });
     res.status(500).json({ success: false, error: 'Failed to create prescription' });

package/lib/index.d.ts

@@ -274,7 +274,7 @@ declare module '@peopl-health/nexus' {
     initializeLlmMonitor(): Promise<{ enabled: boolean; error?: string } | undefined>;
     getWorkflowRunner(): WorkflowRunner;
     processInstruction(code: string, instruction: string, role?: string, options?: { triggeredBy?: string; beforeRun?: () => Promise<string | null | undefined> | string | null | undefined; dedupeWithinMs?: number }): Promise<{ outcome: string | null; reason?: string; error?: string }>;
-    processSystemMessage(code: string, messages: string | string[], role?: string, options?: { triggeredBy?: string; reply?: boolean }): Promise<void>;
+    processSystemMessage(code: string, messages: string | string[], role?: string, options?: { triggeredBy?: string; reply?: boolean }): Promise<{ delivery: Record<string, unknown> | null; sendThrew: boolean } | undefined>;
     processOutreach(code: string, options?: { brief?: OutreachBrief | null; triggeredBy?: string | null; reason?: string | null; firstName?: string | null; dryRun?: boolean; replyToContact?: boolean; allowFollowUp?: boolean }): Promise<OutreachDecision>;
     processCheckInDue(code: string, options: { reminderId: string; type: 'contingencia' | 'seguimiento'; question?: string; firstName?: string | null }): Promise<CheckInDueResult>;
     processScheduledFollowUp(code: string, options: { reminderId: string; firstName: string; now?: Date }): Promise<ScheduledFollowUpResult>;

package/lib/models/escalationReviewModel.js

@@ -12,7 +12,8 @@ const HANDOFF_MODES = ['sent_whatsapp', 'copied'];
 const INTERRUPTED_STATUSES = ['handing_off', 'sending'];
 const CANCELLABLE_AFTER_HANDOFF_STATUSES = ['awaiting_doctor', 'approved', 'returned', 'indications_queued'];
 const CANCELLABLE_STATUSES = ['open', 'documenting', 'draft_ready', ...CANCELLABLE_AFTER_HANDOFF_STATUSES];
-const DOCTOR_DECISIONS = ['approved', 'edited_approved', 'needs_intervention', 'returned', 'monitor', 'direct_chat'];
+const DOCTOR_DECISIONS = ['approved', 'edited_approved', 'plan_approved', 'needs_intervention', 'returned', 'monitor', 'direct_chat'];
+const PLAN_FOLLOW_UPS = ['none', 'check_in', 'vigilancia'];
 const DECISION_SOURCES = ['platform', 'registered_by_navigator', 'chat'];
 const RETURN_REASONS = ['llamar', 'falta_dato', 'no_requiere'];
 
@@ -193,11 +194,39 @@ const doctorHandoffSchema = new mongoose.Schema({
   sentBy: { type: String, required: true },
 }, { timestamps: { createdAt: true, updatedAt: false } });
 
+const planItemSchema = new mongoose.Schema({
+  drug: { type: String, required: true },
+  strength: { type: String, default: null },
+  dose: { type: String, required: true },
+  frequency: { type: String, required: true },
+  days: { type: Number, required: true },
+  position: { type: String, default: null },
+  reason: { type: String, default: null },
+  formularyKey: { type: String, default: null },
+}, { _id: false });
+
+const planSchema = new mongoose.Schema({
+  items: { type: [planItemSchema], default: [] },
+  studies: {
+    type: [new mongoose.Schema({ name: { type: String, required: true }, instructions: { type: String, default: null } }, { _id: false })],
+    default: [],
+  },
+  homeCare: { type: [String], default: [] },
+  note: { type: String, default: null },
+  followUp: {
+    type: new mongoose.Schema({ kind: { type: String, enum: PLAN_FOLLOW_UPS, required: true }, hours: { type: Number, default: null } }, { _id: false }),
+    required: true,
+  },
+  instructions: { type: String, required: true },
+  instructionsEdited: { type: Boolean, default: false },
+}, { _id: false });
+
 const decisionSchema = new mongoose.Schema({
   decision: { type: String, enum: DOCTOR_DECISIONS, required: true },
   source: { type: String, enum: DECISION_SOURCES, required: true },
   draftNumber: { type: Number, required: true },
   finalText: { type: String, default: null },
+  plan: { type: planSchema, default: undefined },
   comment: { type: String, default: null },
   doctorReply: { type: String, default: null },
   returnReason: { type: String, enum: [...RETURN_REASONS, null], default: null },
@@ -210,7 +239,8 @@ const patientDeliverySchema = new mongoose.Schema({
   decisionNumber: { type: Number, required: true },
   messageId: { type: String, default: null },
   status: { type: String, default: null },
-  transport: { type: String, enum: ['text', 'template_recovery', 'predefined_template'], required: true },
+  transport: { type: String, enum: ['text', 'template_recovery', 'predefined_template', 'assistant'], required: true },
+  prescriptionRecordId: { type: String, default: null },
   deferred: { type: Boolean, default: false },
   confirmedBy: { type: String, default: null },
   confirmedAt: { type: Date, default: null },
@@ -381,6 +411,7 @@ module.exports = {
   DOCTOR_DECISIONS,
   HANDOFF_MODES,
   INTERRUPTED_STATUSES,
+  PLAN_FOLLOW_UPS,
   FOLLOWUP_STATUSES,
   RETURN_REASONS,
   URGENCY_LEVELS,

package/lib/routes/index.js

@@ -138,6 +138,7 @@ const escalationReviewRouteDefinitions = {
   'POST /:id/note-facts': 'confirmEscalationReviewNoteFactsController',
   'POST /:id/drafts': 'addEscalationReviewDraftController',
   'POST /:id/doctor-handoffs': 'handOffEscalationReviewController',
+  'POST /:id/plan-instructions': 'previewEscalationReviewPlanController',
   'POST /:id/decisions': 'recordEscalationReviewDecisionController',
   'POST /:id/patient-deliveries': 'sendEscalationReviewIndicationsController',
   'POST /:id/close': 'closeEscalationReviewController',
@@ -314,6 +315,7 @@ const builtInControllers = {
   listReviewBoardController: escalationReviewController.listReviewBoardController,
   getEscalationReviewController: escalationReviewController.getEscalationReviewController,
   getReviewTimelineController: escalationReviewController.getReviewTimelineController,
+  previewEscalationReviewPlanController: escalationReviewController.previewEscalationReviewPlanController,
   requestEscalationReviewDraftController: escalationReviewController.requestEscalationReviewDraftController,
   setEscalationReviewCasesController: escalationReviewController.setEscalationReviewCasesController,
   addEscalationReviewCallLogController: escalationReviewController.addEscalationReviewCallLogController,

package/lib/services/assistantMessageService.js

@@ -26,9 +26,9 @@ const ASSISTANT_MESSAGE_FAILURES = {
 };
 
 class AssistantMessageError extends Error {
-  constructor(reasonCode, acceptedCount = 0) {
+  constructor(reasonCode, acceptedCount = 0, cause = undefined) {
     const [statusCode, message] = ASSISTANT_MESSAGE_FAILURES[reasonCode];
-    super(message);
+    super(message, cause === undefined ? undefined : { cause });
     this.reasonCode = reasonCode;
     this.statusCode = statusCode;
     this.acceptedCount = acceptedCount;
@@ -117,8 +117,10 @@ async function processAssistantSystemMessage(code, messages, role = 'system', op
   if (!reply) return;
   recordPatientSend?.({ code, channel: 'assistant_instruction', sentBy: triggeredBy, text: input.messages.join('\n') });
 
+  let turn;
+  let settled = null;
   try {
-    await executeWithPipeline(code, 'system', 'queue',
+    turn = await executeWithPipeline(code, 'system', 'queue',
       async (preProcessResult, shouldContinue, runId) => {
         return await assistantProcessor.process({
           code,
@@ -131,11 +133,15 @@ async function processAssistantSystemMessage(code, messages, role = 'system', op
             signal: getAbortSignal(runId),
           }
         });
-      }
+      },
+      { onSendSettled: async (outcome) => { settled = outcome; } },
     );
-  } catch {
-    throw new AssistantMessageError('MESSAGE_REPLY_FAILED', acceptedCount);
+  } catch (error) {
+    // The cause stays internal: callers tell a drain that refused the turn from one that may have answered.
+    throw new AssistantMessageError('MESSAGE_REPLY_FAILED', acceptedCount, error);
   }
+  // What the reply's send returned, or null when the turn produced or sent nothing; a send that threw may still have reached the patient.
+  return { delivery: turn?.delivery ?? null, sendThrew: settled === 'threw' };
 }
 
 module.exports = { AssistantMessageError, injectAssistantMessages, processAssistantSystemMessage };

package/lib/services/escalationReviewService.js

@@ -33,6 +33,9 @@ const { doctorAlertHeadline, doctorAlertOpener, renderDoctorMessage, templateSum
 const { generateKeyQuestions } = require('../clinical/services/escalationQuestionsService');
 const { drugsNamedIn } = require('../clinical/services/treatmentProposalService');
 const { characterizationSeedOf } = require('../clinical/helpers/reviewUpdateHelper');
+const {
+  approvedInstructions, assistantInstructionsOf, needsPrescriber, planInstructions, planOf, planSummary, prescriptionText, proposedPlanOf,
+} = require('../clinical/helpers/doctorPlanHelper');
 const { readNoteFacts, assertionOf } = require('../clinical/services/escalationNoteFactsService');
 const { humanReplyFilter } = require('../clinical/config/safetyNetConfig');
 const {
@@ -52,6 +55,7 @@ const { getPatientInformation, logPatientChange } = require('./patientService');
 const { MAX_NOTE_LENGTH, openCaseIds, readPatientCases, updatePatientTask } = require('./patientTaskService');
 const { countMessages } = require('./messageService');
 const { getEscalationApprover, listEscalationApprovers } = require('./physicianService');
+const { createPrescription } = require('./prescriptionService');
 const { getThreadInfo, switchThreadStoppedStatus } = require('./threadService');
 const { effectiveUrgencyOf, levelsOf, patientTimerMinutes, responseDeadlineOf, responseDeadlinePolicy } = require('./reviewDeadlineService');
 const { caseTaskLive, scheduleCaseSync } = require('./escalationCaseTaskService');
@@ -104,7 +108,8 @@ const RECLASSIFIABLE_STATUSES = [...DOCUMENTING_STATUSES, 'awaiting_doctor'];
 const SAME_URGENCY = 'The review is already at that urgency';
 const RECLASSIFY_CHANGED = 'The review changed while you were reclassifying it; read it again before changing the urgency';
 const DIRECT_CHAT_STATUSES = ['open', 'documenting', 'draft_ready', 'returned', 'awaiting_doctor', 'approved', 'needs_intervention'];
-const APPROVALS = ['approved', 'edited_approved'];
+const APPROVALS = ['approved', 'edited_approved', 'plan_approved'];
+const PRESCRIBER_ONLY = 'Only an approving doctor can indicate drugs or studies, or edit the instructions to the assistant';
 const STALE_DRAFT = 'New information reached the review after this draft; wait for the updated draft before approving';
 const STALE_HANDOFF = 'New information reached the review after the draft the doctor received; it went back to documenting for a new draft';
 const DRAFT_CHANGED = 'A newer draft was written after the one you saw; read it before deciding';
@@ -145,7 +150,7 @@ const configured = (key) => {
   return value;
 };
 
-const STATUS_AFTER = { edited_approved: 'approved', monitor: 'monitoring' };
+const STATUS_AFTER = { edited_approved: 'approved', plan_approved: 'approved', monitor: 'monitoring' };
 const statusAfter = (decision) => STATUS_AFTER[decision] ?? decision;
 
 const redactedError = (error) => redactDirectIdentifiers(String(error?.message || ''));
@@ -728,6 +733,18 @@ async function isEscalationApprover(operator) {
   }
 }
 
+// Unlike a read, a failed lookup refuses the decision instead of treating the doctor as not approving.
+async function requireApprover(operator) {
+  let approver;
+  try {
+    approver = await getEscalationApprover(operator);
+  } catch (error) {
+    logger.error('[EscalationReview] Approver lookup failed; the plan was not recorded', { error: redactedError(error) });
+    throw httpError(503, 'The approving doctors could not be read; try again');
+  }
+  if (!approver) throw httpError(403, PRESCRIBER_ONLY);
+}
+
 async function getEscalationReviewById({ id, requestedBy } = {}) {
   const reviewId = reviewIdOf(id);
   const operator = requiredText(requestedBy, 'requestedBy');
@@ -748,7 +765,19 @@ async function getEscalationReviewById({ id, requestedBy } = {}) {
       .updateOne({ _id: review._id }, { $max: { approverViewedAt: readAt } }, { timestamps: false })
       .catch(warnUnmarked);
   }
-  return { review, isApprover, responseDeadline: responseDeadlineOf(review, responseDeadlinePolicy()) };
+  const draft = DECIDABLE_STATUSES.includes(review.status) ? review.drafts?.at(-1) : null;
+  return {
+    review,
+    isApprover,
+    responseDeadline: responseDeadlineOf(review, responseDeadlinePolicy()),
+    proposedPlan: draft ? { draftNumber: review.drafts.length, ...proposedPlanOf(draft) } : null,
+  };
+}
+
+// The instructions a plan would give the assistant, for the doctor to read before approving.
+function previewPlanInstructions({ id, plan } = {}) {
+  reviewIdOf(id);
+  return planInstructions(planOf(plan));
 }
 
 async function getReviewTimeline({ id } = {}) {
@@ -1787,6 +1816,8 @@ async function recordDoctorDecision({
   source,
   decision,
   finalText = null,
+  plan: requestedPlan = null,
+  instructions = null,
   comment = null,
   doctorName = null,
   doctorReply = null,
@@ -1815,6 +1846,17 @@ async function recordDoctorDecision({
     if (!RETURN_REASONS.includes(reason)) throw httpError(400, `reason must be one of: ${RETURN_REASONS.join(', ')}`);
     returnReason = reason;
   }
+  let plan = null;
+  if (decision === 'plan_approved') {
+    if (source !== 'platform') throw httpError(400, 'A plan is approved by the doctor on the platform');
+    // The plan names the draft it started from, so a newer draft is refused instead of decided unseen.
+    if (seenDraftNumber === null) throw httpError(400, 'draftNumber is required for a plan');
+    plan = planOf(requestedPlan);
+    plan = { ...plan, ...approvedInstructions(plan, instructions) };
+    // The team may send home care alone; a note, an edit or a named drug goes out on a doctor's word.
+    const namesDrug = drugsNamedIn(plan.homeCare.join(' ')).length > 0;
+    if (needsPrescriber(plan) || plan.note || plan.instructionsEdited || namesDrug) await requireApprover(operator);
+  }
 
   const review = await loadReview(reviewId);
   const isDraftless = DRAFTLESS_DECISIONS.includes(decision);
@@ -1858,6 +1900,7 @@ async function recordDoctorDecision({
         source,
         draftNumber,
         finalText: approvedText,
+        ...(plan && { plan }),
         comment: optionalText(comment),
         doctorReply: reply,
         ...(returnReason && { returnReason }),
@@ -1993,10 +2036,10 @@ async function sendApprovedIndications({ id, outsideWindowRoute = null, sentBy,
   const claim = newOperationClaim();
   const claimed = await updateReview(reviewId, SENDABLE_STATUSES, { $set: { status: 'sending', operationClaim: claim } });
   const decisionNumber = claimed.decisions.length;
-  const { finalText, decision } = claimed.decisions[decisionNumber - 1];
+  const { finalText, decision, plan } = claimed.decisions[decisionNumber - 1];
   const claimedFrom = statusAfter(decision);
 
-  if (!finalText) {
+  if (!finalText && !plan) {
     await releaseReview(reviewId, 'sending', claimedFrom, claim).catch((releaseError) => {
       logger.error('[EscalationReview] The claim was not released after a decision with no text', {
         escalationReviewId: String(claimed._id), error: releaseError.message,
@@ -2014,6 +2057,7 @@ async function sendApprovedIndications({ id, outsideWindowRoute = null, sentBy,
     });
     throw httpError(409, 'The agent characterized the case after this decision; it went back to documenting for a new draft and decision');
   }
+  if (plan) return sendPlanThroughAssistant({ claimed, claim, decisionNumber, plan, operator, requestId });
 
   // Built outside the try: composing reads Mongo and Airtable, and failing there never sent.
   let message;
@@ -2069,6 +2113,100 @@ async function sendApprovedIndications({ id, outsideWindowRoute = null, sentBy,
   return syncCase(review, operator, requestId);
 }
 
+const PRESCRIBER_EMAIL_KEY = 'ESCALATION_PRESCRIBER_EMAIL';
+
+// The PDF goes out from the Airtable automations; a failed receta never undoes the message already sent.
+async function issuePrescription(review, plan, prescriberEmail) {
+  try {
+    return await createPrescription({
+      code: review.patientCode, prescription: prescriptionText(plan), authorEmail: prescriberEmail, creationSource: 'patient case',
+    });
+  } catch (error) {
+    logger.error('[EscalationReview] The prescription was not created after the plan was sent', {
+      escalationReviewId: String(review._id), error: redactedError(error),
+    });
+    return null;
+  }
+}
+
+// How the assistant's reply left: sent, queued for the patient's reply window, not sent, or unknown.
+function replyOutcome(delivery, sendThrew) {
+  if (sendThrew) return 'unknown';
+  if (!delivery) return 'not_sent';
+  if (delivery.success === true && delivery.deferred === true) return 'queued';
+  if (delivery.success === true && typeof delivery.messageId === 'string' && delivery.messageId) return 'sent';
+  if (delivery.success === false && delivery.deferred !== true && delivery.duplicate !== true) return 'not_sent';
+  return 'unknown';
+}
+
+// The assistant writes the patient message from the doctor's instructions; the review closes unless a follow-up was chosen.
+async function sendPlanThroughAssistant({ claimed, claim, decisionNumber, plan, operator, requestId }) {
+  const reviewId = claimed._id;
+  const release = () => releaseReview(reviewId, 'sending', 'approved', claim).catch((releaseError) => {
+    logger.error('[EscalationReview] The claim was not released after a plan the assistant did not send', {
+      escalationReviewId: String(reviewId), error: releaseError.message,
+    });
+  });
+
+  let prescriberEmail = null;
+  let delivery;
+  let sendThrew;
+  try {
+    if (needsPrescriber(plan)) prescriberEmail = configured(PRESCRIBER_EMAIL_KEY);
+    ({ delivery = null, sendThrew = false } = await getMessaging().processSystemMessage(
+      claimed.patientCode, [assistantInstructionsOf(plan)], 'system', { reply: true, triggeredBy: operator },
+    ) ?? {});
+  } catch (error) {
+    // A turn refused by a deploy's drain never ran; any other failure after the instructions were stored may have answered.
+    if (error?.reasonCode === 'MESSAGE_REPLY_FAILED' && !(error.cause instanceof DrainingError)) {
+      logger.error('[EscalationReview] The assistant turn failed after the instructions were stored; leaving the review in sending', {
+        escalationReviewId: String(reviewId),
+      });
+      throw httpError(502, 'The assistant turn failed after the instructions were stored; check the chat before sending again');
+    }
+    await release();
+    if (error?.cause instanceof DrainingError) throw httpError(503, 'The server is restarting; send the plan again in a minute');
+    throw error;
+  }
+
+  const outcome = replyOutcome(delivery, sendThrew);
+  if (outcome === 'not_sent') {
+    await release();
+    throw httpError(502, 'The assistant did not send a message to the patient; check the chat and send the plan again');
+  }
+  if (outcome === 'unknown') {
+    logger.error('[EscalationReview] The assistant reply could not be confirmed; leaving the review in sending', { escalationReviewId: String(reviewId) });
+    throw httpError(502, 'The assistant reply could not be confirmed; check the chat before sending again');
+  }
+
+  // A queued reply goes out once the patient answers the recovery template; the receta, a template itself, goes now.
+  const queued = outcome === 'queued';
+  const prescriptionRecordId = prescriberEmail ? await issuePrescription(claimed, plan, prescriberEmail) : null;
+  const record = {
+    decisionNumber, messageId: delivery.messageId || null, status: delivery.status || null, transport: 'assistant', deferred: queued, sentBy: operator,
+    ...(prescriptionRecordId && { prescriptionRecordId }),
+  };
+  const recordUpdate = withCaseMirror(claimed, { $set: { patientDelivery: record } }, { recommendation: planSummary(plan) });
+  const status = queued ? 'indications_queued' : 'indications_sent';
+  const review = await completeOperation(reviewId, claim, 'sending', recordUpdate, status);
+  const prescriptionFailed = Boolean(prescriberEmail) && !prescriptionRecordId;
+  await audit(review, operator, requestId, {
+    action: status, decisionNumber, transport: 'assistant', ...(prescriberEmail && { prescription: prescriptionFailed ? 'failed' : 'created' }),
+  });
+  // Closing waits for a sent reply and the receta it promised; otherwise the team still has something to do.
+  if (plan.followUp.kind === 'none' && !queued && !prescriptionFailed) {
+    try {
+      return await closeEscalationReview({ id: reviewId, closedBy: operator, requestId });
+    } catch (error) {
+      logger.error('[EscalationReview] The review was not closed after its plan was sent', {
+        escalationReviewId: String(reviewId), error: redactedError(error),
+      });
+      return syncCase(await loadReview(reviewId), operator, requestId);
+    }
+  }
+  return syncCase(review, operator, requestId);
+}
+
 const EPISODE_TRUST = 0.7;
 const EPISODE_VARIABLE = 'intercurrent_events_summary';
 const EPISODE_SOURCE = 'doctor';
@@ -2076,6 +2214,7 @@ const EPISODE_SOURCE = 'doctor';
 const DECISION_WORDS = {
   approved: 'el médico aprobó las indicaciones',
   edited_approved: 'el médico aprobó las indicaciones con cambios',
+  plan_approved: 'el médico dio las indicaciones',
   needs_intervention: 'el médico pidió valoración presencial',
   returned: 'el médico devolvió el caso a navegación',
 };
@@ -2259,6 +2398,7 @@ module.exports = {
   generateBotDraft,
   getEscalationReviewById,
   getReviewTimeline,
+  previewPlanInstructions,
   handOffToDoctor,
   listEscalationReviews,
   openEscalationReview,

package/lib/services/prescriptionService.js

@@ -0,0 +1,30 @@
+const { Monitoreo_ID } = require('../config/airtableConfig');
+
+const { ensureWhatsAppFormat } = require('../helpers/twilioHelper');
+
+const { addLinkedRecord } = require('./airtableService');
+
+// physicianId links the receta to a physicians row; the Airtable automation picks the PDF template from that physician's specialty.
+async function createPrescription({ code, prescription, authorEmail, creationSource = 'other', physicianId }) {
+  const patientCode = ensureWhatsAppFormat(code);
+  const record = await addLinkedRecord(
+    Monitoreo_ID,
+    'patient_prescriptions',
+    {
+      prescription,
+      author_email: authorEmail,
+      creation_source: creationSource,
+      created: new Date().toISOString(),
+      ...(physicianId && { physician: [physicianId] })
+    },
+    {
+      referenceTable: 'estado_general',
+      referenceFilter: `{whatsapp_id}='${patientCode}'`,
+      linkFieldName: 'patient_id'
+    },
+    patientCode
+  );
+  return record?.id || null;
+}
+
+module.exports = { createPrescription };

package/package.json

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