karajan-code 2.5.0 → 2.6.1

package/src/brain/decisor.js

@@ -0,0 +1,243 @@
+/**
+ * Brain decisor — intent-driven pipeline routing.
+ *
+ * Takes the triage output + task text + config and produces a Decision that
+ * the orchestrator applies as pipelineFlags overrides. The existing stage
+ * if/else in runFlow continues to drive execution; Brain just tells it which
+ * roles are relevant for this particular task.
+ *
+ * This is an MVP that keeps the current architecture. A future iteration
+ * (Pipeline Sovereignty / KJC-PCS-0022) can promote the Decision into a
+ * true DAG with parallel stage execution.
+ */
+
+/**
+ * @typedef {Object} TriageOutput
+ * @property {"trivial"|"simple"|"medium"|"complex"} level
+ * @property {string[]} roles                       - roles triage suggests running
+ * @property {string} [taskType]                    - sw | infra | doc | add-tests | refactor | no-code | audit
+ * @property {string} [reasoning]
+ * @property {number} [confidence]                  - 0..1, often absent
+ * @property {string[]} [domainHints]
+ */
+
+/**
+ * @typedef {Object} Decision
+ * @property {string[]} rolesOn                     - roles to enable in pipelineFlags
+ * @property {string[]} rolesOff                    - roles to explicitly disable
+ * @property {"low"|"medium"|"high"} confidence
+ * @property {string} rationale                     - human-readable reasoning
+ * @property {boolean} consultSolomon               - true if the Brain is unsure
+ * @property {string} [solomonReason]               - why Solomon is needed
+ * @property {string[]} appliedOverrides            - names of manual overrides respected
+ */
+
+const VALID_ROLES = new Set([
+  "planner", "researcher", "architect", "coder", "reviewer", "refactorer",
+  "tester", "security", "impeccable", "triage", "discover", "hu_reviewer", "solomon",
+]);
+
+/**
+ * Translate triage level → base set of roles. Conservative baseline that the
+ * decisor then adjusts via taskType and domain hints.
+ */
+function baselineForLevel(level) {
+  switch (level) {
+    case "trivial": return new Set(["coder"]);
+    case "simple": return new Set(["coder", "reviewer"]);
+    case "medium": return new Set(["coder", "reviewer", "tester"]);
+    case "complex": return new Set(["researcher", "architect", "planner", "coder", "reviewer", "tester", "security"]);
+    default: return new Set(["coder", "reviewer"]);
+  }
+}
+
+/**
+ * Apply taskType adjustments on top of the baseline set (mutates in place).
+ */
+function applyTaskTypeAdjustments(roles, taskType) {
+  switch (taskType) {
+    case "doc":
+      // Documentation tasks: skip testing and security, keep reviewer for tone/clarity.
+      roles.delete("tester");
+      roles.delete("security");
+      roles.delete("refactorer");
+      break;
+    case "add-tests":
+      // Adding tests: tester is primary, security less relevant.
+      roles.add("tester");
+      roles.delete("security");
+      break;
+    case "refactor":
+      // Refactor: no new behavior; tester verifies nothing broke; reviewer checks structure.
+      roles.add("refactorer");
+      roles.add("tester");
+      break;
+    case "infra":
+      // Infra: architect helps; security critical.
+      roles.add("architect");
+      roles.add("security");
+      break;
+    case "audit":
+      // Audit: no coder; reviewer + security.
+      roles.delete("coder");
+      roles.add("reviewer");
+      roles.add("security");
+      break;
+    case "no-code":
+      // No-code tasks (e.g. running SQL queries): drop coder+reviewer+tester.
+      roles.delete("coder");
+      roles.delete("reviewer");
+      roles.delete("tester");
+      break;
+  }
+}
+
+/**
+ * Apply explicit overrides (CLI flags / config) on top of the decision.
+ * force = add; skip = remove. Tracks what was applied.
+ *
+ * @param {Set<string>} roles
+ * @param {{ forceRoles?: string[], skipRoles?: string[] }} overrides
+ * @returns {string[]} applied override names
+ */
+function applyOverrides(roles, overrides) {
+  const applied = [];
+  for (const r of overrides.forceRoles || []) {
+    if (!VALID_ROLES.has(r)) continue;
+    roles.add(r);
+    applied.push(`force:${r}`);
+  }
+  for (const r of overrides.skipRoles || []) {
+    if (!VALID_ROLES.has(r)) continue;
+    roles.delete(r);
+    applied.push(`skip:${r}`);
+  }
+  return applied;
+}
+
+/**
+ * Build a routing Decision from triage output + task text + config.
+ *
+ * @param {Object} args
+ * @param {TriageOutput} args.triage
+ * @param {string} [args.task]
+ * @param {Object} [args.config]                   - resolved config (for rolesEnabled in pipeline)
+ * @param {{ forceRoles?: string[], skipRoles?: string[] }} [args.overrides]
+ * @returns {Decision}
+ */
+export function buildDecision({ triage, task, config = {}, overrides = {} } = {}) {
+  const level = triage?.level || "simple";
+  const taskType = triage?.taskType || "sw";
+
+  // 1. Baseline by complexity.
+  const roles = baselineForLevel(level);
+
+  // 2. Include triage's own suggested roles (triage already factors domain hints).
+  if (Array.isArray(triage?.roles)) {
+    for (const r of triage.roles) {
+      if (VALID_ROLES.has(r)) roles.add(r);
+    }
+  }
+
+  // 3. Task-type-specific adjustments.
+  applyTaskTypeAdjustments(roles, taskType);
+
+  // 4. Config pipeline.X.enabled=false forces a role off (respect user config).
+  const pipeline = config?.pipeline || {};
+  for (const r of Array.from(roles)) {
+    if (pipeline[r]?.enabled === false) {
+      roles.delete(r);
+    }
+  }
+
+  // 5. Manual CLI/flag overrides (highest priority).
+  const appliedOverrides = applyOverrides(roles, overrides);
+
+  // 6. Invariants: coder is always on unless explicitly audit/no-code AND not force-added.
+  if (taskType !== "audit" && taskType !== "no-code" && !overrides.skipRoles?.includes("coder")) {
+    roles.add("coder");
+  }
+
+  // 7. Confidence + Solomon consultation.
+  const explicitConfidence = typeof triage?.confidence === "number" ? triage.confidence : null;
+  let confidence = "medium";
+  let consultSolomon = false;
+  let solomonReason;
+  if (explicitConfidence !== null) {
+    if (explicitConfidence < 0.6) {
+      confidence = "low";
+      consultSolomon = true;
+      solomonReason = `triage confidence ${explicitConfidence.toFixed(2)} < 0.6`;
+    } else if (explicitConfidence >= 0.85) {
+      confidence = "high";
+    }
+  }
+  // Ambiguous level (absent or off-vocabulary) → low confidence regardless.
+  if (!triage?.level) {
+    confidence = "low";
+    consultSolomon = true;
+    solomonReason = "triage returned no level";
+  }
+
+  const rolesOn = Array.from(roles).sort();
+  const rolesOff = Array.from(VALID_ROLES).filter((r) => !roles.has(r)).sort();
+
+  const rationale = buildRationale({ level, taskType, rolesOn, appliedOverrides, triage });
+
+  return {
+    rolesOn,
+    rolesOff,
+    confidence,
+    rationale,
+    consultSolomon,
+    solomonReason,
+    appliedOverrides,
+  };
+}
+
+function buildRationale({ level, taskType, rolesOn, appliedOverrides, triage }) {
+  const parts = [
+    `level=${level}`,
+    `taskType=${taskType}`,
+    `roles=[${rolesOn.join(",")}]`,
+  ];
+  if (triage?.domainHints?.length) {
+    parts.push(`hints=[${triage.domainHints.slice(0, 3).join(",")}]`);
+  }
+  if (appliedOverrides.length) {
+    parts.push(`overrides=[${appliedOverrides.join(",")}]`);
+  }
+  return parts.join(" | ");
+}
+
+/**
+ * Apply a Decision onto an existing pipelineFlags object. Returns a NEW
+ * object — the input is not mutated. Setting roleEnabled flags via a
+ * consistent naming pattern: `${role}Enabled`.
+ *
+ * Unknown roles are silently ignored; the orchestrator only consumes a
+ * fixed set of *Enabled flags.
+ *
+ * @param {Decision} decision
+ * @param {Object} pipelineFlags
+ * @returns {Object} new flags object
+ */
+export function applyDecisionToFlags(decision, pipelineFlags = {}) {
+  const next = { ...pipelineFlags };
+  const flagFor = (role) => {
+    if (role === "hu_reviewer") return "huReviewerEnabled";
+    return `${role}Enabled`;
+  };
+  for (const role of decision.rolesOn) {
+    next[flagFor(role)] = true;
+  }
+  for (const role of decision.rolesOff) {
+    next[flagFor(role)] = false;
+  }
+  // Coder/security/reviewer aren't always toggled via flags in the current
+  // orchestrator (coder is implicit). Don't touch fields the orchestrator
+  // doesn't know; next simply carries them.
+  return next;
+}
+
+export { VALID_ROLES };

package/src/brain/solomon-consult.js

@@ -0,0 +1,171 @@
+/**
+ * Brain → Solomon consultation for routing decisions.
+ *
+ * When the Brain's Decision is low confidence, ambiguous, or the triage+config
+ * combination yields conflicting signals, the Brain consults Solomon. Solomon
+ * ruling is treated as *advisory*: if it returns a concrete role adjustment
+ * (e.g. "add security"), Brain applies it; otherwise Brain keeps the baseline.
+ *
+ * This is intentionally conservative. A future iteration can make Solomon a
+ * binding arbiter for routing (like it is for pipeline-control decisions).
+ *
+ * Architectural invariant: this module is the ONLY sanctioned path from
+ * Brain to Solomon for routing concerns. Stages / rules / agents must not
+ * bypass Brain to reach Solomon directly — see the note on `invokeSolomon`
+ * in `src/orchestrator/solomon-escalation.js` and docs/ARCHITECTURE.md.
+ *
+ * @typedef {import("../types/solomon.js").Conflict} Conflict
+ * @typedef {import("../types/solomon.js").SolomonResult} SolomonResult
+ */
+
+/**
+ * Build a synthetic conflict payload suitable for invokeSolomon().
+ *
+ * @param {Object} args
+ * @param {import("./decisor.js").Decision} args.decision
+ * @param {Object} args.triage
+ * @param {string} args.task
+ * @returns {Conflict} conflict
+ */
+export function buildRoutingConflict({ decision, triage, task }) {
+  return {
+    task,
+    stage: "brain-routing",
+    reason: decision.solomonReason || "low-confidence routing decision",
+    iterationCount: 0,
+    maxIterations: 1,
+    history: [],
+    summary: `Brain rationale: ${decision.rationale}. Roles on: ${decision.rolesOn.join(", ")}. Confidence: ${decision.confidence}.`,
+    // Extra data Solomon's prompt can introspect via conflict.detail
+    detail: {
+      triageLevel: triage?.level,
+      triageTaskType: triage?.taskType,
+      triageConfidence: triage?.confidence,
+      rolesOn: decision.rolesOn,
+      rolesOff: decision.rolesOff,
+      reason: decision.solomonReason,
+    },
+  };
+}
+
+/**
+ * Invoke Solomon with a routing question and translate its ruling back into
+ * adjustments to the Decision's rolesOn/rolesOff lists.
+ *
+ * If anything goes wrong (Solomon disabled, invocation throws, ruling
+ * malformed), the original decision is returned unchanged with a diagnostic
+ * appended to its rationale.
+ *
+ * @param {Object} args
+ * @param {import("./decisor.js").Decision} args.decision
+ * @param {Object} args.triage
+ * @param {string} args.task
+ * @param {Object} args.config
+ * @param {Object} args.logger
+ * @param {Object} [args.emitter]
+ * @param {Object} [args.eventBase]
+ * @param {Object} [args.session]
+ * @param {Function} [args.askQuestion]
+ * @returns {Promise<import("./decisor.js").Decision>}
+ */
+export async function consultSolomonForRouting({
+  decision,
+  triage,
+  task,
+  config,
+  logger,
+  emitter = null,
+  eventBase = {},
+  session = {},
+  askQuestion = null,
+}) {
+  if (!decision?.consultSolomon) return decision;
+  // Route through the existing infrastructure.
+  let invokeSolomon;
+  try {
+    ({ invokeSolomon } = await import("../orchestrator/solomon-escalation.js"));
+  } catch (err) {
+    logger?.warn?.(`brain/solomon-consult: escalation module unavailable (${err.message})`);
+    return decision;
+  }
+
+  const conflict = buildRoutingConflict({ decision, triage, task });
+
+  let ruling;
+  try {
+    ruling = await invokeSolomon({
+      config,
+      logger,
+      emitter,
+      eventBase,
+      stage: "brain-routing",
+      conflict,
+      askQuestion,
+      session,
+      iteration: 0,
+    });
+  } catch (err) {
+    logger?.warn?.(`brain/solomon-consult: invokeSolomon threw (${err.message}) — keeping baseline`);
+    return {
+      ...decision,
+      rationale: `${decision.rationale} | solomon=failed(${err.message})`,
+    };
+  }
+
+  if (!ruling || typeof ruling !== "object") {
+    return {
+      ...decision,
+      rationale: `${decision.rationale} | solomon=no-ruling`,
+    };
+  }
+
+  return applyRulingToDecision(decision, ruling, logger);
+}
+
+/**
+ * Apply a Solomon ruling to a decision. Known ruling fields Solomon may
+ * return that we understand in routing context:
+ *   - action: "approve" / "continue" / "retry_different_approach" / "escalate"
+ *   - suggestedActions: list of strings that may include "add X" / "remove X"
+ *   - conditions: list of strings
+ *
+ * For routing we only look at suggestedActions (text-based) and parse simple
+ * "add X" / "skip X" / "remove X" hints against the valid role set. Everything
+ * else is logged for the rationale and ignored.
+ */
+export function applyRulingToDecision(decision, ruling, logger) {
+  const rolesOn = new Set(decision.rolesOn);
+  const rolesOff = new Set(decision.rolesOff);
+  const applied = [];
+
+  const suggestions = Array.isArray(ruling.suggestedActions) ? ruling.suggestedActions : [];
+  for (const raw of suggestions) {
+    const action = String(raw || "").toLowerCase();
+    const addMatch = action.match(/\b(?:add|enable|include)\s+(\w+)/);
+    const skipMatch = action.match(/\b(?:skip|disable|remove|drop)\s+(\w+)/);
+    if (addMatch) {
+      const role = addMatch[1];
+      rolesOn.add(role);
+      rolesOff.delete(role);
+      applied.push(`solomon-add:${role}`);
+    } else if (skipMatch) {
+      const role = skipMatch[1];
+      rolesOff.add(role);
+      rolesOn.delete(role);
+      applied.push(`solomon-skip:${role}`);
+    }
+  }
+
+  const ruleVerdict = ruling.action || ruling.verdict || "unknown";
+  logger?.info?.(`brain/solomon-consult: Solomon verdict=${ruleVerdict} applied=[${applied.join(",")}]`);
+
+  return {
+    ...decision,
+    rolesOn: Array.from(rolesOn).sort(),
+    rolesOff: Array.from(rolesOff).sort(),
+    appliedOverrides: [...decision.appliedOverrides, ...applied],
+    confidence: applied.length > 0 ? "high" : decision.confidence,
+    consultSolomon: false,
+    rationale: `${decision.rationale} | solomon=${ruleVerdict}${applied.length ? ` applied=${applied.join(",")}` : ""}`,
+  };
+}

package/src/budget/comparison.js

@@ -0,0 +1,96 @@
+/**
+ * Compute "With KJ" vs "Without KJ" budget comparison.
+ *
+ * Karajan reduces token consumption through two mechanisms:
+ *   1. RTK proxy compression (token-level output compression via the
+ *      Rust Token Killer proxy). Tracked as `rtkSavings.estimatedTokensSaved`.
+ *   2. Brain role-output compression (summarization/trimming of inter-role
+ *      outputs). Tracked in `brainCtx.compressionStats.totalSaved`.
+ *
+ * Given the real billed usage (from BudgetTracker) plus the saved tokens,
+ * this helper projects what usage would have been without KJ's compressions.
+ *
+ * Cost projection uses the blended rate from the real usage:
+ *   withoutKjCost = realCost * (realTokens + savedTokens) / realTokens
+ *
+ * When no compression data is available, `hasCompression` is false and the
+ * caller should render only the real cost (no comparison).
+ */
+
+/**
+ * @typedef {Object} KjComparison
+ * @property {boolean} hasCompression              - whether any savings data exists
+ * @property {{ tokens: number, cost: number }} withKj
+ * @property {{ tokens: number, cost: number }} withoutKj
+ * @property {number} savedTokens                  - total tokens saved
+ * @property {number} savedPct                     - savings as percent of the "without" total (0..100)
+ * @property {{ rtkTokens: number, brainTokens: number }} breakdown
+ */
+
+/**
+ * Compute the comparison from the current budget snapshot and available
+ * compression stats.
+ *
+ * @param {Object} args
+ * @param {number} [args.realTokens]                   - budget tracker total tokens
+ * @param {number} [args.realCost]                     - budget tracker cost in USD
+ * @param {{ estimatedTokensSaved?: number }} [args.rtkSavings]
+ * @param {{ compressionStats?: { totalSaved?: number } } | null} [args.brainCtx]
+ * @returns {KjComparison}
+ */
+export function computeKjComparison({ realTokens = 0, realCost = 0, rtkSavings = null, brainCtx = null } = {}) {
+  const realT = Math.max(0, Number(realTokens) || 0);
+  const realC = Math.max(0, Number(realCost) || 0);
+
+  const rtkTokens = Math.max(0, Number(rtkSavings?.estimatedTokensSaved) || 0);
+  const brainTokens = Math.max(0, Number(brainCtx?.compressionStats?.totalSaved) || 0);
+  const savedTokens = rtkTokens + brainTokens;
+
+  if (savedTokens === 0 || realT === 0) {
+    return {
+      hasCompression: false,
+      withKj: { tokens: realT, cost: realC },
+      withoutKj: { tokens: realT, cost: realC },
+      savedTokens: 0,
+      savedPct: 0,
+      breakdown: { rtkTokens, brainTokens },
+    };
+  }
+
+  const withoutKjTokens = realT + savedTokens;
+  const blendedRate = realC / realT;
+  const withoutKjCost = Number((blendedRate * withoutKjTokens).toFixed(4));
+  const savedPct = Number(((savedTokens / withoutKjTokens) * 100).toFixed(1));
+
+  return {
+    hasCompression: true,
+    withKj: { tokens: realT, cost: Number(realC.toFixed(4)) },
+    withoutKj: { tokens: withoutKjTokens, cost: withoutKjCost },
+    savedTokens,
+    savedPct,
+    breakdown: { rtkTokens, brainTokens },
+  };
+}
+
+/**
+ * Render a one-line comparison string for the CLI display. Returns null
+ * when there's no compression data (so the caller can fall back to the
+ * plain budget line).
+ *
+ * Example outputs:
+ *   "With KJ: $0.06 / 1,287 tokens · Without KJ: ~$1.30 / ~11,324 tokens (-89%)"
+ *
+ * @param {KjComparison} cmp
+ * @returns {string|null}
+ */
+export function formatComparisonLine(cmp) {
+  if (!cmp?.hasCompression) return null;
+  const fmt = (n) => n.toLocaleString("en-US");
+  const tok = (n) => `${fmt(n)} tokens`;
+  const cost = (n) => `$${n.toFixed(2)}`;
+  return [
+    `With KJ: ${cost(cmp.withKj.cost)} / ${tok(cmp.withKj.tokens)}`,
+    `Without KJ: ~${cost(cmp.withoutKj.cost)} / ~${tok(cmp.withoutKj.tokens)}`,
+    `(-${cmp.savedPct.toFixed(0)}%)`,
+  ].join(" · ");
+}

package/src/checks/binaries.js

@@ -0,0 +1,123 @@
+/**
+ * Binary / CLI availability checks.
+ *
+ * Covers:
+ *   - Agent CLIs (claude, codex, gemini, aider, opencode)
+ *   - Core binaries (node, npm, git)
+ *   - Docker
+ *   - Serena MCP (optional)
+ *
+ * All binary checks use `strategy: "manual"` because auto-installing binaries
+ * is invasive and platform-specific. Exception: Serena is `"prompt"` (we know
+ * the install command and can offer to run it).
+ */
+
+import { checkBinary, KNOWN_AGENTS } from "../utils/agent-detect.js";
+import { runCommand } from "../utils/process.js";
+import { withDocLink } from "../utils/doc-links.js";
+import { STRATEGY } from "./types.js";
+
+/**
+ * Check the presence of a named agent CLI (claude/codex/gemini/aider).
+ */
+function createAgentCheck(agent) {
+  return {
+    name: `agent:${agent.name}`,
+    label: `Agent: ${agent.name}`,
+    strategy: STRATEGY.MANUAL,
+    async detect() {
+      const result = await checkBinary(agent.name);
+      return {
+        ok: result.ok,
+        severity: "warn", // missing one agent CLI shouldn't block — user may not use it
+        detail: result.ok ? `${result.version} (${result.path})` : "Not found",
+        fix: result.ok ? undefined : withDocLink(`Install: ${agent.install}`, "agent_not_found"),
+      };
+    },
+  };
+}
+
+/**
+ * Check the presence of a core binary (node, npm, git).
+ */
+function createCoreBinaryCheck(bin) {
+  return {
+    name: bin,
+    label: bin,
+    strategy: STRATEGY.MANUAL,
+    async detect() {
+      const result = await checkBinary(bin);
+      return {
+        ok: result.ok,
+        severity: "fail",
+        detail: result.ok ? result.version : "Not found",
+        fix: result.ok ? undefined : `Install ${bin} from its official website.`,
+      };
+    },
+  };
+}
+
+/**
+ * Docker check. Manual strategy (platform-dependent install).
+ */
+export function createDockerCheck() {
+  return {
+    name: "docker",
+    label: "Docker",
+    strategy: STRATEGY.MANUAL,
+    async detect() {
+      const docker = await checkBinary("docker", "--version");
+      return {
+        ok: docker.ok,
+        severity: "warn", // only required if Sonar enabled; soft-fail here
+        detail: docker.ok ? docker.version : "Not found",
+        fix: docker.ok ? undefined : withDocLink("Install Docker: https://docs.docker.com/get-docker/", "sonar_docker"),
+      };
+    },
+  };
+}
+
+/**
+ * Serena MCP (optional). Prompt strategy: we know how to install it.
+ */
+export function createSerenaCheck() {
+  return {
+    name: "serena",
+    label: "Serena MCP",
+    strategy: STRATEGY.MANUAL,
+    applies: (config) => config.serena?.enabled === true,
+    describe: "Install Serena via: uvx --from git+https://github.com/oraios/serena serena",
+    async detect() {
+      let ok = false;
+      try {
+        const res = await runCommand("serena", ["--version"]);
+        ok = res.exitCode === 0;
+      } catch {
+        ok = false;
+      }
+      return {
+        ok,
+        severity: "warn",
+        detail: ok ? "Available" : "Not found (prompts will still include Serena instructions)",
+        fix: ok ? undefined : "Install Serena: uvx --from git+https://github.com/oraios/serena serena --help",
+      };
+    },
+  };
+}
+
+/**
+ * Aggregate: all binary-related checks for the current config.
+ * @returns {import("./types.js").Check[]}
+ */
+export function getBinaryChecks() {
+  const checks = [];
+  for (const agent of KNOWN_AGENTS) {
+    checks.push(createAgentCheck(agent));
+  }
+  for (const bin of ["node", "npm", "git"]) {
+    checks.push(createCoreBinaryCheck(bin));
+  }
+  checks.push(createDockerCheck());
+  checks.push(createSerenaCheck());
+  return checks;
+}