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

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');
 
@@ -136,6 +136,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/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/package.json

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