@peopl-health/nexus 5.11.0-dev.1124 → 5.11.0-dev.1126

package/lib/clinical/AssistantProcessor.js

@@ -8,7 +8,7 @@ const { overlayCohortPreset } = require('./helpers/cohortHelper');
 const { forkShadowTurn } = require('./services/shadowService');
 const { diverge } = require('./services/divergenceService');
 const { getAssistantById } = require('./services/assistantResolver');
-const { maybeSendBridge } = require('./services/bridgeService');
+const { maybeSendBridge, clearBridgeState } = require('./services/bridgeService');
 const { getBridgePresetId } = require('./flags/bridgeConfig');
 const { ToolRuntimeContext } = require('./context/ToolRuntimeContext');
 
@@ -45,7 +45,11 @@ class AssistantProcessor {
 
     if (thread.isInCohort && !runOptions.toolRuntimeContext && runOptions.runId && thread.code) {
       try {
-        runOptions.toolRuntimeContext = new ToolRuntimeContext({ patientCode: thread.code, turnId: runOptions.runId });
+        runOptions.toolRuntimeContext = new ToolRuntimeContext({
+          patientCode: thread.code,
+          turnId: runOptions.runId,
+          shouldContinue: runOptions.shouldContinue,
+        });
       } catch (error) {
         logger.warn('[AssistantProcessor] turn will run untraced', { code: thread.code, error: error.message });
       }
@@ -83,7 +87,6 @@ class AssistantProcessor {
         outbound: output,
         completed: runResult?.completed,
         predictionTimeMs,
-        shouldContinue: runOptions.shouldContinue,
       });
     } catch (error) {
       logger.warn('[AssistantProcessor] trace not stored', {
@@ -136,6 +139,7 @@ class AssistantProcessor {
     if (!this.sendMessage) throw new Error('sendMessage function not configured');
     if (!result?.output) return null;
     await this.sendMessage({ code, body: result.output, processed: true, origin: 'assistant', tools_executed: result.tools_executed, prompt: result.prompt, preset: result.preset, response_id: result.response_id, turnId: result.turnId, traceId: result.traceId });
+    clearBridgeState(code);
     return result.output;
   }
 }

package/lib/clinical/context/ToolRuntimeContext.js

@@ -8,6 +8,7 @@ class ToolRuntimeContext {
     repos = {},
     contextSource = null,
     shadow = false,
+    shouldContinue = null,
   } = {}) {
     if (typeof patientCode !== 'string' || !patientCode) {
       throw new Error('ToolRuntimeContext requires a non-empty patientCode');
@@ -22,6 +23,7 @@ class ToolRuntimeContext {
     this.patientCode = patientCode;
     this.turnId = turnId;
     this.sessionId = sessionId;
+    this.shouldContinue = shouldContinue;
     this.repos = repos;
     this.contextSource = contextSource;
     this.enabledSkills = [];
@@ -42,13 +44,17 @@ class ToolRuntimeContext {
     return toolData;
   }
 
-  async store({ outbound = null, completed = false, predictionTimeMs = null, shouldContinue = null } = {}) {
+  isLive() {
+    return typeof this.shouldContinue !== 'function' || this.shouldContinue();
+  }
+
+  async store({ outbound = null, completed = false, predictionTimeMs = null } = {}) {
     this.trace.setSignals({ activatedSkills: [...this.activatedSkills].sort() });
     this.trace.setOutbound(outbound);
-    this.trace.setStatus(completed ? 'completed' : 'incomplete');
+    const superseded = !this.isLive();
+    this.trace.setStatus(superseded ? 'superseded' : (completed ? 'completed' : 'incomplete'));
     this.trace.setTimings({ predictionTimeMs });
-    const superseded = shouldContinue && !shouldContinue();
-    if (!superseded) await this.trace.save();
+    await this.trace.save();
   }
 
   setSafetyArtifact(artifact) {

package/lib/clinical/providers/AnthropicProvider.js

@@ -11,7 +11,7 @@ const { logger } = require('../../utils/logger');
 
 const runtimeConfig = require('../../config/runtimeConfig');
 
-const { BaseLLMProvider, CONVERSATION_CONTINUATION, DELIVERY_NUDGE, MAX_DELIVERY_NUDGES, TERMINAL_DELIVERY_TOOLS } = require('./BaseLLMProvider');
+const { BaseLLMProvider, CONVERSATION_CONTINUATION, DELIVERY_NUDGE, MAX_DELIVERY_NUDGES, TERMINAL_DELIVERY_TOOLS, isSuperseded } = require('./BaseLLMProvider');
 const { handleFunctionCalls } = require('./OpenAIResponsesProviderTools');
 
 const DEFAULT_MAX_FUNCTION_ROUNDS = 12;
@@ -69,7 +69,7 @@ class AnthropicProvider extends BaseLLMProvider {
   async _invokeModel({
     instructions, input, toolSchemas = [], toolChoice = 'auto', followUpToolChoice = 'auto',
     modelConfig, assistant, phiProcessor = null, trace = null, onFirstIteration = null,
-    resolvedPromptId = null, resolvedPresetId = null
+    resolvedPromptId = null, resolvedPresetId = null, shouldContinue = null
   }, options = {}) {
     const executeTools = options.toolExecutor || handleFunctionCalls;
     let totalRetries = 0;
@@ -170,7 +170,7 @@ class AnthropicProvider extends BaseLLMProvider {
         && (response.content || []).some(block => block.type === 'tool_use');
       try {
         const decision = onFirstIteration({ narrationText, hasToolCalls });
-        if (decision?.sent && decision.dedupNote) bridgeNote = decision.dedupNote;
+        if (decision?.dedupNote) bridgeNote = decision.dedupNote;
       } catch (err) {
         logger.warn('[AnthropicProvider] bridge callback failed', { error: err.message });
       }
@@ -187,6 +187,10 @@ class AnthropicProvider extends BaseLLMProvider {
       let deliveryBreak = false;
       const maxIterations = this.maxFunctionRounds + MAX_DELIVERY_NUDGES + LOOP_ITERATION_HEADROOM;
       for (let iteration = 1; iteration <= maxIterations; iteration++) {
+        if (isSuperseded(shouldContinue)) {
+          logger.info('[AnthropicProvider] turn superseded — aborting tool loop', { iteration });
+          break;
+        }
         const content = finalResponse.content || [];
         const toolUses = content.filter(block => block.type === 'tool_use');
         const ended = finalResponse.stop_reason !== 'tool_use' || !toolUses.length;
@@ -251,9 +255,9 @@ class AnthropicProvider extends BaseLLMProvider {
       }
 
       // Budget exhausted mid-work: the loop stopped while the model still wanted tools, so the reply may be empty. Make it
-      // visible — but not on a delivery break, which also exits with pending calls and is not exhaustion.
+      // visible — but not on a supersede or delivery break, which also exit with pending calls and are not exhaustion.
       const pendingTools = (finalResponse.content || []).filter(block => block.type === 'tool_use');
-      if (finalResponse.stop_reason === 'tool_use' && pendingTools.length && !deliveryBreak) {
+      if (finalResponse.stop_reason === 'tool_use' && pendingTools.length && !deliveryBreak && !isSuperseded(shouldContinue)) {
         logger.warn('[AnthropicProvider] Tool-iteration budget exhausted with pending tool calls', { maxFunctionRounds: this.maxFunctionRounds, pending: pendingTools.map(b => b.name) });
         trace?.setSignals?.({ toolBudgetExhausted: true });
       }

package/lib/clinical/providers/BaseLLMProvider.js

@@ -18,6 +18,10 @@ const TERMINAL_DELIVERY_TOOLS = new Set(['DeliverPatientMessage']);
 const DELIVERY_NUDGE = 'sistema: el turno no puede cerrar sin un mensaje para el paciente. Llama ahora a DeliverPatientMessage con message_text en español. No repitas herramientas clínicas ya ejecutadas en este turno.';
 const MAX_DELIVERY_NUDGES = 1;
 
+function isSuperseded(shouldContinue) {
+  return typeof shouldContinue === 'function' && !shouldContinue();
+}
+
 class BaseLLMProvider {
   constructor(options = {}) {
     if (new.target === BaseLLMProvider) {
@@ -332,8 +336,8 @@ class BaseLLMProvider {
           return result;
         }
 
-        if (config.shadow && !config.shouldContinue()) {
-          logger.info('[runConversation] Shadow superseded — returning without retry', { attempt });
+        if (isSuperseded(config.shouldContinue)) {
+          logger.info('[runConversation] Superseded — returning without retry', { attempt, shadow: config.shadow });
           return result;
         }
 
@@ -344,8 +348,8 @@ class BaseLLMProvider {
         await new Promise(r => setTimeout(r, 500));
       } catch (error) {
         logger.error('[runConversation] Attempt failed', { attempt, error: error.message });
-        if (config.shadow && !config.shouldContinue()) {
-          logger.info('[runConversation] Shadow superseded — abandoning after error', { attempt });
+        if (isSuperseded(config.shouldContinue)) {
+          logger.info('[runConversation] Superseded — abandoning after error', { attempt, shadow: config.shadow });
           return { status: 'cancelled', output_text: '', tools_executed: [], retries: 0 };
         }
         if (attempt === maxRetries) throw error;
@@ -528,4 +532,5 @@ module.exports = {
   DELIVERY_NUDGE,
   MAX_DELIVERY_NUDGES,
   TERMINAL_DELIVERY_TOOLS,
+  isSuperseded,
 };

package/lib/clinical/providers/OpenAIResponsesProvider.js

@@ -9,7 +9,7 @@ const { logger } = require('../../utils/logger');
 
 const runtimeConfig = require('../../config/runtimeConfig');
 
-const { BaseLLMProvider } = require('./BaseLLMProvider');
+const { BaseLLMProvider, isSuperseded } = require('./BaseLLMProvider');
 const { handleFunctionCalls } = require('./OpenAIResponsesProviderTools');
 
 const DEFAULT_MAX_FUNCTION_ROUNDS = 12;
@@ -69,7 +69,7 @@ class OpenAIResponsesProvider extends BaseLLMProvider {
     shadow = false, shouldContinue = null, onFirstIteration = null
   }, options = {}) {
     const executeTools = options.toolExecutor || handleFunctionCalls;
-    const shadowSuperseded = () => shadow && !shouldContinue();
+    const superseded = () => isSuperseded(shouldContinue);
     let totalRetries = 0;
     const allToolsExecuted = [];
     const allToolCalls = [];
@@ -127,7 +127,7 @@ class OpenAIResponsesProvider extends BaseLLMProvider {
       const hasToolCalls = Boolean(assistant) && (response.output || []).some(item => item.type === 'function_call');
       try {
         const decision = onFirstIteration({ narrationText, hasToolCalls });
-        if (decision?.sent && decision.dedupNote) bridgeNote = decision.dedupNote;
+        if (decision?.dedupNote) bridgeNote = decision.dedupNote;
       } catch (err) {
         logger.warn('[OpenAIResponsesProvider] bridge callback failed', { error: err.message });
       }
@@ -140,8 +140,8 @@ class OpenAIResponsesProvider extends BaseLLMProvider {
       apiCallConfig.tool_choice = followUpToolChoice;
 
       for (let round = 1; round <= this.maxFunctionRounds; round++) {
-        if (shadowSuperseded()) {
-          logger.info('[OpenAIResponsesProvider] shadow superseded — aborting tool loop', { round });
+        if (superseded()) {
+          logger.info('[OpenAIResponsesProvider] turn superseded — aborting tool loop', { round, shadow });
           break;
         }
         const functionCalls = finalResponse.output.filter(item => item.type === 'function_call');
@@ -167,9 +167,9 @@ class OpenAIResponsesProvider extends BaseLLMProvider {
       }
 
       // Budget exhausted mid-work: the loop stopped while the model still wanted tools, so the reply may be empty. Make it
-      // visible — but not on a shadow-supersede or delivery break, which also exit with pending calls and are not exhaustion.
+      // visible — but not on a supersede or delivery break, which also exit with pending calls and are not exhaustion.
       const pendingCalls = (finalResponse.output || []).filter(item => item.type === 'function_call');
-      if (pendingCalls.length && !shadowSuperseded() && !deliveryBreak) {
+      if (pendingCalls.length && !superseded() && !deliveryBreak) {
         logger.warn('[OpenAIResponsesProvider] Tool-iteration budget exhausted with pending tool calls', { maxFunctionRounds: this.maxFunctionRounds, pending: pendingCalls.map(c => c.name) });
         trace?.setSignals?.({ toolBudgetExhausted: true });
       }

package/lib/clinical/providers/OpenRouterProvider.js

@@ -1,10 +1,12 @@
 const { OpenAI } = require('openai');
 
+const { logger } = require('../../utils/logger');
 const { retryWithBackoff } = require('../../utils/retryUtils');
 const { withTiming } = require('../../utils/tracingDecorator');
 const { safeParse } = require('../../utils/jsonUtils');
 
 const { OpenAIResponsesProvider } = require('./OpenAIResponsesProvider');
+const { isSuperseded } = require('./BaseLLMProvider');
 const { handleFunctionCalls } = require('./OpenAIResponsesProviderTools');
 
 const OPENROUTER_BASE_URL = 'https://openrouter.ai/api/v1';
@@ -37,7 +39,7 @@ class OpenRouterProvider extends OpenAIResponsesProvider {
 
   async _invokeModel({
     instructions, input, toolSchemas = [], toolChoice = 'auto', followUpToolChoice = 'auto',
-    modelConfig, assistant, phiProcessor = null, trace = null
+    modelConfig, assistant, phiProcessor = null, trace = null, shouldContinue = null
   }, options = {}) {
     const executeTools = options.toolExecutor || handleFunctionCalls;
     let totalRetries = 0;
@@ -74,6 +76,10 @@ class OpenRouterProvider extends OpenAIResponsesProvider {
       apiCallConfig.tool_choice = followUpToolChoice;
 
       for (let round = 1; round <= this.maxFunctionRounds; round++) {
+        if (isSuperseded(shouldContinue)) {
+          logger.info('[OpenRouterProvider] turn superseded — aborting tool loop', { round });
+          break;
+        }
         const message = finalResponse.choices?.[0]?.message;
         const toolCalls = message?.tool_calls || [];
         if (!toolCalls.length) break;

package/lib/clinical/services/bridgeService.js

@@ -25,9 +25,9 @@ function buildDedupNote(bridgeText) {
 function maybeSendBridge({ narrationText, hasToolCalls, code, turnId = null, traceId = null, shouldContinue, sendMessage }) {
   if (!isBridgeEnabled()) return { sent: false };
 
-  const skip = (reason) => {
+  const skip = (reason, extra = {}) => {
     logger.info('[bridge] skipped', { code, reason });
-    return { sent: false };
+    return { sent: false, ...extra };
   };
 
   if (typeof shouldContinue === 'function' && !shouldContinue()) return skip('superseded');
@@ -36,20 +36,35 @@ function maybeSendBridge({ narrationText, hasToolCalls, code, turnId = null, tra
   const text = sanitizeBridgeText(narrationText);
   if (!text) return skip('no_usable_narration');
 
-  if (bridgeTimestamps.get(code) !== undefined) return skip('recent_bridge_in_thread');
+  const pending = bridgeTimestamps.get(code);
+  if (pending !== undefined) {
+    return skip('recent_bridge_in_thread', pending.delivered ? { dedupNote: pending.dedupNote } : {});
+  }
 
-  bridgeTimestamps.set(code, true);
+  const dedupNote = buildDedupNote(text);
+  const entry = { dedupNote, delivered: false };
+  bridgeTimestamps.set(code, entry);
+  const failed = (err) => {
+    bridgeTimestamps.delete(code);
+    logger.warn('[bridge] send failed', { code, error: err.message });
+  };
   try {
     Promise.resolve(sendMessage({ code, body: text, processed: true, origin: 'assistant', raw: { bridge: true }, turnId, traceId }))
-      .catch(err => logger.warn('[bridge] send failed', { code, error: err.message }));
+      .then(() => { entry.delivered = true; })
+      .catch(failed);
   } catch (err) {
-    logger.warn('[bridge] send failed', { code, error: err.message });
+    failed(err);
   }
 
   logger.info('[bridge] sent', { code });
-  return { sent: true, text, dedupNote: buildDedupNote(text) };
+  return { sent: true, text, dedupNote };
+}
+
+function clearBridgeState(code) {
+  bridgeTimestamps.delete(code);
 }
 
 module.exports = {
   maybeSendBridge,
+  clearBridgeState,
 };

package/lib/clinical/services/clinicalAirtableService.js

@@ -21,16 +21,21 @@ const INTAKE_SOURCE_TO_AIRTABLE = {
   team_relay: 'doctor',
 };
 
-async function auditedWrite({ trace, code, table, write }) {
+async function auditedWrite({ trace, code, table, write, isLive = null }) {
   const entry = { table, at: new Date().toISOString(), ok: false };
-  try {
-    const result = await write();
-    entry.ok = true;
-    const record = Array.isArray(result) ? result[0] : result;
-    if (record?.id) entry.recordId = record.id;
-  } catch (err) {
-    entry.error = err?.message || String(err);
-    logger.error('[clinicalAirtableService] Airtable write failed', { table, code, error: entry.error });
+  if (isLive && !isLive()) {
+    entry.skipped = 'superseded';
+    logger.info('[clinicalAirtableService] Airtable write skipped — turn superseded', { table, code });
+  } else {
+    try {
+      const result = await write();
+      entry.ok = true;
+      const record = Array.isArray(result) ? result[0] : result;
+      if (record?.id) entry.recordId = record.id;
+    } catch (err) {
+      entry.error = err?.message || String(err);
+      logger.error('[clinicalAirtableService] Airtable write failed', { table, code, error: entry.error });
+    }
   }
   if (trace?.setSignals) {
     const existing = Array.isArray(trace.signals?.airtableWrites) ? trace.signals.airtableWrites : [];
@@ -92,10 +97,11 @@ async function recordEmergency({ code, trace, symptom, suspectedCondition = '',
   });
 }
 
-async function recordClinicalIntake({ code, trace, messageRaw, source = 'self' }) {
+async function recordClinicalIntake({ code, trace, messageRaw, source = 'self', isLive = null }) {
   return auditedWrite({
     trace,
     code,
+    isLive,
     table: 'intake',
     write: async () => {
       const patientId = await findIntakePatientRecordId(code);
@@ -110,12 +116,13 @@ async function recordClinicalIntake({ code, trace, messageRaw, source = 'self' }
   });
 }
 
-async function recordReminder({ code, trace, actionType, reminderId, reminderDateUtc, reminderType, description }) {
+async function recordReminder({ code, trace, actionType, reminderId, reminderDateUtc, reminderType, description, isLive = null }) {
   const type = REMINDER_TYPE_TO_AIRTABLE[reminderType] || reminderType;
   if (actionType === 'update') {
     return auditedWrite({
       trace,
       code,
+      isLive,
       table: 'reminder',
       write: async () => {
         const updated = await airtableService.updateRecordByFilter(
@@ -133,6 +140,7 @@ async function recordReminder({ code, trace, actionType, reminderId, reminderDat
   return auditedWrite({
     trace,
     code,
+    isLive,
     table: 'reminder',
     write: () => airtableService.addLinkedRecord(
       Monitoreo_ID,

package/lib/clinical/services/shadowService.js

@@ -27,7 +27,7 @@ async function runShadowTurn({
   const shadowAssistant = resolveAssistant(shadowThread);
 
   const context = new ToolRuntimeContext({
-    patientCode: code, turnId: runId, sessionId, shadow: true,
+    patientCode: code, turnId: runId, sessionId, shadow: true, shouldContinue,
   });
 
   const runOptions = {

package/lib/clinical/tools/extractClinicalInfoTool.js

@@ -153,6 +153,7 @@ async function handler(args, context = {}) {
       trace,
       messageRaw: intakeSummary,
       source: intakeSource,
+      isLive: runtime.isLive?.bind(runtime),
     });
   }
 

package/lib/clinical/tools/schedulePatientReminderTool.js

@@ -107,11 +107,18 @@ async function handler(args = {}, context = {}) {
     };
     trace.setSignals({ reminderIntents: [...existing, intent] });
 
+    const isLive = runtime.isLive?.bind(runtime);
+    const superseded = Boolean(isLive) && !isLive();
+
     if (runtime.patientCode) {
-      try {
-        await dispatchReminder({ intent, patientId: runtime.patientCode });
-      } catch (err) {
-        logger.warn('[schedulePatientReminder] reminder FHIR projection failed; ack unaffected', { turnId, error: err?.message });
+      if (superseded) {
+        logger.info('[schedulePatientReminder] reminder projection skipped — turn superseded', { turnId });
+      } else {
+        try {
+          await dispatchReminder({ intent, patientId: runtime.patientCode });
+        } catch (err) {
+          logger.warn('[schedulePatientReminder] reminder FHIR projection failed; ack unaffected', { turnId, error: err?.message });
+        }
       }
     }
 
@@ -124,6 +131,7 @@ async function handler(args = {}, context = {}) {
         reminderDateUtc: fireMoment.toISOString(),
         reminderType,
         description: storedDescription,
+        isLive,
       });
     }
 

package/package.json

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