lynkr 9.5.0 → 9.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lynkr",
-  "version": "9.5.0",
+  "version": "9.7.0",
   "description": "Self-hosted LLM gateway and tier-routing proxy for Claude Code, Cursor, and Codex. Routes across Ollama, AWS Bedrock, OpenRouter, Databricks, Azure OpenAI, llama.cpp, and LM Studio with prompt caching, MCP tools, and 60-80% cost savings.",
   "main": "index.js",
   "bin": {
@@ -16,7 +16,7 @@
     "dev": "nodemon index.js",
     "lint": "eslint src index.js",
     "test": "npm run test:unit && npm run test:performance",
-    "test:unit": "DATABRICKS_API_KEY=test-key DATABRICKS_API_BASE=http://test.com node --test test/routing.test.js test/hybrid-routing-integration.test.js test/web-tools.test.js test/passthrough-mode.test.js test/openrouter-error-resilience.test.js test/format-conversion.test.js test/azure-openai-config.test.js test/azure-openai-format-conversion.test.js test/azure-openai-routing.test.js test/azure-openai-streaming.test.js test/azure-openai-error-resilience.test.js test/azure-openai-integration.test.js test/openai-integration.test.js test/toon-compression.test.js test/llamacpp-integration.test.js test/resilience.test.js test/telemetry-routing.test.js test/memory/store.test.js test/memory/surprise.test.js test/memory/extractor.test.js test/memory/search.test.js test/memory/retriever.test.js test/distill.test.js test/large-payload.test.js test/code-mode.test.js test/prompt-cache-injection.test.js test/risk-analyzer.test.js test/interaction-block.test.js test/preflight.test.js test/token-reduction.test.js test/session-affinity.test.js test/model-registry-cost.test.js",
+    "test:unit": "DATABRICKS_API_KEY=test-key DATABRICKS_API_BASE=http://test.com node --test test/routing.test.js test/hybrid-routing-integration.test.js test/passthrough-mode.test.js test/openrouter-error-resilience.test.js test/format-conversion.test.js test/azure-openai-config.test.js test/azure-openai-format-conversion.test.js test/azure-openai-routing.test.js test/azure-openai-streaming.test.js test/azure-openai-error-resilience.test.js test/azure-openai-integration.test.js test/openai-integration.test.js test/toon-compression.test.js test/llamacpp-integration.test.js test/resilience.test.js test/telemetry-routing.test.js test/memory/store.test.js test/memory/surprise.test.js test/memory/extractor.test.js test/memory/search.test.js test/memory/retriever.test.js test/distill.test.js test/large-payload.test.js test/code-mode.test.js test/prompt-cache-injection.test.js test/risk-analyzer.test.js test/interaction-block.test.js test/preflight.test.js test/token-reduction.test.js test/session-affinity.test.js test/model-registry-cost.test.js test/task-decomposition.test.js test/output-format-guard.test.js test/tier-fallback.test.js test/wrap.test.js",
     "test:memory": "DATABRICKS_API_KEY=test-key DATABRICKS_API_BASE=http://test.com node --test test/memory/store.test.js test/memory/surprise.test.js test/memory/extractor.test.js test/memory/search.test.js test/memory/retriever.test.js",
     "test:new-features": "DATABRICKS_API_KEY=test-key DATABRICKS_API_BASE=http://test.com node --test test/passthrough-mode.test.js test/openrouter-error-resilience.test.js test/format-conversion.test.js",
     "test:performance": "DATABRICKS_API_KEY=test-key DATABRICKS_API_BASE=http://test.com node test/hybrid-routing-performance.test.js && DATABRICKS_API_KEY=test-key DATABRICKS_API_BASE=http://test.com node test/performance-tests.js",
@@ -79,6 +79,7 @@
     "express": "^5.1.0",
     "express-rate-limit": "^8.2.1",
     "fast-glob": "^3.3.2",
+    "graphify": "^1.0.0",
     "hnswlib-node": "^3.0.0",
     "js-tiktoken": "^1.0.20",
     "js-yaml": "^4.1.1",
@@ -89,7 +90,7 @@
     "undici": "^6.22.0"
   },
   "optionalDependencies": {
-    "better-sqlite3": "^12.6.2",
+    "better-sqlite3": "^12.11.1",
     "dockerode": "^4.0.2",
     "tree-sitter": "^0.21.1",
     "tree-sitter-javascript": "^0.21.0",

package/scripts/build-knn-index.js

@@ -51,7 +51,7 @@ async function _readTelemetry(days) {
     return db
       .prepare(
         `SELECT request_text AS query, provider, model, quality_score AS quality,
-                cost, total_latency_ms AS latency, tier
+                cost_usd AS cost, latency_ms AS latency, tier
            FROM routing_telemetry
           WHERE timestamp >= ?
             AND quality_score IS NOT NULL

package/scripts/convert-routellm.py

@@ -0,0 +1,105 @@
+#!/usr/bin/env python3
+"""
+Convert routellm/gpt4_dataset (train.jsonl) → Lynkr kNN bootstrap JSONL.
+
+Stream-downloads from HuggingFace and maps mixtral_score (1-5) to your
+TIER_* model config so the kNN index learns to recommend YOUR real models,
+not RouteLLM's pool (mixtral / gpt-4).
+
+Output format matches scripts/build-knn-index.js bootstrap input:
+    {"query": "...", "provider": "ollama", "model": "minimax-m2.5:cloud",
+     "quality": 95, "cost": 0.001, "latency": 200, "tier": "SIMPLE"}
+
+Usage:
+    .venv/bin/python scripts/convert-routellm.py [--limit 30000] -o routellm.jsonl
+"""
+import argparse
+import json
+import sys
+import urllib.request
+import ssl
+
+# Map mixtral_score → user's tier config.
+# Spread is intentionally aggressive: only score=5 (Mixtral truly nailed it)
+# stays SIMPLE; score=4 escalates to MEDIUM so the kNN index has enough MEDIUM
+# examples to actually recommend non-SIMPLE tiers (vs the previous mapping
+# where 86% of records were SIMPLE and kNN never disagreed with the heuristic).
+SCORE_TO_ROUTE = {
+    5: {"tier": "SIMPLE",    "provider": "ollama",          "model": "minimax-m2.5:cloud", "quality": 95, "cost": 0.001, "latency": 200},
+    4: {"tier": "MEDIUM",    "provider": "azure-anthropic", "model": "claude-sonnet-4-6",  "quality": 80, "cost": 0.003, "latency": 1500},
+    3: {"tier": "MEDIUM",    "provider": "azure-anthropic", "model": "claude-sonnet-4-6",  "quality": 70, "cost": 0.003, "latency": 1500},
+    2: {"tier": "COMPLEX",   "provider": "azure-anthropic", "model": "claude-sonnet-4-6",  "quality": 55, "cost": 0.003, "latency": 1500},
+    1: {"tier": "REASONING", "provider": "azure-anthropic", "model": "claude-opus-4-8",    "quality": 40, "cost": 0.015, "latency": 3500},
+}
+
+URL = "https://huggingface.co/datasets/routellm/gpt4_dataset/resolve/main/train.jsonl"
+
+
+def main():
+    p = argparse.ArgumentParser()
+    p.add_argument("--output", "-o", default="data/routellm-bootstrap.jsonl")
+    p.add_argument("--limit", type=int, default=None,
+                   help="Only convert first N rows")
+    args = p.parse_args()
+
+    print(f"Streaming {URL} …", file=sys.stderr)
+    # Some macOS Python builds have SSL issues with huggingface.co — fall back
+    # to unverified context if needed. The data is public, no auth.
+    ctx = ssl.create_default_context()
+    try:
+        with urllib.request.urlopen(URL, context=ctx, timeout=60) as resp:
+            _stream(resp, args.output, args.limit)
+    except (ssl.SSLError, OSError) as e:
+        print(f"SSL strict failed ({e}); retrying with unverified context", file=sys.stderr)
+        ctx = ssl._create_unverified_context()
+        with urllib.request.urlopen(URL, context=ctx, timeout=60) as resp:
+            _stream(resp, args.output, args.limit)
+
+
+def _stream(resp, out_path, limit):
+    written = 0
+    by_score = {s: 0 for s in SCORE_TO_ROUTE}
+    skipped = 0
+    with open(out_path, "w") as out:
+        for line in resp:
+            if limit and written >= limit:
+                break
+            try:
+                row = json.loads(line)
+            except Exception:
+                skipped += 1
+                continue
+            score = row.get("mixtral_score")
+            if score not in SCORE_TO_ROUTE:
+                skipped += 1
+                continue
+            route = SCORE_TO_ROUTE[score]
+            rec = {
+                "query": row.get("prompt", ""),
+                "provider": route["provider"],
+                "model": route["model"],
+                "quality": route["quality"],
+                "cost": route["cost"],
+                "latency": route["latency"],
+                "tier": route["tier"],
+            }
+            if not rec["query"]:
+                skipped += 1
+                continue
+            out.write(json.dumps(rec) + "\n")
+            written += 1
+            by_score[score] += 1
+            if written % 5000 == 0:
+                print(f"  {written} written…", file=sys.stderr)
+
+    print(f"\nWrote {written} records to {out_path} ({skipped} skipped)", file=sys.stderr)
+    print(f"By mixtral_score: {by_score}", file=sys.stderr)
+    print(f"\nTier distribution:", file=sys.stderr)
+    for score, route in SCORE_TO_ROUTE.items():
+        n = by_score[score]
+        if n:
+            print(f"  {route['tier']:>10}  {route['provider']}:{route['model']:30s}  n={n}", file=sys.stderr)
+
+
+if __name__ == "__main__":
+    main()

package/src/agents/decomposition/dispatcher.js

@@ -0,0 +1,185 @@
+/**
+ * Subtask dispatcher (Phase 3).
+ *
+ * Executes a validated plan respecting its dependency DAG:
+ *   - subtasks are grouped into topological "levels" (Kahn's algorithm)
+ *   - subtasks in the same level have no dependency on each other → run in
+ *     parallel via the existing ParallelCoordinator (spawnParallel)
+ *   - a subtask receives ONLY its own prompt plus the compressed results of the
+ *     subtasks it depends on (context isolation — the token win)
+ *
+ * The spawn functions are injectable for testing.
+ */
+
+const logger = require("../../logger");
+
+// Cap how much of a dependency's result we forward, to preserve the
+// context-isolation savings (subagents already return summaries; this bounds
+// pathological cases).
+const MAX_CONTEXT_CHARS = 2000;
+
+/**
+ * Group subtasks into dependency levels. Returns array of arrays of ids.
+ * Throws if the graph is unresolvable (should not happen — planner validated).
+ */
+function topologicalLevels(subtasks) {
+  const byId = new Map(subtasks.map((s) => [s.id, s]));
+  const indegree = new Map(subtasks.map((s) => [s.id, 0]));
+  const dependents = new Map(subtasks.map((s) => [s.id, []]));
+
+  for (const s of subtasks) {
+    for (const dep of s.dependsOn) {
+      if (!byId.has(dep)) continue;
+      indegree.set(s.id, indegree.get(s.id) + 1);
+      dependents.get(dep).push(s.id);
+    }
+  }
+
+  const levels = [];
+  let frontier = subtasks.filter((s) => indegree.get(s.id) === 0).map((s) => s.id);
+  const resolved = new Set();
+
+  while (frontier.length > 0) {
+    levels.push(frontier);
+    const next = [];
+    for (const id of frontier) {
+      resolved.add(id);
+      for (const child of dependents.get(id)) {
+        indegree.set(child, indegree.get(child) - 1);
+        if (indegree.get(child) === 0) next.push(child);
+      }
+    }
+    frontier = next;
+  }
+
+  if (resolved.size !== subtasks.length) {
+    throw new Error("Unresolvable subtask graph (cycle or dangling dependency)");
+  }
+  return levels;
+}
+
+function compressResult(text) {
+  if (typeof text !== "string") return String(text ?? "");
+  if (text.length <= MAX_CONTEXT_CHARS) return text;
+  return text.slice(0, MAX_CONTEXT_CHARS) + "\n…[truncated]";
+}
+
+function buildContextForSubtask(subtask, resultsById) {
+  if (!subtask.dependsOn || subtask.dependsOn.length === 0) return null;
+  const parts = [];
+  for (const dep of subtask.dependsOn) {
+    const r = resultsById.get(dep);
+    if (r && r.success && r.result) {
+      parts.push(`Result of subtask ${dep}:\n${compressResult(r.result)}`);
+    } else if (r) {
+      parts.push(`Subtask ${dep} did not complete successfully.`);
+    }
+  }
+  return parts.length > 0 ? parts.join("\n\n") : null;
+}
+
+/**
+ * Dispatch a validated plan.
+ * @param {Object} plan - { subtasks: [...] }
+ * @param {Object} [options]
+ * @param {string} [options.sessionId]
+ * @param {string} [options.cwd]
+ * @param {Function} [options.spawnParallel] - (agentTypes[], prompts[], opts) => results[]
+ * @returns {Promise<{results: Array, levels: Array, stats: Object}>}
+ */
+async function dispatchPlan(plan, options = {}) {
+  const spawnParallel = options.spawnParallel || require("../index").spawnParallel;
+  const subtasks = plan.subtasks;
+  const byId = new Map(subtasks.map((s) => [s.id, s]));
+  const levels = topologicalLevels(subtasks);
+  const resultsById = new Map();
+
+  let totalInputTokens = 0;
+  let totalOutputTokens = 0;
+  let totalSubagents = 0;
+
+  for (let li = 0; li < levels.length; li++) {
+    const levelIds = levels[li];
+    const levelSubtasks = levelIds.map((id) => byId.get(id));
+
+    const agentTypes = levelSubtasks.map((s) => s.agentType);
+    const prompts = levelSubtasks.map((s) => s.prompt);
+    const perTaskContext = levelSubtasks.map((s) => buildContextForSubtask(s, resultsById));
+
+    logger.info(
+      { level: li, count: levelIds.length, ids: levelIds },
+      "[Decomposition] Dispatching subtask level"
+    );
+
+    // spawnParallel shares one options object; pass per-task context by spawning
+    // the level as individual parallel calls when contexts differ.
+    const levelResults = await runLevel(
+      spawnParallel,
+      agentTypes,
+      prompts,
+      perTaskContext,
+      options
+    );
+
+    levelResults.forEach((res, idx) => {
+      const st = levelSubtasks[idx];
+      totalSubagents += 1;
+      totalInputTokens += res?.stats?.inputTokens || 0;
+      totalOutputTokens += res?.stats?.outputTokens || 0;
+      resultsById.set(st.id, {
+        id: st.id,
+        agentType: st.agentType,
+        success: !!res?.success,
+        result: res?.success ? res.result : null,
+        error: res?.success ? null : res?.error || "unknown error",
+        stats: res?.stats || {},
+      });
+    });
+  }
+
+  const results = subtasks.map((s) => resultsById.get(s.id));
+  return {
+    results,
+    levels,
+    stats: {
+      subagents: totalSubagents,
+      inputTokens: totalInputTokens,
+      outputTokens: totalOutputTokens,
+    },
+  };
+}
+
+/**
+ * Run one level. When subtasks in the level have differing injected contexts we
+ * spawn them as separate parallel calls (each with its own mainContext), then
+ * await all. When none need context, a single spawnParallel batch is used.
+ */
+async function runLevel(spawnParallel, agentTypes, prompts, perTaskContext, options) {
+  const anyContext = perTaskContext.some((c) => c);
+
+  if (!anyContext) {
+    return spawnParallel(agentTypes, prompts, {
+      sessionId: options.sessionId,
+      cwd: options.cwd,
+    });
+  }
+
+  // Mixed/with-context: one spawnParallel call per subtask so each gets its own
+  // mainContext, executed concurrently.
+  const calls = agentTypes.map((type, i) =>
+    spawnParallel([type], [prompts[i]], {
+      sessionId: options.sessionId,
+      cwd: options.cwd,
+      mainContext: perTaskContext[i] ? { relevant_context: perTaskContext[i] } : undefined,
+    }).then((arr) => arr[0])
+  );
+  return Promise.all(calls);
+}
+
+module.exports = {
+  dispatchPlan,
+  topologicalLevels,
+  buildContextForSubtask,
+  compressResult,
+  MAX_CONTEXT_CHARS,
+};

package/src/agents/decomposition/gate.js

@@ -0,0 +1,136 @@
+/**
+ * Decomposition gate (Phase 1).
+ *
+ * Decides whether breaking a task into isolated-context subtasks is actually
+ * worth it. This is the make-or-break of the feature: naive "decompose
+ * everything" loses money, because every subagent carries fixed overhead
+ * (planning + per-agent handoff/summarisation). Decomposition only pays off
+ * when the task is (a) genuinely complex, (b) large enough to amortise that
+ * overhead, and (c) divisible into reasonably independent units.
+ *
+ * Pure and synchronous so it can be unit-tested without a model. The caller
+ * supplies a pre-computed complexity `analysis` (from routing/complexity-analyzer)
+ * and the raw payload.
+ */
+
+const DEFAULTS = {
+  minComplexity: 60, // 0-100; only decompose genuinely complex work
+  minTokens: 3000, // estimated monolithic tokens; below this the overhead wins
+  minIndependentUnits: 2, // need at least 2 separable pieces to bother
+  maxSubtasks: 6,
+};
+
+const ENUMERATION_RE = /^\s*(?:[-*+]|\d+[.)]|step\s+\d+\b)/gim;
+const CONJUNCTION_RE = /\b(?:and then|then|also|additionally|as well as|after that|finally|next,)\b/gi;
+const IMPERATIVE_RE = /\b(?:add|create|build|implement|write|refactor|update|fix|remove|delete|migrate|test|document|configure|set up|wire|integrate|generate)\b/gi;
+const FILE_PATH_RE = /\b[\w./-]+\.(?:js|ts|tsx|jsx|py|go|rs|java|rb|c|cpp|h|json|yaml|yml|md|sql|sh|css|html)\b/gi;
+
+function _uniqueMatches(text, re) {
+  const set = new Set();
+  const matches = text.match(re) || [];
+  for (const m of matches) set.add(m.toLowerCase().trim());
+  return set;
+}
+
+/**
+ * Heuristically estimate how many independent units a task contains.
+ * Conservative: takes the strongest of several weak signals rather than summing
+ * them, so a single rambling sentence doesn't look like five subtasks.
+ * @param {string} text
+ * @returns {number}
+ */
+function estimateIndependentUnits(text) {
+  if (!text || typeof text !== "string") return 1;
+
+  const enumerated = (text.match(ENUMERATION_RE) || []).length;
+  const conjunctions = (text.match(CONJUNCTION_RE) || []).length;
+  const imperatives = _uniqueMatches(text, IMPERATIVE_RE).size;
+  const files = _uniqueMatches(text, FILE_PATH_RE).size;
+
+  // Each signal is an independent lower-bound estimate of separable units.
+  const signals = [
+    enumerated, // explicit list items
+    conjunctions + 1, // "do A and then B" → 2 units
+    imperatives, // distinct action verbs
+    files, // distinct files usually map to distinct work
+  ];
+
+  const estimate = Math.max(...signals, 1);
+  return estimate;
+}
+
+/**
+ * Decide whether to decompose.
+ * @param {Object} analysis - result of analyzeComplexity(payload)
+ * @param {Object} payload - the request payload
+ * @param {Object} [options]
+ * @param {Object} [options.config] - threshold overrides (see DEFAULTS)
+ * @param {string} [options.riskLevel] - 'low'|'medium'|'high'; 'high' disables decomposition
+ * @param {string} [options.taskText] - explicit task text (else derived from analysis/payload)
+ * @returns {{ decompose: boolean, reason: string, signals: Object }}
+ */
+function shouldDecompose(analysis, payload = {}, options = {}) {
+  const cfg = { ...DEFAULTS, ...(options.config || {}) };
+
+  const score = Number(analysis?.score ?? 0);
+  const estimatedTokens = Number(
+    analysis?.breakdown?.tokens?.estimated ?? options.estimatedTokens ?? 0
+  );
+
+  const taskText =
+    options.taskText ||
+    analysis?.content ||
+    _firstUserText(payload) ||
+    "";
+
+  const independentUnits = estimateIndependentUnits(taskText);
+
+  const signals = {
+    score,
+    estimatedTokens,
+    independentUnits,
+    riskLevel: options.riskLevel || "low",
+    thresholds: cfg,
+  };
+
+  // Never decompose high-risk work — keep it in one capable context where the
+  // exempt-from-laziness concerns (validation/security) stay coherent.
+  if (options.riskLevel === "high") {
+    return { decompose: false, reason: "high_risk_skip", signals };
+  }
+
+  if (score < cfg.minComplexity) {
+    return { decompose: false, reason: "below_complexity_threshold", signals };
+  }
+
+  if (estimatedTokens < cfg.minTokens) {
+    return { decompose: false, reason: "too_small_to_amortise_overhead", signals };
+  }
+
+  if (independentUnits < cfg.minIndependentUnits) {
+    return { decompose: false, reason: "not_divisible", signals };
+  }
+
+  return { decompose: true, reason: "decompose_worthwhile", signals };
+}
+
+function _firstUserText(payload) {
+  const messages = payload?.messages;
+  if (!Array.isArray(messages)) return "";
+  const user = [...messages].reverse().find((m) => m.role === "user");
+  if (!user) return "";
+  if (typeof user.content === "string") return user.content;
+  if (Array.isArray(user.content)) {
+    return user.content
+      .filter((b) => b?.type === "text" || typeof b?.text === "string")
+      .map((b) => b.text || "")
+      .join("\n");
+  }
+  return "";
+}
+
+module.exports = {
+  shouldDecompose,
+  estimateIndependentUnits,
+  DEFAULTS,
+};

package/src/agents/decomposition/index.js

@@ -0,0 +1,183 @@
+/**
+ * Task decomposition — orchestration entry point.
+ *
+ * Ties the phases together:
+ *   1. gate        — decide if decomposing is worth it (cost-aware)
+ *   2. planner     — produce a validated subtask DAG (one model call)
+ *   3. dispatcher  — run subtasks (parallel within dependency levels, isolated context)
+ *   4. synthesizer — combine results into the final answer (one model call)
+ *   5. quality     — confidence-score the synthesis; flag low-confidence output
+ *   6. telemetry   — record decision + estimated net token savings; shadow mode
+ *
+ * Opt-in via TASK_DECOMPOSITION_ENABLED=true. Requires AGENTS_ENABLED=true
+ * (it builds on the subagent machinery). Any failure degrades gracefully to a
+ * non-decomposed result so the caller can solve monolithically.
+ */
+
+const config = require("../../config");
+const logger = require("../../logger");
+const { shouldDecompose } = require("./gate");
+const { generatePlan } = require("./planner");
+const { dispatchPlan } = require("./dispatcher");
+const { synthesize } = require("./synthesizer");
+const telemetry = require("./telemetry");
+const { analyzeComplexity } = require("../../routing/complexity-analyzer");
+const confidenceScorer = require("../../routing/confidence-scorer");
+
+const CODE_HINT_RE = /\b(code|function|implement|refactor|bug|class|api|module|test)\b/i;
+
+function getConfig() {
+  return (
+    config.taskDecomposition || {
+      enabled: false,
+      shadow: false,
+      planModel: "sonnet",
+      synthModel: "sonnet",
+      minConfidence: 0.5,
+      gate: {},
+    }
+  );
+}
+
+/**
+ * @param {string} task - the task text to (maybe) decompose
+ * @param {Object} [options]
+ * @param {string} [options.sessionId]
+ * @param {string} [options.cwd]
+ * @param {string} [options.riskLevel] - 'high' disables decomposition
+ * @param {Object} [options._inject] - test seams { generatePlan, dispatchPlan, synthesize, analyze }
+ * @returns {Promise<Object>} result object (see below)
+ */
+async function runDecomposedTask(task, options = {}) {
+  const cfg = getConfig();
+  const inject = options._inject || {};
+
+  if (!cfg.enabled) {
+    return { decomposed: false, reason: "disabled" };
+  }
+  if (!config.agents?.enabled) {
+    return { decomposed: false, reason: "agents_disabled" };
+  }
+  if (!task || typeof task !== "string") {
+    return { decomposed: false, reason: "empty_task" };
+  }
+
+  const payload = { messages: [{ role: "user", content: task }] };
+
+  let analysis;
+  try {
+    analysis = await (inject.analyze || analyzeComplexity)(payload);
+  } catch (err) {
+    logger.warn({ err: err.message }, "[Decomposition] Complexity analysis failed");
+    return { decomposed: false, reason: "analysis_failed" };
+  }
+
+  const monolithicTokens =
+    analysis?.breakdown?.tokens?.estimated || telemetry.estimateTokens(task);
+
+  const gate = shouldDecompose(analysis, payload, {
+    config: cfg.gate,
+    riskLevel: options.riskLevel,
+    taskText: task,
+  });
+
+  // Shadow mode: record what we WOULD do, but never actually decompose.
+  if (cfg.shadow) {
+    telemetry.record({
+      mode: "shadow",
+      sessionId: options.sessionId,
+      gate,
+      monolithicTokens,
+    });
+    return { decomposed: false, reason: "shadow_mode", gate };
+  }
+
+  if (!gate.decompose) {
+    telemetry.record({ mode: "live", decision: "skip", gate, monolithicTokens });
+    return { decomposed: false, reason: gate.reason, gate };
+  }
+
+  // Phase 2: plan
+  const plan = await (inject.generatePlan || generatePlan)({
+    task,
+    model: cfg.planModel,
+    maxSubtasks: cfg.gate?.maxSubtasks || 6,
+  });
+  if (!plan) {
+    telemetry.record({ mode: "live", decision: "plan_failed", gate, monolithicTokens });
+    return { decomposed: false, reason: "plan_failed", gate };
+  }
+
+  // Phase 3: dispatch
+  const dispatch = await (inject.dispatchPlan || dispatchPlan)(plan, {
+    sessionId: options.sessionId,
+    cwd: options.cwd,
+  });
+
+  // Phase 4: synthesize
+  const synth = await (inject.synthesize || synthesize)({
+    task,
+    subtaskResults: dispatch.results,
+    model: cfg.synthModel,
+  });
+
+  // Phase 5: quality gate
+  const taskType = CODE_HINT_RE.test(task) ? "code" : "reasoning";
+  let confidence = 1;
+  try {
+    confidence = await confidenceScorer.score(
+      { content: [{ type: "text", text: synth.text }] },
+      { taskType }
+    );
+  } catch (err) {
+    logger.debug({ err: err.message }, "[Decomposition] Confidence scoring failed");
+  }
+  const belowThreshold = confidence < (cfg.minConfidence ?? 0.5);
+
+  const savings = telemetry.estimateSavings({
+    monolithicTokens,
+    planUsage: plan.usage,
+    dispatchStats: dispatch.stats,
+    synthUsage: synth.usage,
+  });
+
+  telemetry.record({
+    mode: "live",
+    decision: "decomposed",
+    sessionId: options.sessionId,
+    gate,
+    subtasks: plan.subtasks.length,
+    levels: dispatch.levels.length,
+    strategy: plan.strategy,
+    confidence,
+    belowThreshold,
+    synthesisFallback: synth.fallback,
+    savings,
+  });
+
+  logger.info(
+    {
+      subtasks: plan.subtasks.length,
+      levels: dispatch.levels.length,
+      confidence: confidence.toFixed(2),
+      savedTokens: savings.savedTokens,
+    },
+    "[Decomposition] Task decomposed"
+  );
+
+  return {
+    decomposed: true,
+    result: synth.text,
+    reason: "decomposed",
+    plan,
+    subtaskResults: dispatch.results,
+    quality: { confidence, belowThreshold, taskType },
+    // When confidence is low, the caller should prefer a monolithic re-solve.
+    recommendFallback: belowThreshold,
+    stats: { ...dispatch.stats, levels: dispatch.levels.length },
+    savings,
+    gate,
+  };
+}
+
+module.exports = { runDecomposedTask, getConfig };