@peopl-health/nexus 5.10.0-dev.1075 → 5.10.0-dev.1078

package/lib/clinical/tools/getActiveRecommendationsTool.js

@@ -0,0 +1,43 @@
+const { readActiveRecommendations } = require('../../fhir');
+
+const definition = {
+  name: 'getActiveRecommendations',
+  description: '**Does:** Returns the patient\'s active symptom-management recommendations from both origins — in-chat plans (`chat`) and weekly-triage plans (`triage`) — merged and source-tagged. Read-only.\n\n**Required inputs:** none. Optional `ctcae_term` (PRO-CTCAE-tolerant symptom filter), `include_inactive` (bool; also returns superseded plans).\n\n**When to call:** before recommending, to see what the patient was already advised, whether it helped (`latest_outcome`), and avoid contradicting an active plan.\n\n**Returns:** `has_any`, `ctcae_filter`, `include_inactive`, `sources_present[]`, `recommendations[]` (each: `source`, `is_active`, `recommendation_id` (the handle for recordRecommendationOutcome), `symptoms[]`, `recommendation`, `when_to_escalate`, `expected_effectiveness`, `is_pharmacological_med_needed`, `latest_outcome` `{outcome, adherence, source, notes}`|null, `generated_at`).',
+  strict: false,
+  parameters: {
+    type: 'object',
+    properties: {
+      ctcae_term: {
+        type: 'string',
+        description: 'Filter to recommendations targeting this PRO-CTCAE symptom. Omit for all.',
+      },
+      include_inactive: {
+        type: 'boolean',
+        description: 'Include superseded / expired plans. Defaults to false (active only).',
+      },
+    },
+    required: [],
+  },
+};
+
+async function handler(args = {}, context = {}) {
+  try {
+    const runtime = context?.toolRuntimeContext || null;
+    if (!runtime?.turnId || !runtime?.patientCode) {
+      return JSON.stringify({ success: false, error: 'getActiveRecommendations requires an active turn context (turnId, patientCode).', data: {} });
+    }
+    const data = await readActiveRecommendations({
+      patientId: runtime.patientCode,
+      ctcaeTerm: typeof args?.ctcae_term === 'string' ? args.ctcae_term : null,
+      includeInactive: args?.include_inactive === true,
+    });
+    return JSON.stringify({ success: true, data });
+  } catch (err) {
+    return JSON.stringify({ success: false, error: err?.message || 'getActiveRecommendations failed', data: {} });
+  }
+}
+
+module.exports = {
+  definition,
+  handler,
+};

package/lib/clinical/tools/recordRecommendationOutcomeTool.js

@@ -0,0 +1,72 @@
+const { recordRecommendationOutcome } = require('../../fhir');
+
+const NO_MATCH_HINT = 'No active recommendation matched — there may be no current care plan, or none targeting that symptom. Handle the symptom normally (open a case / route).';
+
+const definition = {
+  name: 'recordRecommendationOutcome',
+  description: '**Does:** Records how a symptom-management recommendation went for the patient — appended to the recommendation\'s history so the next plan can adapt. Feeds the SAME outcome loop as the weekly-triage feedback form.\n\n**Required inputs:** one of `recommendation_id` (preferred — from getActiveRecommendations) or `ctcae_term` (fallback; resolves the active recommendation for that symptom), plus at least one of `outcome` (`improved`|`partial`|`no_relief`|`worsened`|`not_tried`|`unknown`) or `adherence` (`full`|`partial`|`none`) — an adherence-only report defaults `outcome` to `unknown`. Optional `notes`.\n\n**Returns:** `recorded` (bool). When true: `recommendation_id`, `outcome`, optional `adherence`. When false: `hint` (no active recommendation matched).',
+  strict: false,
+  parameters: {
+    type: 'object',
+    properties: {
+      recommendation_id: {
+        type: 'string',
+        description: 'The recommendation to attach the outcome to (from getActiveRecommendations). Preferred over ctcae_term.',
+      },
+      ctcae_term: {
+        type: 'string',
+        description: 'Fallback when recommendation_id is unknown: the PRO-CTCAE symptom whose active recommendation the outcome is about.',
+      },
+      outcome: {
+        type: 'string',
+        enum: ['improved', 'partial', 'no_relief', 'worsened', 'not_tried', 'unknown'],
+        description: 'How the recommendation went.',
+      },
+      adherence: {
+        type: 'string',
+        enum: ['full', 'partial', 'none'],
+        description: 'Whether the patient followed it (distinct axis from outcome).',
+      },
+      notes: { type: 'string', description: 'Optional free-text detail from the patient.' },
+    },
+    required: [],
+  },
+};
+
+async function handler(args = {}, context = {}) {
+  try {
+    const runtime = context?.toolRuntimeContext || null;
+    if (!runtime?.turnId || !runtime?.patientCode) {
+      return JSON.stringify({ success: false, error: 'recordRecommendationOutcome requires an active turn context (turnId, patientCode).', data: {} });
+    }
+    const recommendationId = typeof args?.recommendation_id === 'string' ? args.recommendation_id.trim() || null : null;
+    const ctcaeTerm = typeof args?.ctcae_term === 'string' ? args.ctcae_term.trim() || null : null;
+    if (!recommendationId && !ctcaeTerm) {
+      return JSON.stringify({ success: false, error: 'provide recommendation_id or ctcae_term.', data: {} });
+    }
+    const outcome = typeof args?.outcome === 'string' ? args.outcome.trim().toLowerCase() || null : null;
+    const adherence = typeof args?.adherence === 'string' ? args.adherence.trim().toLowerCase() || null : null;
+    if (!outcome && !adherence) {
+      return JSON.stringify({ success: false, error: 'provide outcome or adherence — nothing to record.', data: {} });
+    }
+    const result = await recordRecommendationOutcome({
+      patientId: runtime.patientCode,
+      recommendationId,
+      ctcaeTerm,
+      outcome,
+      adherence,
+      notes: typeof args?.notes === 'string' ? args.notes.trim() || null : null,
+    });
+    if (!result.recorded) {
+      return JSON.stringify({ success: true, data: { recorded: false, hint: NO_MATCH_HINT } });
+    }
+    return JSON.stringify({ success: true, data: result });
+  } catch (err) {
+    return JSON.stringify({ success: false, error: err?.message || 'recordRecommendationOutcome failed', data: {} });
+  }
+}
+
+module.exports = {
+  definition,
+  handler,
+};

package/lib/clinical/tools/registerClinicalTools.js

@@ -20,6 +20,13 @@ const TOOLS = [
   require('./getActiveSymptomLandscapeTool'),
   require('./recordInterventionTool'),
   require('./setContingencyPlanTool'),
+  require('./submitPalliativeAssessmentTool'),
+  require('./updatePalliativeAssessmentTool'),
+  require('./submitPalliativeCarePlanTool'),
+  require('./submitSafetyGateTool'),
+  require('./submitRecommendationPlanTool'),
+  require('./getActiveRecommendationsTool'),
+  require('./recordRecommendationOutcomeTool'),
   require('./getPatientRiskAssessmentTool'),
   require('./getPatientHistoryTool'),
   require('./getRouterContextBundleTool'),

package/lib/fhir/index.js

@@ -3,7 +3,12 @@ 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 {
+  storeRecommendationPlan,
+  recommendationPlanExists,
+  readActiveRecommendations,
+  recordRecommendationOutcome,
+} = require('./services/recommendationService');
 const { storeContingency, readContingencies } = require('./services/contingencyService');
 const { storeIntervention, readInterventions } = require('./services/interventionService');
 const { storeCluster, readClusters } = require('./services/clusterService');
@@ -41,6 +46,8 @@ module.exports = {
   safetyGateExists,
   storeRecommendationPlan,
   recommendationPlanExists,
+  readActiveRecommendations,
+  recordRecommendationOutcome,
   storeContingency,
   readContingencies,
   storeIntervention,

package/lib/fhir/services/recommendationService.js

@@ -1,8 +1,22 @@
-const { fhirId } = require('../helpers/fhirHelper');
+const { fhirId, codeSystemUrl, identifierSystem } = require('../helpers/fhirHelper');
+const { codeableConcept, extension, toIso } = require('../helpers/elementHelper');
+const { identifierValue, extMap } = require('../helpers/fhirReadHelper');
 const { PROJECTOR_NAME } = require('../projections/recommendationPlanProjection');
+const { RECOMMENDATION_REC_SLUG } = require('../constants/projectionSlugs');
 const { getFhirStore } = require('../stores/fhirStore');
 const { project, storeResources } = require('./fhirService');
 
+const OUTCOME_SYSTEM_KEY = 'recommendation-outcome';
+const OUTCOME_VALUES = ['improved', 'partial', 'no_relief', 'worsened', 'not_tried', 'unknown'];
+const ADHERENCE_VALUES = ['full', 'partial', 'none'];
+const CHAT_ACTIVE_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
+const NOTE_KEYS = {
+  'cuándo escalar': 'whenToEscalate',
+  'efectividad esperada': 'expectedEffectiveness',
+  contraindicaciones: 'contraindications',
+  'requiere coordinación farmacológica': 'isPharmacologicalMedNeeded',
+};
+
 async function storeRecommendationPlan({ patientId, plan }) {
   if (plan.patientId !== patientId) {
     throw new Error(`storeRecommendationPlan patientId mismatch: expected ${patientId}`);
@@ -21,7 +35,179 @@ async function recommendationPlanExists({ runId }) {
   return Boolean(resource);
 }
 
+async function readActiveRecommendations({ patientId, ctcaeTerm = null, includeInactive = false }) {
+  const store = getFhirStore();
+  const patient = `Patient/${fhirId(patientId)}`;
+  const filter = (ctcaeTerm || '').trim().toLowerCase() || null;
+  const recSystem = identifierSystem(RECOMMENDATION_REC_SLUG);
+
+  const entries = (await store.find({ patient, resourceType: 'Task' }))
+    .filter((task) => (task.identifier || []).some((id) => id.system === recSystem))
+    .map((task) => {
+      const recommendationId = identifierValue(task, RECOMMENDATION_REC_SLUG);
+      if (!recommendationId) return null;
+      const runId = recommendationId.replace(/-rec[^-]*$/, '');
+      return { task, recommendationId, runId, source: sourceOf(runId), authoredOn: task.authoredOn || null };
+    })
+    .filter(Boolean);
+
+  const latestTriageRunId = latestTriageRun(entries);
+  const chatCutoffMs = Date.now() - CHAT_ACTIVE_WINDOW_MS;
+
+  const recommendations = [];
+  for (const entry of entries) {
+    const isActive = entry.source === 'triage'
+      ? entry.runId === latestTriageRunId
+      : Boolean(entry.authoredOn) && Date.parse(toIso(entry.authoredOn)) >= chatCutoffMs;
+    if (!includeInactive && !isActive) continue;
+    const item = reconstructRecommendation(entry.task, entry.recommendationId, entry.runId, isActive);
+    if (filter && !item.symptoms.some((term) => term.toLowerCase() === filter)) continue;
+    recommendations.push(item);
+  }
+  recommendations.sort((a, b) => a.recommendation_id.localeCompare(b.recommendation_id));
+
+  return {
+    has_any: recommendations.length > 0,
+    ctcae_filter: filter,
+    include_inactive: includeInactive,
+    sources_present: [...new Set(recommendations.map((item) => item.source))].sort(),
+    recommendations,
+  };
+}
+
+async function recordRecommendationOutcome({ patientId, recommendationId = null, ctcaeTerm = null, outcome = null, adherence = null, notes = null }) {
+  if (adherence !== null && !ADHERENCE_VALUES.includes(adherence)) {
+    throw new Error(`invalid adherence: ${JSON.stringify(adherence)}. Must be full | partial | none (or omitted).`);
+  }
+  const resolvedOutcome = outcome || (adherence !== null ? 'unknown' : outcome);
+  if (!OUTCOME_VALUES.includes(resolvedOutcome)) {
+    throw new Error(`invalid outcome: ${JSON.stringify(resolvedOutcome)}. Must be one of ${JSON.stringify(OUTCOME_VALUES)}.`);
+  }
+  const target = await resolveTask({ patientId, recommendationId, ctcaeTerm });
+  if (!target) return { recorded: false };
+  const output = buildOutcomeOutput({ outcome: resolvedOutcome, adherence, notes });
+  await storeResources([target.task], { merge: appendOutput(output) });
+  return {
+    recorded: true,
+    recommendation_id: target.recommendationId,
+    outcome: resolvedOutcome,
+    ...(adherence ? { adherence } : {}),
+  };
+}
+
+async function resolveTask({ patientId, recommendationId, ctcaeTerm }) {
+  const store = getFhirStore();
+  if (recommendationId) {
+    const task = await store.getByReference(`Task/${fhirId(recommendationId)}`);
+    return task ? { task, recommendationId: identifierValue(task, RECOMMENDATION_REC_SLUG) || recommendationId } : null;
+  }
+  const term = (ctcaeTerm || '').trim().toLowerCase();
+  if (!term) return null;
+  const active = await readActiveRecommendations({ patientId });
+  const match = active.recommendations.find((item) => item.symptoms.some((symptom) => symptom.toLowerCase() === term));
+  if (!match) return null;
+  const task = await store.getByReference(`Task/${fhirId(match.recommendation_id)}`);
+  return task ? { task, recommendationId: match.recommendation_id } : null;
+}
+
+function buildOutcomeOutput({ outcome, adherence, notes }) {
+  const output = {
+    type: codeableConcept(OUTCOME_SYSTEM_KEY),
+    valueCodeableConcept: codeableConcept(outcome, { code: outcome, system: codeSystemUrl(OUTCOME_SYSTEM_KEY) }),
+    extension: [extension('recommendation-outcome-source', { valueString: 'chat' })],
+  };
+  if (adherence) output.extension.push(extension('recommendation-outcome-adherence', { valueString: adherence }));
+  if (notes) output.extension.push(extension('recommendation-outcome-notes', { valueString: notes }));
+  output.extension.push(extension('recommendation-outcome-recorded-at', { valueDateTime: toIso(new Date()) }));
+  return output;
+}
+
+const appendOutput = (output) => (prior, incoming) => ({
+  ...incoming,
+  output: [...(prior.output || []), output],
+});
+
+function reconstructRecommendation(task, recommendationId, runId, isActive) {
+  const noteMap = parseNotes(task.note);
+  const symptoms = ((task.code && task.code.coding) || []).map((coding) => coding.code).filter(Boolean);
+  return {
+    source: sourceOf(runId),
+    is_active: isActive,
+    recommendation_id: recommendationId,
+    symptoms,
+    recommendation: task.description || null,
+    when_to_escalate: noteMap.whenToEscalate || null,
+    expected_effectiveness: noteMap.expectedEffectiveness || null,
+    is_pharmacological_med_needed: noteMap.isPharmacologicalMedNeeded === 'true',
+    latest_outcome: latestOutcome(task.output),
+    generated_at: task.authoredOn || null,
+  };
+}
+
+function parseNotes(note) {
+  const out = {};
+  for (const entry of note || []) {
+    const text = String(entry.text || '');
+    const separator = text.indexOf(': ');
+    if (separator < 0) continue;
+    const key = NOTE_KEYS[text.slice(0, separator)];
+    if (key) out[key] = text.slice(separator + 2);
+  }
+  return out;
+}
+
+function latestOutcome(output) {
+  const rows = (output || [])
+    .filter((entry) => (entry.type || {}).text === OUTCOME_SYSTEM_KEY)
+    .map((entry) => {
+      const ext = extMap(entry);
+      return {
+        outcome: ((entry.valueCodeableConcept || {}).coding || [])[0]?.code || (entry.valueCodeableConcept || {}).text || null,
+        adherence: ext['recommendation-outcome-adherence'] || null,
+        source: ext['recommendation-outcome-source'] || null,
+        notes: ext['recommendation-outcome-notes'] || null,
+        recordedAt: ext['recommendation-outcome-recorded-at'] || null,
+      };
+    });
+  if (!rows.length) return null;
+  const merged = rows.reduce((prior, row) => ({
+    outcome: row.outcome === 'unknown' && prior.outcome && prior.outcome !== 'unknown' ? prior.outcome : row.outcome,
+    adherence: row.adherence === null ? prior.adherence : row.adherence,
+    source: row.source === null ? prior.source : row.source,
+    notes: row.notes === null ? prior.notes : row.notes,
+    recordedAt: row.recordedAt === null ? prior.recordedAt : row.recordedAt,
+  }));
+  return {
+    outcome: merged.outcome,
+    adherence: merged.adherence,
+    source: merged.source || 'chat',
+    notes: merged.notes,
+  };
+}
+
+function sourceOf(runId) {
+  return runId.startsWith('recrun-triage-') ? 'triage' : 'chat';
+}
+
+function latestTriageRun(entries) {
+  let latest = null;
+  for (const entry of entries) {
+    if (entry.source !== 'triage') continue;
+    if (!latest || supersedesTriage(entry, latest)) latest = entry;
+  }
+  return latest ? latest.runId : null;
+}
+
+function supersedesTriage(candidate, current) {
+  const a = candidate.authoredOn ? Date.parse(toIso(candidate.authoredOn)) : -Infinity;
+  const b = current.authoredOn ? Date.parse(toIso(current.authoredOn)) : -Infinity;
+  if (a !== b) return a > b;
+  return candidate.runId > current.runId;
+}
+
 module.exports = {
   storeRecommendationPlan,
   recommendationPlanExists,
+  readActiveRecommendations,
+  recordRecommendationOutcome,
 };

package/package.json

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