lynkr 9.4.6 → 9.6.0

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

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

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

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

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

package/src/agents/decomposition/telemetry.js

@@ -0,0 +1,55 @@
+/**
+ * Decomposition telemetry + shadow mode (Phase 6).
+ *
+ * Appends one JSON line per decomposition decision to
+ * data/decomposition-decisions.jsonl so the net token effect can be audited.
+ * Because the research is clear that decomposition can COST more than it saves,
+ * a shadow mode (TASK_DECOMPOSITION_SHADOW=true) runs the gate + records what it
+ * WOULD have done without actually decomposing — so savings can be validated on
+ * real traffic before enabling for real.
+ */
+
+const fs = require("fs");
+const path = require("path");
+const logger = require("../../logger");
+
+const LOG_PATH = path.join(__dirname, "../../../data/decomposition-decisions.jsonl");
+
+function estimateTokens(text) {
+  if (typeof text !== "string") return 0;
+  return Math.ceil(text.length / 4);
+}
+
+/**
+ * Rough net-savings estimate.
+ * monolithic ≈ what one big context would have cost (estimated input tokens).
+ * decomposed ≈ planning + Σ(subagent in+out) + synthesis.
+ * Positive `savedTokens` = decomposition was cheaper.
+ */
+function estimateSavings({ monolithicTokens, planUsage, dispatchStats, synthUsage }) {
+  const decomposed =
+    (planUsage?.inputTokens || 0) +
+    (planUsage?.outputTokens || 0) +
+    (dispatchStats?.inputTokens || 0) +
+    (dispatchStats?.outputTokens || 0) +
+    (synthUsage?.inputTokens || 0) +
+    (synthUsage?.outputTokens || 0);
+  return {
+    monolithicTokens: monolithicTokens || 0,
+    decomposedTokens: decomposed,
+    savedTokens: (monolithicTokens || 0) - decomposed,
+  };
+}
+
+function record(entry) {
+  const line = { timestamp: Date.now(), ...entry };
+  try {
+    fs.mkdirSync(path.dirname(LOG_PATH), { recursive: true });
+    fs.appendFileSync(LOG_PATH, JSON.stringify(line) + "\n");
+  } catch (err) {
+    logger.debug({ err: err.message }, "[Decomposition] Telemetry append failed");
+  }
+  return line;
+}
+
+module.exports = { record, estimateSavings, estimateTokens, LOG_PATH };