lynkr 9.4.6 → 9.6.0

package/README.md

@@ -545,6 +545,28 @@ TOOL_INJECTION_ENABLED=false
 CODE_MODE_ENABLED=true
 ```
 
+Always-on (no config): **smart tool selection** (server mode), **RTK tool-result
+compression** (test/git/grep/lint/build/JSON output), **MCP tool dedup** (drops
+built-in WebSearch/WebFetch when an Exa/Tavily MCP tool is present), and
+**request bypass** (Claude CLI Warmup / title-extraction calls are answered
+locally, never hitting a provider).
+
+Optional **terse-output mode** to cut *output* tokens:
+```bash
+CAVEMAN_ENABLED=true        # off by default — nudges the model to be concise
+CAVEMAN_LEVEL=lite          # lite | full | ultra
+```
+
+### Cost tracking & model pricing
+Per-request cost is computed from a model-pricing registry (LiteLLM → models.dev,
+cached 24h) and recorded in telemetry. Models the registry doesn't know record
+`cost_usd=null` (logged once) rather than a fabricated price. Pin prices for
+unknown models:
+```bash
+# Per-1M-token USD prices, JSON keyed by model name
+MODEL_PRICE_OVERRIDES={"my-model":{"input":0.5,"output":1.5}}
+```
+
 ### Memory System (Titans-inspired)
 ```bash
 MEMORY_ENABLED=true
@@ -609,11 +631,13 @@ npm install -g lynkr
 curl -fsSL https://raw.githubusercontent.com/Fast-Editor/Lynkr/main/install.sh | bash
 ```
 
-**Homebrew**
+**Homebrew** (macOS / Linux)
 ```bash
 brew tap fast-editor/lynkr
 brew install lynkr
+lynkr --version
 ```
+Upgrade later with `brew update && brew upgrade lynkr`. The formula tracks the latest [`lynkr` npm release](https://www.npmjs.com/package/lynkr) automatically.
 
 **Docker**
 ```bash
@@ -652,35 +676,45 @@ npm start
 
 ## Benchmark Results
 
-Measured on real agentic coding workloads (Claude Code / Cursor sessions) with Ollama, Moonshot, and Azure OpenAI backends. Run with `node benchmark-tier-routing.js`.
+Head-to-head against **LiteLLM** on the **same backends** (Ollama `minimax-m2.5`, Moonshot, Azure OpenAI), 9 scenarios across 4 feature categories. Apples-to-apples comparison is Lynkr vs LiteLLM **billed tokens on the same scenario**. Run with `node benchmark-tier-routing.js`.
 
-### Token compression
+> _Run: June 5, 2026 · Lynkr v9.3.2 · LiteLLM v1.87.1 · macOS, Apple Silicon._
 
-| Scenario | Tokens without Lynkr | Tokens with Lynkr | Reduction |
+### Token reduction (vs LiteLLM, same model & prompt)
+
+| Mechanism | Lynkr | LiteLLM | Result |
 |---|---|---|---|
-| 14-tool request (read task) | 1,042 | **547** | **47%** |
-| 14-tool request (write task) | 1,043 | **412** | **60%** |
-| Large JSON grep result (60 items) | 3,458 | **427** | **87.6%** |
+| Smart tool selection (14 tools) | **959** tokens · $0.0044 | 2,085 tokens · $0.0091 | **53% fewer tokens, 52% cheaper** |
+| TOON compression (60-item grep JSON) | **427** tokens · $0.009 | 3,458 tokens · $0.018 | **87.6% fewer tokens, 50% cheaper** |
 
-Lynkr strips irrelevant tool schemas before forwarding (smart tool selection) and binary-compresses large JSON tool results (TOON) — both happen in-process with no added latency.
+Lynkr strips irrelevant tool schemas (smart tool selection) and binary-compresses large JSON tool results (TOON) — both in-process, no added latency.
 
 ### Semantic cache
 
 | | Tokens billed | Response time |
 |---|---|---|
 | First call (cold) | 2,857 | 1,891ms |
-| **Second call — paraphrased, cache hit** | **0** | **171ms** |
+| **Second call — paraphrased, cache hit** | **0** (served from cache) | **171ms (11× faster)** |
 
-Near-identical prompts return cached responses in 171ms. Zero tokens billed on a cache hit.
+Near-identical prompts return cached responses in 171ms. Zero model tokens billed on a cache hit.
 
 ### Tier routing
 
-| Request | Routed to |
-|---|---|
-| "What does git stash do?" | SIMPLE → local model (free) |
-| JWT vs cookies security analysis | COMPLEX → cloud model (correct) |
+| Request | Lynkr routes to | LiteLLM routes to |
+|---|---|---|
+| "What does git stash do?" | `minimax-m2.5` (local, free) | Ollama (local) |
+| JWT vs cookies security analysis | `moonshot` (cloud — correct) | **Ollama (local — wrong call)** |
+
+Lynkr scores each request on 15 dimensions (token count, code complexity, reasoning markers, risk signals, agentic patterns) and escalates automatically. LiteLLM's `cost-based-routing` sends everything to the cheapest model regardless of complexity.
+
+### Cost projection (100,000 requests/month, same backend)
+
+| | Monthly cost | vs LiteLLM |
+|---|---|---|
+| LiteLLM | ~$818 | baseline |
+| **Lynkr** | **~$409** | **~50% cheaper** |
 
-Lynkr scores each request on 15 dimensions (token count, code complexity, reasoning markers, risk signals, agentic patterns) and routes automatically. No caller changes needed.
+_Based on a tool-heavy agentic session (TOON scenario). On equal footing — same provider, same model — Lynkr is cheaper due to token optimization._
 
 → [Full benchmark report with methodology](BENCHMARK_REPORT.md)
 

package/install.sh

@@ -108,8 +108,24 @@ clone_or_update() {
 install_dependencies() {
     print_info "Installing dependencies..."
     cd "$INSTALL_DIR"
-    npm install --production
+    # --omit=dev keeps optionalDependencies (better-sqlite3, hnswlib-node,
+    # tree-sitter) which back telemetry, the memory store and routing ML.
+    # The postinstall hook (scripts/check-native.js) verifies the native ABI
+    # and rebuilds if Node was upgraded — best-effort, never fails the install.
+    npm install --omit=dev
     print_success "Dependencies installed"
+
+    # Native optional modules need a C/C++ toolchain only if no prebuilt binary
+    # is available for this platform. They degrade gracefully if absent.
+    if ! node -e "const D=require('better-sqlite3'); new D(':memory:').close()" >/dev/null 2>&1; then
+        print_warning "Native module 'better-sqlite3' is not loadable."
+        echo "     Telemetry, the memory store and sessions need it. To enable:"
+        echo "       - Ensure a build toolchain is present (Xcode CLT on macOS, build-essential + python3 on Linux), then:"
+        echo "       - ${BLUE}cd $INSTALL_DIR && npm run rebuild-native${NC}"
+        echo "     Lynkr still runs without it (those features stay disabled)."
+    else
+        print_success "Native modules OK (telemetry, memory, sessions enabled)"
+    fi
 }
 
 # Create default .env file
@@ -131,7 +147,7 @@ create_env_file() {
 MODEL_PROVIDER=ollama
 
 # Server Configuration
-PORT=8080
+PORT=8081
 
 # Ollama Configuration (default for local development)
 OLLAMA_MODEL=qwen2.5-coder:7b
@@ -161,7 +177,7 @@ EOF
         print_info "📝 Configuration ready! Key settings:"
         echo "     • Default provider: Ollama (local, offline)"
         echo "     • Memory system: Enabled (learns from conversations)"
-        echo "     • Port: 8080"
+        echo "     • Port: 8081"
         echo ""
         print_warning "To use cloud providers (Databricks/OpenAI/Azure):"
         echo "     Edit: ${BLUE}nano $INSTALL_DIR/.env${NC}"
@@ -220,7 +236,7 @@ print_next_steps() {
     echo "     ${BLUE}lynkr${NC}"
     echo ""
     echo "  3. Configure Claude Code CLI:"
-    echo "     ${BLUE}export ANTHROPIC_BASE_URL=http://localhost:8080${NC}"
+    echo "     ${BLUE}export ANTHROPIC_BASE_URL=http://localhost:8081${NC}"
     echo "     ${BLUE}claude${NC}"
     echo ""
     echo "  ${YELLOW}Option B: Use Cloud Providers (Databricks/OpenAI/Azure)${NC}"
@@ -238,7 +254,7 @@ print_next_steps() {
     echo "     ${BLUE}lynkr${NC}"
     echo ""
     echo "  3. Configure Claude Code CLI:"
-    echo "     ${BLUE}export ANTHROPIC_BASE_URL=http://localhost:8080${NC}"
+    echo "     ${BLUE}export ANTHROPIC_BASE_URL=http://localhost:8081${NC}"
     echo "     ${BLUE}export ANTHROPIC_API_KEY=any-non-empty-value${NC}  ${GREEN}← Placeholder${NC}"
     echo "     ${BLUE}claude${NC}"
     echo ""

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lynkr",
-  "version": "9.4.6",
+  "version": "9.6.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": {
@@ -8,13 +8,15 @@
     "lynkr-setup": "scripts/setup.js"
   },
   "scripts": {
+    "postinstall": "node scripts/check-native.js",
+    "rebuild-native": "node scripts/check-native.js",
     "prestart": "node -e \"if(process.env.HEADROOM_ENABLED==='true'&&process.env.HEADROOM_DOCKER_ENABLED!=='false'){process.exit(0)}else{process.exit(1)}\" && docker compose --profile headroom up -d --build headroom 2>/dev/null || echo 'Headroom skipped (disabled or Docker not running)'",
     "start": "node index.js 2>&1 | npx pino-pretty --sync",
     "stop": "node -e \"if(process.env.HEADROOM_ENABLED==='true'&&process.env.HEADROOM_DOCKER_ENABLED!=='false'){process.exit(0)}else{process.exit(1)}\" && docker compose --profile headroom down || echo 'Headroom skipped (disabled or Docker not running)'",
     "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: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/task-decomposition.test.js test/output-format-guard.test.js test/tier-fallback.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",

package/public/dashboard.html

@@ -244,6 +244,7 @@ const App = {
     const t = d.today;
     const s = d.stats;
 
+    const tierLabel = t => t === 'default' ? 'default' : String(t).toLowerCase();
     const providerCards = d.providers.length === 0
       ? `<p class="text-slate-500 text-sm">No providers configured</p>`
       : d.providers.map(p => `
@@ -251,10 +252,21 @@ const App = {
           <div class="flex items-center gap-2">
             <span class="status-dot ${providerDot(p.type)}"></span>
             <span class="text-sm font-medium text-slate-200">${p.name}</span>
+            ${(p.tiers || []).map(t => `<span class="badge bg-slate-600/60 text-slate-300">${tierLabel(t)}</span>`).join('')}
           </div>
           <span class="text-xs ${p.type === 'local' ? 'text-green-400' : 'text-blue-400'}">${p.type}</span>
         </div>`).join('');
 
+    const providerWarnings = (d.providerWarnings || []).map(w => `
+        <div class="flex items-center justify-between bg-amber-500/10 border border-amber-500/30 rounded-lg px-4 py-3">
+          <div class="flex items-center gap-2">
+            <span class="text-amber-400 text-sm">⚠</span>
+            <span class="text-sm font-medium text-amber-200">${w.name}</span>
+            ${(w.tiers || []).map(t => `<span class="badge bg-amber-500/20 text-amber-300">${tierLabel(t)}</span>`).join('')}
+          </div>
+          <span class="text-xs text-amber-400">no credentials</span>
+        </div>`).join('');
+
     const recentRows = (d.recentRequests || []).map(r => `
       <tr class="table-row border-b border-slate-700/50">
         <td class="py-2 px-3 text-xs text-slate-500">${fmt.ago(r.timestamp)}</td>
@@ -279,7 +291,7 @@ const App = {
         <!-- Providers -->
         ${card(`
           <h3 class="text-sm font-semibold text-slate-300 mb-3">Configured Providers</h3>
-          <div class="flex flex-col gap-2">${providerCards}</div>
+          <div class="flex flex-col gap-2">${providerCards}${providerWarnings}</div>
         `)}
 
         <!-- 24h Stats -->

package/scripts/check-native.js

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+/**
+ * Native module ABI guard (postinstall).
+ *
+ * better-sqlite3 (and the other native optionalDependencies) are compiled
+ * against a specific Node ABI. When Node is upgraded, the prebuilt/compiled
+ * binary stops loading with:
+ *
+ *   "was compiled against a different Node.js version using
+ *    NODE_MODULE_VERSION 115. This version of Node.js requires
+ *    NODE_MODULE_VERSION 141."
+ *
+ * The failure is silent at runtime — telemetry, request logs, and the memory
+ * store all sit behind try/catch and simply go empty. This probe detects the
+ * mismatch and rebuilds the native modules so it self-heals on `npm install`.
+ *
+ * It is intentionally best-effort: it NEVER exits non-zero, so it can't break
+ * `npm install` on machines without a build toolchain (the modules are
+ * optional and the app degrades gracefully without them).
+ */
+
+const { execSync } = require("child_process");
+
+// Native optionalDependencies that are ABI-sensitive. If Node changed, all of
+// them are stale, so we rebuild the set in one pass.
+const NATIVE_DEPS = [
+  "better-sqlite3",
+  "hnswlib-node",
+  "tree-sitter",
+  "tree-sitter-javascript",
+  "tree-sitter-python",
+  "tree-sitter-typescript",
+];
+
+function log(msg) {
+  console.log(`[check-native] ${msg}`);
+}
+
+/**
+ * Probe better-sqlite3 — the canary. `require()` alone is not enough: the
+ * native addon only loads when a Database is instantiated.
+ * @returns {"ok"|"absent"|"mismatch"}
+ */
+function probe() {
+  let Database;
+  try {
+    Database = require("better-sqlite3");
+  } catch (err) {
+    if (err && err.code === "MODULE_NOT_FOUND") return "absent";
+    return "mismatch";
+  }
+  try {
+    const db = new Database(":memory:");
+    db.close();
+    return "ok";
+  } catch (err) {
+    if (/NODE_MODULE_VERSION|different Node\.js version|invalid ELF|dlopen|\.node/i.test(err.message || "")) {
+      return "mismatch";
+    }
+    // Some other instantiation error — not an ABI issue we can fix by rebuild.
+    return "ok";
+  }
+}
+
+function main() {
+  const status = probe();
+
+  if (status === "absent") {
+    // Optional dependency not installed (e.g. build skipped). Nothing to do.
+    return;
+  }
+  if (status === "ok") {
+    return;
+  }
+
+  log("native module ABI mismatch detected (Node was likely upgraded). Rebuilding native modules…");
+  try {
+    execSync(`npm rebuild ${NATIVE_DEPS.join(" ")}`, { stdio: "inherit" });
+  } catch {
+    log("rebuild did not complete (a build toolchain may be missing). Continuing — native features will be disabled until you run: npm rebuild better-sqlite3");
+    return;
+  }
+
+  // Re-probe to report the outcome.
+  if (probe() === "ok") {
+    log("native modules rebuilt successfully.");
+  } else {
+    log("native modules still not loadable after rebuild. Run `npm rebuild better-sqlite3` manually.");
+  }
+}
+
+try {
+  main();
+} catch (err) {
+  // Never fail the install.
+  log(`skipped (${err.message})`);
+}

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