@peopl-health/nexus 5.54.0-dev.7997 → 5.54.0-dev.8011

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/config/safetyNetConfig.js

@@ -1,28 +1,46 @@
 const runtimeConfig = require('../../config/runtimeConfig');
 
-const DEFAULT_OFFER_WINDOW_MS = 4 * 60 * 60 * 1000;
-const DEFAULT_HUMAN_QUIET_MS = 60 * 60 * 1000;
+const DEFAULT_OFFER_WINDOW_MS = 24 * 60 * 60 * 1000;
+const DEFAULT_HUMAN_QUIET_MS = 24 * 60 * 60 * 1000;
+const DEFAULT_ACTIVITY_QUIET_MS = 2 * 60 * 60 * 1000;
 const DEFAULT_TAP_WINDOW_MS = 30 * 60 * 1000;
-const DEFAULT_PLEDGE_MS = 30 * 60 * 1000;
+const DEFAULT_PLEDGE_MS = 8 * 60 * 60 * 1000;
 const DEFAULT_SWEEP_INTERVAL_MS = 5 * 60 * 1000;
 
 const CONTACT_WINDOW = { timeZone: 'America/Mexico_City', startHour: 8, endHour: 21 };
 
 const SAFETY_NET_SOURCE = 'paused_safety_net';
 
-const humanReplyFilter = (code, since) => ({
+const PATIENT_FACING_ORIGINS = ['whatsapp_platform', 'assistant'];
+const HUMAN_ORIGINS = ['whatsapp_platform'];
+const UNDELIVERED_STATUSES = ['failed', 'undelivered'];
+const RECEIVED_STATUSES = ['delivered', 'read'];
+
+const anyReplyFilter = (code, since) => ({
   numero: code,
   from_me: true,
   content_sid: null,
-  origin: { $ne: 'assistant' },
+  origin: { $in: PATIENT_FACING_ORIGINS },
+  'statusInfo.status': { $nin: UNDELIVERED_STATUSES },
   triggeredBy: { $ne: SAFETY_NET_SOURCE },
   createdAt: { $gt: since }
 });
 
+const humanReplyFilter = (code, since) => ({
+  ...anyReplyFilter(code, since),
+  origin: { $in: HUMAN_ORIGINS }
+});
+
+const settledHumanReplyFilter = (code, since, unconfirmedBefore) => ({
+  ...humanReplyFilter(code, since),
+  $or: [
+    { 'statusInfo.status': { $in: RECEIVED_STATUSES } },
+    { createdAt: { $lte: unconfirmedBefore } }
+  ]
+});
+
 const CHOICE_LABEL_KEYS = {
-  urgent: 'PAUSED_SAFETY_NET_URGENT_LABEL',
-  callback: 'PAUSED_SAFETY_NET_CALLBACK_LABEL',
-  later: 'PAUSED_SAFETY_NET_LATER_LABEL'
+  callback: 'PAUSED_SAFETY_NET_CALLBACK_LABEL'
 };
 
 let injected = {};
@@ -49,15 +67,20 @@ const duration = (key, envKey, fallback) => {
 module.exports = {
   CONTACT_WINDOW,
   SAFETY_NET_SOURCE,
+  DEFAULT_PLEDGE_MS,
+  anyReplyFilter,
   humanReplyFilter,
+  settledHumanReplyFilter,
   CHOICE_LABEL_KEYS,
   configureSafetyNet,
   _resetSafetyNetConfig,
   getSafetyNetContentSid: () => text('contentSid', 'PAUSED_SAFETY_NET_CONTENT_SID'),
+  getSafetyNetUnassignedContentSid: () => text('unassignedContentSid', 'PAUSED_SAFETY_NET_UNASSIGNED_CONTENT_SID'),
   getSafetyNetPhone: () => text('phone', 'PAUSED_SAFETY_NET_PHONE'),
   getSafetyNetLabel: (choice) => text(`${choice}Label`, CHOICE_LABEL_KEYS[choice]),
   getOfferWindowMs: () => duration('offerWindowMs', 'PAUSED_SAFETY_NET_WINDOW_MS', DEFAULT_OFFER_WINDOW_MS),
   getHumanQuietMs: () => duration('humanQuietMs', 'SAFETY_NET_HUMAN_QUIET_MS', DEFAULT_HUMAN_QUIET_MS),
+  getActivityQuietMs: () => duration('activityQuietMs', 'SAFETY_NET_ACTIVITY_QUIET_MS', DEFAULT_ACTIVITY_QUIET_MS),
   getTapWindowMs: () => duration('tapWindowMs', 'SAFETY_NET_TAP_WINDOW_MS', DEFAULT_TAP_WINDOW_MS),
   getPledgeMs: () => duration('pledgeMs', 'SAFETY_NET_PLEDGE_MS', DEFAULT_PLEDGE_MS),
   getSweepIntervalMs: () => duration('sweepIntervalMs', 'SAFETY_NET_SWEEP_INTERVAL_MS', DEFAULT_SWEEP_INTERVAL_MS)

package/lib/clinical/services/assistantService.js

@@ -15,7 +15,7 @@ const { cleanupFiles } = require('../../helpers/filesHelper.js');
 const { getMessages, countMessages } = require('../../services/messageService');
 
 const { getAssistantById } = require('./assistantResolver');
-const { coverUnansweredPatient } = require('./pausedSafetyNetService');
+const { PAUSED, coverUnansweredPatient } = require('./pausedSafetyNetService');
 
 const MEDIA_BACKLOG_LIMIT = 10;
 
@@ -112,7 +112,7 @@ const preProcessMessagesCore = async (code, message_ = null, thread) => {
       return { shouldProcess: false, messages: null, timings, pendingMediaUpdates: [] };
     }
 
-    if (thread.stopped) await coverUnansweredPatient({ code });
+    if (thread.stopped) await coverUnansweredPatient({ code, reason: PAUSED });
 
     const backlog = await fetchMediaBacklog(code, lastMessage[0]);
     const replies = [...backlog, ...lastMessage];

package/lib/clinical/services/pausedSafetyNetService.js

@@ -1,12 +1,12 @@
 const {
-  CONTACT_WINDOW,
   SAFETY_NET_SOURCE,
+  getActivityQuietMs,
   getHumanQuietMs,
   getOfferWindowMs,
-  getPledgeMs,
   getSafetyNetContentSid,
   getSafetyNetLabel,
   getSafetyNetPhone,
+  getSafetyNetUnassignedContentSid,
   getTapWindowMs
 } = require('../config/safetyNetConfig');
 const { logger } = require('../../utils/logger');
@@ -15,28 +15,23 @@ const { acquireSendClaim, completeSendClaim, releaseSendClaim } = require('../..
 
 const { normalizePayload: normalize, registerInteractiveRoute, unregisterInteractiveRoute } = require('../../core/interactiveRouteService');
 const { getMessages } = require('../../services/messageService');
-const { getPatientTasks, updatePatientTask } = require('../../services/patientTaskService');
 
 const { WriteClaimStore } = require('./writeClaimStore');
-const { PAUSED_THREAD_DETAILS_PREFIX, recordPausedThreadMessage, recordUnresolvedRequest } = require('./clinicalAirtableService');
-const { humanRepliedSince, openPledge, stopSafetyNetSweep } = require('./safetyNetPledgeService');
+const { recordPausedThreadMessage, recordUnresolvedRequest } = require('./clinicalAirtableService');
+const { anyoneRepliedSince, humanRepliedSince, openPledge, stopSafetyNetSweep } = require('./safetyNetPledgeService');
 
 const getMessaging = () => require('../../core/NexusMessaging');
 
 const SOURCE = SAFETY_NET_SOURCE;
 const PAYLOAD_PREFIX = 'peopl_safetynet_';
-const CHOICES = ['urgent', 'callback', 'later'];
+const CHOICES = ['callback'];
+const PAUSED = 'paused';
+const UNASSIGNED = 'unassigned';
 const REQUEST_CATEGORY = 'contact_team_member';
-const CAN_WAIT_NOTE = 'El paciente indicó que su solicitud puede esperar.';
-const ATTENDED_STATUS = 'sin atender';
 
 const REQUEST_COPY = {
-  urgent: {
-    question: 'El paciente indicó que su situación es urgente',
-    details: (code) => `El paciente ${code} recibió el aviso de bot en pausa y eligió "urgencia". Se le dio el número para llamar. Revisar la conversación ahora.`
-  },
   callback: {
-    question: 'El paciente pidió que el equipo lo contacte hoy',
+    question: 'El paciente pidió que el equipo lo contacte',
     details: (code) => `El paciente ${code} recibió el aviso de bot en pausa y pidió que lo contacten. Se le prometió contacto; revisar la conversación.`
   }
 };
@@ -81,15 +76,25 @@ function matchSafetyNetChoice(payload, title) {
   }) || null;
 }
 
+const dialledNumbers = (template) => Object.values(template?.types ?? {})
+  .flatMap((type) => type?.actions ?? [])
+  .filter((action) => action?.type === 'PHONE_NUMBER')
+  .map((action) => action?.phone);
+
 async function warnIfPhoneDiffersFromTemplate(contentSid) {
   const phone = getSafetyNetPhone();
   if (!phone || phoneCheckedFor === contentSid) return;
   phoneCheckedFor = contentSid;
   try {
-    const body = await getMessaging().requireProvider().renderTemplate(contentSid);
+    const provider = getMessaging().requireProvider();
     const digits = (value) => String(value ?? '').replace(/\D/g, '');
-    if (body && !digits(body).includes(digits(phone))) {
-      logger.error('[PausedSafetyNet] The configured phone number is absent from the template body', { contentSid });
+    const wanted = digits(phone);
+
+    if (dialledNumbers(await provider.getTemplate(contentSid)).map(digits).includes(wanted)) return;
+
+    const body = await provider.renderTemplate(contentSid);
+    if (body && !digits(body).includes(wanted)) {
+      logger.error('[PausedSafetyNet] The configured phone number is absent from the template', { contentSid });
     }
   } catch (error) {
     phoneCheckedFor = null;
@@ -97,13 +102,19 @@ async function warnIfPhoneDiffersFromTemplate(contentSid) {
   }
 }
 
-async function offerSafetyNet({ code }) {
+function templateFor(reason) {
+  if (reason !== UNASSIGNED) return getSafetyNetContentSid();
+  return getSafetyNetUnassignedContentSid() || getSafetyNetContentSid();
+}
+
+async function offerSafetyNet({ code, reason = PAUSED }) {
   try {
-    const contentSid = getSafetyNetContentSid();
-    if (!code || !contentSid || !getSafetyNetPhone()) return { sent: false, reason: 'not_configured' };
+    if (!code || !getSafetyNetContentSid() || !getSafetyNetPhone()) return { sent: false, reason: 'not_configured' };
     if (await offerClaims().get(code)) return { sent: false, reason: 'recent_offer' };
     if (await humanRepliedSince(code, new Date(Date.now() - getHumanQuietMs()))) return { sent: false, reason: 'human_active' };
+    if (await anyoneRepliedSince(code, new Date(Date.now() - getActivityQuietMs()))) return { sent: false, reason: 'conversation_active' };
 
+    const contentSid = templateFor(reason);
     await warnIfPhoneDiffersFromTemplate(contentSid);
 
     const result = await getMessaging().sendMessage({ code, contentSid, triggeredBy: SOURCE });
@@ -118,11 +129,13 @@ async function offerSafetyNet({ code }) {
   }
 }
 
+const offerContentSids = () => [getSafetyNetContentSid(), getSafetyNetUnassignedContentSid()].filter(Boolean);
+
 async function offerIsLive(code) {
   try {
     const since = new Date(Date.now() - getOfferWindowMs());
     const [sent] = await getMessages(
-      { numero: code, from_me: true, content_sid: getSafetyNetContentSid(), createdAt: { $gt: since } },
+      { numero: code, from_me: true, content_sid: { $in: offerContentSids() }, createdAt: { $gt: since } },
       { sort: { createdAt: -1 }, limit: 1 }
     );
     return Boolean(sent);
@@ -140,7 +153,7 @@ async function unansweredText(code) {
   return written ? written.plainBody || written.body : null;
 }
 
-async function coverUnansweredPatient({ code }) {
+async function coverUnansweredPatient({ code, reason = PAUSED }) {
   if (!code) return;
 
   const claim = await acquireSendClaim({ idempotencyKey: `safetynet-cover:${code}` });
@@ -148,7 +161,7 @@ async function coverUnansweredPatient({ code }) {
 
   const results = await Promise.allSettled([
     unansweredText(code).then((text) => recordPausedThreadMessage({ code, text })),
-    offerSafetyNet({ code }),
+    offerSafetyNet({ code, reason }),
   ]);
 
   const covered = results.every((r) => r.status === 'fulfilled');
@@ -168,32 +181,8 @@ async function fileUrgentRequest(code, choice) {
   });
 }
 
-async function markCanWait(code) {
-  const { requests = [] } = await getPatientTasks(code);
-  const target = requests.find((request) => request.status === ATTENDED_STATUS
-    && request.category === REQUEST_CATEGORY
-    && String(request.details || '').startsWith(PAUSED_THREAD_DETAILS_PREFIX));
-  if (!target) return false;
-
-  await updatePatientTask({
-    code,
-    kind: 'requests',
-    recordId: target.recordId,
-    changes: {
-      urgency: 'routine',
-      note: [target.note, CAN_WAIT_NOTE].filter(Boolean).join('\n')
-    },
-    updatedBy: SOURCE,
-    source: SOURCE
-  });
-  return true;
-}
-
 async function applyChoice(code, choice) {
-  if (choice === 'later') return { queued: true, downgraded: await markCanWait(code), pledge: null };
-
   const queued = await fileUrgentRequest(code, choice);
-  if (choice !== 'callback') return { queued, pledge: null };
   if (!queued) return { queued, pledge: null };
 
   try {
@@ -218,30 +207,12 @@ function ackFor(choice, outcome) {
     return withPhone('No pudimos registrar tu solicitud.', 'Por favor llámanos al {phone} para que te atendamos.');
   }
 
-  if (choice === 'urgent') {
-    return withPhone('Entendido, ya avisamos al equipo.', 'Si es una urgencia médica, llámanos ahora al {phone}.');
-  }
-
-  if (choice === 'later') {
-    return outcome.downgraded
-      ? withPhone('Gracias, lo anotamos. El equipo revisará tu mensaje.', 'Si necesitas ayuda antes, llámanos al {phone}.')
-      : withPhone('Gracias. El equipo revisará tu mensaje.', 'Si necesitas ayuda antes, llámanos al {phone}.');
-  }
-
   if (!outcome.pledge) {
     return withPhone('Listo, ya avisamos al equipo y te van a contactar.', 'Si te sientes peor antes, llámanos al {phone}.');
   }
 
-  if (outcome.pledge.deferredToWindow) {
-    return withPhone(
-      `Listo, ya avisamos al equipo. Te van a contactar en cuanto abran, a partir de las ${CONTACT_WINDOW.startHour}:00.`,
-      'Si es una urgencia médica, llámanos ahora al {phone}.'
-    );
-  }
-
-  const minutes = Math.round(getPledgeMs() / 60000);
   return withPhone(
-    `Listo. Un miembro del equipo te va a contactar en los próximos ${minutes} minutos.`,
+    'Listo. Un miembro del equipo te va a contactar a la brevedad.',
     'Si te sientes peor antes, llámanos al {phone}.'
   );
 }
@@ -310,6 +281,8 @@ module.exports = {
   coverUnansweredPatient,
   disarmSafetyNet,
   offerSafetyNet,
+  PAUSED,
+  UNASSIGNED,
   handleSafetyNetTap,
   matchSafetyNetChoice,
   registerSafetyNetRoutes,

package/lib/clinical/services/safetyNetPledgeService.js

@@ -1,7 +1,10 @@
-const { CONTACT_WINDOW, getPledgeMs, getSweepIntervalMs, humanReplyFilter } = require('../config/safetyNetConfig');
+const {
+  CONTACT_WINDOW, DEFAULT_PLEDGE_MS, anyReplyFilter, getPledgeMs, getSweepIntervalMs, humanReplyFilter,
+  settledHumanReplyFilter
+} = require('../config/safetyNetConfig');
 const { createIntervalSweeper } = require('../../utils/intervalSweeper');
 const { logger } = require('../../utils/logger');
-const { clampToHourWindow } = require('../../utils/scheduleUtils');
+const { addContactHours } = require('../../utils/scheduleUtils');
 
 const { SafetyNetPledge } = require('../../models/safetyNetPledgeModel');
 
@@ -13,24 +16,36 @@ const SWEEP_LIMIT = 200;
 const BREACH_CATEGORY = 'contact_team_member';
 const BREACH_QUESTION = 'El paciente sigue esperando el contacto que se le prometió';
 
-async function humanRepliedSince(code, since) {
-  const [reply] = await getMessages(humanReplyFilter(code, since), { sort: { createdAt: -1 }, limit: 1 });
+const DELIVERY_GRACE_MS = 10 * 60 * 1000;
+const HOUR_MS = 60 * 60 * 1000;
+
+async function repliedSince(filter) {
+  const [reply] = await getMessages(filter, { sort: { createdAt: -1 }, limit: 1 });
   return Boolean(reply);
 }
 
+const humanRepliedSince = (code, since) => repliedSince(humanReplyFilter(code, since));
+const humanReplySettledSince = (code, since) => repliedSince(
+  settledHumanReplyFilter(code, since, new Date(Date.now() - DELIVERY_GRACE_MS))
+);
+const anyoneRepliedSince = (code, since) => repliedSince(anyReplyFilter(code, since));
+
 function pledgeDueAt(pledgedAt) {
-  const target = new Date(pledgedAt.getTime() + getPledgeMs());
-  const opened = clampToHourWindow(target, CONTACT_WINDOW);
-  if (!opened) return { dueAt: target, deferredToWindow: false };
-  return { dueAt: opened, deferredToWindow: opened.getTime() > target.getTime() };
+  const configured = addContactHours(pledgedAt, getPledgeMs() / HOUR_MS, CONTACT_WINDOW);
+  if (configured) return { dueAt: configured };
+
+  logger.error('[SafetyNetPledge] The configured pledge does not fit in working hours; using the default', {
+    pledgeMs: getPledgeMs()
+  });
+  return { dueAt: addContactHours(pledgedAt, DEFAULT_PLEDGE_MS / HOUR_MS, CONTACT_WINDOW) };
 }
 
 async function openPledge({ code }) {
   const pledgedAt = new Date();
-  const { dueAt, deferredToWindow } = pledgeDueAt(pledgedAt);
-  const pledge = await SafetyNetPledge.create({ code, pledgedAt, dueAt, deferredToWindow });
-  logger.info('[SafetyNetPledge] Contact pledged', { code, dueAt, deferredToWindow });
-  return { pledgeId: pledge._id, dueAt, deferredToWindow };
+  const { dueAt } = pledgeDueAt(pledgedAt);
+  const pledge = await SafetyNetPledge.create({ code, pledgedAt, dueAt });
+  logger.info('[SafetyNetPledge] Contact pledged', { code, dueAt });
+  return { pledgeId: pledge._id, dueAt };
 }
 
 async function reportBreach(pledge) {
@@ -51,6 +66,11 @@ const settle = async (id, from, state) => Boolean(
   await SafetyNetPledge.findOneAndUpdate({ _id: id, state: from }, { $set: { state, resolvedAt: new Date() } }).lean()
 );
 
+const returnToPending = (id) => SafetyNetPledge.updateOne(
+  { _id: id, state: 'reporting' },
+  { $set: { state: 'pending', reportingSince: null } }
+);
+
 const takeReportingLease = async (id) => Boolean(
   await SafetyNetPledge.findOneAndUpdate(
     { _id: id, $or: [{ state: 'pending' }, { state: 'reporting', reportingSince: { $lt: new Date(Date.now() - REPORT_LEASE_MS) } }] },
@@ -73,13 +93,18 @@ async function sweepSafetyNetPledges() {
     try {
       if (!await takeReportingLease(pledge._id)) continue;
 
-      if (await humanRepliedSince(pledge.code, pledge.pledgedAt)) {
+      if (await humanReplySettledSince(pledge.code, pledge.pledgedAt)) {
         await settle(pledge._id, 'reporting', 'met');
         continue;
       }
 
+      if (await humanRepliedSince(pledge.code, pledge.pledgedAt)) {
+        await returnToPending(pledge._id);
+        continue;
+      }
+
       if (!await reportBreach(pledge)) {
-        await SafetyNetPledge.updateOne({ _id: pledge._id, state: 'reporting' }, { $set: { state: 'pending', reportingSince: null } });
+        await returnToPending(pledge._id);
         logger.error('[SafetyNetPledge] Breach was not recorded, pledge returns to pending for the next sweep', { code: pledge.code });
         continue;
       }
@@ -104,7 +129,9 @@ const stopSafetyNetSweep = () => sweeper.stop();
 module.exports = {
   startSafetyNetSweep,
   stopSafetyNetSweep,
+  anyoneRepliedSince,
   humanRepliedSince,
+  humanReplySettledSince,
   openPledge,
   pledgeDueAt,
   sweepSafetyNetPledges,

package/lib/core/NexusMessaging.js

@@ -31,7 +31,7 @@ const { releaseHeldMessages, sweepHeldMessages } = require('../services/heldMess
 const { BatchingManager } = require('../core/BatchingManager');
 const { ProcessingPipeline } = require('../core/ProcessingPipeline');
 const { preProcessMessages, configureOpenAIProvider, AssistantProcessor, TURN_KIND } = require('../clinical');
-const { coverUnansweredPatient } = require('../clinical/services/pausedSafetyNetService');
+const { UNASSIGNED, coverUnansweredPatient } = require('../clinical/services/pausedSafetyNetService');
 const { buildOutreachCarrier } = require('../clinical/services/outreachCarrierService');
 const { routineOutreachCollisionReason } = require('../clinical/services/outreachSweepService');
 const {
@@ -46,7 +46,6 @@ const { isLlmMonitorEnabled } = require('../clinical/flags/llmMonitorConfig');
 const { createQueueAdapter } = require('../queue');
 const { ScheduledMessageJob } = require('../jobs/ScheduledMessageJob');
 const { TemplateApprovalJob } = require('../jobs/TemplateApprovalJob');
-const { WorkflowRunner } = require('./DeferredWorkRunner');
 const { invokeInteractiveRoute } = require('./interactiveRouteService');
 
 const { PhiProcessor } = require('./PhiProcessor');
@@ -136,8 +135,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,
@@ -322,7 +319,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); }
@@ -697,7 +693,7 @@ class NexusMessaging {
         return null;
       });
       if (!resolved) {
-        await coverUnansweredPatient({ code: chatId });
+        await coverUnansweredPatient({ code: chatId, reason: UNASSIGNED });
         return null;
       }
 
@@ -1102,8 +1098,6 @@ class NexusMessaging {
     await withTimeout(this._reconciliationStopped, teardownMs, 'queueReconciliation.stop')
       .catch(error => logger.warn('[NexusMessaging] Reconciliation sweep did not settle in time', { error: error.message }));
 
-    if (this.workflowRunner) this.workflowRunner.stop();
-
     if (this.queueAdapter) {
       await withTimeout(this.queueAdapter.shutdown(), teardownMs, 'queueAdapter.shutdown')
         .catch(error => logger.warn('[NexusMessaging] Queue shutdown did not finish', { error: error.message }));

package/lib/index.d.ts

@@ -254,7 +254,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>;
     processOutreach(code: string, options?: { brief?: OutreachBrief | null; triggeredBy?: string | null; reason?: string | null; firstName?: string | null; dryRun?: boolean }): Promise<OutreachDecision>;
@@ -548,17 +547,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

@@ -301,6 +301,7 @@ class Nexus {
 }
 
 module.exports = {
+  createWorkflowRunner,
   Nexus,
   DrainingError,
   TwilioProvider,

package/lib/models/safetyNetPledgeModel.js

@@ -6,7 +6,6 @@ const safetyNetPledgeSchema = new mongoose.Schema({
   code: { type: String, required: true },
   pledgedAt: { type: Date, required: true },
   dueAt: { type: Date, required: true },
-  deferredToWindow: { type: Boolean, default: false },
   state: { type: String, enum: PLEDGE_STATES, default: 'pending' },
   reportingSince: { type: Date, default: null },
   resolvedAt: { type: Date, default: null },

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;
@@ -242,7 +236,6 @@ async function upsertRecord(baseID, tableName, fields, options = {}, context = n
 
 module.exports = {
   setEvalMode,
-  isPermanentAirtableError,
   addRecord,
   getRecords,
   getRecordByFilter,

package/lib/utils/scheduleUtils.js

@@ -50,6 +50,29 @@ function contactHoursBetween(from, to, { timeZone, startHour, endHour }) {
   return cursor.isBefore(end) ? Infinity : total;
 }
 
+function addContactHours(from, hours, { timeZone, startHour, endHour }) {
+  const start = moment.tz(from, timeZone);
+  if (!start.isValid() || !(hours >= 0)) {
+    logger.warn('[addContactHours] Invalid input', { from, hours, timeZone });
+    return null;
+  }
+
+  let remaining = hours * 60 * 60 * 1000;
+  let cursor = start.clone();
+  for (let day = 0; day < MAX_CONTACT_SPAN_DAYS; day += 1) {
+    const opens = cursor.clone().startOf('day').hour(startHour);
+    const closes = cursor.clone().startOf('day').hour(endHour);
+    if (cursor.isBefore(opens)) cursor = opens;
+    if (cursor.isBefore(closes)) {
+      const available = closes.diff(cursor);
+      if (remaining < available) return cursor.clone().add(remaining, 'ms').toDate();
+      remaining -= available;
+    }
+    cursor = opens.clone().add(1, 'day');
+  }
+  return remaining === 0 ? cursor.toDate() : null;
+}
+
 function calculateDelay(sendTime, timeZone) {
   if (!sendTime) return DEFAULT_DELAY;
 
@@ -88,4 +111,4 @@ function calculateDelay(sendTime, timeZone) {
   }
 }
 
-module.exports = { calculateDelay, clampToHourWindow, isWithinHourWindow, contactHoursBetween, DEFAULT_TIMEZONE };
+module.exports = { addContactHours, calculateDelay, clampToHourWindow, isWithinHourWindow, contactHoursBetween, DEFAULT_TIMEZONE };

package/package.json

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

package/lib/core/DeferredWorkRunner.js

@@ -1,257 +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);
-    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' };
-  }
-
-  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) {
-    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 };