karajan-code 1.25.3 → 1.27.0

package/README.md

@@ -459,6 +459,7 @@ Karajan Code works great on its own, but combining it with these MCP servers giv
 | [**GitHub MCP**](https://github.com/modelcontextprotocol/servers/tree/main/src/github) | Create PRs, manage issues, read repos directly from the agent | Combine with `--auto-push` for end-to-end: code → review → push → PR |
 | [**Serena**](https://github.com/oramasearch/serena) | Symbol-level code navigation (find references, go-to-definition) for JS/TS projects | Enable with `--enable-serena` to inject symbol context into coder/reviewer prompts |
 | [**Chrome DevTools MCP**](https://github.com/anthropics/anthropic-quickstarts/tree/main/chrome-devtools-mcp) | Browser automation, screenshots, console/network inspection | Verify UI changes visually after `kj` modifies frontend code |
+| [**RTK**](https://github.com/rtk-ai/rtk) | Reduces LLM token consumption by 60-90% on Bash command outputs (git, test, build) | Install globally with `brew install rtk && rtk init --global` — all KJ agent commands automatically compressed |
 
 ## Role Templates
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "1.25.3",
+  "version": "1.27.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",

package/src/commands/doctor.js

@@ -204,6 +204,36 @@ async function checkBecariaInfra(config) {
   return checks;
 }
 
+async function checkRtk() {
+  try {
+    const res = await runCommand("rtk", ["--version"]);
+    if (res.exitCode === 0) {
+      return {
+        name: "rtk",
+        label: "RTK (Rust Token Killer)",
+        ok: true,
+        detail: `${res.stdout.trim()} — token savings active`,
+        fix: null
+      };
+    }
+    return {
+      name: "rtk",
+      label: "RTK (Rust Token Killer)",
+      ok: true,
+      detail: "Not found — install for 60-90% token savings: brew install rtk",
+      fix: null
+    };
+  } catch {
+    return {
+      name: "rtk",
+      label: "RTK (Rust Token Killer)",
+      ok: true,
+      detail: "Not found — install for 60-90% token savings: brew install rtk",
+      fix: null
+    };
+  }
+}
+
 async function checkRuleFiles(config) {
   const projectDir = config.projectDir || process.cwd();
   const reviewRules = await loadFirstExisting(resolveRoleMdPath("reviewer", projectDir));
@@ -248,6 +278,7 @@ export async function runChecks({ config }) {
   }
 
   checks.push(...await checkRuleFiles(config));
+  checks.push(await checkRtk());
 
   return checks;
 }

package/src/commands/init.js

@@ -7,6 +7,7 @@ import { exists, ensureDir } from "../utils/fs.js";
 import { getKarajanHome } from "../utils/paths.js";
 import { detectAvailableAgents } from "../utils/agent-detect.js";
 import { createWizard, isTTY } from "../utils/wizard.js";
+import { runCommand } from "../utils/process.js";
 
 async function runWizard(config, logger) {
   const agents = await detectAvailableAgents();
@@ -270,6 +271,21 @@ export async function initCommand({ logger, flags = {} }) {
   await ensureReviewRules(reviewRulesPath, logger);
   await ensureCoderRules(coderRulesPath, logger);
   await installSkills(logger, interactive);
+
+  // Check RTK availability and inform user
+  let hasRtk = false;
+  try {
+    const rtkRes = await runCommand("rtk", ["--version"]);
+    hasRtk = rtkRes.exitCode === 0;
+  } catch {
+    hasRtk = false;
+  }
+  if (!hasRtk) {
+    logger.info("");
+    logger.info("RTK (Rust Token Killer) can reduce token usage by 60-90%.");
+    logger.info("  Install: brew install rtk && rtk init --global");
+  }
+
   await setupSonarQube(config, logger);
   await scaffoldBecariaGateway(config, flags, logger);
 }

package/src/orchestrator/post-loop-stages.js

@@ -5,6 +5,93 @@ import { addCheckpoint, saveSession } from "../session-store.js";
 import { emitProgress, makeEvent } from "../utils/events.js";
 import { invokeSolomon } from "./solomon-escalation.js";
 
+const KNOWN_AGENTS = ["claude", "codex", "gemini"];
+
+/**
+ * Build an ordered fallback chain for a role.
+ * Primary provider first, then remaining known agents (no duplicates).
+ */
+function buildFallbackChain(config, roleName) {
+  const primary =
+    config?.roles?.[roleName]?.provider ||
+    config?.roles?.coder?.provider ||
+    config?.coder ||
+    "claude";
+  return [primary, ...KNOWN_AGENTS.filter((a) => a !== primary)];
+}
+
+/**
+ * Detect if a role output is an agent/spawn failure (vs a genuine evaluation failure).
+ * Agent failures have `result.error` but no `result.verdict`.
+ */
+function isAgentFailure(output) {
+  if (!output || output.ok) return false;
+  return Boolean(output.result?.error) && !output.result?.verdict;
+}
+
+/**
+ * Run a role (TesterRole or SecurityRole) with agent fallback chain.
+ * If the primary agent fails to start (spawn/auth failure), tries the next agent.
+ * Genuine evaluation failures (agent ran but verdict=fail) are NOT retried.
+ *
+ * @returns {{ output, provider, attempts }}
+ */
+async function runRoleWithFallback(RoleClass, { roleName, config, logger, emitter, eventBase, task, iteration, diff }) {
+  const chain = buildFallbackChain(config, roleName);
+  const attempts = [];
+
+  for (const provider of chain) {
+    const overrideConfig = {
+      ...config,
+      roles: { ...config.roles, [roleName]: { ...config.roles?.[roleName], provider } }
+    };
+
+    const role = new RoleClass({ config: overrideConfig, logger, emitter });
+    await role.init({ task, iteration });
+
+    const start = Date.now();
+    let output;
+    try {
+      output = await role.run({ task, diff });
+    } catch (err) {
+      output = {
+        ok: false,
+        result: { error: err.message, provider },
+        summary: `${roleName} threw: ${err.message}`
+      };
+    }
+    const duration = Date.now() - start;
+
+    attempts.push({ provider, ok: output.ok, duration, summary: output.summary });
+
+    if (output.ok || !isAgentFailure(output)) {
+      return { output, provider, attempts };
+    }
+
+    logger.warn(`${roleName} agent "${provider}" failed (${duration}ms): ${output.summary} — trying next agent`);
+    emitProgress(emitter, makeEvent(`${roleName}:fallback`, { ...eventBase, stage: roleName }, {
+      status: "warn",
+      message: `Agent "${provider}" failed, falling back`,
+      detail: { provider, duration, summary: output.summary, remaining: chain.length - attempts.length }
+    }));
+  }
+
+  // All agents failed
+  const lastAttempt = attempts[attempts.length - 1];
+  const allProviders = attempts.map((a) => a.provider).join(", ");
+  logger.error(`${roleName}: all agents failed (${allProviders})`);
+
+  return {
+    output: {
+      ok: false,
+      result: { error: `All agents failed: ${allProviders}`, attempts },
+      summary: `All ${roleName} agents failed (${allProviders}) — check agent installation and configuration`
+    },
+    provider: lastAttempt?.provider,
+    attempts
+  };
+}
+
 export async function runTesterStage({ config, logger, emitter, eventBase, session, coderRole, trackBudget, iteration, task, diff, askQuestion }) {
   logger.setContext({ iteration, stage: "tester" });
   emitProgress(
@@ -14,30 +101,28 @@ export async function runTesterStage({ config, logger, emitter, eventBase, sessi
     })
   );
 
-  const tester = new TesterRole({ config, logger, emitter });
-  await tester.init({ task, iteration });
   const testerStart = Date.now();
-  let testerOutput;
-  try {
-    testerOutput = await tester.run({ task, diff });
-  } catch (err) {
-    logger.warn(`Tester threw: ${err.message}`);
-    testerOutput = { ok: false, summary: `Tester error: ${err.message}`, result: { error: err.message } };
-  }
+  const { output: testerOutput, provider, attempts } = await runRoleWithFallback(
+    TesterRole,
+    { roleName: "tester", config, logger, emitter, eventBase, task, iteration, diff }
+  );
+  const totalDuration = Date.now() - testerStart;
+
   trackBudget({
     role: "tester",
-    provider: config?.roles?.tester?.provider || coderRole.provider,
+    provider: provider || coderRole.provider,
     model: config?.roles?.tester?.model || coderRole.model,
     result: testerOutput,
-    duration_ms: Date.now() - testerStart
+    duration_ms: totalDuration
   });
 
   await addCheckpoint(session, {
     stage: "tester",
     iteration,
     ok: testerOutput.ok,
-    provider: config?.roles?.tester?.provider || coderRole.provider,
-    model: config?.roles?.tester?.model || coderRole.model || null
+    provider: provider || coderRole.provider,
+    model: config?.roles?.tester?.model || coderRole.model || null,
+    attempts: attempts.length > 1 ? attempts : undefined
   });
 
   emitProgress(
@@ -94,30 +179,28 @@ export async function runSecurityStage({ config, logger, emitter, eventBase, ses
     })
   );
 
-  const security = new SecurityRole({ config, logger, emitter });
-  await security.init({ task, iteration });
   const securityStart = Date.now();
-  let securityOutput;
-  try {
-    securityOutput = await security.run({ task, diff });
-  } catch (err) {
-    logger.warn(`Security threw: ${err.message}`);
-    securityOutput = { ok: false, summary: `Security error: ${err.message}`, result: { error: err.message } };
-  }
+  const { output: securityOutput, provider, attempts } = await runRoleWithFallback(
+    SecurityRole,
+    { roleName: "security", config, logger, emitter, eventBase, task, iteration, diff }
+  );
+  const totalDuration = Date.now() - securityStart;
+
   trackBudget({
     role: "security",
-    provider: config?.roles?.security?.provider || coderRole.provider,
+    provider: provider || coderRole.provider,
     model: config?.roles?.security?.model || coderRole.model,
     result: securityOutput,
-    duration_ms: Date.now() - securityStart
+    duration_ms: totalDuration
   });
 
   await addCheckpoint(session, {
     stage: "security",
     iteration,
     ok: securityOutput.ok,
-    provider: config?.roles?.security?.provider || coderRole.provider,
-    model: config?.roles?.security?.model || coderRole.model || null
+    provider: provider || coderRole.provider,
+    model: config?.roles?.security?.model || coderRole.model || null,
+    attempts: attempts.length > 1 ? attempts : undefined
   });
 
   emitProgress(
@@ -214,3 +297,6 @@ export async function runImpeccableStage({ config, logger, emitter, eventBase, s
   // Impeccable is advisory — failures do not block the pipeline
   return { action: "ok", stageResult: { ok: impeccableOutput.ok, verdict, summary: impeccableOutput.summary || "No frontend design issues found" } };
 }
+
+// Exported for testing
+export { buildFallbackChain, isAgentFailure, runRoleWithFallback };

package/src/orchestrator/preflight-checks.js

@@ -0,0 +1,266 @@
+/**
+ * Preflight environment checks for kj_run.
+ *
+ * Runs AFTER policy resolution (so we know which stages are active)
+ * and BEFORE session iteration loop (so we fail fast or degrade gracefully).
+ *
+ * Design: always returns ok:true (graceful degradation, never hard-fail).
+ * Disabled stages are auto-disabled via configOverrides instead of blocking.
+ */
+
+import { checkBinary } from "../utils/agent-detect.js";
+import { isSonarReachable, sonarUp } from "../sonar/manager.js";
+import { runCommand } from "../utils/process.js";
+import { emitProgress, makeEvent } from "../utils/events.js";
+
+function normalizeApiHost(rawHost) {
+  return String(rawHost || "http://localhost:9000").replace(/host\.docker\.internal/g, "localhost");
+}
+
+function parseJsonSafe(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+async function checkDocker() {
+  const result = await checkBinary("docker");
+  return {
+    name: "docker",
+    ok: result.ok,
+    detail: result.ok ? `Docker ${result.version}` : "Docker not found",
+  };
+}
+
+async function checkSonarReachable(host) {
+  const reachable = await isSonarReachable(host);
+  if (reachable) {
+    return { name: "sonar-reachable", ok: true, detail: `SonarQube reachable at ${host}`, remediated: false };
+  }
+
+  // Auto-remediation: try to start SonarQube
+  try {
+    const upResult = await sonarUp(host);
+    if (upResult.exitCode === 0) {
+      // Verify it's actually reachable now
+      const reachableAfter = await isSonarReachable(host);
+      if (reachableAfter) {
+        return { name: "sonar-reachable", ok: true, detail: `SonarQube started and reachable at ${host}`, remediated: true };
+      }
+    }
+  } catch {
+    // sonarUp failed, fall through
+  }
+
+  return { name: "sonar-reachable", ok: false, detail: `SonarQube not reachable at ${host} (auto-start failed)` };
+}
+
+async function checkSonarAuth(config) {
+  const host = normalizeApiHost(config.sonarqube?.host);
+
+  // Check explicit token first
+  const explicitToken = process.env.KJ_SONAR_TOKEN || process.env.SONAR_TOKEN || config.sonarqube?.token;
+  if (explicitToken) {
+    // Validate the token works
+    const res = await runCommand("curl", [
+      "-sS", "-o", "/dev/null", "-w", "%{http_code}",
+      "-H", `Authorization: Bearer ${explicitToken}`,
+      "--max-time", "5",
+      `${host}/api/authentication/validate`
+    ]);
+    if (res.exitCode === 0 && res.stdout.trim().startsWith("2")) {
+      return { name: "sonar-auth", ok: true, detail: "Sonar token valid", token: explicitToken };
+    }
+  }
+
+  // Try admin credentials to generate a token
+  const adminUser = process.env.KJ_SONAR_ADMIN_USER || config.sonarqube?.admin_user || "admin";
+  const candidates = [
+    process.env.KJ_SONAR_ADMIN_PASSWORD,
+    config.sonarqube?.admin_password,
+    "admin"
+  ].filter(Boolean);
+
+  for (const password of [...new Set(candidates)]) {
+    const validateRes = await runCommand("curl", [
+      "-sS", "-u", `${adminUser}:${password}`,
+      `${host}/api/authentication/validate`
+    ]);
+    if (validateRes.exitCode !== 0) continue;
+    const parsed = parseJsonSafe(validateRes.stdout);
+    if (!parsed?.valid) continue;
+
+    // Generate a user token
+    const tokenName = `karajan-preflight-${Date.now()}`;
+    const tokenRes = await runCommand("curl", [
+      "-sS", "-u", `${adminUser}:${password}`,
+      "-X", "POST",
+      "--data-urlencode", `name=${tokenName}`,
+      `${host}/api/user_tokens/generate`
+    ]);
+    if (tokenRes.exitCode !== 0) continue;
+    const tokenParsed = parseJsonSafe(tokenRes.stdout);
+    if (tokenParsed?.token) {
+      return { name: "sonar-auth", ok: true, detail: "Sonar token generated", token: tokenParsed.token };
+    }
+  }
+
+  return { name: "sonar-auth", ok: false, detail: "Could not validate or generate Sonar token" };
+}
+
+async function checkSecurityAgent(config) {
+  const provider = config.roles?.security?.provider
+    || config.roles?.coder?.provider
+    || config.coder
+    || "claude";
+
+  const result = await checkBinary(provider);
+  return {
+    name: "security-agent",
+    ok: result.ok,
+    detail: result.ok ? `Security agent "${provider}" available (${result.version})` : `Security agent "${provider}" not found`,
+    provider,
+  };
+}
+
+/**
+ * Run preflight environment checks.
+ *
+ * @param {object} opts
+ * @param {object} opts.config - Karajan config
+ * @param {object} opts.logger - Logger instance
+ * @param {object|null} opts.emitter - Event emitter
+ * @param {object} opts.eventBase - Base event data
+ * @param {object} opts.resolvedPolicies - Output from applyPolicies()
+ * @param {boolean} opts.securityEnabled - Whether security stage is enabled
+ * @returns {{ ok: boolean, checks: object[], remediations: string[], configOverrides: object, warnings: string[] }}
+ */
+export async function runPreflightChecks({ config, logger, emitter, eventBase, resolvedPolicies, securityEnabled }) {
+  const sonarEnabled = Boolean(config.sonarqube?.enabled) && resolvedPolicies.sonar !== false;
+  const isExternalSonar = Boolean(config.sonarqube?.external);
+  const sonarHost = normalizeApiHost(config.sonarqube?.host);
+
+  const result = {
+    ok: true,
+    checks: [],
+    remediations: [],
+    configOverrides: {},
+    warnings: [],
+  };
+
+  // Short-circuit: nothing to check
+  if (!sonarEnabled && !securityEnabled) {
+    logger.info("Preflight: skipped (no sonar, no security)");
+    emitProgress(emitter, makeEvent("preflight:end", { ...eventBase, stage: "preflight" }, {
+      message: "Preflight skipped (no checks needed)",
+      detail: result
+    }));
+    return result;
+  }
+
+  emitProgress(emitter, makeEvent("preflight:start", { ...eventBase, stage: "preflight" }, {
+    message: "Running preflight environment checks",
+    detail: { sonarEnabled, securityEnabled }
+  }));
+
+  // --- 1. Docker (only if sonar enabled and not external) ---
+  if (sonarEnabled && !isExternalSonar) {
+    const dockerCheck = await checkDocker();
+    result.checks.push(dockerCheck);
+
+    emitProgress(emitter, makeEvent("preflight:check", { ...eventBase, stage: "preflight" }, {
+      status: dockerCheck.ok ? "ok" : "warn",
+      message: `Docker: ${dockerCheck.detail}`,
+      detail: dockerCheck
+    }));
+
+    if (!dockerCheck.ok) {
+      result.configOverrides.sonarDisabled = true;
+      result.warnings.push("Docker not available — SonarQube auto-disabled");
+      logger.warn("Preflight: Docker not found, disabling SonarQube");
+
+      // Skip remaining sonar checks, continue to security
+      if (!securityEnabled) {
+        emitProgress(emitter, makeEvent("preflight:end", { ...eventBase, stage: "preflight" }, {
+          status: "warn", message: "Preflight completed with warnings", detail: result
+        }));
+        return result;
+      }
+    }
+  }
+
+  // --- 2. SonarQube reachable ---
+  if (sonarEnabled && !result.configOverrides.sonarDisabled) {
+    const reachableCheck = await checkSonarReachable(sonarHost);
+    result.checks.push(reachableCheck);
+
+    if (reachableCheck.remediated) {
+      result.remediations.push("SonarQube auto-started via docker compose");
+    }
+
+    emitProgress(emitter, makeEvent("preflight:check", { ...eventBase, stage: "preflight" }, {
+      status: reachableCheck.ok ? "ok" : "warn",
+      message: `SonarQube reachability: ${reachableCheck.detail}`,
+      detail: reachableCheck
+    }));
+
+    if (!reachableCheck.ok) {
+      result.configOverrides.sonarDisabled = true;
+      result.warnings.push("SonarQube not reachable — auto-disabled");
+      logger.warn("Preflight: SonarQube not reachable after remediation, disabling");
+    }
+  }
+
+  // --- 3. SonarQube auth/token ---
+  if (sonarEnabled && !result.configOverrides.sonarDisabled) {
+    const authCheck = await checkSonarAuth(config);
+    result.checks.push(authCheck);
+
+    emitProgress(emitter, makeEvent("preflight:check", { ...eventBase, stage: "preflight" }, {
+      status: authCheck.ok ? "ok" : "warn",
+      message: `SonarQube auth: ${authCheck.detail}`,
+      detail: { name: authCheck.name, ok: authCheck.ok, detail: authCheck.detail }
+    }));
+
+    if (authCheck.ok && authCheck.token) {
+      process.env.KJ_SONAR_TOKEN = authCheck.token;
+      result.remediations.push("Sonar token resolved and cached in KJ_SONAR_TOKEN");
+      logger.info("Preflight: Sonar token resolved and cached");
+    } else if (!authCheck.ok) {
+      result.configOverrides.sonarDisabled = true;
+      result.warnings.push("SonarQube auth failed — auto-disabled");
+      logger.warn("Preflight: Sonar auth failed, disabling SonarQube");
+    }
+  }
+
+  // --- 4. Security agent ---
+  if (securityEnabled) {
+    const secCheck = await checkSecurityAgent(config);
+    result.checks.push(secCheck);
+
+    emitProgress(emitter, makeEvent("preflight:check", { ...eventBase, stage: "preflight" }, {
+      status: secCheck.ok ? "ok" : "warn",
+      message: `Security agent: ${secCheck.detail}`,
+      detail: secCheck
+    }));
+
+    if (!secCheck.ok) {
+      result.configOverrides.securityDisabled = true;
+      result.warnings.push(`Security agent "${secCheck.provider}" not found — security stage auto-disabled`);
+      logger.warn(`Preflight: Security agent "${secCheck.provider}" not found, disabling security stage`);
+    }
+  }
+
+  const hasWarnings = result.warnings.length > 0;
+  emitProgress(emitter, makeEvent("preflight:end", { ...eventBase, stage: "preflight" }, {
+    status: hasWarnings ? "warn" : "ok",
+    message: hasWarnings
+      ? `Preflight completed with ${result.warnings.length} warning(s)`
+      : "Preflight passed — all checks OK",
+    detail: result
+  }));
+
+  return result;
+}

package/src/orchestrator.js

@@ -34,6 +34,7 @@ import { runCoderStage, runRefactorerStage, runTddCheckStage, runSonarStage, run
 import { runTesterStage, runSecurityStage, runImpeccableStage } from "./orchestrator/post-loop-stages.js";
 import { waitForCooldown, MAX_STANDBY_RETRIES } from "./orchestrator/standby.js";
 import { detectTestFramework } from "./utils/project-detect.js";
+import { runPreflightChecks } from "./orchestrator/preflight-checks.js";
 
 
 // --- Extracted helper functions (pure refactoring, zero behavior change) ---
@@ -857,7 +858,23 @@ async function runPreLoopStages({ config, logger, emitter, eventBase, session, f
     }));
   }
 
-  const updatedConfig = resolvePipelinePolicies({ flags, config, stageResults, emitter, eventBase, session, pipelineFlags });
+  let updatedConfig = resolvePipelinePolicies({ flags, config, stageResults, emitter, eventBase, session, pipelineFlags });
+
+  // --- Preflight environment checks ---
+  const preflightResult = await runPreflightChecks({
+    config: updatedConfig, logger, emitter, eventBase,
+    resolvedPolicies: session.resolved_policies,
+    securityEnabled: pipelineFlags.securityEnabled
+  });
+  session.preflight = preflightResult;
+  await saveSession(session);
+
+  if (preflightResult.configOverrides.sonarDisabled) {
+    updatedConfig = { ...updatedConfig, sonarqube: { ...updatedConfig.sonarqube, enabled: false } };
+  }
+  if (preflightResult.configOverrides.securityDisabled) {
+    pipelineFlags.securityEnabled = false;
+  }
 
   // --- Researcher → Planner ---
   const { plannedTask } = await runPlanningPhases({ config: updatedConfig, logger, emitter, eventBase, session, stageResults, pipelineFlags, coderRole, trackBudget, task, askQuestion });