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

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, clearBridgeState } = require('./services/bridgeService');
+const { maybeSendBridge } = require('./services/bridgeService');
 const { getBridgePresetId } = require('./flags/bridgeConfig');
 const { ToolRuntimeContext } = require('./context/ToolRuntimeContext');
 
@@ -136,7 +136,6 @@ 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, isSuperseded } = require('./BaseLLMProvider');
+const { BaseLLMProvider, CONVERSATION_CONTINUATION, DELIVERY_NUDGE, MAX_DELIVERY_NUDGES, TERMINAL_DELIVERY_TOOLS } = 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, shouldContinue = null
+    resolvedPromptId = null, resolvedPresetId = 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?.dedupNote) bridgeNote = decision.dedupNote;
+        if (decision?.sent && decision.dedupNote) bridgeNote = decision.dedupNote;
       } catch (err) {
         logger.warn('[AnthropicProvider] bridge callback failed', { error: err.message });
       }
@@ -187,10 +187,6 @@ 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;
@@ -255,9 +251,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 supersede or delivery break, which also exit with pending calls and are not exhaustion.
+      // visible — but not on a delivery break, which also exits with pending calls and is not exhaustion.
       const pendingTools = (finalResponse.content || []).filter(block => block.type === 'tool_use');
-      if (finalResponse.stop_reason === 'tool_use' && pendingTools.length && !deliveryBreak && !isSuperseded(shouldContinue)) {
+      if (finalResponse.stop_reason === 'tool_use' && pendingTools.length && !deliveryBreak) {
         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,10 +18,6 @@ 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) {
@@ -336,8 +332,8 @@ class BaseLLMProvider {
           return result;
         }
 
-        if (isSuperseded(config.shouldContinue)) {
-          logger.info('[runConversation] Superseded — returning without retry', { attempt, shadow: config.shadow });
+        if (config.shadow && !config.shouldContinue()) {
+          logger.info('[runConversation] Shadow superseded — returning without retry', { attempt });
           return result;
         }
 
@@ -348,8 +344,8 @@ class BaseLLMProvider {
         await new Promise(r => setTimeout(r, 500));
       } catch (error) {
         logger.error('[runConversation] Attempt failed', { attempt, error: error.message });
-        if (isSuperseded(config.shouldContinue)) {
-          logger.info('[runConversation] Superseded — abandoning after error', { attempt, shadow: config.shadow });
+        if (config.shadow && !config.shouldContinue()) {
+          logger.info('[runConversation] Shadow superseded — abandoning after error', { attempt });
           return { status: 'cancelled', output_text: '', tools_executed: [], retries: 0 };
         }
         if (attempt === maxRetries) throw error;
@@ -532,5 +528,4 @@ 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, isSuperseded } = require('./BaseLLMProvider');
+const { BaseLLMProvider } = 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 superseded = () => isSuperseded(shouldContinue);
+    const shadowSuperseded = () => shadow && !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?.dedupNote) bridgeNote = decision.dedupNote;
+        if (decision?.sent && 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 (superseded()) {
-          logger.info('[OpenAIResponsesProvider] turn superseded — aborting tool loop', { round, shadow });
+        if (shadowSuperseded()) {
+          logger.info('[OpenAIResponsesProvider] shadow superseded — aborting tool loop', { round });
           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 supersede or delivery break, which also exit with pending calls and are not exhaustion.
+      // visible — but not on a shadow-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 && !superseded() && !deliveryBreak) {
+      if (pendingCalls.length && !shadowSuperseded() && !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,12 +1,10 @@
 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';
@@ -39,7 +37,7 @@ class OpenRouterProvider extends OpenAIResponsesProvider {
 
   async _invokeModel({
     instructions, input, toolSchemas = [], toolChoice = 'auto', followUpToolChoice = 'auto',
-    modelConfig, assistant, phiProcessor = null, trace = null, shouldContinue = null
+    modelConfig, assistant, phiProcessor = null, trace = null
   }, options = {}) {
     const executeTools = options.toolExecutor || handleFunctionCalls;
     let totalRetries = 0;
@@ -76,10 +74,6 @@ 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, extra = {}) => {
+  const skip = (reason) => {
     logger.info('[bridge] skipped', { code, reason });
-    return { sent: false, ...extra };
+    return { sent: false };
   };
 
   if (typeof shouldContinue === 'function' && !shouldContinue()) return skip('superseded');
@@ -36,35 +36,20 @@ function maybeSendBridge({ narrationText, hasToolCalls, code, turnId = null, tra
   const text = sanitizeBridgeText(narrationText);
   if (!text) return skip('no_usable_narration');
 
-  const pending = bridgeTimestamps.get(code);
-  if (pending !== undefined) {
-    return skip('recent_bridge_in_thread', pending.delivered ? { dedupNote: pending.dedupNote } : {});
-  }
+  if (bridgeTimestamps.get(code) !== undefined) return skip('recent_bridge_in_thread');
 
-  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 });
-  };
+  bridgeTimestamps.set(code, true);
   try {
     Promise.resolve(sendMessage({ code, body: text, processed: true, origin: 'assistant', raw: { bridge: true }, turnId, traceId }))
-      .then(() => { entry.delivered = true; })
-      .catch(failed);
+      .catch(err => logger.warn('[bridge] send failed', { code, error: err.message }));
   } catch (err) {
-    failed(err);
+    logger.warn('[bridge] send failed', { code, error: err.message });
   }
 
   logger.info('[bridge] sent', { code });
-  return { sent: true, text, dedupNote };
-}
-
-function clearBridgeState(code) {
-  bridgeTimestamps.delete(code);
+  return { sent: true, text, dedupNote: buildDedupNote(text) };
 }
 
 module.exports = {
   maybeSendBridge,
-  clearBridgeState,
 };

package/lib/clinical/services/skillService.js

@@ -11,26 +11,59 @@ const TOOLS_TABLE = 'tools';
 const CACHE_TTL = 5 * 60 * 1000;
 const CACHE_KEY = 'skills';
 const TOOLS_CACHE_KEY = 'toolCatalog';
+const BACKTICK_SPAN_RX = /`([^`\n]+)`/g;
+const LEADING_CALL_RX = /^([A-Za-z][A-Za-z0-9]*)\s*(?:[(.]|$)/;
+const MULTI_WORD_RX = /[a-z][A-Z]/;
 
 const cache = new MapCache({ maxSize: 2, ttl: CACHE_TTL });
 
-async function unavailableToolNames() {
-  let catalog = cache.get(TOOLS_CACHE_KEY);
-  if (!catalog) {
-    const records = await getRecordByFilter(Config_ID, TOOLS_TABLE, 'TRUE()');
-    catalog = (records || []).map((row) => row.tool_id).filter(Boolean);
-    cache.set(TOOLS_CACHE_KEY, catalog);
+async function readToolCatalog() {
+  const cached = cache.get(TOOLS_CACHE_KEY);
+  if (cached) return cached;
+
+  let records;
+  try {
+    records = await getRecordByFilter(Config_ID, TOOLS_TABLE, 'TRUE()');
+  } catch (error) {
+    logger.warn('[skillService] tool catalog unreadable; drift check falls back to the skill body', { error: error.message });
+    return null;
+  }
+  if (!records) {
+    logger.warn('[skillService] tool catalog unreadable; drift check falls back to the skill body', { table: TOOLS_TABLE });
+    return null;
   }
+
+  const catalog = records.map((row) => row.tool_id).filter(Boolean);
+  cache.set(TOOLS_CACHE_KEY, catalog);
+  return catalog;
+}
+
+async function unavailableToolNames() {
+  const catalog = await readToolCatalog();
+  if (!catalog) return [];
   const registered = new Set(getRegisteredToolNames());
   return catalog.filter((id) => !registered.has(id));
 }
 
+function mentionedToolNames(text) {
+  const names = new Set();
+  for (const [, span] of text.matchAll(BACKTICK_SPAN_RX)) {
+    const id = span.match(LEADING_CALL_RX)?.[1];
+    if (id && MULTI_WORD_RX.test(id)) names.add(id);
+  }
+  return names;
+}
+
 async function warnOnRegistryDrift(name, body) {
-  if (getRegisteredToolNames().length === 0) return;
+  const registeredNames = getRegisteredToolNames();
+  if (registeredNames.length === 0) return;
+  const registered = new Set(registeredNames);
   const text = String(body || '');
-  const missing = (await unavailableToolNames())
-    .filter((id) => new RegExp(`\\b${id}\\b`).test(text))
-    .sort();
+
+  const fromCatalog = (await unavailableToolNames()).filter((id) => new RegExp(`\\b${id}\\b`).test(text));
+  const fromBody = [...mentionedToolNames(text)].filter((id) => !registered.has(id));
+  const missing = [...new Set([...fromCatalog, ...fromBody])].sort();
+
   if (missing.length > 0) {
     logger.error('[skillService] Skill body calls tools that are not registered — the model cannot follow this body', {
       skill: name, missing,

package/package.json

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