lynkr 9.5.0 → 9.7.0

package/src/routing/index.js

@@ -486,7 +486,10 @@ async function _determineProviderSmartInner(payload, options = {}) {
         : null;
       if (queryText) {
         knnResult = await getKnnRouter().query(queryText);
-        if (knnResult && knnResult.confidence > 0.7 && knnResult.model && knnResult.model !== selectedModel) {
+        // Confidence thresholds (env-configurable; defaults 0.7 high / 0.4 low):
+        const KNN_HIGH = Number.parseFloat(process.env.LYNKR_KNN_CONFIDENCE_HIGH) || 0.7;
+        const KNN_LOW  = Number.parseFloat(process.env.LYNKR_KNN_CONFIDENCE_LOW)  || 0.4;
+        if (knnResult && knnResult.confidence > KNN_HIGH && knnResult.model && knnResult.model !== selectedModel) {
           // High confidence — trust kNN's model recommendation directly.
           logger.debug({
             from: `${provider}:${selectedModel}`,
@@ -496,7 +499,7 @@ async function _determineProviderSmartInner(payload, options = {}) {
           provider = knnResult.provider;
           selectedModel = knnResult.model;
           method = method + '+knn';
-        } else if (knnResult && knnResult.confidence > 0.4 && knnResult.confidence <= 0.7) {
+        } else if (knnResult && knnResult.confidence > KNN_LOW && knnResult.confidence <= KNN_HIGH) {
           // 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
@@ -532,10 +535,26 @@ async function _determineProviderSmartInner(payload, options = {}) {
   // 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
+      // Build candidates: current selection and kNN alternative if different.
+      //
+      // Tier-aware filter: only treat the kNN suggestion as a real candidate
+      // if it matches a (provider, model) combo configured in ANY TIER_*
+      // entry. The bandit is allowed to explore freely across the user's
+      // configured tiers (e.g. swap a SIMPLE request to the COMPLEX-tier
+      // model), but is forbidden from picking a credentialed-but-untiered
+      // model (e.g. an Azure OpenAI deployment whose endpoint is set in .env
+      // for some other use, but not referenced by any TIER_*). This keeps
+      // tier routing as the source of truth for what's eligible while
+      // preserving cross-tier bandit exploration.
       const allCandidates = [{ provider, model: selectedModel }];
       if (knnResult.model !== selectedModel) {
-        allCandidates.push({ provider: knnResult.provider, model: knnResult.model });
+        const configured = require('./model-tiers').getModelTierSelector().getAllConfiguredModels();
+        const inConfig = configured.some(
+          m => m.provider === knnResult.provider && m.model === knnResult.model
+        );
+        if (inConfig) {
+          allCandidates.push({ provider: knnResult.provider, model: knnResult.model });
+        }
       }
 
       if (allCandidates.length > 1) {
@@ -697,6 +716,14 @@ function getRoutingHeaders(decision) {
     headers['X-Lynkr-Cost-Optimized'] = 'true';
   }
 
+  // Tier-aware fallback surfacing (never silent).
+  if (decision.fallback) {
+    headers['X-Lynkr-Fallback'] = 'true';
+    if (decision.fromTier) headers['X-Lynkr-Fallback-From-Tier'] = decision.fromTier;
+    if (decision.servedTier) headers['X-Lynkr-Served-Tier'] = decision.servedTier;
+    if (decision.fallbackDirection) headers['X-Lynkr-Fallback-Direction'] = decision.fallbackDirection;
+  }
+
   if (decision.risk?.level) {
     headers['X-Lynkr-Risk'] = decision.risk.level;
     const hits = Array.from(new Set([

package/src/routing/knn-router.js

@@ -29,7 +29,10 @@ const META_FILE = path.join(INDEX_DIR, 'meta.json');
 const MAX_ELEMENTS = 50000;
 const DIM = 768; // nomic-embed-text default
 const K = 10;
-const MIN_INDEX_SIZE = 1000;
+// Default 1000 is a safety floor for quality; override via env when you
+// want to activate kNN with less data (e.g. bootstrapping from your own
+// telemetry before reaching 1k entries).
+const MIN_INDEX_SIZE = Number.parseInt(process.env.LYNKR_KNN_MIN_INDEX_SIZE, 10) || 1000;
 
 let _hnsw = null;
 let _hnswLoaded = false;
@@ -72,7 +75,11 @@ class KnnRouter {
       this.meta = metaData.entries || [];
       this.size = this.meta.length;
       this.index = new hnsw.HierarchicalNSW('cosine', this.dim);
-      this.index.readIndexSync(INDEX_FILE, MAX_ELEMENTS);
+      // hnswlib-node v3 API: readIndexSync(filename, allowReplaceDeleted=false).
+      // (Earlier Lynkr code passed MAX_ELEMENTS here — wrong type, threw on load.)
+      this.index.readIndexSync(INDEX_FILE, false);
+      // resize if needed so we can keep adding up to MAX_ELEMENTS
+      try { this.index.resizeIndex(MAX_ELEMENTS); } catch (_) {}
       this.ready = true;
       logger.info({ size: this.size, dim: this.dim }, '[KnnRouter] Index loaded');
       return true;

package/src/routing/model-tiers.js

@@ -258,6 +258,40 @@ class ModelTierSelector {
     };
   }
 
+  /**
+   * Return every {provider, model} combo configured for a tier.
+   * Today TIER_* parses to a single provider:model, so this returns at most
+   * one entry. Kept as an array so callers don't have to change when
+   * multi-model tier syntax is added (e.g. TIER_SIMPLE=ollama:m1,ollama:m2).
+   */
+  getModelsForTier(tier) {
+    const tierConfig = config.modelTiers?.[tier];
+    if (!tierConfig) return [];
+    const parsed = this._parseTierConfig(tierConfig);
+    return parsed ? [{ provider: parsed.provider, model: parsed.model }] : [];
+  }
+
+  /**
+   * Return the union of every {provider, model} configured across all tiers,
+   * deduped. Used by the bandit-candidate filter to constrain exploration to
+   * the user's stated tier preferences — the bandit may pick any combo the
+   * user has configured for any tier, but never a model that isn't in any
+   * TIER_* entry (even if its credentials happen to be set).
+   */
+  getAllConfiguredModels() {
+    const seen = new Set();
+    const out = [];
+    for (const tier of ['SIMPLE', 'MEDIUM', 'COMPLEX', 'REASONING']) {
+      for (const m of this.getModelsForTier(tier)) {
+        const key = `${m.provider}:${m.model}`;
+        if (seen.has(key)) continue;
+        seen.add(key);
+        out.push(m);
+      }
+    }
+    return out;
+  }
+
   /**
    * Parse tier config string (format: provider:model)
    * Examples: "ollama:llama3.2", "azure-openai:gpt-5.2-chat", "openai:gpt-4o"

package/src/routing/tier-fallback.js

@@ -0,0 +1,91 @@
+/**
+ * Tier-aware fallback chain (escalate-then-demote).
+ *
+ * When a tier's provider fails, prefer a MORE capable tier first (climb toward
+ * REASONING), and only if every higher tier is also unavailable do we fall
+ * downward — all the way to the local SIMPLE tier as a last resort. This biases
+ * for correctness/availability over cost, matching a conservative routing policy.
+ *
+ * Example ladder: SIMPLE → MEDIUM → COMPLEX → REASONING
+ *   - COMPLEX fails  → [REASONING, MEDIUM, SIMPLE]
+ *   - REASONING fails → [COMPLEX, MEDIUM, SIMPLE]
+ *   - MEDIUM fails    → [COMPLEX, REASONING, SIMPLE]
+ *
+ * Pure and dependency-injectable so it can be unit-tested without real providers.
+ */
+
+const logger = require("../logger");
+
+const TIER_ORDER = ["SIMPLE", "MEDIUM", "COMPLEX", "REASONING"];
+
+/** Default availability check: a provider is unavailable if its circuit is OPEN. */
+function defaultIsProviderAvailable(provider) {
+  try {
+    const { getCircuitBreakerRegistry } = require("../clients/circuit-breaker");
+    const registry = getCircuitBreakerRegistry();
+    const all = typeof registry.getAll === "function" ? registry.getAll() : [];
+    const entry = Array.isArray(all) ? all.find((b) => b.name === provider) : null;
+    return !(entry && entry.state === "OPEN");
+  } catch {
+    return true; // fail open — never block fallback on a health-check error
+  }
+}
+
+/** Resolve a tier name to { tier, provider, model }, or null if not configured. */
+function resolveTier(tier, selector) {
+  try {
+    const sel = selector || require("./model-tiers").getModelTierSelector();
+    const r = sel.selectModel(tier);
+    if (!r || !r.provider || !r.model) return null;
+    return { tier, provider: r.provider, model: r.model };
+  } catch {
+    return null; // tier not configured (TIER_<X> unset) — skip it
+  }
+}
+
+/**
+ * Build the escalate-then-demote fallback chain for a failed tier.
+ *
+ * @param {string} currentTier - the tier whose provider just failed
+ * @param {Object} [opts]
+ * @param {Object} [opts.selector] - model-tiers selector (injected for tests)
+ * @param {Function} [opts.isProviderAvailable] - (provider) => boolean (injected for tests)
+ * @returns {Array<{tier,provider,model,demotedFrom,direction}>} ordered candidates
+ */
+function getFallbackChain(currentTier, opts = {}) {
+  const isAvailable = opts.isProviderAvailable || defaultIsProviderAvailable;
+  const idx = TIER_ORDER.indexOf(currentTier);
+  if (idx === -1) return [];
+
+  const higher = TIER_ORDER.slice(idx + 1); // ascending toward REASONING
+  const lower = TIER_ORDER.slice(0, idx).reverse(); // descending toward SIMPLE
+  const ordered = [...higher, ...lower];
+
+  const seen = new Set();
+  // Never re-attempt the exact provider:model that just failed.
+  const current = resolveTier(currentTier, opts.selector);
+  if (current) seen.add(`${current.provider}:${current.model}`);
+
+  const chain = [];
+  for (const tier of ordered) {
+    const resolved = resolveTier(tier, opts.selector);
+    if (!resolved) continue;
+    const key = `${resolved.provider}:${resolved.model}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    if (!isAvailable(resolved.provider)) continue;
+    chain.push({
+      ...resolved,
+      demotedFrom: currentTier,
+      direction: TIER_ORDER.indexOf(tier) > idx ? "up" : "down",
+    });
+  }
+
+  logger.debug(
+    { currentTier, chain: chain.map((c) => `${c.tier}:${c.provider}`) },
+    "[TierFallback] Built fallback chain"
+  );
+  return chain;
+}
+
+module.exports = { getFallbackChain, resolveTier, TIER_ORDER };

package/src/server.js

@@ -29,6 +29,7 @@ const { registerTaskTools } = require("./tools/tasks");
 const { registerTestTools } = require("./tools/tests");
 const { registerMcpTools } = require("./tools/mcp");
 const { registerAgentTaskTool } = require("./tools/agent-task");
+const { registerDecomposeTool } = require("./tools/decompose");
 const { initConfigWatcher, getConfigWatcher } = require("./config/watcher");
 const { initializeHeadroom, shutdownHeadroom, getHeadroomManager } = require("./headroom");
 const { getWorkerPool, isWorkerPoolReady } = require("./workers/pool");
@@ -62,6 +63,7 @@ if (LAZY_TOOLS_ENABLED) {
   registerTestTools();
   registerMcpTools();
   registerAgentTaskTool();
+  registerDecomposeTool();
   logger.info({ mode: "eager" }, "All tools loaded at startup");
 }
 

package/src/tools/decompose.js

@@ -0,0 +1,91 @@
+const { registerTool } = require(".");
+const { runDecomposedTask } = require("../agents/decomposition");
+const logger = require("../logger");
+
+/**
+ * DecomposeTask tool — breaks a complex task into focused subtasks with isolated
+ * context, runs them (parallel where independent), and synthesizes the result.
+ *
+ * Opt-in: requires TASK_DECOMPOSITION_ENABLED=true and AGENTS_ENABLED=true.
+ * Degrades gracefully — if the gate decides decomposition isn't worth it (or
+ * planning fails), it returns ok:true with decomposed:false and a reason so the
+ * caller can solve the task monolithically.
+ */
+function registerDecomposeTool() {
+  registerTool(
+    "DecomposeTask",
+    async ({ args = {} }, context = {}) => {
+      const task = args.task || args.prompt || args.description;
+
+      if (!task || typeof task !== "string") {
+        return {
+          ok: false,
+          status: 400,
+          content: JSON.stringify({ error: "task is required" }, null, 2),
+        };
+      }
+
+      logger.info(
+        { task: task.slice(0, 100), sessionId: context.sessionId },
+        "DecomposeTask: evaluating task for decomposition"
+      );
+
+      try {
+        const result = await runDecomposedTask(task, {
+          sessionId: context.sessionId,
+          cwd: context.cwd,
+          riskLevel: args.riskLevel || context.riskLevel,
+        });
+
+        if (result.decomposed) {
+          return {
+            ok: true,
+            status: 200,
+            content: result.result,
+            metadata: {
+              decomposed: true,
+              subtasks: result.plan?.subtasks?.length,
+              levels: result.stats?.levels,
+              strategy: result.plan?.strategy,
+              confidence: result.quality?.confidence,
+              recommendFallback: result.recommendFallback,
+              savedTokens: result.savings?.savedTokens,
+            },
+          };
+        }
+
+        // Not decomposed — signal the caller to solve monolithically.
+        return {
+          ok: true,
+          status: 200,
+          content: JSON.stringify(
+            {
+              decomposed: false,
+              reason: result.reason,
+              guidance: "Solve this task directly without decomposition.",
+            },
+            null,
+            2
+          ),
+          metadata: { decomposed: false, reason: result.reason },
+        };
+      } catch (error) {
+        logger.error({ error: error.message }, "DecomposeTask: error");
+        return {
+          ok: false,
+          status: 500,
+          content: JSON.stringify(
+            { error: "Decomposition error", message: error.message },
+            null,
+            2
+          ),
+        };
+      }
+    },
+    { category: "decompose" }
+  );
+
+  logger.info("DecomposeTask tool registered");
+}
+
+module.exports = { registerDecomposeTool };

package/src/tools/lazy-loader.js

@@ -77,6 +77,11 @@ const TOOL_CATEGORIES = {
     loader: () => require('./agent-task').registerAgentTaskTool,
     priority: 2,
   },
+  decompose: {
+    keywords: ['decompose', 'subtask', 'break down', 'break into', 'split task', 'plan and execute'],
+    loader: () => require('./decompose').registerDecomposeTool,
+    priority: 2,
+  },
   'code-mode': {
     keywords: ['mcp', 'execute', 'server', 'tool', 'code mode'],
     loader: () => require('./code-mode').registerCodeModeTools,
@@ -296,6 +301,9 @@ function loadCategoryForTool(toolName) {
     // TinyFish (web agent)
     'web_agent': 'tinyfish',
     'agent_task': 'agentTask',
+
+    // Task decomposition
+    'decomposetask': 'decompose',
   };
 
   // Direct mapping