@peopl-health/nexus 5.68.7 → 5.68.9

package/lib/clinical/config/cohortConfig.js

@@ -65,4 +65,4 @@ function clearCohortCache() {
   inFlightRead = null;
 }
 
-module.exports = { isInCohort, clearCohortCache };
+module.exports = { isInCohort, isCohortEnabled, clearCohortCache };

package/lib/clinical/context/ToolRuntimeContext.js

@@ -56,6 +56,7 @@ class ToolRuntimeContext {
     this.skillActivationIteration = new Map();
     this.currentIteration = null;
     this.toolHistory = [];
+    this.toolRejections = [];
     this.safetyArtifact = null;
     this.palliativeAssessment = null;
     this.careplan = null;
@@ -93,9 +94,11 @@ class ToolRuntimeContext {
     this.trace.addStep({ iteration, ...toolData });
     if (toolData.success) this.toolHistory.push(toolData);
     if (!toolData.success || isToolFailure(toolData.tool_output)) {
+      const code = refusalCode(toolData.tool_output);
+      this.toolRejections.push({ tool: toolData.tool_name, code, iteration: iteration ?? null });
       logger.warn('[toolRuntime] tool call rejected', {
         tool: toolData.tool_name,
-        reason: refusalCode(toolData.tool_output),
+        reason: code,
         iteration: iteration ?? null,
         turnId: this.turnId || null,
       });
@@ -108,7 +111,7 @@ class ToolRuntimeContext {
   }
 
   async store({ outbound = null, completed = false, predictionTimeMs = null, error = null } = {}) {
-    this.trace.setSignals({ activatedSkills: [...this.activatedSkills].sort() });
+    this.trace.setSignals({ activatedSkills: [...this.activatedSkills].sort(), toolRejections: [...this.toolRejections] });
     this.trace.setOutbound(outbound || this.trace.outbound || null);
     const hasError = error !== null && error !== undefined;
     const isSuperseded = hasError ? false : !this.isLive();

package/lib/clinical/flags/flagSnapshot.js

@@ -0,0 +1,59 @@
+const { isCohortEnabled } = require('../config/cohortConfig');
+const { isBridgeEnabled } = require('./bridgeConfig');
+const { contextReadLive, contextMirrorLive, contextVerifierLive } = require('./clinicalContextFlags');
+const { clinicalPatternFloorLive } = require('./clinicalPatternFloorFlags');
+const { isComposerEnabled, isAgentSelfRenderEnabled } = require('./composerFlags');
+const { isContingencyCancelOnReplyLive, isArmOnOpenCeilingLive, isContingencyRuleBlockLive } = require('./contingencyFlags');
+const { escalationAssessmentLive, escalationUpdateModeLive } = require('./escalationFlags');
+const { inboundRecoveryLive, coldInboundMode } = require('./inboundRecoveryFlags');
+const { isLlmAuditEnabled } = require('./llmAuditConfig');
+const { isLlmMonitorEnabled } = require('./llmMonitorConfig');
+const { patternConsultLive } = require('./patternConsultFlags');
+const { recommendationRetryLive } = require('./recommendationRecoveryFlags');
+const { isShadowEnabled } = require('./shadowConfig');
+const { supportLightFromChatLive } = require('./supportLightFlags');
+const { triageGateFloorLive } = require('./triageGateFloorFlags');
+const { triageRecommendationLive, rankComparatorLive } = require('./triageRecommendationFlags');
+const { isConversationalDeclarationLive, isConversationalDraftReuseLive, isDeclarationModelCheckLive } = require('./turnEfficiencyFlags');
+
+const FLAG_READERS = {
+  cohort: isCohortEnabled,
+  bridge: isBridgeEnabled,
+  contextRead: contextReadLive,
+  contextMirror: contextMirrorLive,
+  contextVerifier: contextVerifierLive,
+  clinicalPatternFloor: clinicalPatternFloorLive,
+  composer: isComposerEnabled,
+  agentSelfRender: isAgentSelfRenderEnabled,
+  contingencyCancelOnReply: isContingencyCancelOnReplyLive,
+  armOnOpenCeiling: isArmOnOpenCeilingLive,
+  contingencyRuleBlock: isContingencyRuleBlockLive,
+  escalationAssessment: escalationAssessmentLive,
+  escalationUpdateMode: escalationUpdateModeLive,
+  inboundRecovery: inboundRecoveryLive,
+  coldInboundMode,
+  llmAudit: isLlmAuditEnabled,
+  llmMonitor: isLlmMonitorEnabled,
+  patternConsult: patternConsultLive,
+  recommendationRetry: recommendationRetryLive,
+  shadow: isShadowEnabled,
+  supportLightFromChat: supportLightFromChatLive,
+  triageGateFloor: triageGateFloorLive,
+  triageRecommendation: triageRecommendationLive,
+  rankComparator: rankComparatorLive,
+  conversationalDeclaration: isConversationalDeclarationLive,
+  conversationalDraftReuse: isConversationalDraftReuseLive,
+  declarationModelCheck: isDeclarationModelCheckLive,
+};
+
+function snapshotClinicalFlags() {
+  return Object.fromEntries(Object.entries(FLAG_READERS).map(([name, read]) => {
+    try {
+      return [name, read()];
+    } catch (error) {
+      return [name, null];
+    }
+  }));
+}
+
+module.exports = { snapshotClinicalFlags };

package/lib/clinical/providers/AnthropicProvider.js

@@ -240,7 +240,7 @@ class AnthropicProvider extends BaseLLMProvider {
           if (lastUserTurn?.role === 'user') {
             deliveryNudges++;
             previousRoundTools = [];
-            trace?.setSignals?.({ deliveryNudges });
+            trace?.setSignals?.({ deliveryNudges, nudgeKind: canDecide ? 'outreach' : 'delivery' });
             logger.warn('[AnthropicProvider] Turn will not close — nudging', { tool: canDecide ? OUTREACH_DECISION_TOOL : 'DeliverPatientMessage', deliveryNudges, hasEnded, isBudgetSpent });
             const turnContent = Array.isArray(lastUserTurn.content)
               ? lastUserTurn.content

package/lib/clinical/providers/BaseLLMProvider.js

@@ -10,6 +10,7 @@ const { resolveSkillCatalog } = require('../services/skillService');
 const { RISK_HEADLINE_MARKER } = require('../services/riskHeadlineService');
 const { resolveClinicalContext } = require('../services/clinicalContextReadService');
 const { isContingencyRuleBlockLive } = require('../flags/contingencyFlags');
+const { snapshotClinicalFlags } = require('../flags/flagSnapshot');
 const { TURN_KIND } = require('../context/turnContext');
 const { extractPatientMessage } = require('../../helpers/patientMessageHelper');
 const runtimeConfig = require('../../config/runtimeConfig');
@@ -102,7 +103,7 @@ class BaseLLMProvider {
       presetId: resolvedPresetId, presetVersion: resolvedPresetVersion, modelConfig,
     } = await composePrompt({ presetId, presetVersion, promptId: assistantId, variables: promptVariables });
 
-    const { toolIds, filtered, descriptions: toolDescriptions } = await resolveTools({
+    const { toolIds, filtered, descriptions: toolDescriptions, unregisteredToolIds = [] } = await resolveTools({
       promptId: resolvedPromptId || assistantId, assistant, presetToolIds,
     });
     const requestedAdditionalToolIds = Array.isArray(prePromptResult?.additionalToolIds)
@@ -200,7 +201,12 @@ class BaseLLMProvider {
     }
 
     trace?.setPrompt({ resolvedPresetId, resolvedPresetVersion });
-    trace?.setSignals?.({ offeredToolIds: effectiveToolIds, enabledSkills });
+    trace?.setSignals?.({
+      offeredToolIds: effectiveToolIds,
+      enabledSkills,
+      flags: snapshotClinicalFlags(),
+      ...(unregisteredToolIds.length > 0 && { unregisteredToolIds }),
+    });
 
     const { response, toolsExecuted, retries, usage } = await this._invokeModel({
       instructions: instructions || devContent || '',

package/lib/clinical/services/promptComposerService.js

@@ -191,6 +191,7 @@ async function fetchToolsByRecordIds(recordIds) {
   return tools;
 }
 
+const BLANK_TOOL_ID = '(blank tool_id)';
 const warnedUnlinked = new Set();
 
 function warnUnlinkedRegisteredTools(linkedToolIds, promptId) {
@@ -228,6 +229,7 @@ async function resolveTools({ promptId, assistant, presetToolIds = null, status
   const activeTools = mappedTools.filter(t => !t.status || t.status === 'prod' || (!isProd && t.status === 'dev'));
 
   const validToolIds = [];
+  const unregisteredToolIds = [];
   const descriptions = {};
 
   for (const tool of activeTools) {
@@ -237,6 +239,7 @@ async function resolveTools({ promptId, assistant, presetToolIds = null, status
       // An Airtable column retyped away from long text would otherwise reach the model as [object Object].
       if (typeof tool.description === 'string' && tool.description) descriptions[id] = tool.description;
     } else {
+      unregisteredToolIds.push(id || BLANK_TOOL_ID);
       logger.error('[promptComposer] Tool mapped in Airtable but not registered in code', { toolId: id, promptId });
     }
   }
@@ -252,7 +255,7 @@ async function resolveTools({ promptId, assistant, presetToolIds = null, status
 
   logger.debug('[promptComposer] Tools resolved', { promptId, mapped: activeTools.length, valid: validToolIds.length, filtered: true });
 
-  return { toolIds: validToolIds, filtered: true, descriptions };
+  return { toolIds: validToolIds, filtered: true, descriptions, unregisteredToolIds };
 }
 
 function clearCache() {

package/lib/models/escalationReviewModel.js

@@ -98,6 +98,7 @@ const draftSchema = new mongoose.Schema({
   missingCharacterization: { type: [String], default: undefined },
   suggestCall: { type: suggestCallSchema, default: undefined },
   sectionsUnavailable: { type: [String], default: undefined },
+  snapshotAt: { type: Date, default: undefined },
 }, { timestamps: { createdAt: true, updatedAt: false } });
 
 const doctorHandoffSchema = new mongoose.Schema({

package/lib/services/escalationReviewService.js

@@ -44,7 +44,7 @@ const AUDIT_SOURCE = 'escalation_review';
 const RECENT_REVIEW_LIMIT = 20;
 const TIMELINE_LIMIT = 500;
 const MAX_REVIEW_UPDATES = 50;
-const DRAFT_DEBOUNCE_MS = 60 * 1000;
+const DRAFT_DEBOUNCE_MS = 20 * 1000;
 const DRAFT_OPERATOR = 'bot:escalationDraft';
 const DIRECT_CHAT_ATTEMPTS = 3;
 const RECHECK_DELAY_MS = 60 * 1000;
@@ -1098,6 +1098,7 @@ async function settleFollowUp(snapshot, { background = true } = {}) {
 }
 
 async function generateBotDraft({ id, lease = null } = {}) {
+  const startedAt = new Date();
   const review = await loadReview(reviewIdOf(id));
   if (review.closedAt || !DOCUMENTING_STATUSES.includes(review.status)) return { review: null, retry: false };
   const latest = (review.drafts ?? []).at(-1);
@@ -1127,6 +1128,7 @@ async function generateBotDraft({ id, lease = null } = {}) {
   }
 
   const entry = {
+    snapshotAt: startedAt,
     doctorText: withIdentity({ identity, review, doctorText: draft.doctorText }),
     patientMessage: draft.patientMessage,
     writtenBy: DRAFT_OPERATOR,
@@ -1137,13 +1139,16 @@ async function generateBotDraft({ id, lease = null } = {}) {
     ...(draft.suggestCall && { suggestCall: draft.suggestCall }),
     ...(draft.sectionsUnavailable?.length && { sectionsUnavailable: draft.sectionsUnavailable }),
   };
-  const saved = await getEscalationReview().findOneAndUpdate(
-    { _id: review._id, status: { $in: DOCUMENTING_STATUSES }, draftDueAt: lease, drafts: { $size: (review.drafts ?? []).length } },
-    { $push: { drafts: entry }, $set: { status: 'draft_ready', draftDueAt: null, draftFailedAt: null }, $unset: { identityBlock: '' } },
+  const EscalationReview = getEscalationReview();
+  const saved = await EscalationReview.findOneAndUpdate(
+    { _id: review._id, status: { $in: DOCUMENTING_STATUSES }, draftDueAt: { $lte: lease }, drafts: { $size: (review.drafts ?? []).length } },
+    { $push: { drafts: entry }, $set: { status: 'draft_ready', draftFailedAt: null }, $unset: { identityBlock: '' } },
     { new: true },
   ).lean();
-  if (saved) await audit(saved, DRAFT_OPERATOR, null, { action: 'draft_saved', draftNumber: saved.drafts.length });
-  return { review: saved, retry: false };
+  if (!saved) return { review: null, retry: false };
+  const released = await EscalationReview.updateOne({ _id: review._id, draftDueAt: lease }, { $set: { draftDueAt: null } }, BOOKKEEPING);
+  await audit(saved, DRAFT_OPERATOR, null, { action: 'draft_saved', draftNumber: saved.drafts.length });
+  return { review: released.matchedCount ? { ...saved, draftDueAt: null } : saved, retry: false };
 }
 
 async function noteFactsContext(review) {
@@ -1361,7 +1366,7 @@ async function handOffToDoctor({ id, mode, physicianEmail = null, sentBy, reques
     if (!approver) throw httpError(403, 'The physician is not an escalation review approver');
   }
 
-  const draftedAt = draft.createdAt ? new Date(draft.createdAt).getTime() : null;
+  const draftedAt = draftTimeOf(draft) ? new Date(draftTimeOf(draft)).getTime() : null;
   if (draftedAt && (review.alarms ?? []).some((alarm) => new Date(alarm.raisedAt).getTime() > draftedAt)) {
     throw httpError(409, 'A new alarm arrived after this draft was written; review it and save a new draft before sending it to the doctor');
   }
@@ -1457,7 +1462,7 @@ async function recordDoctorDecision({
   // Truthiness, not != null: an empty textarea is a decline with nothing to say.
   if (decision === 'needs_intervention' && finalText) approvedText = requiredText(finalText, 'finalText');
 
-  if (APPROVALS.includes(decision) && arrivedAfter(review, draft.createdAt)) {
+  if (APPROVALS.includes(decision) && arrivedAfter(review, draftTimeOf(draft))) {
     if (review.status === 'awaiting_doctor') {
       const redraft = draft.writtenBy === DRAFT_OPERATOR ? { draftDueAt: new Date(), draftAttempts: 0 } : {};
       const returned = await updateReview(reviewId, ['awaiting_doctor'], { $set: { status: 'documenting', ...redraft } }, {
@@ -1572,6 +1577,8 @@ const latestUpdateGuard = (review) => {
   return { updates: { $size: updates.length }, [`updates.${updates.length - 1}.turnId`]: updates.at(-1).turnId };
 };
 
+const draftTimeOf = (draft) => draft.snapshotAt ?? draft.createdAt;
+
 const arrivedAfter = (review, since) => Boolean(since) && [
   ...(review.alarms ?? []).map((alarm) => alarm.raisedAt),
   ...(review.updates ?? []).map((update) => update.at),

package/lib/services/reviewDraftSweepService.js

@@ -6,7 +6,7 @@ const { getEscalationReview } = require('../models/escalationReviewModel');
 const { BOOKKEEPING, DOCUMENTING_STATUSES, generateBotDraft } = require('./escalationReviewService');
 
 const SWEEP_LIMIT = 1;
-const DEFAULT_SWEEP_INTERVAL_MS = 30 * 1000;
+const DEFAULT_SWEEP_INTERVAL_MS = 10 * 1000;
 const RETRY_DELAY_MS = 5 * 60 * 1000;
 const MAX_DRAFT_ATTEMPTS = 3;
 const LEASE_MS = 10 * 60 * 1000;

package/package.json

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