lynkr 9.0.2 → 9.1.3

package/src/routing/index.js

@@ -22,15 +22,59 @@ const {
 const { getAgenticDetector, AGENT_TYPES } = require('./agentic-detector');
 const { getModelTierSelector, TIER_DEFINITIONS } = require('./model-tiers');
 const { getCostOptimizer } = require('./cost-optimizer');
+const { analyzeRisk } = require('./risk-classifier');
+
+// Phase 3-6 routing modules
+const { getKnnRouter } = require('./knn-router');
+const { getBandit } = require('./bandit');
+const { getShadowPolicy, compareAndLog: shadowCompareAndLog } = require('./shadow-mode');
+const { chooseFastest } = require('./deadline');
+const { applyTenantOverrides } = require('./tenant-policy');
 
 // Telemetry modules
 const telemetry = require('./telemetry');
 const { scoreResponseQuality } = require('./quality-scorer');
 const { getLatencyTracker } = require('./latency-tracker');
 
+// Phase 1 modules
+const contextValidator = require('./context-validator');
+const { countPayloadTokens } = require('./tokenizer');
+
 // Local providers
 const LOCAL_PROVIDERS = ['ollama', 'llamacpp', 'lmstudio'];
 
+/**
+ * Returns true when any message content block is an image.
+ * Handles both string content and structured content arrays.
+ */
+function _payloadHasImages(payload) {
+  const messages = payload?.messages;
+  if (!Array.isArray(messages)) return false;
+  return messages.some(msg => {
+    const content = msg?.content;
+    if (!Array.isArray(content)) return false;
+    return content.some(block => block?.type === 'image' || block?.type === 'image_url');
+  });
+}
+
+/**
+ * List of providers that currently have credentials configured.
+ * Used by the Phase 1.2 cost-optimizer override to scope candidates.
+ */
+function _enabledProviders() {
+  const out = [];
+  if (config.databricks?.url && config.databricks?.apiKey) out.push('databricks');
+  if (config.azureAnthropic?.endpoint && config.azureAnthropic?.apiKey) out.push('azure-anthropic');
+  if (config.bedrock?.apiKey) out.push('bedrock');
+  if (config.openrouter?.apiKey) out.push('openrouter');
+  if (config.openai?.apiKey) out.push('openai');
+  if (config.azureOpenAI?.endpoint && config.azureOpenAI?.apiKey) out.push('azure-openai');
+  if (config.ollama?.endpoint) out.push('ollama');
+  if (config.llamacpp?.endpoint) out.push('llamacpp');
+  if (config.lmstudio?.endpoint) out.push('lmstudio');
+  return out;
+}
+
 /**
  * Check if a provider is local
  */
@@ -40,15 +84,28 @@ function isLocalProvider(provider) {
 
 /**
  * Check if fallback is enabled
+ * In tier routing mode, fallback is always enabled
  */
 function isFallbackEnabled() {
+  if (config.modelTiers?.enabled) {
+    // Tier routing mode: fallback always enabled
+    return true;
+  }
+  // Static provider mode: use FALLBACK_ENABLED
   return config.modelProvider?.fallbackEnabled !== false;
 }
 
 /**
  * Get the configured fallback provider
+ * In tier routing mode, fallback = TIER_REASONING provider
  */
 function getFallbackProvider() {
+  if (config.modelTiers?.enabled && config.modelTiers?.REASONING) {
+    // Tier routing mode: extract provider from TIER_REASONING
+    const match = config.modelTiers.REASONING.match(/^([a-z-]+):/);
+    if (match) return match[1];
+  }
+  // Static provider mode: use FALLBACK_PROVIDER
   return config.modelProvider?.fallbackProvider ?? 'databricks';
 }
 
@@ -97,6 +154,18 @@ function getBestLocalProvider() {
 async function determineProviderSmart(payload, options = {}) {
   const primaryProvider = config.modelProvider?.type ?? 'databricks';
 
+  // Risk analysis runs orthogonally to complexity. We compute it once
+  // up-front so it can short-circuit force_local and feed the tier
+  // selector below. Even when tier routing is disabled we still surface
+  // the signal for telemetry.
+  let risk = null;
+  try {
+    risk = analyzeRisk(payload);
+  } catch (err) {
+    logger.debug({ err: err.message }, '[Routing] Risk analysis failed, ignoring');
+    risk = null;
+  }
+
   // If tier routing is disabled, use static configuration
   if (!config.modelTiers?.enabled) {
     return {
@@ -104,9 +173,39 @@ async function determineProviderSmart(payload, options = {}) {
       model: null,
       method: 'static',
       reason: 'tier_routing_disabled',
+      risk,
     };
   }
 
+  // High-risk requests jump straight to COMPLEX and skip the rest of
+  // the analysis. This is independent of complexity score — a one-line
+  // edit to auth/middleware.ts should never go to a local model.
+  if (risk?.level === 'high' && isFallbackEnabled()) {
+    try {
+      const selector = getModelTierSelector();
+      const modelSelection = selector.selectModel('COMPLEX', null);
+      const decision = {
+        provider: modelSelection.provider,
+        model: modelSelection.model,
+        tier: 'COMPLEX',
+        method: 'risk',
+        reason: 'high_risk_forced_tier',
+        score: 100,
+        risk,
+      };
+      routingMetrics.record(decision);
+      logger.debug({
+        tier: 'COMPLEX',
+        provider: decision.provider,
+        instructionHits: risk.instructionHits,
+        pathHits: risk.pathHits,
+      }, '[Routing] High risk → forcing tier');
+      return decision;
+    } catch (err) {
+      logger.debug({ err: err.message }, '[Routing] Risk-forced tier selection failed, falling through');
+    }
+  }
+
   // Quick check for force patterns
   if (shouldForceLocal(payload)) {
     // When tier routing is enabled, respect TIER_SIMPLE instead of blindly choosing local
@@ -121,6 +220,7 @@ async function determineProviderSmart(payload, options = {}) {
           method: 'force',
           reason: 'force_local_pattern',
           score: 0,
+          risk,
         };
         routingMetrics.record(decision);
         return decision;
@@ -135,6 +235,7 @@ async function determineProviderSmart(payload, options = {}) {
       method: 'force',
       reason: 'force_local_pattern',
       score: 0,
+      risk,
     };
     routingMetrics.record(decision);
     return decision;
@@ -148,6 +249,7 @@ async function determineProviderSmart(payload, options = {}) {
       method: 'force',
       reason: 'force_cloud_pattern',
       score: 100,
+      risk,
     };
     routingMetrics.record(decision);
     return decision;
@@ -201,6 +303,7 @@ async function determineProviderSmart(payload, options = {}) {
             reason: 'autonomous_workflow',
             score: analysis.score,
             agenticResult,
+            risk,
           };
           routingMetrics.record(decision);
           return decision;
@@ -236,9 +339,11 @@ async function determineProviderSmart(payload, options = {}) {
     }
   }
 
-  // Apply routing decision based on tier config (TIER_* env vars are mandatory)
+  // Apply routing decision based on tier config (TIER_* env vars take precedence
+  // but Phase 1.2 lets the cost-optimizer pick a cheaper qualifying model when safe).
   let provider;
   let method = 'tier_config';
+  let costOptimized = false;
 
   const selector = getModelTierSelector();
   const modelSelection = selector.selectModel(tier, null);
@@ -247,8 +352,242 @@ async function determineProviderSmart(payload, options = {}) {
   selectedModel = modelSelection.model;
   logger.debug({ tier, provider, model: selectedModel }, '[Routing] Using tier config');
 
-  // TIER_* env vars are the final word — no cost optimization override.
-  // The user explicitly configured provider:model per tier; respect that.
+  // Phase 1.2 — cost-optimizer override.
+  // Only kick in when:
+  //  - feature flag enabled (default true, disable with LYNKR_COST_OPTIMIZE=false)
+  //  - risk level is not high (high-risk keeps the explicitly-configured model)
+  //  - the optimizer finds a meaningfully cheaper qualifying model
+  const costOptimizeEnabled = process.env.LYNKR_COST_OPTIMIZE !== 'false'
+    && config.routing?.costOptimize !== false;
+  if (costOptimizeEnabled && risk?.level !== 'high') {
+    try {
+      const optimizer = getCostOptimizer();
+      const availableProviders = _enabledProviders();
+      const cheapest = optimizer.findCheapestForTier(tier, availableProviders);
+      if (cheapest && cheapest.model && cheapest.model !== selectedModel) {
+        const current = optimizer.estimateCost(selectedModel, 1000);
+        const candidate = optimizer.estimateCost(cheapest.model, 1000);
+        if (candidate.totalEstimate > 0 && candidate.totalEstimate < current.totalEstimate * 0.75) {
+          logger.debug({
+            tier,
+            from: `${provider}:${selectedModel}`,
+            to: `${cheapest.provider}:${cheapest.model}`,
+            savedPerK: (current.totalEstimate - candidate.totalEstimate).toFixed(6),
+          }, '[Routing] Cost-optimizer override');
+          provider = cheapest.provider;
+          selectedModel = cheapest.model;
+          method = 'tier_config+cost_optimized';
+          costOptimized = true;
+        }
+      }
+    } catch (err) {
+      logger.debug({ err: err.message }, '[Routing] Cost-optimize failed, keeping tier_config selection');
+    }
+  }
+
+  // Phase 1.3 — context window validation. If estimated tokens exceed the
+  // selected model's context (with response headroom), escalate to a
+  // context-capable model regardless of tier.
+  try {
+    const estimatedTokens = countPayloadTokens(payload, selectedModel);
+    const ctxResult = contextValidator.validate(selectedModel, estimatedTokens);
+    if (!ctxResult.ok) {
+      const capable = selector.findContextCapable(estimatedTokens, tier);
+      if (capable) {
+        logger.info({
+          from: `${provider}:${selectedModel}`,
+          to: `${capable.provider}:${capable.model}`,
+          required: estimatedTokens,
+          oldContext: ctxResult.context,
+          newContext: capable.context,
+        }, '[Routing] Context window escalation');
+        provider = capable.provider;
+        selectedModel = capable.model;
+        if (capable.tier) tier = capable.tier;
+        method = method + '+context_escalated';
+      } else {
+        logger.warn({
+          model: selectedModel,
+          required: estimatedTokens,
+          available: ctxResult.context,
+        }, '[Routing] No context-capable fallback — request may fail upstream');
+      }
+    }
+  } catch (err) {
+    logger.debug({ err: err.message }, '[Routing] Context validation failed, proceeding without check');
+  }
+
+  // Phase 1.4 — vision capability guard.
+  // If the payload contains image content blocks but the selected model lacks
+  // vision support, silently swap to the cheapest vision-capable model at or
+  // above the current tier. Prevents silent upstream failures.
+  if (_payloadHasImages(payload)) {
+    try {
+      const { getModelRegistrySync } = require('./model-registry');
+      const registry = getModelRegistrySync();
+      const modelInfo = registry.getCost(selectedModel);
+      if (!modelInfo?.vision) {
+        const visionModel = selector.findVisionCapable(tier);
+        if (visionModel) {
+          logger.info({
+            from: `${provider}:${selectedModel}`,
+            to: `${visionModel.provider}:${visionModel.model}`,
+            tier: visionModel.tier,
+          }, '[Routing] Vision guard — upgrading to vision-capable model');
+          provider = visionModel.provider;
+          selectedModel = visionModel.model;
+          if (visionModel.tier !== tier) tier = visionModel.tier;
+          method = method + '+vision_guard';
+        } else {
+          logger.warn({ model: selectedModel }, '[Routing] Vision guard — no vision-capable model found, request may fail');
+        }
+      }
+    } catch (err) {
+      logger.debug({ err: err.message }, '[Routing] Vision guard check failed, proceeding');
+    }
+  }
+
+  // Phase 3.1 — kNN routing hint.
+  // If the index has enough entries, query it with the last user message.
+  // A high-confidence kNN suggestion overrides the heuristic selection.
+  let knnResult = null;
+  if (config.routing?.knnEnabled !== false) {
+    try {
+      const msgs = payload?.messages;
+      const lastMsg = Array.isArray(msgs) ? msgs[msgs.length - 1]?.content : null;
+      const queryText = typeof lastMsg === 'string' ? lastMsg
+        : Array.isArray(lastMsg) ? lastMsg.filter(b => b?.type === 'text').map(b => b.text || '').join(' ')
+        : null;
+      if (queryText) {
+        knnResult = await getKnnRouter().query(queryText);
+        if (knnResult && knnResult.confidence > 0.7 && knnResult.model && knnResult.model !== selectedModel) {
+          // High confidence — trust kNN's model recommendation directly.
+          logger.debug({
+            from: `${provider}:${selectedModel}`,
+            to: `${knnResult.provider}:${knnResult.model}`,
+            confidence: knnResult.confidence.toFixed(3),
+          }, '[Routing] kNN override');
+          provider = knnResult.provider;
+          selectedModel = knnResult.model;
+          method = method + '+knn';
+        } else if (knnResult && knnResult.confidence > 0.4 && knnResult.confidence <= 0.7) {
+          // Ambiguous signal — neighbors are split, we can't trust any single model
+          // recommendation. Err on quality: bump the current tier one step up so the
+          // request gets a more capable model rather than risking a bad answer from
+          // a model that was borderline for similar past requests.
+          const TIER_ORDER = ['SIMPLE', 'MEDIUM', 'COMPLEX', 'REASONING'];
+          const currentIdx = TIER_ORDER.indexOf(tier);
+          if (currentIdx >= 0 && currentIdx < TIER_ORDER.length - 1) {
+            const upgradedTier = TIER_ORDER[currentIdx + 1];
+            try {
+              const upgraded = selector.selectModel(upgradedTier, null);
+              logger.debug({
+                from: `${tier}:${provider}:${selectedModel}`,
+                to: `${upgradedTier}:${upgraded.provider}:${upgraded.model}`,
+                confidence: knnResult.confidence.toFixed(3),
+              }, '[Routing] kNN ambiguous — escalating tier for safety');
+              provider = upgraded.provider;
+              selectedModel = upgraded.model;
+              tier = upgradedTier;
+              method = method + '+knn_ambiguous_escalate';
+            } catch (err) {
+              logger.debug({ err: err.message }, '[Routing] kNN ambiguous escalation failed, keeping current tier');
+            }
+          }
+        }
+      }
+    } catch (err) {
+      logger.debug({ err: err.message }, '[Routing] kNN query failed, ignoring');
+    }
+  }
+
+  // Phase 4.1 — LinUCB bandit intra-tier selection.
+  // When there are two candidates (heuristic vs kNN), the bandit picks the
+  // one with the highest estimated UCB score for the current context.
+  if (config.routing?.banditEnabled !== false && knnResult && knnResult.model) {
+    try {
+      // Build candidates: current selection and kNN alternative if different
+      const allCandidates = [{ provider, model: selectedModel }];
+      if (knnResult.model !== selectedModel) {
+        allCandidates.push({ provider: knnResult.provider, model: knnResult.model });
+      }
+
+      if (allCandidates.length > 1) {
+        const bandit = getBandit();
+        const TASK_TYPES = ['code_gen', 'summarization', 'reasoning', 'factoid', 'chat', 'other'];
+        const inferredTask = (analysis.breakdown?.taskType?.reason || 'other').toLowerCase();
+        const taskIdx = Math.max(0, TASK_TYPES.findIndex(t => inferredTask.includes(t)));
+        const ctx = [
+          (analysis.score || 0) / 100,
+          Math.log(Math.max(1, analysis.breakdown?.tokenCount || 0) + 1) / 15,
+          ((payload?.tools?.length ?? 0) > 0) ? 1 : 0,
+          options.streaming ? 1 : 0,
+          risk?.level === 'high' ? 1 : risk?.level === 'medium' ? 0.5 : 0,
+          agenticResult?.isAgentic ? 1 : 0,
+          ...TASK_TYPES.map((_, i) => i === taskIdx ? 1 : 0),
+        ];
+        const picked = bandit.pick(tier, allCandidates, ctx);
+        if (picked && picked.model !== selectedModel) {
+          logger.debug({
+            from: `${provider}:${selectedModel}`,
+            to: `${picked.provider}:${picked.model}`,
+            ucb: picked.ucb?.toFixed(4),
+            explored: picked.explored,
+          }, '[Routing] Bandit override');
+          provider = picked.provider;
+          selectedModel = picked.model;
+          method = method + (picked.explored ? '+bandit_explore' : '+bandit');
+        }
+      }
+    } catch (err) {
+      logger.debug({ err: err.message }, '[Routing] Bandit pick failed, ignoring');
+    }
+  }
+
+  // Phase 6.3 — deadline-aware fastest-model selection.
+  // Payload carries _deadlineMs injected by the orchestrator from the
+  // LYNKR-Deadline-Ms request header.
+  const deadlineMs = payload?._deadlineMs ?? null;
+  if (deadlineMs) {
+    try {
+      const fastest = chooseFastest([{ provider, model: selectedModel }], deadlineMs);
+      if (fastest && fastest.model !== selectedModel) {
+        logger.debug({
+          from: `${provider}:${selectedModel}`,
+          to: `${fastest.provider}:${fastest.model}`,
+          deadlineMs,
+        }, '[Routing] Deadline override');
+        provider = fastest.provider;
+        selectedModel = fastest.model;
+        method = method + '+deadline';
+      }
+    } catch (err) {
+      logger.debug({ err: err.message }, '[Routing] Deadline check failed, ignoring');
+    }
+  }
+
+  // Phase 6.1 — per-tenant policy overrides.
+  // tenantPolicy comes from options (threaded from Express res.locals via
+  // orchestrator → databricks → here).
+  if (options.tenantPolicy) {
+    try {
+      const overridden = applyTenantOverrides(
+        { provider, model: selectedModel, tier, method },
+        options.tenantPolicy,
+      );
+      if (overridden && overridden.model !== selectedModel) {
+        logger.debug({
+          from: `${provider}:${selectedModel}`,
+          to: `${overridden.provider}:${overridden.model}`,
+        }, '[Routing] Tenant override');
+        provider = overridden.provider;
+        selectedModel = overridden.model;
+        method = overridden.method;
+      }
+    } catch (err) {
+      logger.debug({ err: err.message }, '[Routing] Tenant override failed, ignoring');
+    }
+  }
 
   const decision = {
     provider,
@@ -262,9 +601,19 @@ async function determineProviderSmart(payload, options = {}) {
     analysis,
     embeddingsResult,
     agenticResult,
-    costOptimized: false,
+    costOptimized,
+    risk,
+    knnResult,
   };
 
+  // Phase 4.4 — shadow-mode policy comparison (fire-and-forget).
+  const shadowFn = getShadowPolicy();
+  if (shadowFn) {
+    setImmediate(() =>
+      shadowCompareAndLog({ payload, activeDecision: decision, shadowFn }).catch(() => {})
+    );
+  }
+
   // Phase 3: Record metrics
   routingMetrics.record(decision);
 
@@ -322,6 +671,18 @@ function getRoutingHeaders(decision) {
     headers['X-Lynkr-Cost-Optimized'] = 'true';
   }
 
+  if (decision.risk?.level) {
+    headers['X-Lynkr-Risk'] = decision.risk.level;
+    const hits = Array.from(new Set([
+      ...(decision.risk.instructionHits || []),
+      ...(decision.risk.pathHits || []),
+    ]));
+    if (hits.length > 0) {
+      // Header values are ASCII-only; comma-join the first few hits.
+      headers['X-Lynkr-Risk-Hits'] = hits.slice(0, 8).join(',');
+    }
+  }
+
   return headers;
 }
 
@@ -350,6 +711,7 @@ module.exports = {
 
   // Re-export analyzer for direct access
   analyzeComplexity: require('./complexity-analyzer').analyzeComplexity,
+  analyzeRisk,
 
   // Intelligent routing modules
   getAgenticDetector,
@@ -358,6 +720,14 @@ module.exports = {
   AGENT_TYPES,
   TIER_DEFINITIONS,
 
+  // Phase 3-6 modules
+  getKnnRouter,
+  getBandit,
+  getShadowPolicy,
+  shadowCompareAndLog,
+  chooseFastest,
+  applyTenantOverrides,
+
   // Telemetry
   telemetry,
   scoreResponseQuality,

package/src/routing/interaction.js

@@ -0,0 +1,183 @@
+/**
+ * Routing Interaction Block
+ *
+ * Builds an "interaction" block that explains, in plain text, what
+ * Lynkr decided to do with a request — which tier, which provider,
+ * why it routed there, and what (if anything) the user should do next.
+ *
+ * Lynkr already surfaces this information via X-Lynkr-* response
+ * headers, but headers are invisible to most users in Claude Code /
+ * Cursor / Codex. The interaction block lives in the response body
+ * so it shows up alongside the model's reply when the visible-routing
+ * env flag is on (LYNKR_VISIBLE_ROUTING=true).
+ *
+ * @module routing/interaction
+ */
+
+/**
+ * Rough estimate of cost savings vs always-COMPLEX baseline. Not
+ * invoice-grade, just a reproducible number for users to glance at.
+ *
+ * @param {string|null} tier
+ * @param {string|null} provider
+ * @returns {number} 0-100
+ */
+function estimateSavingsPercent(tier, provider) {
+  if (!tier) return 0;
+  const t = tier.toUpperCase();
+  // Local providers carry the same savings band as their tier.
+  const isLocal = provider && ['ollama', 'llamacpp', 'lmstudio'].includes(provider);
+  if (t === 'SIMPLE') return isLocal ? 100 : 70;
+  if (t === 'MEDIUM') return isLocal ? 90 : 45;
+  if (t === 'COMPLEX') return 10;
+  if (t === 'REASONING') return 0;
+  return 0;
+}
+
+/**
+ * Choose a mode label that describes what happened.
+ *
+ * @param {object} decision
+ * @returns {string}
+ */
+function modeFor(decision) {
+  if (decision.method === 'risk') return 'risk_forced_tier';
+  if (decision.method === 'agentic') return 'agentic_workflow';
+  if (decision.method === 'force' && decision.reason === 'force_local_pattern') return 'force_local';
+  if (decision.method === 'force' && decision.reason === 'force_cloud_pattern') return 'force_cloud';
+  if (decision.method === 'static') return 'static';
+  return 'tier_routed';
+}
+
+/**
+ * Produce a one-line, terminal-friendly route label, e.g.
+ *   "[Lynkr] tier=COMPLEX provider=databricks risk=high score=78"
+ *
+ * @param {object} decision
+ * @returns {string}
+ */
+function routeLabel(decision) {
+  const parts = ['[Lynkr]'];
+  if (decision.tier) parts.push(`tier=${decision.tier}`);
+  if (decision.provider) parts.push(`provider=${decision.provider}`);
+  if (decision.model) parts.push(`model=${decision.model}`);
+  if (decision.risk?.level) parts.push(`risk=${decision.risk.level}`);
+  if (typeof decision.score === 'number') parts.push(`score=${decision.score}`);
+  return parts.join(' ');
+}
+
+/**
+ * Headline + next_step are model-facing prose. We keep them terse so
+ * they don't pollute the user's view when the model echoes them back.
+ *
+ * @param {object} decision
+ * @returns {{ headline: string, next_step: string }}
+ */
+function copyFor(decision) {
+  const mode = modeFor(decision);
+  if (mode === 'risk_forced_tier') {
+    return {
+      headline: `Lynkr routed to ${decision.tier} tier because the request touches a protected domain.`,
+      next_step: 'Review the response carefully — sensitive logic was involved.',
+    };
+  }
+  if (mode === 'agentic_workflow') {
+    return {
+      headline: `Lynkr detected an agentic workflow and routed to ${decision.provider || decision.tier}.`,
+      next_step: 'No action needed — autonomous workflows always use cloud providers.',
+    };
+  }
+  if (mode === 'force_local') {
+    return {
+      headline: 'Lynkr routed to the local tier (greeting or trivial request).',
+      next_step: 'No action needed.',
+    };
+  }
+  if (mode === 'force_cloud') {
+    return {
+      headline: `Lynkr forced cloud routing (${decision.provider || 'cloud'}) for this request.`,
+      next_step: 'No action needed.',
+    };
+  }
+  if (mode === 'static') {
+    return {
+      headline: `Lynkr used the static provider ${decision.provider}.`,
+      next_step: 'Tier routing is disabled — set TIER_* env vars to enable.',
+    };
+  }
+  return {
+    headline: `Lynkr routed to the ${decision.tier || 'default'} tier (${decision.provider || 'unknown'}).`,
+    next_step: 'No action needed.',
+  };
+}
+
+/**
+ * Build the full interaction block.
+ *
+ * @param {object} decision - The routing decision (from determineProviderSmart
+ *   or the pre-route in api/router.js). Must at least have `provider`; ideally
+ *   includes `tier`, `model`, `method`, `reason`, `score`, and `risk`.
+ * @returns {object}
+ */
+function buildInteractionBlock(decision) {
+  if (!decision || typeof decision !== 'object') return null;
+  const { headline, next_step } = copyFor(decision);
+  return {
+    tool: 'lynkr.route',
+    mode: modeFor(decision),
+    headline,
+    route_label: routeLabel(decision),
+    reason: decision.reason || 'unspecified',
+    tier: decision.tier || null,
+    provider: decision.provider || null,
+    model: decision.model || null,
+    risk: decision.risk?.level || 'low',
+    risk_hits: Array.from(new Set([
+      ...(decision.risk?.instructionHits || []),
+      ...(decision.risk?.pathHits || []),
+    ])),
+    complexity_score: typeof decision.score === 'number' ? decision.score : null,
+    estimated_savings_percent: estimateSavingsPercent(decision.tier, decision.provider),
+    next_step,
+  };
+}
+
+/**
+ * Attach an interaction block to an Anthropic-format response body.
+ * Mutates and returns the body.
+ *
+ * Anthropic clients ignore unknown top-level fields, so this is safe.
+ *
+ * @param {object} body
+ * @param {object} interaction
+ * @returns {object}
+ */
+function attachToAnthropicResponse(body, interaction) {
+  if (!body || !interaction) return body;
+  body.lynkr_interaction = interaction;
+  return body;
+}
+
+/**
+ * Attach an interaction block to an OpenAI chat-completions response.
+ * Mutates and returns the body.
+ *
+ * @param {object} body
+ * @param {object} interaction
+ * @returns {object}
+ */
+function attachToOpenAIResponse(body, interaction) {
+  if (!body || !interaction) return body;
+  body.lynkr_interaction = interaction;
+  return body;
+}
+
+module.exports = {
+  buildInteractionBlock,
+  attachToAnthropicResponse,
+  attachToOpenAIResponse,
+  // Exposed for tests
+  estimateSavingsPercent,
+  modeFor,
+  routeLabel,
+};