karajan-code 4.70.4 → 5.0.0

package/src/brain/decision-tracker.js

@@ -1,125 +0,0 @@
-/**
- * Tracks every routing decision the Brain makes during a session and enforces
- * safety limits (max decisions per session, indecision-loop detection).
- *
- * Decisions are appended to `session.brainDecisions`. Consumers call
- * `recordDecision(tracker, decision, context)` after a buildDecision() call
- * and `checkLimits(tracker)` before making another decision.
- *
- * The limits are soft guards, not hard failures: hitting a limit surfaces
- * a status that the orchestrator can use to escalate to Solomon or pause
- * the session for human input.
- */
-
-import { setBrainDecisions } from "../session/mutators.js";
-
-export const DEFAULT_MAX_DECISIONS = 20;
-export const INDECISION_REPEAT_THRESHOLD = 3; // 3 identical classifications in a row
-
-/**
- * @typedef {Object} RecordedDecision
- * @property {number} seq
- * @property {string} at                            - ISO timestamp
- * @property {string} intent                        - e.g. "sw:medium" (taskType:level)
- * @property {string[]} rolesOn
- * @property {"low"|"medium"|"high"} confidence
- * @property {string} rationale
- * @property {string[]} appliedOverrides
- */
-
-/**
- * @typedef {Object} TrackerStatus
- * @property {"ok"|"max-reached"|"indecision"} status
- * @property {number} decisionCount
- * @property {string} [detail]
- */
-
-/**
- * Initialize a tracker bound to a session. If the session already has a
- * `brainDecisions` array (e.g. from a resumed session), keep it.
- *
- * @param {Object} session
- * @param {{ max?: number }} [options]
- * @returns {{ session: Object, max: number }}
- */
-export function createTracker(session, { max = DEFAULT_MAX_DECISIONS } = {}) {
-  if (!Array.isArray(session.brainDecisions)) {
-    setBrainDecisions(session, []);
-  }
-  return { session, max };
-}
-
-/**
- * Append a decision to the tracker.
- *
- * @param {{ session: Object, max: number }} tracker
- * @param {Object} decision                         - output of buildDecision()
- * @param {{ taskType?: string, level?: string }} intent
- * @returns {RecordedDecision}
- */
-export function recordDecision(tracker, decision, intent = {}) {
-  const seq = tracker.session.brainDecisions.length + 1;
-  const entry = {
-    seq,
-    at: new Date().toISOString(),
-    intent: `${intent.taskType || "?"}:${intent.level || "?"}`,
-    rolesOn: Array.isArray(decision.rolesOn) ? [...decision.rolesOn] : [],
-    confidence: decision.confidence || "medium",
-    rationale: decision.rationale || "",
-    appliedOverrides: Array.isArray(decision.appliedOverrides) ? [...decision.appliedOverrides] : [],
-  };
-  tracker.session.brainDecisions.push(entry);
-  return entry;
-}
-
-/**
- * Compute status of the tracker. Called BEFORE recording a new decision so
- * the orchestrator can decide to escalate instead of calling the Brain again.
- *
- * @param {{ session: Object, max: number }} tracker
- * @returns {TrackerStatus}
- */
-export function checkLimits(tracker) {
-  const decisions = tracker.session.brainDecisions || [];
-  const decisionCount = decisions.length;
-
-  if (decisionCount >= tracker.max) {
-    return {
-      status: "max-reached",
-      decisionCount,
-      detail: `Brain made ${decisionCount} decisions (limit ${tracker.max}). Escalate to Solomon or human.`,
-    };
-  }
-
-  // Indecision loop: last N decisions share the exact same intent.
-  const window = decisions.slice(-INDECISION_REPEAT_THRESHOLD);
-  if (window.length >= INDECISION_REPEAT_THRESHOLD && window.every((d) => d.intent === window[0].intent)) {
-    return {
-      status: "indecision",
-      decisionCount,
-      detail: `Brain classified the same intent (${window[0].intent}) ${INDECISION_REPEAT_THRESHOLD} times in a row — loop detected.`,
-    };
-  }
-
-  return { status: "ok", decisionCount };
-}
-
-/**
- * Build a short summary of all decisions made in the session. Useful for the
- * final report and for debugging.
- *
- * @param {{ session: Object }} tracker
- * @returns {{ total: number, byIntent: Record<string,number>, lastRationale: string }}
- */
-export function summarize(tracker) {
-  const decisions = tracker.session.brainDecisions || [];
-  const byIntent = {};
-  for (const d of decisions) {
-    byIntent[d.intent] = (byIntent[d.intent] || 0) + 1;
-  }
-  return {
-    total: decisions.length,
-    byIntent,
-    lastRationale: decisions.at(-1)?.rationale ?? "",
-  };
-}

package/src/brain/decisor.js

@@ -1,243 +0,0 @@
-/**
- * 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: _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((a, b) => a.localeCompare(b));
-  const rolesOff = Array.from(VALID_ROLES).filter((r) => !roles.has(r)).sort((a, b) => a.localeCompare(b));
-
-  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

@@ -1,171 +0,0 @@
-/**
- * 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((a, b) => a.localeCompare(b)),
-    rolesOff: Array.from(rolesOff).sort((a, b) => a.localeCompare(b)),
-    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/brain/standby-scheduler.js

@@ -1,8 +0,0 @@
-// Shim de compatibilidad: standby-scheduler vive ahora en karajan-core.
-// Mantiene la ruta para callers internos del CLI.
-export {
-  _resetScheduledForTests,
-  scheduleResume,
-  cancelScheduled,
-  reconcileAll,
-} from "karajan-core/standby-scheduler";

package/src/budget/comparison.js

@@ -1,96 +0,0 @@
-/**
- * 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(" · ");
-}