lynkr 9.9.1 → 9.10.0

package/src/agents/decomposition/gate.js

@@ -1,136 +0,0 @@
-/**
- * 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

@@ -1,183 +0,0 @@
-/**
- * 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 };

package/src/agents/decomposition/model-call.js

@@ -1,75 +0,0 @@
-/**
- * Thin model-call helper for the decomposition planner/synthesizer.
- *
- * Mirrors the provider-forcing logic in agents/executor.js so planning and
- * synthesis use the configured MODEL_PROVIDER rather than hard-falling back to
- * Azure. The actual invoker is injectable (`opts.invoke`) so the planner and
- * synthesizer can be unit-tested without a live provider.
- */
-
-const logger = require("../../logger");
-
-function resolveForceProvider(model) {
-  const modelLower = String(model || "").toLowerCase();
-  const isClaudeFamily =
-    modelLower.includes("claude") ||
-    modelLower.includes("sonnet") ||
-    modelLower.includes("haiku") ||
-    modelLower.includes("opus");
-  const isGptFamily = modelLower.includes("gpt");
-
-  if (isClaudeFamily || isGptFamily) {
-    const config = require("../../config");
-    return config.modelProvider?.type || config.modelProvider?.provider || null;
-  }
-  return null;
-}
-
-/**
- * Call the model and return the Anthropic-format response JSON.
- * @param {Object} params
- * @param {Array} params.messages
- * @param {string} params.model
- * @param {number} [params.maxTokens=2048]
- * @param {number} [params.temperature=0.2]
- * @param {Function} [params.invoke] - injectable invoker (default: clients/databricks.invokeModel)
- * @returns {Promise<Object>} Anthropic-format response JSON
- */
-async function callModel({ messages, model, maxTokens = 2048, temperature = 0.2, invoke } = {}) {
-  const invoker = invoke || require("../../clients/databricks").invokeModel;
-  const payload = {
-    model,
-    messages,
-    max_tokens: maxTokens,
-    temperature,
-  };
-  const forceProvider = resolveForceProvider(model);
-
-  const response = await invoker(payload, { forceProvider });
-  if (!response || !response.json) {
-    throw new Error("Invalid model response in decomposition model-call");
-  }
-  return response.json;
-}
-
-/**
- * Extract concatenated text from an Anthropic-format response.
- */
-function extractText(responseJson) {
-  const content = responseJson?.content;
-  if (!Array.isArray(content)) return "";
-  return content
-    .filter((b) => b?.type === "text")
-    .map((b) => b.text || "")
-    .join("\n")
-    .trim();
-}
-
-function sumUsage(responseJson) {
-  return {
-    inputTokens: responseJson?.usage?.input_tokens || 0,
-    outputTokens: responseJson?.usage?.output_tokens || 0,
-  };
-}
-
-module.exports = { callModel, extractText, sumUsage, resolveForceProvider, logger };

package/src/agents/decomposition/planner.js

@@ -1,223 +0,0 @@
-/**
- * Decomposition planner (Phase 2).
- *
- * Turns a complex task into a small subtask DAG using a single model call
- * (plan-and-solve style — plan generated in one shot). Output is validated:
- * ids unique, dependencies reference real ids, no cycles, subtask count capped.
- * If anything fails to parse/validate the planner returns null and the caller
- * falls back to a monolithic solve.
- */
-
-const { callModel, extractText } = require("./model-call");
-const logger = require("../../logger");
-
-// Agent types the dispatcher knows how to spawn. Planner is steered toward
-// these; unknown types are coerced to general-purpose at dispatch time.
-const KNOWN_AGENT_TYPES = [
-  "Explore",
-  "Plan",
-  "general-purpose",
-  "Test",
-  "Debug",
-  "Fix",
-  "Refactor",
-  "Documentation",
-];
-
-function buildPlannerPrompt(task, maxSubtasks) {
-  return `You are a task-decomposition planner. Break the task below into the SMALLEST set of focused subtasks that can be solved with isolated context. Fewer is better — do NOT over-split. If the task is not genuinely divisible, return a single subtask.
-
-Rules:
-- At most ${maxSubtasks} subtasks.
-- Each subtask must be independently solvable given only its prompt plus the results of the subtasks it depends on.
-- Mark dependencies via "dependsOn" (array of subtask ids). Independent subtasks (empty dependsOn) will run in parallel.
-- Prefer assigning each subtask an agent type from: ${KNOWN_AGENT_TYPES.join(", ")}.
-- Keep each subtask prompt self-contained and specific.
-
-Respond with ONLY a JSON object, no prose, in exactly this shape:
-{
-  "strategy": "one short sentence on how you split it",
-  "subtasks": [
-    { "id": "s1", "agentType": "Explore", "prompt": "...", "dependsOn": [] }
-  ]
-}
-
-TASK:
-${task}`;
-}
-
-/**
- * Extract the first balanced JSON object from a string (handles models that
- * wrap JSON in prose or ```json fences).
- */
-function extractJsonObject(text) {
-  if (!text) return null;
-  const fenced = text.match(/```(?:json)?\s*([\s\S]*?)```/i);
-  const candidate = fenced ? fenced[1] : text;
-
-  const start = candidate.indexOf("{");
-  if (start === -1) return null;
-
-  let depth = 0;
-  let inString = false;
-  let escape = false;
-  for (let i = start; i < candidate.length; i++) {
-    const ch = candidate[i];
-    if (escape) {
-      escape = false;
-      continue;
-    }
-    if (ch === "\\") {
-      escape = true;
-      continue;
-    }
-    if (ch === '"') {
-      inString = !inString;
-      continue;
-    }
-    if (inString) continue;
-    if (ch === "{") depth++;
-    else if (ch === "}") {
-      depth--;
-      if (depth === 0) {
-        const slice = candidate.slice(start, i + 1);
-        try {
-          return JSON.parse(slice);
-        } catch {
-          return null;
-        }
-      }
-    }
-  }
-  return null;
-}
-
-/**
- * Validate and normalise a parsed plan. Returns a clean plan or null.
- */
-function validatePlan(parsed, maxSubtasks) {
-  if (!parsed || !Array.isArray(parsed.subtasks) || parsed.subtasks.length === 0) {
-    return null;
-  }
-
-  const subtasks = [];
-  const seenIds = new Set();
-
-  for (let i = 0; i < parsed.subtasks.length && subtasks.length < maxSubtasks; i++) {
-    const st = parsed.subtasks[i];
-    if (!st || typeof st.prompt !== "string" || st.prompt.trim().length === 0) {
-      return null; // malformed subtask → reject whole plan, fall back
-    }
-    const id = typeof st.id === "string" && st.id.trim() ? st.id.trim() : `s${i + 1}`;
-    if (seenIds.has(id)) return null; // duplicate ids
-    seenIds.add(id);
-
-    const agentType = KNOWN_AGENT_TYPES.includes(st.agentType)
-      ? st.agentType
-      : "general-purpose";
-
-    const dependsOn = Array.isArray(st.dependsOn)
-      ? st.dependsOn.filter((d) => typeof d === "string")
-      : [];
-
-    subtasks.push({ id, agentType, prompt: st.prompt.trim(), dependsOn });
-  }
-
-  // Dependencies must reference real ids and contain no cycles.
-  for (const st of subtasks) {
-    for (const dep of st.dependsOn) {
-      if (!seenIds.has(dep)) return null; // dangling dependency
-    }
-  }
-  if (hasCycle(subtasks)) return null;
-
-  return {
-    strategy: typeof parsed.strategy === "string" ? parsed.strategy : "",
-    subtasks,
-  };
-}
-
-/**
- * Cycle detection via DFS colouring.
- */
-function hasCycle(subtasks) {
-  const byId = new Map(subtasks.map((s) => [s.id, s]));
-  const state = new Map(); // id → 0 unvisited, 1 visiting, 2 done
-
-  function visit(id) {
-    const cur = state.get(id) || 0;
-    if (cur === 1) return true; // back-edge → cycle
-    if (cur === 2) return false;
-    state.set(id, 1);
-    const node = byId.get(id);
-    for (const dep of node?.dependsOn || []) {
-      if (visit(dep)) return true;
-    }
-    state.set(id, 2);
-    return false;
-  }
-
-  for (const s of subtasks) {
-    if (visit(s.id)) return true;
-  }
-  return false;
-}
-
-/**
- * Generate a validated plan for a task.
- * @param {Object} params
- * @param {string} params.task
- * @param {string} [params.model="sonnet"] - planning needs reasoning; use a capable model
- * @param {number} [params.maxSubtasks=6]
- * @param {Function} [params.invoke] - injectable model invoker (for tests)
- * @returns {Promise<{strategy:string, subtasks:Array, usage:Object}|null>}
- */
-async function generatePlan({ task, model = "sonnet", maxSubtasks = 6, invoke } = {}) {
-  if (!task || typeof task !== "string") return null;
-
-  let responseJson;
-  try {
-    responseJson = await callModel({
-      messages: [{ role: "user", content: buildPlannerPrompt(task, maxSubtasks) }],
-      model,
-      maxTokens: 1500,
-      temperature: 0.1,
-      invoke,
-    });
-  } catch (err) {
-    logger.warn({ err: err.message }, "[Decomposition] Planner model call failed");
-    return null;
-  }
-
-  const text = extractText(responseJson);
-  const parsed = extractJsonObject(text);
-  const plan = validatePlan(parsed, maxSubtasks);
-
-  if (!plan) {
-    logger.warn(
-      { preview: text.slice(0, 200) },
-      "[Decomposition] Plan failed validation — will fall back to monolithic"
-    );
-    return null;
-  }
-
-  plan.usage = {
-    inputTokens: responseJson?.usage?.input_tokens || 0,
-    outputTokens: responseJson?.usage?.output_tokens || 0,
-  };
-
-  logger.info(
-    { subtasks: plan.subtasks.length, strategy: plan.strategy },
-    "[Decomposition] Plan generated"
-  );
-  return plan;
-}
-
-module.exports = {
-  generatePlan,
-  validatePlan,
-  extractJsonObject,
-  hasCycle,
-  buildPlannerPrompt,
-  KNOWN_AGENT_TYPES,
-};

package/src/agents/decomposition/synthesizer.js

@@ -1,89 +0,0 @@
-/**
- * Result synthesizer (Phase 4).
- *
- * Combines the (compressed) results of all subtasks into one coherent final
- * answer to the original task. Single model call. If synthesis fails, the
- * caller falls back to concatenating the subtask results.
- */
-
-const { callModel, extractText } = require("./model-call");
-const logger = require("../../logger");
-
-const MAX_RESULT_CHARS = 4000;
-
-function buildSynthesisPrompt(task, subtaskResults) {
-  const blocks = subtaskResults
-    .map((r) => {
-      const status = r.success ? "OK" : `FAILED (${r.error})`;
-      const body = r.success
-        ? truncate(r.result, MAX_RESULT_CHARS)
-        : "(no result)";
-      return `### Subtask ${r.id} [${r.agentType}] — ${status}\n${body}`;
-    })
-    .join("\n\n");
-
-  return `You are synthesizing the results of several subtasks into one final answer for the original request. Integrate the findings into a single coherent response. Resolve overlaps, note any subtask that failed, and do not invent results that no subtask produced.
-
-ORIGINAL TASK:
-${task}
-
-SUBTASK RESULTS:
-${blocks}
-
-Write the final answer now.`;
-}
-
-function truncate(text, max) {
-  if (typeof text !== "string") return String(text ?? "");
-  return text.length <= max ? text : text.slice(0, max) + "\n…[truncated]";
-}
-
-/**
- * Concatenation fallback used when the synthesis model call fails.
- */
-function concatFallback(subtaskResults) {
-  return subtaskResults
-    .filter((r) => r.success && r.result)
-    .map((r) => `## ${r.id} (${r.agentType})\n${r.result}`)
-    .join("\n\n");
-}
-
-/**
- * @param {Object} params
- * @param {string} params.task
- * @param {Array} params.subtaskResults - from dispatcher
- * @param {string} [params.model="sonnet"]
- * @param {Function} [params.invoke]
- * @returns {Promise<{text:string, fallback:boolean, usage:Object}>}
- */
-async function synthesize({ task, subtaskResults, model = "sonnet", invoke } = {}) {
-  const anySuccess = subtaskResults.some((r) => r.success);
-  if (!anySuccess) {
-    return { text: "All subtasks failed; no result could be produced.", fallback: true, usage: {} };
-  }
-
-  try {
-    const responseJson = await callModel({
-      messages: [{ role: "user", content: buildSynthesisPrompt(task, subtaskResults) }],
-      model,
-      maxTokens: 4096,
-      temperature: 0.3,
-      invoke,
-    });
-    const text = extractText(responseJson);
-    if (!text) throw new Error("Empty synthesis");
-    return {
-      text,
-      fallback: false,
-      usage: {
-        inputTokens: responseJson?.usage?.input_tokens || 0,
-        outputTokens: responseJson?.usage?.output_tokens || 0,
-      },
-    };
-  } catch (err) {
-    logger.warn({ err: err.message }, "[Decomposition] Synthesis failed — concatenating results");
-    return { text: concatFallback(subtaskResults), fallback: true, usage: {} };
-  }
-}
-
-module.exports = { synthesize, buildSynthesisPrompt, concatFallback };