lynkr 9.0.2 → 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;
@@ -263,6 +310,7 @@ async function determineProviderSmart(payload, options = {}) {
     embeddingsResult,
     agenticResult,
     costOptimized: false,
+    risk,
   };
 
   // Phase 3: Record metrics
@@ -322,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;
 }
 
@@ -350,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,
+};

package/src/routing/risk-analyzer.js

@@ -0,0 +1,194 @@
+/**
+ * Risk Analyzer
+ *
+ * Scores a request along a risk axis that is orthogonal to complexity.
+ * A trivially short edit to `auth/middleware.ts` is still high risk and
+ * should not be served by a cheap local model.
+ *
+ * @module routing/risk-analyzer
+ */
+
+const { extractContent } = require('./complexity-analyzer');
+
+// Substring keywords found in file paths or instruction text.
+// Matched case-insensitively as raw substrings, so "auth" hits
+// "src/auth/login.ts" and "authentication".
+const PROTECTED_PATH_KEYWORDS = [
+  'auth', 'oauth', 'jwt', 'session', 'security', 'permission', 'rbac',
+  'payment', 'payments', 'billing', 'invoice', 'subscription',
+  'migration', 'migrations', 'schema',
+  'infra', 'terraform', 'kustomize', 'helm', 'kubernetes',
+  '.github/workflows', '.env', 'secret', 'credential',
+  'api-key', 'api_key', 'apikey', 'token',
+  'webhook', 'admin',
+];
+
+// Whole-word instruction keywords that signal sensitive intent regardless
+// of which files are involved. Higher signal than path keywords because
+// they reflect what the user is *asking for*.
+const HIGH_RISK_INSTRUCTION_KEYWORDS = [
+  'authentication', 'authorization', 'permission', 'security',
+  'payment', 'billing', 'migration', 'database schema',
+  'encrypt', 'decrypt', 'secret', 'credential', 'api key',
+  'production', 'deploy', 'rollout', 'rollback',
+];
+
+// Path-extracting patterns. We look at:
+//   1. Anything that looks like a file path inside the instruction text.
+//   2. Explicit path-like fields in tool inputs (e.g. tool_use blocks).
+const PATH_LIKE_RE = /(?:^|[\s`'"([])([./a-zA-Z0-9_-]+\.[a-zA-Z0-9]{1,8})(?=[\s`'")\]:,;]|$)/g;
+const SLASHED_PATH_RE = /(?:^|[\s`'"([])((?:[a-zA-Z0-9_.-]+\/)+[a-zA-Z0-9_.-]+)(?=[\s`'")\]:,;]|$)/g;
+
+/**
+ * Pull every path-shaped substring out of free-form text.
+ * @param {string} text
+ * @returns {string[]}
+ */
+function extractPathsFromText(text) {
+  if (!text) return [];
+  const out = new Set();
+  let m;
+  while ((m = PATH_LIKE_RE.exec(text)) !== null) {
+    out.add(m[1]);
+  }
+  while ((m = SLASHED_PATH_RE.exec(text)) !== null) {
+    out.add(m[1]);
+  }
+  return Array.from(out);
+}
+
+/**
+ * Walk every tool_use block in the conversation and collect any string
+ * inputs that look like paths. Catches cases where the model already
+ * called an Edit/Read tool on a sensitive file.
+ * @param {object} payload
+ * @returns {string[]}
+ */
+function extractPathsFromToolUses(payload) {
+  const out = new Set();
+  const messages = payload?.messages;
+  if (!Array.isArray(messages)) return [];
+
+  for (const msg of messages) {
+    if (!Array.isArray(msg?.content)) continue;
+    for (const block of msg.content) {
+      if (block?.type !== 'tool_use' || !block.input) continue;
+      const stack = [block.input];
+      while (stack.length) {
+        const node = stack.pop();
+        if (typeof node === 'string') {
+          if (node.includes('/') || node.includes('.')) {
+            // Treat short tool-input strings that look path-y as paths.
+            if (node.length <= 200) out.add(node);
+          }
+        } else if (Array.isArray(node)) {
+          for (const v of node) stack.push(v);
+        } else if (node && typeof node === 'object') {
+          for (const v of Object.values(node)) stack.push(v);
+        }
+      }
+    }
+  }
+  return Array.from(out);
+}
+
+/**
+ * Find which keywords from `keywords` appear (case-insensitively) inside
+ * any of `haystack`. Substring match — by design — so "auth" matches
+ * both "src/auth/login.ts" and the word "authorization".
+ * @param {string[]} keywords
+ * @param {string[]} haystack
+ * @returns {string[]} hit keywords, sorted
+ */
+function findHits(keywords, haystack) {
+  const hits = new Set();
+  const joined = haystack.join('\n').toLowerCase();
+  for (const kw of keywords) {
+    if (joined.includes(kw.toLowerCase())) hits.add(kw);
+  }
+  return Array.from(hits).sort();
+}
+
+/**
+ * Analyze the risk level of a request.
+ *
+ * Risk is orthogonal to complexity:
+ *   - low    → no protected paths or sensitive keywords detected
+ *   - medium → protected paths *or* a read-only task on a protected area
+ *   - high   → instruction explicitly names sensitive domain logic,
+ *              or protected paths combined with a write-intent task
+ *
+ * @param {object} payload - Anthropic-format request payload
+ * @returns {{ level: 'low'|'medium'|'high',
+ *             reason: string,
+ *             pathHits: string[],
+ *             instructionHits: string[],
+ *             paths: string[] }}
+ */
+function analyzeRisk(payload) {
+  const instructionText = extractContent(payload) || '';
+  const lowText = instructionText.toLowerCase();
+
+  const textPaths = extractPathsFromText(instructionText);
+  const toolPaths = extractPathsFromToolUses(payload);
+  const allPaths = Array.from(new Set([...textPaths, ...toolPaths]));
+
+  // Instruction-level hits scan the raw text. Path-level hits scan only
+  // the extracted path strings so phrases like "authentication is hard"
+  // don't double-fire as a path hit.
+  const instructionHits = findHits(HIGH_RISK_INSTRUCTION_KEYWORDS, [instructionText]);
+  const pathHits = findHits(PROTECTED_PATH_KEYWORDS, allPaths.length ? allPaths : []);
+  // Also let path keywords match against the instruction text — covers
+  // "update the auth flow" with no path mentioned.
+  const textPathHits = findHits(PROTECTED_PATH_KEYWORDS, [instructionText]);
+  const mergedPathHits = Array.from(new Set([...pathHits, ...textPathHits])).sort();
+
+  if (instructionHits.length > 0) {
+    return {
+      level: 'high',
+      reason: 'High-risk instruction keyword detected.',
+      pathHits: mergedPathHits,
+      instructionHits,
+      paths: allPaths,
+    };
+  }
+
+  if (mergedPathHits.length > 0) {
+    // Read-only intent on a protected area is medium, not high.
+    // Heuristic: presence of explain/summarize/read verbs.
+    const readOnly = /\b(explain|summarize|describe|what does|walk me through|read|show|list|search|find|grep|locate)\b/i.test(lowText);
+    if (readOnly) {
+      return {
+        level: 'medium',
+        reason: 'Protected paths involved but task appears read-only.',
+        pathHits: mergedPathHits,
+        instructionHits: [],
+        paths: allPaths,
+      };
+    }
+    return {
+      level: 'high',
+      reason: 'Protected path referenced with write-capable intent.',
+      pathHits: mergedPathHits,
+      instructionHits: [],
+      paths: allPaths,
+    };
+  }
+
+  return {
+    level: 'low',
+    reason: 'No risk signals detected.',
+    pathHits: [],
+    instructionHits: [],
+    paths: allPaths,
+  };
+}
+
+module.exports = {
+  analyzeRisk,
+  PROTECTED_PATH_KEYWORDS,
+  HIGH_RISK_INSTRUCTION_KEYWORDS,
+  // Exposed for tests
+  extractPathsFromText,
+  extractPathsFromToolUses,
+};