lynkr 9.0.1 → 9.1.2

package/src/orchestrator/preflight.js

@@ -0,0 +1,188 @@
+/**
+ * Preflight Checks
+ *
+ * Runs user-supplied commands before invoking the model. If they all
+ * exit 0, the work is already done — we skip the LLM call entirely
+ * and return a synthetic "preflight_satisfied" response at zero cost.
+ *
+ * Typical use case: a fix-the-failing-test request that arrives after
+ * the test already passes (CI lag, retry-after-fix, idempotent agent
+ * retries).
+ *
+ * The request opts in by including a top-level `preflight_commands`
+ * array on the Anthropic-format payload, e.g.:
+ *
+ *   {
+ *     "model": "...",
+ *     "messages": [...],
+ *     "preflight_commands": ["pnpm test -- user-service"]
+ *   }
+ *
+ * Disabled by default — gated on LYNKR_PREFLIGHT_ENABLED=true. The
+ * commands run with the same permissions as the Lynkr server, so
+ * operators should only enable this on workspaces where that is OK.
+ *
+ * @module orchestrator/preflight
+ */
+
+const { spawnSync } = require('child_process');
+const path = require('path');
+const config = require('../config');
+const logger = require('../logger');
+
+const MAX_COMMANDS = 10;
+const MAX_OUTPUT_BYTES = 4000;
+
+/**
+ * Extract the preflight command list from a request payload.
+ * Accepts either `preflight_commands` (Lynkr-specific) or
+ * `metadata.lynkr_preflight_commands` (for clients that strip unknown
+ * top-level fields).
+ *
+ * @param {object} payload
+ * @returns {string[]}
+ */
+function extractCommands(payload) {
+  if (!payload) return [];
+  const raw =
+    payload.preflight_commands ||
+    payload.metadata?.lynkr_preflight_commands ||
+    [];
+  if (!Array.isArray(raw)) return [];
+  return raw
+    .filter(cmd => typeof cmd === 'string' && cmd.trim().length > 0)
+    .slice(0, MAX_COMMANDS);
+}
+
+/**
+ * Resolve the workspace path for command execution. Falls back to
+ * process.cwd() if no workspace is supplied (the caller should usually
+ * pass one explicitly).
+ *
+ * @param {string|null|undefined} cwd
+ * @returns {string|null} absolute path, or null if invalid
+ */
+function resolveCwd(cwd) {
+  if (!cwd || typeof cwd !== 'string') return null;
+  if (!path.isAbsolute(cwd)) return null;
+  return cwd;
+}
+
+/**
+ * Run a single command, returning a structured result.
+ *
+ * @param {string} command
+ * @param {string} cwd
+ * @param {number} timeoutMs
+ * @returns {{ command: string, exit_code: number|null, stdout: string, stderr: string, timed_out: boolean }}
+ */
+function runCommand(command, cwd, timeoutMs) {
+  const result = spawnSync(command, {
+    cwd,
+    shell: true,
+    encoding: 'utf8',
+    timeout: timeoutMs,
+    maxBuffer: 10 * 1024 * 1024,
+  });
+  return {
+    command,
+    exit_code: result.status,
+    stdout: (result.stdout || '').slice(-MAX_OUTPUT_BYTES),
+    stderr: (result.stderr || '').slice(-MAX_OUTPUT_BYTES),
+    timed_out: result.signal === 'SIGTERM',
+  };
+}
+
+/**
+ * Try the preflight pass. Returns null when preflight should be
+ * skipped (disabled, no commands, missing cwd). Returns a result
+ * object otherwise.
+ *
+ * @param {object} args
+ * @param {object} args.payload - Anthropic-format request payload
+ * @param {string} [args.cwd] - Workspace cwd (absolute path)
+ * @returns {null | {
+ *   satisfied: boolean,
+ *   results: object[],
+ *   failedCommand: string|null,
+ *   reason: string,
+ * }}
+ */
+function tryPreflight({ payload, cwd }) {
+  if (!config.routing?.preflightEnabled) return null;
+  const commands = extractCommands(payload);
+  if (commands.length === 0) return null;
+  const workspaceCwd = resolveCwd(cwd);
+  if (!workspaceCwd) {
+    logger.debug({ cwd }, '[Preflight] No valid cwd, skipping');
+    return null;
+  }
+
+  const timeoutMs = config.routing?.preflightTimeoutMs || 120000;
+  const results = [];
+  for (const command of commands) {
+    const r = runCommand(command, workspaceCwd, timeoutMs);
+    results.push(r);
+    if (r.exit_code !== 0) {
+      return {
+        satisfied: false,
+        results,
+        failedCommand: command,
+        reason: r.timed_out
+          ? `Preflight command timed out: ${command}`
+          : `Preflight command exited ${r.exit_code}: ${command}`,
+      };
+    }
+  }
+  return {
+    satisfied: true,
+    results,
+    failedCommand: null,
+    reason: 'All preflight commands passed.',
+  };
+}
+
+/**
+ * Build a synthetic "preflight satisfied" Anthropic Message response
+ * that processMessage can return without hitting the model.
+ *
+ * @param {object} args
+ * @param {string} args.model
+ * @param {object} args.preflightResult
+ * @returns {object} The full processMessage return value.
+ */
+function buildSatisfiedResponse({ model, preflightResult }) {
+  const summary = `Preflight satisfied — work appears already complete (${preflightResult.results.length} command${preflightResult.results.length === 1 ? '' : 's'} passed).`;
+  return {
+    response: {
+      json: {
+        id: `msg_preflight_${Date.now()}`,
+        type: 'message',
+        role: 'assistant',
+        content: [{ type: 'text', text: summary }],
+        model,
+        stop_reason: 'end_turn',
+        stop_sequence: null,
+        usage: { input_tokens: 0, output_tokens: 0 },
+        lynkr_preflight: {
+          satisfied: true,
+          reason: preflightResult.reason,
+          results: preflightResult.results,
+        },
+      },
+      ok: true,
+      status: 200,
+    },
+    steps: 0,
+    durationMs: 0,
+    terminationReason: 'preflight_satisfied',
+  };
+}
+
+module.exports = {
+  tryPreflight,
+  buildSatisfiedResponse,
+  extractCommands,
+  // Exposed for tests
+  resolveCwd,
+};

package/src/routing/index.js

@@ -22,6 +22,7 @@ const {
 const { getAgenticDetector, AGENT_TYPES } = require('./agentic-detector');
 const { getModelTierSelector, TIER_DEFINITIONS } = require('./model-tiers');
 const { getCostOptimizer } = require('./cost-optimizer');
+const { analyzeRisk } = require('./risk-analyzer');
 
 // Telemetry modules
 const telemetry = require('./telemetry');
@@ -97,6 +98,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 +117,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 +164,7 @@ async function determineProviderSmart(payload, options = {}) {
           method: 'force',
           reason: 'force_local_pattern',
           score: 0,
+          risk,
         };
         routingMetrics.record(decision);
         return decision;
@@ -135,6 +179,7 @@ async function determineProviderSmart(payload, options = {}) {
       method: 'force',
       reason: 'force_local_pattern',
       score: 0,
+      risk,
     };
     routingMetrics.record(decision);
     return decision;
@@ -148,6 +193,7 @@ async function determineProviderSmart(payload, options = {}) {
       method: 'force',
       reason: 'force_cloud_pattern',
       score: 100,
+      risk,
     };
     routingMetrics.record(decision);
     return decision;
@@ -201,6 +247,7 @@ async function determineProviderSmart(payload, options = {}) {
             reason: 'autonomous_workflow',
             score: analysis.score,
             agenticResult,
+            risk,
           };
           routingMetrics.record(decision);
           return decision;
@@ -247,37 +294,8 @@ async function determineProviderSmart(payload, options = {}) {
   selectedModel = modelSelection.model;
   logger.debug({ tier, provider, model: selectedModel }, '[Routing] Using tier config');
 
-  // Cost optimization: check if cheaper model can handle this tier
-  let costOptimized = false;
-  if (config.routing?.costOptimization && tier) {
-    try {
-      const optimizer = getCostOptimizer();
-      const availableProviders = [provider];
-
-      // Also consider local provider if not already selected
-      const localProvider = getBestLocalProvider();
-      if (localProvider !== provider) {
-        availableProviders.push(localProvider);
-      }
-
-      const cheapest = optimizer.findCheapestForTier(tier, availableProviders);
-      if (cheapest && cheapest.provider !== provider) {
-        logger.debug({
-          from: provider,
-          to: cheapest.provider,
-          tier,
-          savings: `${cheapest.model} is cheaper`,
-        }, '[Routing] Cost optimization: switching provider');
-
-        provider = cheapest.provider;
-        selectedModel = cheapest.model;
-        costOptimized = true;
-        method = 'cost_optimized';
-      }
-    } catch (err) {
-      logger.debug({ err: err.message }, 'Cost optimization failed');
-    }
-  }
+  // TIER_* env vars are the final word — no cost optimization override.
+  // The user explicitly configured provider:model per tier; respect that.
 
   const decision = {
     provider,
@@ -291,7 +309,8 @@ async function determineProviderSmart(payload, options = {}) {
     analysis,
     embeddingsResult,
     agenticResult,
-    costOptimized,
+    costOptimized: false,
+    risk,
   };
 
   // Phase 3: Record metrics
@@ -351,6 +370,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;
 }
 
@@ -379,6 +410,7 @@ module.exports = {
 
   // Re-export analyzer for direct access
   analyzeComplexity: require('./complexity-analyzer').analyzeComplexity,
+  analyzeRisk,
 
   // Intelligent routing modules
   getAgenticDetector,

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,
+};