@peopl-health/nexus 6.0.0-dev.466 → 6.0.0-dev.611

package/lib/adapters/messageAdapters/TwilioMessageAdapter.js

@@ -1,6 +1,6 @@
 const { logger } = require('../../utils/logger');
 
-const { enrichMessageWithTwilioMedia } = require('../../helpers/twilioMediaHelper');
+const { enrichMessageWithTwilioMedia, resolveContactFromTwilioMedia } = require('../../helpers/twilioMediaHelper');
 
 const { MessageAdapter } = require('../MessageAdapter');
 
@@ -8,9 +8,14 @@ class TwilioMessageAdapter extends MessageAdapter {
   async normalize(rawMessage) {
     const from = rawMessage.From || '';
     const interactive = this._extractInteractive(rawMessage);
-    const media = await this._resolveMedia(rawMessage);
+    const contactBody = await this._resolveContact(rawMessage);
+    const media = contactBody ? null : await this._resolveMedia(rawMessage);
     const hasMedia = parseInt(rawMessage.NumMedia || '0', 10) > 0;
-    const body = rawMessage.Body || this._extractInteractionText(interactive) || (hasMedia ? `[Media:${media?.mediaType || 'attachment'}]` : '');
+    const body = contactBody
+      ? [contactBody, rawMessage.Body].filter(Boolean).join('\n')
+      : (rawMessage.Body
+        || this._extractInteractionText(interactive)
+        || (hasMedia ? `[Media:${media?.mediaType || 'attachment'}]` : ''));
 
     return {
       messageId: rawMessage.MessageSid || null,
@@ -28,6 +33,15 @@ class TwilioMessageAdapter extends MessageAdapter {
     };
   }
 
+  async _resolveContact(rawMessage) {
+    try {
+      return await resolveContactFromTwilioMedia(rawMessage);
+    } catch (error) {
+      logger.error('[TwilioMessageAdapter] Error resolving Twilio contact message', error);
+      return null;
+    }
+  }
+
   async _resolveMedia(rawMessage) {
     const numMedia = parseInt(rawMessage.NumMedia || '0', 10);
     if (numMedia <= 0) return null;

package/lib/clinical/AssistantProcessor.js

@@ -4,6 +4,7 @@ const { getThread } = require('../helpers/threadHelper');
 const { runAssistantWithRetries } = require('./helpers/assistantHelper');
 
 const { forkShadowTurn } = require('./services/shadowService');
+const { diverge } = require('./services/divergenceService');
 const { getAssistantById } = require('./services/assistantResolver');
 
 class AssistantProcessor {
@@ -30,7 +31,9 @@ class AssistantProcessor {
         message,
         shouldContinue: runOptions.shouldContinue,
         runId: runOptions.runId,
+        additionalInstructions: runOptions.additionalInstructions,
         executeLLM: this.executeLLM.bind(this),
+        onComplete: (shadow) => diverge({ shadow, runId: runOptions.runId }),
       });
     }
 

package/lib/clinical/config/divergenceConfig.js

@@ -0,0 +1,63 @@
+const { Config_ID } = require('../../config/airtableConfig');
+
+const { getRecordByFilter } = require('../../services/airtableService');
+
+const MapCache = require('../../utils/MapCache');
+const { safeParse, safeParseArray, isPlainObject } = require('../../utils/jsonUtils');
+
+const DIVERGENCE_CONFIG_TABLE = 'divergence';
+const CACHE_TTL = 5 * 60 * 1000;
+const CACHE_KEY = 'divergenceConfig';
+const COMPARATOR_TYPES = ['scalar', 'set'];
+const ORACLE_CONNECTION_DEFAULTS = { enabled: false, baseUrl: '', timeoutMs: null };
+const STOCHASTIC_DEFAULTS = { enabled: false, presetId: '' };
+
+const cache = new MapCache({ maxSize: 1, ttl: CACHE_TTL });
+
+async function load() {
+  const cached = cache.get(CACHE_KEY);
+  if (cached) return cached;
+
+  const records = await getRecordByFilter(Config_ID, DIVERGENCE_CONFIG_TABLE, 'TRUE()');
+  if (!records) throw new Error('divergence config could not be read from the Config base');
+  const byKey = Object.fromEntries(records.map((r) => [r.config, r.value]));
+
+  if (!byKey.FIELDS) throw new Error('divergence config missing from Config base: FIELDS');
+  const fields = safeParseArray(byKey.FIELDS);
+  if (!fields) throw new Error('divergence config FIELDS is not a JSON array');
+  if (!fields.length) throw new Error('divergence config FIELDS is empty; nothing would be compared');
+
+  const unknown = fields.filter(({ type }) => !COMPARATOR_TYPES.includes(type));
+  if (unknown.length) throw new Error(`divergence config FIELDS has unknown types: ${unknown.map(({ field, type }) => `${field}:${type}`).join(', ')}`);
+
+  const misplaced = fields.filter(({ type, emergencyKinds }) => emergencyKinds && type !== 'scalar');
+  if (misplaced.length) throw new Error(`divergence config emergencyKinds only applies to scalar fields: ${misplaced.map(({ field }) => field).join(', ')}`);
+
+  const parsedOracle = safeParse(byKey.ORACLE_CONNECTION, null);
+  if (byKey.ORACLE_CONNECTION && !isPlainObject(parsedOracle)) throw new Error('divergence config ORACLE_CONNECTION is not a JSON object');
+  const oracleConnection = { ...ORACLE_CONNECTION_DEFAULTS, ...(parsedOracle || {}) };
+  if (oracleConnection.enabled) {
+    oracleConnection.timeoutMs = Number(oracleConnection.timeoutMs);
+    if (!Number.isFinite(oracleConnection.timeoutMs) || oracleConnection.timeoutMs <= 0) throw new Error('divergence config ORACLE_CONNECTION.timeoutMs is not a positive number');
+  }
+
+  const parsedStochastic = safeParse(byKey.STOCHASTIC, null);
+  if (byKey.STOCHASTIC && !isPlainObject(parsedStochastic)) throw new Error('divergence config STOCHASTIC is not a JSON object');
+  const stochastic = { ...STOCHASTIC_DEFAULTS, ...(parsedStochastic || {}) };
+  if (stochastic.enabled && !stochastic.presetId) throw new Error('divergence config STOCHASTIC.presetId is required when enabled');
+
+  const config = { FIELDS: fields, ORACLE_CONNECTION: oracleConnection, STOCHASTIC: stochastic };
+  cache.set(CACHE_KEY, config);
+  return config;
+}
+
+async function get(key) {
+  const config = await load();
+  return config[key];
+}
+
+module.exports = {
+  getFields: () => get('FIELDS'),
+  getOracleConnection: () => get('ORACLE_CONNECTION'),
+  getStochastic: () => get('STOCHASTIC'),
+};

package/lib/clinical/helpers/divergenceHelper.js

@@ -0,0 +1,100 @@
+const { isDeepStrictEqual } = require('node:util');
+
+const divergenceConfig = require('../config/divergenceConfig');
+const { requireOpenAIProvider } = require('../config/llmConfig');
+
+const VERDICT_SCHEMA = {
+  type: 'object',
+  properties: {
+    verdict: { type: 'string', enum: ['pass', 'review', 'fail'] },
+    rationale: { type: 'string' },
+  },
+  required: ['verdict', 'rationale'],
+  additionalProperties: false,
+};
+
+const ungraded = (rationale) => ({ verdict: 'review', rationale, graded: false });
+
+function readVerdictText(result) {
+  if (result?.output_text) return result.output_text;
+  const output = Array.isArray(result?.output) ? result.output : [];
+  const message = output.find((item) => item.type === 'message');
+  const content = Array.isArray(message?.content) ? message.content : [];
+  const part = content.find((c) => typeof c?.text === 'string');
+  return part?.text || '';
+}
+
+const COMPARATORS = {
+  scalar: (expected, actual) => expected === actual,
+  set: (expected, actual) => isDeepStrictEqual(new Set(expected || []), new Set(actual || [])),
+};
+
+const OUTCOME_RULES = [
+  [({ deterministic }) => deterministic.divergences.some((d) => d.isEmergencyFlip), 'review'],
+  [({ stochastic }) => stochastic.verdict === 'fail', 'fail'],
+  [({ deterministic }) => !deterministic.hasPassed, 'diverged'],
+  [({ stochastic }) => stochastic.verdict === 'review', 'review'],
+];
+
+function deterministicDivergence(expected = {}, actual = {}, fields) {
+  const divergences = fields
+    .filter(({ field, type }) => {
+      const compare = COMPARATORS[type];
+      if (!compare) throw new Error(`unknown divergence field type '${type}'`);
+      return !compare(expected?.[field], actual?.[field]);
+    })
+    .map(({ field, emergencyKinds = [] }) => ({
+      field,
+      expected: expected?.[field],
+      actual: actual?.[field],
+      isEmergencyFlip: emergencyKinds.includes(expected?.[field]) || emergencyKinds.includes(actual?.[field]),
+    }));
+  return { divergences, hasPassed: divergences.length === 0 };
+}
+
+async function stochasticDivergence(expectedMessage, actualMessage) {
+  const { enabled, presetId } = await divergenceConfig.getStochastic();
+  if (!enabled) return ungraded('stochastic message grading not enabled');
+
+  const expected = (expectedMessage || '').trim();
+  const actual = (actualMessage || '').trim();
+  if (!expected || !actual) return ungraded('message text missing on one side');
+
+  let provider;
+  try {
+    provider = requireOpenAIProvider();
+  } catch (error) {
+    return ungraded(`provider unavailable: ${error.message}`);
+  }
+
+  try {
+    const result = await provider.runStructured({
+      presetId,
+      input: [{ role: 'user', content: `ORIGINAL:\n${expected}\n\nREWRITTEN:\n${actual}` }],
+      text: { format: { type: 'json_schema', name: 'stochastic_verdict', schema: VERDICT_SCHEMA, strict: true } },
+    });
+    const parsed = JSON.parse(readVerdictText(result));
+    const verdict = ['pass', 'review', 'fail'].includes(parsed.verdict) ? parsed.verdict : 'review';
+    return { verdict, rationale: parsed.rationale || '', graded: true };
+  } catch (error) {
+    return ungraded(`grading error: ${error.message}`);
+  }
+}
+
+async function classify({ expected, actual, expectedMessage, actualMessage }) {
+  const fields = await divergenceConfig.getFields();
+  const deterministic = deterministicDivergence(expected, actual, fields);
+  const stochastic = await stochasticDivergence(expectedMessage, actualMessage);
+  const result = OUTCOME_RULES.find(([applies]) => applies({ deterministic, stochastic }))?.[1] || 'pass';
+  return {
+    deterministic,
+    stochastic,
+    result,
+    isEmergencyReview: deterministic.divergences.some((d) => d.isEmergencyFlip),
+  };
+}
+
+module.exports = {
+  deterministicDivergence,
+  classify,
+};

package/lib/clinical/helpers/seedHelper.js

@@ -0,0 +1,62 @@
+const { cleanForJson, isPlainObject } = require('../../utils/jsonUtils');
+
+const SEED_FORMATS = {
+  '.json': {
+    isValid: (c) => isPlainObject(c) && Object.values(c).every(isPlainObject),
+    hint: 'an object keyed by id whose values are plain objects',
+  },
+  '.jsonl': {
+    isValid: (c) => Array.isArray(c) && c.every(isPlainObject),
+    hint: 'a list of plain objects',
+  },
+};
+
+// clinical-agent file-store shapes:
+//   keyedFile → KeyedJSONFile (`{pk: doc}` written as `.json`)
+//   jsonlFile → JSONLFileStore (list-of-dicts written as `.jsonl`)
+function keyedFile(records, primaryKey) {
+  const out = {};
+  for (const record of records) {
+    const doc = cleanForJson(record);
+    const key = doc[primaryKey];
+    if (key === undefined || key === null || key === '') {
+      throw new Error(`keyed store record is missing primary key '${primaryKey}'`);
+    }
+    const skey = String(key);
+    if (Object.prototype.hasOwnProperty.call(out, skey)) {
+      throw new Error(`keyed store has duplicate primary key '${primaryKey}' value '${skey}'`);
+    }
+    out[skey] = doc;
+  }
+  return out;
+}
+
+function jsonlFile(records) {
+  return records.map(cleanForJson);
+}
+
+function validateSeed(seed) {
+  const basenames = new Set();
+  for (const [name, content] of Object.entries(seed)) {
+    const basename = name.split('/').pop();
+    if (!basename || basename === '.' || basename === '..') {
+      throw new Error(`invalid seed file name: '${name}'`);
+    }
+    if (basenames.has(basename)) {
+      throw new Error(`duplicate seed file basename: '${basename}'`);
+    }
+    basenames.add(basename);
+
+    const ext = Object.keys(SEED_FORMATS).find((extension) => basename.endsWith(extension));
+    const format = ext ? SEED_FORMATS[ext] : null;
+    if (!format) throw new Error(`seed file must end in .json or .jsonl: '${name}'`);
+    if (!format.isValid(content)) throw new Error(`'${name}' must be ${format.hint}`);
+  }
+  return seed;
+}
+
+module.exports = {
+  keyedFile,
+  jsonlFile,
+  validateSeed,
+};

package/lib/clinical/index.js

@@ -23,7 +23,14 @@ const llmConfigModule = require('./config/llmConfig');
 
 const { ToolRuntimeContext } = require('./context/ToolRuntimeContext');
 
+const { getCtcaeCatalog } = require('./stores/CtcaeCatalog');
+
+async function initialize() {
+  await getCtcaeCatalog().initialize();
+}
+
 module.exports = {
+  initialize,
   createLLMProvider,
   PROVIDER_VARIANTS,
   OpenAIResponsesProvider,

package/lib/clinical/memory/DefaultMemoryManager.js

@@ -11,6 +11,7 @@ const runtimeConfig = require('../../config/runtimeConfig');
 const { MemoryManager } = require('./MemoryManager');
 
 const DEFAULT_MAX_HISTORICAL_MESSAGES = 50;
+const ALLOWED_SYSTEM_ROLES = new Set(['system', 'developer']);
 
 class DefaultMemoryManager extends MemoryManager {
   constructor(options = {}) {
@@ -37,7 +38,7 @@ class DefaultMemoryManager extends MemoryManager {
         const toolItems = getMessageTools(msg);
         const contentItems = formatMessage(msg)
           .map(content => ({
-            role: msg.origin === 'patient' ? 'user' : 'assistant',
+            role: this._resolveContextRole(msg),
             content: content,
             type: 'message'
           }))
@@ -52,6 +53,17 @@ class DefaultMemoryManager extends MemoryManager {
     }
   }
 
+  _resolveContextRole(msg) {
+    if (msg.origin === 'patient') return 'user';
+    if (msg.origin === 'system' && msg.raw?.role) {
+      const role = String(msg.raw.role).trim().toLowerCase();
+      if (ALLOWED_SYSTEM_ROLES.has(role)) return role;
+      logger.warn('[DefaultMemoryManager] Unexpected system message role, using fallback', { role: msg.raw.role });
+      return 'system';
+    }
+    return 'assistant';
+  }
+
   async processResponse(response, thread) {
     this._logActivity('Processing response', { threadCode: thread.code, responseId: response.id });
     try {

package/lib/clinical/models/divergenceModel.js

@@ -0,0 +1,41 @@
+const mongoose = require('mongoose');
+
+const { clinicalConnection } = require('../config/connection');
+
+const divergenceSchema = new mongoose.Schema({
+  turnId: { type: String, required: true },
+  code: { type: String, required: true },
+  request: { type: Object, default: null },
+  response: { type: Object, default: null },
+  expectedMessage: { type: String, default: null },
+  actualMessage: { type: String, default: null },
+  result: { type: String, default: null },
+  isEmergencyReview: { type: Boolean, default: false },
+  deterministic: { type: Object, default: null },
+  stochastic: { type: Object, default: null },
+  expected: { type: Object, default: null },
+  actual: { type: Object, default: null },
+}, { timestamps: true });
+
+divergenceSchema.index({ code: 1, createdAt: -1 });
+divergenceSchema.index({ result: 1, createdAt: -1 });
+divergenceSchema.index({ turnId: 1 }, { unique: true });
+
+divergenceSchema.statics.record = function record({ shadow, request, report }) {
+  return this.create({
+    turnId: shadow?.turnId || null,
+    code: shadow?.context?.patientCode || null,
+    request,
+    ...report,
+  });
+};
+
+function getDivergenceModel() {
+  const conn = clinicalConnection();
+  return conn.models.Divergence || conn.model('Divergence', divergenceSchema, 'divergence');
+}
+
+module.exports = {
+  getDivergenceModel,
+  divergenceSchema,
+};

package/lib/clinical/models/turnTraceModel.js

@@ -44,6 +44,17 @@ turnTraceSchema.methods.addStep = function addStep(step) { this.steps.push({ ...
 turnTraceSchema.methods.setStatus = function setStatus(status, abort = null) { this.status = status; this.abort = abort; };
 turnTraceSchema.methods.setTimings = function setTimings(timings) { this.timings = { ...this.timings, ...timings }; };
 
+turnTraceSchema.methods.toDecision = function toDecision() {
+  const decision = this.safetyDecision || {};
+  const signals = this.signals || {};
+  return {
+    escalation_kind: decision.escalationKind || null,
+    outbound_purpose: signals.outboundPurpose || null,
+    branch_taken: signals.branchTaken || null,
+    red_flags_matched: decision.redFlagsMatched || [],
+  };
+};
+
 turnTraceSchema.methods.setPrompt = function setPrompt({ resolved, resolvedPresetId, resolvedPresetVersion }) {
   this.prompt = {
     resolved: resolved || null,

package/lib/clinical/providers/BaseLLMProvider.js

@@ -53,6 +53,22 @@ class BaseLLMProvider {
     const devContent = this._buildInstructions({ resolvedPrompt, toolSchemas, prePromptResult, additionalInstructions });
     const input = this._buildInput({ context, prePromptResult, additionalInstructions, promptVariables, modelConfig });
 
+    // Capture before _invokeModel: the divergence oracle replays this shadow request shape.
+    if (shadow && assistant?.toolRuntimeContext) {
+      assistant.toolRuntimeContext.divergenceInputs = {
+        clinicalData: {
+          clinicalContext: promptVariables?.clinical_context || '',
+          lastSymptoms: promptVariables?.last_symptoms || '',
+          patientMemories: promptVariables?.patient_memories || '',
+          conversationSummaries: promptVariables?.conversation_summaries || '',
+        },
+        input,
+        model: modelConfig?.model || null,
+        toolIds: Array.isArray(toolIds) ? toolIds : [],
+        additionalInstructions: additionalInstructions || null,
+      };
+    }
+
     trace?.setPrompt({ resolved: devContent, resolvedPresetId, resolvedPresetVersion });
 
     const { response, toolsExecuted, retries, usage } = await this._invokeModel({

package/lib/clinical/services/clinicalAgentService.js

@@ -0,0 +1,18 @@
+const axios = require('axios');
+
+async function runClinicalAgent(request, { baseUrl, apiKey, timeoutMs } = {}) {
+  if (!baseUrl) throw new Error('runClinicalAgent requires a baseUrl');
+  const res = await axios({
+    url: `${baseUrl}/api/oracle/turn`,
+    method: 'POST',
+    data: request,
+    timeout: timeoutMs,
+    headers: { 'content-type': 'application/json', 'x-api-key': apiKey },
+    validateStatus: () => true,
+  });
+  return { status: res.status, body: res.data ?? null };
+}
+
+module.exports = {
+  runClinicalAgent
+};

package/lib/clinical/services/divergenceService.js

@@ -0,0 +1,74 @@
+const divergenceConfig = require('../config/divergenceConfig');
+const { getDivergenceModel } = require('../models/divergenceModel');
+const { classify } = require('../helpers/divergenceHelper');
+const runtimeConfig = require('../../config/runtimeConfig');
+const { logger } = require('../../utils/logger');
+
+const { runClinicalAgent } = require('./clinicalAgentService');
+
+async function runDivergence({ request, connection, trace, actualMessage }) {
+  let post;
+  try {
+    post = await runClinicalAgent(request, connection);
+    if (post.status !== 200) {
+      return { ok: false, status: post.status, response: post.body };
+    }
+  } catch (error) {
+    return { ok: false, status: 503, response: { error: error.message } };
+  }
+  const expected = post.body?.run?.sessions?.[0]?.turns?.[0] || {};
+  const expectedMessage = post.body?.response || '';
+
+  const actual = trace.toDecision();
+  const outcome = await classify({
+    expected, actual, expectedMessage, actualMessage,
+  });
+
+  return {
+    ok: true, ...outcome, expected, actual, expectedMessage, actualMessage, response: post.body,
+  };
+}
+
+async function diverge({ shadow, runId }) {
+  const inputs = shadow?.context?.divergenceInputs;
+  if (!inputs) return null;
+  if (!shadow.result?.completed) return null;
+
+  const { enabled, baseUrl, timeoutMs } = await divergenceConfig.getOracleConnection();
+  if (!enabled || !baseUrl) return null;
+
+  const request = {
+    runId,
+    clinicalData: inputs.clinicalData,
+    input: inputs.input || [],
+    model: inputs.model,
+    enabledTools: inputs.toolIds || [],
+    additionalInstructions: inputs.additionalInstructions || null,
+  };
+
+  const connection = {
+    baseUrl,
+    apiKey: runtimeConfig.get('CLINICAL_AGENT_BENCH_KEY', ''),
+    timeoutMs,
+  };
+
+  const report = await runDivergence({
+    request, connection, trace: shadow.context.trace, actualMessage: shadow.result?.output || '',
+  });
+
+  if (report.ok) {
+    try {
+      await getDivergenceModel().record({ shadow, request, report });
+    } catch (error) {
+      logger.warn('[divergence] persist failed', { runId, error: error.message });
+    }
+  } else {
+    logger.warn('[divergence] oracle failed', { runId, status: report.status });
+  }
+
+  return report;
+}
+
+module.exports = {
+  diverge,
+};

package/lib/clinical/services/promptComposerService.js

@@ -178,7 +178,8 @@ async function resolveTools({ promptId, assistant, presetToolIds = null, status
   const hasAssistantTools = assistant?.tools?.size > 0;
 
   if (!hasRegistryTools && !hasAssistantTools) return { toolIds: [], filtered: false, descriptions: {} };
-  if (!presetToolIds) return { toolIds: [], filtered: false, descriptions: {} };
+  if (presetToolIds == null) return { toolIds: [], filtered: false, descriptions: {} };
+  if (presetToolIds.length === 0) return { toolIds: [], filtered: true, descriptions: {} };
 
   const mappedTools = await fetchToolsByRecordIds(presetToolIds);
   if (!mappedTools.length) return { toolIds: [], filtered: false, descriptions: {} };

package/lib/clinical/services/seedService.js

@@ -0,0 +1,21 @@
+const { createProjectorRegistry } = require('../../helpers/projectorHelper');
+const { validateSeed } = require('../helpers/seedHelper');
+
+const registry = createProjectorRegistry({
+  label: 'seed projector',
+  assemble: (items) => {
+    const seed = {};
+    const seen = new Set();
+    for (const { name, content } of items) {
+      if (seen.has(name)) throw new Error(`duplicate seed file name: '${name}'`);
+      seen.add(name);
+      if (content !== undefined) seed[name] = content;
+    }
+    return validateSeed(seed);
+  },
+});
+
+module.exports = {
+  registerSeedProjector: registry.register,
+  projectSeed: registry.project,
+};

package/lib/clinical/services/shadowMessageService.js

@@ -0,0 +1,58 @@
+const { getTurnTraceModel } = require('../models/turnTraceModel');
+const runtimeConfig = require('../../config/runtimeConfig');
+const { logger } = require('../../utils/logger');
+
+const PAIRING_WINDOW_MS = 5 * 60 * 1000;
+
+function isShowShadowRepliesEnabled() {
+  return runtimeConfig.get('SHOW_SHADOW_REPLIES', 'false') === 'true';
+}
+
+async function attachShadowReplies(messages, code) {
+  if (!isShowShadowRepliesEnabled()) return messages;
+
+  const assistantMessages = messages.filter((msg) => msg.origin === 'assistant' && msg.response_id);
+  if (!assistantMessages.length) return messages;
+
+  let traces;
+  try {
+    let min = Infinity;
+    let max = -Infinity;
+    messages.forEach((msg) => {
+      const at = new Date(msg.createdAt).getTime();
+      if (at < min) min = at;
+      if (at > max) max = at;
+    });
+    const gte = new Date(min - PAIRING_WINDOW_MS);
+    const lte = new Date(max + PAIRING_WINDOW_MS);
+    traces = await getTurnTraceModel()
+      .find({ patientCode: code, outbound: { $ne: null }, createdAt: { $gte: gte, $lte: lte } })
+      .select({ outbound: 1, createdAt: 1 })
+      .sort({ createdAt: 1 })
+      .lean();
+  } catch (error) {
+    logger.warn('[shadowReply] lookup skipped', { code, error: error.message });
+    return messages;
+  }
+  if (!traces.length) return messages;
+
+  const used = new Set();
+  assistantMessages.forEach((msg) => {
+    const at = new Date(msg.createdAt).getTime();
+    let bestIndex = -1;
+    let bestDelta = PAIRING_WINDOW_MS;
+    traces.forEach((trace, index) => {
+      if (used.has(index)) return;
+      const delta = Math.abs(new Date(trace.createdAt).getTime() - at);
+      if (delta <= bestDelta) { bestDelta = delta; bestIndex = index; }
+    });
+    if (bestIndex >= 0) {
+      used.add(bestIndex);
+      msg.shadowReply = traces[bestIndex].outbound;
+    }
+  });
+
+  return messages;
+}
+
+module.exports = { attachShadowReplies, isShowShadowRepliesEnabled };

package/lib/clinical/services/shadowService.js

@@ -11,6 +11,7 @@ async function runShadowTurn({
   sessionId = null,
   shouldContinue = () => true,
   runId,
+  additionalInstructions = null,
   resolveAssistant,
   executeLLM,
 }) {
@@ -23,7 +24,9 @@ async function runShadowTurn({
 
   const context = new ToolRuntimeContext({ patientCode: code, turnId: runId, sessionId, thread: shadowThread });
 
-  const runOptions = { toolRuntimeContext: context, shadow: true, shouldContinue };
+  const runOptions = {
+    toolRuntimeContext: context, shadow: true, shouldContinue, additionalInstructions,
+  };
 
   const result = await runInShadowScope(() =>
     executeLLM(shadowThread, shadowAssistant, runOptions, message),
@@ -32,7 +35,9 @@ async function runShadowTurn({
   return { turnId: runId, context, result };
 }
 
-function forkShadowTurn({ thread, message, shouldContinue, runId, executeLLM }) {
+function forkShadowTurn({
+  thread, message, shouldContinue, runId, additionalInstructions = null, executeLLM, onComplete = null,
+}) {
   Promise.resolve()
     .then(() => {
       if (!isShadowEnabled()) return null;
@@ -41,10 +46,14 @@ function forkShadowTurn({ thread, message, shouldContinue, runId, executeLLM })
         message,
         shouldContinue,
         runId,
+        additionalInstructions,
         resolveAssistant: (shadowThread) => getAssistantById(shadowThread.getAssistantId(), shadowThread),
         executeLLM,
       });
     })
+    .then((shadow) => (shadow && onComplete
+      ? Promise.resolve(onComplete(shadow)).catch((error) => logger.warn('[divergence] failed', { code: thread?.code, error: error?.message }))
+      : null))
     .catch((error) => logger.error('[shadow] turn failed', { code: thread?.code, error: error?.message }));
 }