@peopl-health/nexus 5.44.0-dev.6838 → 5.44.0-dev.6850

package/README.md

@@ -116,38 +116,6 @@ const bus = nexus.getMessaging().getEventBus();
 bus.on('message:received', (m) => console.log('rx', m.id));
 ```
 
-## Workflows (Optional)
-
-Register a named unit of work, deduplicated by a key you derive from the trigger.
-
-```js
-const runner = nexus.getMessaging().getWorkflowRunner();
-
-await runner.register({
-  kind: 'triage-projection',
-  dedupeKey: (trigger) => String(trigger.submissionId),
-  prepare: async (trigger, checkpoints, save) => { /* ... */ },
-  retrySchedule: [5, 10, 20, 40],   // minutes; omit for fire-and-forget
-});
-
-await runner.enqueue('triage-projection', { submissionId });
-```
-
-With `retrySchedule` the trigger and a checkpoint journal are stored in Mongo and the schedule runs
-on an in-process timer — deferred workflows never touch the queue adapter, so they add no Redis load.
-`prepare` resumes from `checkpoints`; call `save(patch)` before each external call so a retry does
-not repeat completed work. Throw an error carrying `permanent: true` to give up immediately instead
-of walking the schedule; the Airtable helpers tag their own permanent 4xx errors that way, in
-`withAirtableRetry`, which all five of them route through. They rethrow on failure too, so an
-Airtable outage reaches `prepare` as an exception and walks the retry schedule on its own rather
-than reading as success.
-
-Recovery is automatic: registering sweeps for work left behind by a previous process, and the runner
-keeps sweeping so work whose worker died mid-`prepare` is reclaimed once its claim goes stale.
-`enqueue` on an abandoned key revives it, keeping its checkpoints. Work is retained for 24 hours
-after its last update and then expires — the dedupe key expires with it, so idempotency has the
-same horizon as retention.
-
 ## Assistants (Optional)
 
 Register assistant classes and (optionally) a custom resolver. OpenAI is supported via `llm: 'openai'`.

package/lib/clinical/helpers/clinicalWorkflowGuard.js

@@ -72,7 +72,7 @@ function validateClinicalDelivery(trace, { enabledSkills = [], skillActivationIt
   if (signals.clinicalIntakeCompleted !== true) {
     return {
       error: REFUSAL.intakeBeforeDelivery,
-      recovery: 'Classify the complete patient message: call extractClinicalInfo with every supported tag it carries, or commit the workflow matching the clinical event it names. Do not file an administrative escalation for a turn that carries no pending request.',
+      recovery: 'Classify the complete patient message: call extractClinicalInfo with every supported tag it carries, or declare its non_clinical_request when it carries no clinical content and only asks for something you answer yourself, or commit the workflow matching the clinical event it names. Do not file an administrative escalation for a turn that carries no pending request, or for a request you answer yourself.',
       requiredToolIds: [
         'extractClinicalInfo', 'reportResultsReceived', 'reportCrisis',
         'reportMedicalEscalation',

package/lib/clinical/providers/BaseLLMProvider.js

@@ -554,6 +554,10 @@ class BaseLLMProvider {
       const value = calls.find(call => call.name === name)?.input?.[field];
       return typeof value === 'string' && value.trim() ? value : null;
     };
+    const extraction = calls.find(call => call.name === EXTRACTION_TOOL)?.input;
+    if (pick(EXTRACTION_TOOL, 'non_clinical_request') && pick(EXTRACTION_TOOL, 'raw_message') && extraction?.detected_tags?.length === 0) {
+      return { text: null, reasoning: null };
+    }
     const authored = pick(BRIDGE_TOOL, 'message_text');
     if (authored) return { text: authored, reasoning: pick(BRIDGE_TOOL, 'reasoning') };
     return { text: pick(EXTRACTION_TOOL, 'bridge_text'), reasoning: pick(EXTRACTION_TOOL, 'bridge_reasoning') };

package/lib/clinical/tools/extractClinicalInfoTool.js

@@ -12,11 +12,12 @@ const DETECTED_TAG_ENUM = [
   'symptom', 'indication', 'treatment', 'adherence', 'medication', 'appointment',
   'emotion', 'lab_value', 'diagnosis', 'allergy', 'comorbidity', 'performance_status',
 ];
+const NON_CLINICAL_REQUESTS = ['external_booking'];
 const MAX_CONTEXT_TURNS = 6;
 
 const definition = {
   name: 'extractClinicalInfo',
-  description: '**Does:** Extracts ALL structured clinical facts from the current patient message — symptoms, labs, medications, diagnoses, appointments, treatments — and returns them as a discriminated-union `clinical_facts[]` list keyed by `kind`. Call ONCE per turn with ALL detected tags in a single call — one call covers every category.\n\n**Required inputs:** `raw_message` (the patient\'s current turn text, VERBATIM — the full contents of `<patient_message>`, every line of it when the turn carries more than one), `detected_tags` (list, at least one of: `symptom`, `indication`, `treatment`, `adherence`, `medication`, `appointment`, `emotion`, `lab_value`, `diagnosis`, `allergy`, `comorbidity`, `performance_status`), `intake_source` (`self` | `caregiver` | `team_relay`).\n\n**When to call:** at the start of any turn where the patient message mentions, explicitly or implicitly, any of the 12 supported categories. The result drives every downstream router-side read (landscape / history / risk / patterns).\n\n**When NOT to call:**\n- When the patient SHARED raw numeric results / lab values / files — use `reportResultsReceived` instead (it both logs the share AND emits FHIR Observations directly).\n- More than once per turn — a single call covers every category.\n\n**Returns:** `data.clinical_facts[]` — a discriminated-union list where each record has `kind` (observation | medication | condition | procedure | appointment | allergy) plus common fields `{id, code, effective, notes}` (null/default fields are OMITTED — e.g. `interpretation` appears only when non-default) and kind-specific fields:\n- `kind=observation`: `code_ctcae`, `value`, `grade_scale`,   `episode_id`, `trend`. Read `grade_scale` to anchor the   grade assigned in `recordClinicalImpression`. It is present   whenever the term has a curated CTCAE ladder, and ABSENT   when it does not — an absent `grade_scale` means there is no   rubric for this term, not that one was withheld. An absent   `grade_scale` means the term has no curated rubric, not   that one was withheld — so there is nothing to grade   against from memory. Call `lookupCtcaeEntry` when you   suspect the term itself is wrong; otherwise say where the   grade came from in `grade_estimate.source`.\n- `kind=medication`: `adherence_status` (`started` |   `ongoing` | `non_adherent` | …).\n- `kind=condition`: `clinical_status` (`active` | `resolved`   | …) — patient self-report of an existing diagnosis   (distinct from `openCondition` which commits a new   agent-tracked case).\n- `kind=procedure`: patient-reported procedure done   elsewhere (distinct from `recordIntervention` which is   agent-authored); `venue`/`outcome` may be null in the   current extraction phase.\n- `kind=appointment`: `scheduled_for`, `purpose` (may be   null in the current extraction phase).\nThe system writes the matching FHIR resource (Observation / MedicationStatement / Condition / Procedure / Appointment) + `Provenance` per fact on the audit lane; `allergy`, `comorbidity`, and `performance_status` are captured in a dedicated aggregate, not as a per-fact resource.\n\n**When the result asks you to confirm:** `data.pending_confirmation[]` means the patient reported a REAL clinical event but named it only generically («me suspendieron el tratamiento»), so it was deliberately NOT recorded. Each entry carries `{term, category, missing, quote}`; the list holds EVERY fact withheld this turn, but ask about the FIRST one only. Ask the patient for exactly what its `missing` names, in ONE short natural question, and never state or imply that anything was recorded. When they answer, call `extractClinicalInfo` again on their reply and it will be recorded then. `data.context_gaps[]` — only ever sent when there is nothing to confirm — names ONE stored variable that is stale or incomplete; raise it only if the conversation allows it naturally. Both lists are empty whenever the turn carries a safety flag: never ask housekeeping questions during a safety event.\n\n**Side effects:** System emits a FHIR resource + `Provenance` per fact on the audit lane, except `allergy`/`comorbidity`/`performance_status` (aggregated). Facts listed in `pending_confirmation` are NOT written to the patient record — they are held back until the patient confirms them.',
+  description: '**Does:** Extracts ALL structured clinical facts from the current patient message — symptoms, labs, medications, diagnoses, appointments, treatments — and returns them as a discriminated-union `clinical_facts[]` list keyed by `kind`. Call ONCE per turn with ALL detected tags in a single call — one call covers every category.\n\n**Required inputs:** `raw_message` (the patient\'s current turn text, VERBATIM — the full contents of `<patient_message>`, every line of it when the turn carries more than one), `detected_tags` (list, at least one of: `symptom`, `indication`, `treatment`, `adherence`, `medication`, `appointment`, `emotion`, `lab_value`, `diagnosis`, `allergy`, `comorbidity`, `performance_status`; empty only for a purely conversational message or when declaring `non_clinical_request`), `intake_source` (`self` | `caregiver` | `team_relay`).\n\n**When to call:** at the start of any turn where the patient message mentions, explicitly or implicitly, any of the 12 supported categories. The result drives every downstream router-side read (landscape / history / risk / patterns).\n\n**When NOT to call:**\n- When the patient SHARED raw numeric results / lab values / files — use `reportResultsReceived` instead (it both logs the share AND emits FHIR Observations directly).\n- More than once per turn — a single call covers every category.\n\n**Returns:** `data.clinical_facts[]` — a discriminated-union list where each record has `kind` (observation | medication | condition | procedure | appointment | allergy) plus common fields `{id, code, effective, notes}` (null/default fields are OMITTED — e.g. `interpretation` appears only when non-default) and kind-specific fields:\n- `kind=observation`: `code_ctcae`, `value`, `grade_scale`,   `episode_id`, `trend`. Read `grade_scale` to anchor the   grade assigned in `recordClinicalImpression`. It is present   whenever the term has a curated CTCAE ladder, and ABSENT   when it does not — an absent `grade_scale` means there is no   rubric for this term, not that one was withheld. An absent   `grade_scale` means the term has no curated rubric, not   that one was withheld — so there is nothing to grade   against from memory. Call `lookupCtcaeEntry` when you   suspect the term itself is wrong; otherwise say where the   grade came from in `grade_estimate.source`.\n- `kind=medication`: `adherence_status` (`started` |   `ongoing` | `non_adherent` | …).\n- `kind=condition`: `clinical_status` (`active` | `resolved`   | …) — patient self-report of an existing diagnosis   (distinct from `openCondition` which commits a new   agent-tracked case).\n- `kind=procedure`: patient-reported procedure done   elsewhere (distinct from `recordIntervention` which is   agent-authored); `venue`/`outcome` may be null in the   current extraction phase.\n- `kind=appointment`: `scheduled_for`, `purpose` (may be   null in the current extraction phase).\nThe system writes the matching FHIR resource (Observation / MedicationStatement / Condition / Procedure / Appointment) + `Provenance` per fact on the audit lane; `allergy`, `comorbidity`, and `performance_status` are captured in a dedicated aggregate, not as a per-fact resource.\n\n**When the result asks you to confirm:** `data.pending_confirmation[]` means the patient reported a REAL clinical event but named it only generically («me suspendieron el tratamiento»), so it was deliberately NOT recorded. Each entry carries `{term, category, missing, quote}`; the list holds EVERY fact withheld this turn, but ask about the FIRST one only. Ask the patient for exactly what its `missing` names, in ONE short natural question, and never state or imply that anything was recorded. When they answer, call `extractClinicalInfo` again on their reply and it will be recorded then. `data.context_gaps[]` — only ever sent when there is nothing to confirm — names ONE stored variable that is stale or incomplete; raise it only if the conversation allows it naturally. Both lists are empty whenever the turn carries a safety flag: never ask housekeeping questions during a safety event.\n\n**Side effects:** System emits a FHIR resource + `Provenance` per fact on the audit lane, except `allergy`/`comorbidity`/`performance_status` (aggregated). Facts listed in `pending_confirmation` are NOT written to the patient record — they are held back until the patient confirms them.',
   strict: true,
   parameters: {
     type: 'object',
@@ -86,8 +87,18 @@ const definition = {
         anyOf: [{ type: 'string' }, { type: 'null' }],
         description: 'Una frase: en qué detalle del inbound anclaste `bridge_text` y por qué ese detalle. INTERNO; el paciente nunca lo ve. null cuando `bridge_text` es null.',
       },
+      non_clinical_request: {
+        anyOf: [{ type: 'string', enum: NON_CLINICAL_REQUESTS }, { type: 'null' }],
+        description: [
+          'Declara que el mensaje NO trae contenido clínico y solo pide algo que tú contestas directamente, sin el equipo.',
+          '- external_booking: agendar, reprogramar o cancelar una cita con un médico, una sesión de tratamiento (quimio, radio, infusión) o un estudio de laboratorio o imagen.',
+          'Va con `detected_tags` vacío. Si el mensaje también menciona un síntoma, emoción, medicamento, tratamiento o resultado, etiqueta esas variables y manda `null` aquí.',
+          'Manda `null` cuando la petición necesita que el equipo actúe (p. ej. una sesión del programa de acompañamiento de AUNA) y cuando el paciente solo cuenta que tiene una cita.',
+          'Con este campo, `bridge_text` va en `null`: la respuesta es un solo mensaje.',
+        ].join('\n'),
+      },
     },
-    required: ['raw_message', 'detected_tags', 'intake_source', 'response_format', 'context', 'bridge_text', 'bridge_reasoning'],
+    required: ['raw_message', 'detected_tags', 'intake_source', 'response_format', 'context', 'bridge_text', 'bridge_reasoning', 'non_clinical_request'],
     additionalProperties: false,
   },
 };
@@ -116,7 +127,12 @@ async function handler(args, context = {}) {
 
   if (!detectedTags.length) {
     const supported = [...SUPPORTED_TAGS].sort();
-    const safetyFlags = await scanSafetyFlags(rawMessage);
+    const declaredRequest = !detectedTagsRaw.length && NON_CLINICAL_REQUESTS.includes(args?.non_clinical_request) ? args.non_clinical_request : null;
+    if (declaredRequest && trace?.signals?.clinicalFactsExtracted) {
+      return JSON.stringify({ success: false, error: 'This turn already extracted clinical facts, so it cannot be declared a non-clinical request. Continue the clinical workflow those facts require.' });
+    }
+    const scannedFlags = await scanSafetyFlags(rawMessage);
+    const safetyFlags = scannedFlags || [];
     if (trace?.setSignals) trace.setSignals({ clinicalIntakeCompleted: false, clinicalMentions: [], safetyFlags });
 
     const providerDecision = trace?.signals?.clinicalIntakeDecisionRequired;
@@ -130,15 +146,25 @@ async function handler(args, context = {}) {
       }
       conversationalInbound = isPurelyConversational(rawMessage, conversationalTokens);
     }
-    if (!detectedTagsRaw.length && conversationalInbound) {
+    if (declaredRequest && scannedFlags?.length === 0) {
+      if (trace?.setSignals) trace.setSignals({ clinicalIntakeCompleted: true });
+      return JSON.stringify({
+        success: true,
+        data: { degraded: false, non_clinical_request: declaredRequest, clinical_facts: [] },
+      });
+    }
+    if (!declaredRequest && !detectedTagsRaw.length && conversationalInbound) {
       if (trace?.setSignals) trace.setSignals({ clinicalIntakeCompleted: true });
       return JSON.stringify({
         success: true,
         data: { degraded: false, conversational_inbound: true, clinical_facts: [] },
       });
     }
+    const emptyTagsError = declaredRequest
+      ? `The message matched a safety pattern or the safety scan was unavailable, so it cannot be declared a non-clinical request. Re-call with every applicable supported tag (${supported.join(', ')}).`
+      : `extractClinicalInfo was called with an empty \`detected_tags\` list and the inbound is not purely conversational. The intake decision is incomplete, so direct delivery remains blocked. Re-call with every applicable supported tag (${supported.join(', ')}). If the message carries no clinical content and only makes a request that \`non_clinical_request\` covers, re-call with empty tags and that field set. If it carries no clinical content but needs the team to act on a request, commit that workflow instead. Commit nothing when the turn carries neither.`;
     const error = !detectedTagsRaw.length
-      ? `extractClinicalInfo was called with an empty \`detected_tags\` list and the inbound is not purely conversational. The intake decision is incomplete, so direct delivery remains blocked. Re-call with every applicable supported tag (${supported.join(', ')}), or, if the message carries no clinical content but does carry an administrative or referral request, commit that workflow instead. Commit nothing when the turn carries neither.`
+      ? emptyTagsError
       : `extractClinicalInfo received detected_tags=${JSON.stringify(detectedTagsRaw)} but none are supported. Use only these exact strings (lowercase): ${supported.join(', ')}. Re-call with the corrected tags.`;
     return JSON.stringify({ success: false, error, supported_tags: supported, received_tags: detectedTagsRaw });
   }
@@ -167,6 +193,7 @@ async function handler(args, context = {}) {
       clinicalIntakeCompleted: intakeCompleted,
       clinicalMentions: [...clinicalMentions, ...pendingMentions],
       safetyFlags,
+      ...(clinicalMentions.length || pendingMentions.length ? { clinicalFactsExtracted: true } : {}),
     });
   } else {
     logger.warn('[extractClinicalInfo] no trace on runtime context; signals not recorded', { turnId: runtime?.turnId });
@@ -215,7 +242,7 @@ async function scanSafetyFlags(text) {
     return detectSafetyFlags(text, await getSafetyFlagPatterns());
   } catch (err) {
     logger.warn('[extractClinicalInfo] deterministic safety scan failed', { error: err?.message });
-    return [];
+    return null;
   }
 }
 

package/lib/clinical/tools/reportUnresolvedRequestv2Tool.js

@@ -4,14 +4,14 @@ const { logger } = require('../../utils/logger');
 
 const definition = {
   'name': 'reportUnresolvedRequestv2',
-  'description': '**Does:** Escalates ADMINISTRATIVE / OPERATIVE matters — and non-clinical referrals to other services (psico-oncología, paliativos, non-oncology medical) — to the appropriate team queue. Records what was left pending, why it needs the team, operational urgency, and what was already communicated to the patient. It carries NO clinical-escalation semantics for the patient\'s oncology condition — those go to `reportMedicalEscalation`.\n\n**Required inputs:** `unresolved_question`, `category` (operational routing — REQUIRED for the queue), `urgency` (`routine` | `soon` | `urgent`; default `routine`), `escalation_details`, `resolution_attempted` (bool).\n\n**When to call:**\n- Administrative matter (appointments / insurance / authorisations / letters / rescheduling / transport).\n- Patient request that needs human (non-clinical) intervention.\n- Outside the agent\'s scope or knowledge (non-clinical).\n- A routine referral (psico-oncología, paliativos).\n- Callback from a specific team member (`category=contact_team_member`), or enrollment in a program / workshop / support group (`category=program_enrollment`).\nAlways pair with a `DeliverPatientMessage` acknowledging the escalation.\n\n**When NOT to call (use the clinical tools instead):**\n- ANY medical escalation — confirmed emergency, same-day evaluation, OR an asynchronous clinical concern (a symptom persisting >72h, a worrying trend, a treatment concern, stale clinical context) — use `reportMedicalEscalation` (urgency_level stat | asap | urgent | routine).\n- Active mental-health crisis — use `reportCrisis`.\n- Patient SHARED results / values / files — use `reportResultsReceived`.\n- Questions answerable from the CTCAE catalog or skill protocols — answer directly.\n\n**Returns:** an ack ({} on the happy path). Out-of-enum `urgency`/`category` are coerced (to `routine`/`other`) and disclosed via `coerced_urgency`/`coerced_category`; inputs over 500 chars are truncated and disclosed via `truncated_fields`. If the escalation could not be queued to the team it comes back with `queued: false` — do NOT tell the patient the team was notified in that case; acknowledge and say you are still working on it.\n\n**Side effects:** Emits `OUT_OF_SCOPE_LOGGED` to the appropriate team queue.',
+  'description': '**Does:** Escalates ADMINISTRATIVE / OPERATIVE matters — and non-clinical referrals to other services (psico-oncología, paliativos, non-oncology medical) — to the appropriate team queue. Records what was left pending, why it needs the team, operational urgency, and what was already communicated to the patient. It carries NO clinical-escalation semantics for the patient\'s oncology condition — those go to `reportMedicalEscalation`.\n\n**Required inputs:** `unresolved_question`, `category` (operational routing — REQUIRED for the queue), `urgency` (`routine` | `soon` | `urgent`; default `routine`), `escalation_details`, `resolution_attempted` (bool).\n\n**When to call:**\n- Administrative matter the team has to act on (insurance / authorisations / letters / transport), including scheduling or rescheduling a session of the AUNA accompaniment program (psico-oncología, nutrición).\n- Patient request that needs human (non-clinical) intervention.\n- Outside the agent\'s scope or knowledge (non-clinical).\n- A routine referral (psico-oncología, paliativos).\n- Callback from a specific team member (`category=contact_team_member`), or enrollment in a program / workshop / support group (`category=program_enrollment`).\nAlways pair with a `DeliverPatientMessage` acknowledging the escalation.\n\n**When NOT to call:**\n- ANY medical escalation — confirmed emergency, same-day evaluation, OR an asynchronous clinical concern (a symptom persisting >72h, a worrying trend, a treatment concern, stale clinical context) — use `reportMedicalEscalation` (urgency_level stat | asap | urgent | routine).\n- Active mental-health crisis — use `reportCrisis`.\n- Patient SHARED results / values / files — use `reportResultsReceived`.\n- Booking, rescheduling or cancelling a doctor appointment, a treatment session (chemo / radiotherapy / infusion) or a lab / imaging study — these are not booked through this channel; answer the patient directly with where to book, as your instructions describe. When that turn carries no clinical content, declare it with `non_clinical_request` in `extractClinicalInfo`.\n- Questions answerable from the CTCAE catalog or skill protocols — answer directly.\n\n**Returns:** an ack ({} on the happy path). Out-of-enum `urgency`/`category` are coerced (to `routine`/`other`) and disclosed via `coerced_urgency`/`coerced_category`; inputs over 500 chars are truncated and disclosed via `truncated_fields`. If the escalation could not be queued to the team it comes back with `queued: false` — do NOT tell the patient the team was notified in that case; acknowledge and say you are still working on it.\n\n**Side effects:** Emits `OUT_OF_SCOPE_LOGGED` to the appropriate team queue.',
   'strict': true,
   'parameters': {
     'type': 'object',
     'properties': {
       'unresolved_question': {
         'type': 'string',
-        'description': 'El pendiente ADMINISTRATIVO / OPERATIVO o de DERIVACIÓN que requiere al equipo. Cubre: (1) administrativo — citas, seguros, autorizaciones, cartas, reprogramación, transporte; (2) solicitud que requiere intervención humana no clínica; (3) fuera de tus alcances o conocimientos; (4) derivación/referencia a otro servicio (psico-oncología, paliativos, médico no oncológico) — eso es COORDINACIÓN, no escalación clínica. NO uses esta herramienta para ESCALACIONES CLÍNICAS del cuadro oncológico — un síntoma que persiste, una tendencia preocupante, un treatment_concern o contexto clínico desactualizado van por `reportMedicalEscalation` (urgency_level `routine` para revisión asíncrona del equipo). Resultados ya realizados que compartió el paciente van por `reportResultsReceived`.'
+        'description': 'El pendiente ADMINISTRATIVO / OPERATIVO o de DERIVACIÓN que requiere al equipo. Cubre: (1) administrativo que el equipo tiene que resolver — seguros, autorizaciones, cartas, transporte, y agendar o reprogramar sesiones del programa de acompañamiento de AUNA (psico-oncología, nutrición); (2) solicitud que requiere intervención humana no clínica; (3) fuera de tus alcances o conocimientos; (4) derivación/referencia a otro servicio (psico-oncología, paliativos, médico no oncológico) — eso es COORDINACIÓN, no escalación clínica. NO uses esta herramienta para ESCALACIONES CLÍNICAS del cuadro oncológico — un síntoma que persiste, una tendencia preocupante, un treatment_concern o contexto clínico desactualizado van por `reportMedicalEscalation` (urgency_level `routine` para revisión asíncrona del equipo). Resultados ya realizados que compartió el paciente van por `reportResultsReceived`. Tampoco la uses para agendar, reprogramar o cancelar citas con médicos, sesiones de tratamiento (quimio, radio, infusión) o estudios de laboratorio o imagen: no se agendan por este medio y eso se le responde directamente al paciente.'
       },
       'escalation_details': {
         'type': 'string',
@@ -32,7 +32,7 @@ const definition = {
           'program_enrollment',
           'other'
         ],
-        'description': 'Categoría operativa/administrativa o de derivación del pendiente para ruteo. `contact_team_member` = el paciente quiere hablar con / pasar un mensaje a / que lo llame de vuelta un miembro del equipo. `program_enrollment` = inscribirse a charlas, talleres, grupos de apoyo o check-ups. Las categorías de ESCALACIÓN CLÍNICA (symptom_persistent, treatment_concern, stale_context) se retiraron — esas escalaciones van por `reportMedicalEscalation`.'
+        'description': 'Categoría operativa/administrativa o de derivación del pendiente para ruteo. `scheduling` = agendar o reprogramar sesiones del programa de acompañamiento de AUNA (no citas médicas, sesiones de tratamiento ni estudios). `contact_team_member` = el paciente quiere hablar con / pasar un mensaje a / que lo llame de vuelta un miembro del equipo. `program_enrollment` = inscribirse a charlas, talleres, grupos de apoyo o check-ups. Las categorías de ESCALACIÓN CLÍNICA (symptom_persistent, treatment_concern, stale_context) se retiraron — esas escalaciones van por `reportMedicalEscalation`.'
       },
       'resolution_attempted': {
         'anyOf': [
@@ -54,7 +54,7 @@ const definition = {
               'soon',
               'urgent'
             ],
-            'description': 'routine = sin plazo; soon = plazo en la semana; urgent = mismo día (transporte para hoy, conflicto de cita mañana).'
+            'description': 'routine = sin plazo; soon = plazo en la semana; urgent = mismo día (transporte para hoy, una sesión de programa que choca mañana).'
           },
           {
             'type': 'null'

package/lib/core/NexusMessaging.js

@@ -33,7 +33,6 @@ const { isLlmMonitorEnabled } = require('../clinical/flags/llmMonitorConfig');
 const { createQueueAdapter } = require('../queue');
 const { ScheduledMessageJob } = require('../jobs/ScheduledMessageJob');
 const { TemplateApprovalJob } = require('../jobs/TemplateApprovalJob');
-const { WorkflowRunner } = require('./WorkflowRunner');
 
 const { PhiProcessor } = require('./PhiProcessor');
 
@@ -118,8 +117,6 @@ class NexusMessaging {
       queueAdapter: this.queueAdapter,
     });
 
-    this.workflowRunner = new WorkflowRunner({ queueAdapter: this.queueAdapter });
-
     this.phiProcessor = new PhiProcessor({
       encode: config.phi?.encode || false,
       ner: config.phi?.ner || null,
@@ -303,7 +300,6 @@ class NexusMessaging {
   getAssistantProcessor() { return this.assistantProcessor; }
   getLlmMonitor() { return this.llmMonitor; }
   getQueueAdapter() { return this.queueAdapter; }
-  getWorkflowRunner() { return this.workflowRunner; }
   getPhiProcessor() { return this.phiProcessor; }
   isConnected() { return this.provider?.getConnectionStatus() ?? false; }
   isProcessing(chatId) { return this.batchingManager.isProcessing(chatId); }
@@ -744,7 +740,6 @@ class NexusMessaging {
   async disconnect() {
     this.queueReconciliation?.stop();
     if (this.provider) await this.provider.disconnect();
-    if (this.workflowRunner) this.workflowRunner.stop();
     if (this.queueAdapter) await this.queueAdapter.shutdown();
     this.events.removeAllListeners();
   }

package/lib/core/workflowRunner.js

@@ -0,0 +1,35 @@
+function createWorkflowRunner({ queueAdapter } = {}) {
+  if (!queueAdapter) throw new Error('createWorkflowRunner requires a queueAdapter');
+  const workflows = new Map();
+
+  async function register(workflow = {}) {
+    if (!workflow.kind || typeof workflow.kind !== 'string') throw new Error('workflow requires a kind');
+    if (workflow.kind.includes('__')) throw new Error(`workflow '${workflow.kind}' must not contain '__' (reserved as the jobId delimiter)`);
+    if (typeof workflow.dedupeKey !== 'function') throw new Error(`workflow '${workflow.kind}' requires a dedupeKey function`);
+    if (typeof workflow.prepare !== 'function') throw new Error(`workflow '${workflow.kind}' requires a prepare function`);
+    if (workflows.has(workflow.kind)) throw new Error(`workflow '${workflow.kind}' is already registered`);
+    workflows.set(workflow.kind, workflow);
+    try {
+      await queueAdapter.process(workflow.kind, (trigger) => workflow.prepare(trigger));
+    } catch (error) {
+      workflows.delete(workflow.kind);
+      throw error;
+    }
+    return workflow;
+  }
+
+  function enqueue(kind, trigger, options = {}) {
+    const workflow = workflows.get(kind);
+    if (!workflow) throw new Error(`no workflow registered for '${kind}'`);
+    const dedupeKey = workflow.dedupeKey(trigger);
+    if (dedupeKey == null || (typeof dedupeKey === 'string' && !dedupeKey.trim())) {
+      throw new Error(`workflow '${kind}' produced an empty dedupe key`);
+    }
+    if (typeof dedupeKey !== 'string') throw new Error(`workflow '${kind}' produced a non-string dedupe key`);
+    return queueAdapter.enqueue(kind, trigger, { ...options, jobId: `${kind}__${dedupeKey}` });
+  }
+
+  return { register, enqueue };
+}
+
+module.exports = { createWorkflowRunner };

package/lib/index.d.ts

@@ -243,7 +243,6 @@ declare module '@peopl-health/nexus' {
     getAssistantProcessor(): AssistantProcessor;
     getLlmMonitor(): { start(options?: { scheduleDaily?: boolean }): Promise<{ enabled: boolean }> } | null;
     initializeLlmMonitor(): Promise<{ enabled: boolean; error?: string } | undefined>;
-    getWorkflowRunner(): WorkflowRunner;
     processInstruction(code: string, instruction: string, role?: string, options?: { triggeredBy?: string }): Promise<void>;
     processSystemMessage(code: string, messages: string | string[], role?: string, options?: { triggeredBy?: string; reply?: boolean }): Promise<void>;
     isConnected(): boolean;
@@ -456,17 +455,16 @@ declare module '@peopl-health/nexus' {
   export interface Workflow {
     kind: string;
     dedupeKey: (trigger: any) => string;
-    prepare: (trigger: any, checkpoints?: any, save?: (patch: any) => Promise<void>) => Promise<any>;
-    retrySchedule?: number[];
+    prepare: (trigger: any) => Promise<any>;
   }
 
   export interface WorkflowRunner {
     register(workflow: Workflow): Promise<Workflow>;
-    enqueue(kind: string, trigger: any, options?: QueueJobOptions): Promise<string | null>;
-    sweep(only?: string[]): Promise<string[]>;
-    stop(): void;
+    enqueue(kind: string, trigger: any, options?: QueueJobOptions): Promise<string>;
   }
 
+  export function createWorkflowRunner(options: { queueAdapter: QueueAdapter }): WorkflowRunner;
+
   // Memory System
   export interface PatientMemoryDocument {
     _id: any;

package/lib/index.js

@@ -27,6 +27,7 @@ const { BaileysProvider } = require('./adapters/BaileysProvider');
 const { setPreprocessingHandler, hasPreprocessingHandler, invokePreprocessingHandler } = require('./services/preprocessingService');
 const { requestIdMiddleware, getRequestId } = require('./middleware/requestId');
 const { QueueAdapter, LocalQueueAdapter, RedisQueueAdapter, createQueueAdapter, registerQueueAdapter } = require('./queue');
+const { createWorkflowRunner } = require('./core/workflowRunner');
 const routes = require('./routes');
 const { resetAll } = require('./config/lifecycle');
 const { EvalProvider } = require('./eval/EvalProvider');
@@ -220,6 +221,7 @@ class Nexus {
 }
 
 module.exports = {
+  createWorkflowRunner,
   Nexus,
   TwilioProvider,
   BaileysProvider,

package/lib/services/airtableService.js

@@ -15,11 +15,6 @@ const AIRTABLE_API_URL = 'https://api.airtable.com/v0';
 const AXIOS_TIMEOUT_CODE = 'ECONNABORTED';
 const RETRY_BASE_DELAY_MS = 1000;
 
-function isPermanentAirtableError(error) {
-  const status = error?.statusCode;
-  return typeof status === 'number' && status >= 400 && status < 500 && status !== 429;
-}
-
 let isEvalMode = false;
 
 function setEvalMode(enabled) {
@@ -47,7 +42,6 @@ async function withAirtableRetry(operation, label, { retryNetworkErrors = true }
       const isTransient = TRANSIENT_STATUS_CODES.includes(error.statusCode)
         || (retryNetworkErrors && isTransientNetworkError(error));
       if (!isTransient || attempt === MAX_ATTEMPTS) {
-        if (isPermanentAirtableError(error)) error.permanent = true;
         throw error;
       }
       const baseDelay = error.statusCode === RATE_LIMITED_STATUS ? RATE_LIMIT_DELAY_MS : RETRY_BASE_DELAY_MS;
@@ -235,7 +229,6 @@ async function upsertRecord(baseID, tableName, fields, { mergeOn } = {}, context
 
 module.exports = {
   setEvalMode,
-  isPermanentAirtableError,
   addRecord,
   getRecords,
   getRecordByFilter,

package/package.json

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

package/lib/core/WorkflowRunner.js

@@ -1,265 +0,0 @@
-const { describeThrown } = require('../utils/errorUtils');
-const { logger } = require('../utils/logger');
-
-const { DeferredWork, RETENTION_MS } = require('../models/deferredWorkModel');
-
-const STALE_CLAIM_MS = 5 * 60 * 1000;
-const MINUTE_MS = 60 * 1000;
-const INDEX_TIMEOUT_MS = 1000;
-const SWEEP_INTERVAL_MS = 60 * 1000;
-
-let indexesReady = null;
-
-function ensureIndexes() {
-  if (!indexesReady) {
-    indexesReady = DeferredWork.init().catch((error) => {
-      indexesReady = null;
-      logger.error('[WorkflowRunner] Index build failed, dedupe and retention are not guaranteed', { error: error.message });
-    });
-  }
-  return indexesReady;
-}
-
-function withIndexTimeout(promise) {
-  let timer;
-  const timeout = new Promise((resolve) => {
-    timer = setTimeout(resolve, INDEX_TIMEOUT_MS);
-    timer.unref();
-  });
-  return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
-}
-
-class WorkflowRunner {
-  constructor({ queueAdapter, sweepIntervalMs = SWEEP_INTERVAL_MS } = {}) {
-    if (!queueAdapter) throw new Error('WorkflowRunner requires a queueAdapter');
-    this.queueAdapter = queueAdapter;
-    this.sweepIntervalMs = sweepIntervalMs;
-    this.sweepTimer = null;
-    this.timers = new Map();
-    this.workflows = new Map();
-    this.stopped = false;
-  }
-
-  async register(workflow = {}) {
-    if (!workflow.kind || typeof workflow.kind !== 'string') throw new Error('workflow requires a kind');
-    if (workflow.kind.includes('__')) throw new Error(`workflow '${workflow.kind}' must not contain '__' (reserved as the jobId delimiter)`);
-    if (typeof workflow.dedupeKey !== 'function') throw new Error(`workflow '${workflow.kind}' requires a dedupeKey function`);
-    if (typeof workflow.prepare !== 'function') throw new Error(`workflow '${workflow.kind}' requires a prepare function`);
-    if (this.workflows.has(workflow.kind)) throw new Error(`workflow '${workflow.kind}' is already registered`);
-    if (workflow.retrySchedule !== undefined) {
-      if (!Array.isArray(workflow.retrySchedule) || !workflow.retrySchedule.length) {
-        throw new Error(`workflow '${workflow.kind}' requires a non-empty retrySchedule array`);
-      }
-      if (workflow.retrySchedule.some((minutes) => !Number.isFinite(minutes) || minutes <= 0)) {
-        throw new Error(`workflow '${workflow.kind}' requires retrySchedule entries to be positive minutes`);
-      }
-      if (workflow.retrySchedule.some((minutes) => minutes * MINUTE_MS >= RETENTION_MS)) {
-        throw new Error(`workflow '${workflow.kind}' requires retrySchedule entries under the ${RETENTION_MS / MINUTE_MS}m retention, or the record expires before the attempt fires`);
-      }
-    }
-
-    this.workflows.set(workflow.kind, workflow);
-    if (workflow.retrySchedule) {
-      await this.sweep([workflow.kind]).catch((error) => {
-        logger.error('[WorkflowRunner] Sweep on register failed', { kind: workflow.kind, error: error.message });
-      });
-      this._startSweeping();
-      return workflow;
-    }
-
-    try {
-      await this.queueAdapter.process(workflow.kind, (trigger) => workflow.prepare(trigger));
-    } catch (error) {
-      this.workflows.delete(workflow.kind);
-      throw error;
-    }
-    return workflow;
-  }
-
-  enqueue(kind, trigger, options = {}) {
-    const workflow = this.workflows.get(kind);
-    if (!workflow) throw new Error(`no workflow registered for '${kind}'`);
-    const dedupeKey = workflow.dedupeKey(trigger);
-    if (dedupeKey == null || (typeof dedupeKey === 'string' && !dedupeKey.trim())) {
-      throw new Error(`workflow '${kind}' produced an empty dedupe key`);
-    }
-    if (typeof dedupeKey !== 'string') throw new Error(`workflow '${kind}' produced a non-string dedupe key`);
-    if (!workflow.retrySchedule) {
-      return this.queueAdapter.enqueue(kind, trigger, { ...options, jobId: `${kind}__${dedupeKey}` });
-    }
-    return this._armDeferred(workflow, trigger, dedupeKey);
-  }
-
-  async sweep(only = null) {
-    const deferredKinds = [...this.workflows.values()].filter((w) => w.retrySchedule).map((w) => w.kind);
-    const kinds = only ? deferredKinds.filter((kind) => only.includes(kind)) : deferredKinds;
-    if (!kinds.length) return [];
-
-    const orphaned = await DeferredWork.find({
-      kind: { $in: kinds },
-      $or: [
-        { status: 'pending' },
-        { status: 'processing', claimedAt: { $lt: new Date(Date.now() - STALE_CLAIM_MS) } }
-      ]
-    });
-
-    const rearmed = orphaned.map((work) => this._arm(
-      this.workflows.get(work.kind),
-      work._id,
-      this._delayUntilDue(work),
-    ));
-    if (rearmed.length) logger.info('[WorkflowRunner] Swept', { kinds, rearmed: rearmed.length });
-    return rearmed;
-  }
-
-  _startSweeping() {
-    if (this.stopped || this.sweepTimer || !this.sweepIntervalMs) return;
-    this.sweepTimer = setInterval(() => {
-      this.sweep().catch((error) => logger.error('[WorkflowRunner] Periodic sweep failed', { error: error.message }));
-    }, this.sweepIntervalMs);
-    this.sweepTimer.unref();
-  }
-
-  stop() {
-    this.stopped = true;
-    if (this.sweepTimer) clearInterval(this.sweepTimer);
-    this.sweepTimer = null;
-    for (const timer of this.timers.values()) clearTimeout(timer);
-    this.timers.clear();
-  }
-
-  async _armDeferred(workflow, trigger, dedupeKey) {
-    const { kind } = workflow;
-    await withIndexTimeout(ensureIndexes());
-    const work = await DeferredWork.findOne({ kind, dedupeKey })
-      || await DeferredWork.create({ kind, dedupeKey, trigger }).catch(async (error) => {
-        if (error.code !== 11000) throw error;
-        return await DeferredWork.findOne({ kind, dedupeKey });
-      });
-    if (work.status === 'abandoned') {
-      const { modifiedCount } = await DeferredWork.updateOne(
-        { _id: work._id, status: 'abandoned' },
-        { $set: { status: 'pending', attempt: 0, nextAttemptAt: new Date(), lastError: null, claimedAt: null } }
-      );
-      if (!modifiedCount) return null;
-      logger.info('[WorkflowRunner] Re-arming abandoned work', { kind, dedupeKey });
-      return this._arm(workflow, work._id, 0);
-    }
-    if (work.status !== 'pending') {
-      logger.info('[WorkflowRunner] Skipping, work is in flight or complete', { kind, dedupeKey, status: work.status });
-      return null;
-    }
-    return this._arm(workflow, work._id, this._delayUntilDue(work));
-  }
-
-  _delayUntilDue(work) {
-    return Math.max(0, new Date(work.nextAttemptAt).getTime() - Date.now());
-  }
-
-  _arm(workflow, workId, delayMs) {
-    const id = String(workId);
-    // An attempt still in flight when stop() lands must not re-arm after shutdown. The
-    // record stays pending in Mongo, so the next process recovers it on its sweep.
-    if (this.stopped) return id;
-    clearTimeout(this.timers.get(id));
-    const timer = setTimeout(() => {
-      this.timers.delete(id);
-      this._runDeferred(workflow, id).catch((error) => {
-        logger.error('[WorkflowRunner] Deferred run failed', { kind: workflow.kind, deferredWorkId: id, error: error.message });
-      });
-    }, delayMs);
-    timer.unref();
-    this.timers.set(id, timer);
-    return id;
-  }
-
-  async _runDeferred(workflow, deferredWorkId) {
-    const claimedAt = new Date();
-    const prior = await DeferredWork.findOneAndUpdate(
-      {
-        _id: deferredWorkId,
-        $or: [
-          { status: 'pending', nextAttemptAt: { $lte: claimedAt } },
-          { status: 'processing', claimedAt: { $lt: new Date(claimedAt.getTime() - STALE_CLAIM_MS) } }
-        ]
-      },
-      { $set: { status: 'processing', claimedAt } },
-      { new: false }
-    );
-    if (!prior) {
-      logger.info('[WorkflowRunner] Claimed elsewhere or not due', { kind: workflow.kind, deferredWorkId });
-      return { claimed: false };
-    }
-
-    const reclaimed = prior.status === 'processing';
-    const work = { ...prior.toObject(), attempt: prior.attempt + (reclaimed ? 1 : 0) };
-    if (reclaimed) await this._write(work, claimedAt, { attempt: work.attempt });
-
-    const checkpoints = { ...(work.checkpoints || {}) };
-    const save = async (patch) => {
-      Object.assign(checkpoints, patch);
-      const $set = {};
-      for (const [key, value] of Object.entries(patch || {})) $set[`checkpoints.${key}`] = value;
-      if (Object.keys($set).length) await this._write(work, claimedAt, $set);
-    };
-
-    try {
-      await workflow.prepare(work.trigger, checkpoints, save);
-    } catch (error) {
-      return await this._rescheduleOrAbandon(workflow, work, claimedAt, error);
-    }
-    await this._write(work, claimedAt, { status: 'done', claimedAt: null });
-    return { status: 'done' };
-  }
-
-  // matchedCount, not modifiedCount: the fence is "do we still hold the claim", and
-  // modifiedCount is also 0 for a write that matched but set an identical value - a
-  // save() rewriting an unchanged checkpoint is not a lost claim.
-  async _write(work, claimedAt, $set) {
-    const { matchedCount } = await DeferredWork.updateOne({ _id: work._id, claimedAt }, { $set });
-    if (!matchedCount) logger.warn('[WorkflowRunner] Claim lost, write discarded', { deferredWorkId: String(work._id) });
-    return matchedCount > 0;
-  }
-
-  async _rescheduleOrAbandon(workflow, work, claimedAt, error) {
-    // prepare() is consumer code and can throw anything, including null. Dereferencing
-    // it here used to raise a TypeError out of this handler, so neither branch ran and
-    // the record stayed `processing` until stale recovery hit the same failure again.
-    const lastError = describeThrown(error);
-    const delayMinutes = workflow.retrySchedule[work.attempt];
-    if (error?.permanent === true || delayMinutes === undefined) {
-      await this._write(work, claimedAt, { status: 'abandoned', lastError, claimedAt: null });
-      logger.error('[WorkflowRunner] Abandoned', {
-        kind: workflow.kind,
-        dedupeKey: work.dedupeKey,
-        attempt: work.attempt,
-        permanent: error?.permanent === true,
-        error: lastError
-      });
-      return { status: 'abandoned' };
-    }
-
-    const attempt = work.attempt + 1;
-    const delayMs = delayMinutes * MINUTE_MS;
-    const kept = await this._write(work, claimedAt, {
-      status: 'pending',
-      attempt,
-      nextAttemptAt: new Date(Date.now() + delayMs),
-      lastError,
-      claimedAt: null
-    });
-    if (!kept) return { claimed: false };
-
-    logger.warn('[WorkflowRunner] Rescheduled', {
-      kind: workflow.kind,
-      dedupeKey: work.dedupeKey,
-      attempt,
-      delayMinutes,
-      error: lastError
-    });
-    this._arm(workflow, work._id, delayMs);
-    return { status: 'pending', attempt };
-  }
-}
-
-module.exports = { WorkflowRunner };

package/lib/models/deferredWorkModel.js

@@ -1,24 +0,0 @@
-const mongoose = require('mongoose');
-
-const STATUS_VALUES = ['pending', 'processing', 'done', 'abandoned'];
-const RETENTION_MS = 24 * 60 * 60 * 1000;
-
-const deferredWorkSchema = new mongoose.Schema({
-  kind: { type: String, required: true },
-  dedupeKey: { type: String, required: true },
-  trigger: { type: mongoose.Schema.Types.Mixed, default: null },
-  checkpoints: { type: mongoose.Schema.Types.Mixed, default: () => ({}) },
-  status: { type: String, enum: STATUS_VALUES, default: 'pending' },
-  attempt: { type: Number, default: 0 },
-  nextAttemptAt: { type: Date, default: Date.now },
-  claimedAt: { type: Date, default: null },
-  lastError: { type: String, default: null }
-}, { timestamps: true });
-
-deferredWorkSchema.index({ kind: 1, dedupeKey: 1 }, { unique: true, name: 'dedupe_idx' });
-deferredWorkSchema.index({ status: 1, nextAttemptAt: 1 }, { name: 'due_idx' });
-deferredWorkSchema.index({ updatedAt: 1 }, { expireAfterSeconds: RETENTION_MS / 1000, name: 'ttl_idx' });
-
-const DeferredWork = mongoose.model('DeferredWork', deferredWorkSchema);
-
-module.exports = { DeferredWork, RETENTION_MS };