karajan-code 1.3.0 → 1.4.0

package/README.md

@@ -36,7 +36,9 @@ Instead of running one AI agent and manually reviewing its output, `kj` chains a
 - **Review profiles** — standard, strict, relaxed, paranoid
 - **Budget tracking** — per-session token and cost monitoring with `--trace`
 - **Git automation** — auto-commit, auto-push, auto-PR after approval
-- **Session management** — pause/resume with fail-fast detection
+- **Session management** — pause/resume with fail-fast detection and automatic cleanup of expired sessions
+- **Plugin system** — extend with custom agents via `.karajan/plugins/`
+- **Retry with backoff** — automatic recovery from transient API errors (429, 5xx) with exponential backoff and jitter
 - **Planning Game integration** — optionally pair with [Planning Game](https://github.com/AgenteIA-Geniova/planning-game) for agile project management (tasks, sprints, estimation) — like Jira, but open-source and XP-native
 
 > **Best with MCP** — Karajan Code is designed to be used as an MCP server inside your AI agent (Claude, Codex, etc.). The agent sends tasks to `kj_run`, gets real-time progress notifications, and receives structured results — no copy-pasting needed.
@@ -428,7 +430,7 @@ Use `kj roles show <role>` to inspect any template. Create a project override to
 git clone https://github.com/manufosela/karajan-code.git
 cd karajan-code
 npm install
-npm test              # Run 761+ tests with Vitest
+npm test              # Run 899+ tests with Vitest
 npm run test:watch    # Watch mode
 npm run validate      # Lint + test
 ```
@@ -439,6 +441,7 @@ npm run validate      # Lint + test
 
 ## Links
 
+- [Website](https://karajancode.com) (also [kj-code.com](https://kj-code.com))
 - [Changelog](CHANGELOG.md)
 - [Security Policy](SECURITY.md)
 - [License (AGPL-3.0)](LICENSE)

package/docs/README.es.md

@@ -36,7 +36,9 @@ En lugar de ejecutar un agente de IA y revisar manualmente su output, `kj` encad
 - **Perfiles de revision** — standard, strict, relaxed, paranoid
 - **Tracking de presupuesto** — monitorizacion de tokens y costes por sesion con `--trace`
 - **Automatizacion Git** — auto-commit, auto-push, auto-PR tras aprobacion
-- **Gestion de sesiones** — pausa/reanudacion con deteccion fail-fast
+- **Gestion de sesiones** — pausa/reanudacion con deteccion fail-fast y limpieza automatica de sesiones expiradas
+- **Sistema de plugins** — extiende con agentes custom via `.karajan/plugins/`
+- **Retry con backoff** — recuperacion automatica ante errores transitorios de API (429, 5xx) con backoff exponencial y jitter
 - **Integracion con Planning Game** — combina opcionalmente con [Planning Game](https://github.com/AgenteIA-Geniova/planning-game) para gestion agil de proyectos (tareas, sprints, estimacion) — como Jira, pero open-source y nativo XP
 
 > **Mejor con MCP** — Karajan Code esta disenado para usarse como servidor MCP dentro de tu agente de IA (Claude, Codex, etc.). El agente envia tareas a `kj_run`, recibe notificaciones de progreso en tiempo real, y obtiene resultados estructurados — sin copiar y pegar.
@@ -227,7 +229,7 @@ Usa `kj roles show <rol>` para inspeccionar cualquier template. Crea un override
 git clone https://github.com/manufosela/karajan-code.git
 cd karajan-code
 npm install
-npm test              # Ejecutar 761+ tests con Vitest
+npm test              # Ejecutar 899+ tests con Vitest
 npm run test:watch    # Modo watch
 npm run validate      # Lint + test
 ```
@@ -238,6 +240,7 @@ npm run validate      # Lint + test
 
 ## Enlaces
 
+- [Web](https://karajancode.com) (tambien [kj-code.com](https://kj-code.com))
 - [Changelog](../CHANGELOG.md)
 - [Politica de seguridad](../SECURITY.md)
 - [Licencia (AGPL-3.0)](../LICENSE)

package/package.json

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

package/src/cli.js

@@ -71,6 +71,7 @@ program
   .option("--max-total-minutes <n>")
   .option("--base-branch <name>")
   .option("--base-ref <ref>")
+  .option("--coder-fallback <name>")
   .option("--reviewer-fallback <name>")
   .option("--reviewer-retries <n>")
   .option("--auto-commit")

package/src/config.js

@@ -33,7 +33,7 @@ const DEFAULTS = {
   review_rules: "./review-rules.md",
   coder_rules: "./coder-rules.md",
   base_branch: "main",
-  coder_options: { model: null, auto_approve: true },
+  coder_options: { model: null, auto_approve: true, fallback_coder: null },
   reviewer_options: {
     output_format: "json",
     require_schema: true,
@@ -240,6 +240,7 @@ export function applyRunOverrides(config, flags) {
   if (flags.maxIterationMinutes) out.session.max_iteration_minutes = Number(flags.maxIterationMinutes);
   if (flags.maxTotalMinutes) out.session.max_total_minutes = Number(flags.maxTotalMinutes);
   if (flags.baseBranch) out.base_branch = flags.baseBranch;
+  if (flags.coderFallback) out.coder_options.fallback_coder = flags.coderFallback;
   if (flags.reviewerFallback) out.reviewer_options.fallback_reviewer = flags.reviewerFallback;
   if (flags.reviewerRetries !== undefined) out.reviewer_options.retries = Number(flags.reviewerRetries);
   if (flags.autoCommit !== undefined) out.git.auto_commit = Boolean(flags.autoCommit);

package/src/orchestrator/agent-fallback.js

@@ -0,0 +1,83 @@
+import { createAgent } from "../agents/index.js";
+import { addCheckpoint } from "../session-store.js";
+import { detectRateLimit } from "../utils/rate-limit-detector.js";
+
+/**
+ * Run a coder-like role with fallback on rate limit.
+ * Tries the primary agent first. If it fails with a rate limit,
+ * switches to the fallback agent (if configured).
+ * Non-rate-limit failures stop immediately (no fallback).
+ *
+ * Returns { execResult, attempts, allRateLimited }
+ */
+export async function runCoderWithFallback({
+  coderName,
+  fallbackCoder,
+  config,
+  logger,
+  emitter,
+  RoleClass,
+  roleInput,
+  session,
+  iteration,
+  onAttemptResult
+}) {
+  const candidates = [coderName];
+  if (fallbackCoder && fallbackCoder !== coderName) {
+    candidates.push(fallbackCoder);
+  }
+
+  const attempts = [];
+  let allRateLimited = true;
+
+  for (const name of candidates) {
+    const agentConfig = {
+      ...config,
+      roles: { ...config.roles, coder: { ...config.roles?.coder, provider: name } }
+    };
+
+    const role = new RoleClass({ config: agentConfig, logger, emitter, createAgentFn: createAgent });
+    await role.init();
+
+    const execResult = await role.execute(roleInput);
+
+    if (onAttemptResult) {
+      await onAttemptResult({ coder: name, result: execResult.result });
+    }
+
+    const rateLimited = !execResult.ok && detectRateLimit({
+      stderr: execResult.result?.error || "",
+      stdout: execResult.result?.output || ""
+    }).isRateLimit;
+
+    attempts.push({
+      coder: name,
+      ok: execResult.ok,
+      rateLimited,
+      result: execResult.result,
+      execResult
+    });
+
+    await addCheckpoint(session, {
+      stage: "coder-attempt",
+      iteration,
+      coder: name,
+      ok: execResult.ok,
+      rateLimited
+    });
+
+    if (execResult.ok) {
+      return { execResult, attempts, allRateLimited: false };
+    }
+
+    // Only fallback on rate limit errors
+    if (!rateLimited) {
+      allRateLimited = false;
+      return { execResult: null, attempts, allRateLimited: false };
+    }
+
+    logger.warn(`Agent ${name} hit rate limit, trying fallback...`);
+  }
+
+  return { execResult: null, attempts, allRateLimited };
+}

package/src/orchestrator/iteration-stages.js

@@ -1,4 +1,5 @@
 import { createAgent } from "../agents/index.js";
+import { CoderRole } from "../roles/coder-role.js";
 import { RefactorerRole } from "../roles/refactorer-role.js";
 import { SonarRole } from "../roles/sonar-role.js";
 import { addCheckpoint, markSessionStatus, saveSession, pauseSession } from "../session-store.js";
@@ -7,7 +8,9 @@ import { evaluateTddPolicy } from "../review/tdd-policy.js";
 import { validateReviewResult } from "../review/schema.js";
 import { emitProgress, makeEvent } from "../utils/events.js";
 import { runReviewerWithFallback } from "./reviewer-fallback.js";
+import { runCoderWithFallback } from "./agent-fallback.js";
 import { invokeSolomon } from "./solomon-escalation.js";
+import { detectRateLimit } from "../utils/rate-limit-detector.js";
 
 export async function runCoderStage({ coderRoleInstance, coderRole, config, logger, emitter, eventBase, session, plannedTask, trackBudget, iteration }) {
   logger.setContext({ iteration, stage: "coder" });
@@ -35,8 +38,70 @@ export async function runCoderStage({ coderRoleInstance, coderRole, config, logg
   trackBudget({ role: "coder", provider: coderRole.provider, model: coderRole.model, result: coderExecResult.result, duration_ms: Date.now() - coderStart });
 
   if (!coderExecResult.ok) {
-    await markSessionStatus(session, "failed");
     const details = coderExecResult.result?.error || coderExecResult.summary || "unknown error";
+    const rateLimitCheck = detectRateLimit({
+      stderr: coderExecResult.result?.error || "",
+      stdout: coderExecResult.result?.output || ""
+    });
+
+    if (rateLimitCheck.isRateLimit) {
+      // Try fallback agent if configured
+      const fallbackCoder = config.coder_options?.fallback_coder;
+      if (fallbackCoder && fallbackCoder !== coderRole.provider) {
+        logger.warn(`Coder ${coderRole.provider} hit rate limit, falling back to ${fallbackCoder}`);
+        emitProgress(
+          emitter,
+          makeEvent("coder:fallback", { ...eventBase, stage: "coder" }, {
+            message: `Coder ${coderRole.provider} rate-limited, switching to ${fallbackCoder}`,
+            detail: { primary: coderRole.provider, fallback: fallbackCoder }
+          })
+        );
+
+        const fallbackResult = await runCoderWithFallback({
+          coderName: fallbackCoder,
+          fallbackCoder: null,
+          config,
+          logger,
+          emitter,
+          RoleClass: CoderRole,
+          roleInput: { task: plannedTask, reviewerFeedback: session.last_reviewer_feedback, sonarSummary: session.last_sonar_summary, onOutput: coderOnOutput },
+          session,
+          iteration,
+          onAttemptResult: ({ coder, result }) => {
+            trackBudget({ role: "coder", provider: coder, model: coderRole.model, result, duration_ms: Date.now() - coderStart });
+          }
+        });
+
+        if (fallbackResult.execResult?.ok) {
+          await addCheckpoint(session, { stage: "coder", iteration, note: `Coder completed via fallback (${fallbackCoder})` });
+          emitProgress(
+            emitter,
+            makeEvent("coder:end", { ...eventBase, stage: "coder" }, {
+              message: `Coder completed (fallback: ${fallbackCoder})`
+            })
+          );
+          return;
+        }
+      }
+
+      // No fallback or fallback also failed — pause
+      const question = `Agent ${coderRole.provider} hit a rate limit: ${rateLimitCheck.message}. Session paused until the token window resets.`;
+      await pauseSession(session, {
+        question,
+        context: { iteration, stage: "coder", reason: "rate_limit", agent: coderRole.provider, detail: rateLimitCheck.message }
+      });
+      emitProgress(
+        emitter,
+        makeEvent("coder:rate_limit", { ...eventBase, stage: "coder" }, {
+          status: "paused",
+          message: question,
+          detail: { agent: coderRole.provider, rateLimitMessage: rateLimitCheck.message, sessionId: session.id }
+        })
+      );
+      return { action: "pause", result: { paused: true, sessionId: session.id, question, context: "rate_limit" } };
+    }
+
+    await markSessionStatus(session, "failed");
     emitProgress(
       emitter,
       makeEvent("coder:end", { ...eventBase, stage: "coder" }, {
@@ -71,8 +136,30 @@ export async function runRefactorerStage({ refactorerRole, config, logger, emitt
   const refResult = await refRole.execute(plannedTask);
   trackBudget({ role: "refactorer", provider: refactorerRole.provider, model: refactorerRole.model, result: refResult.result, duration_ms: Date.now() - refactorerStart });
   if (!refResult.ok) {
-    await markSessionStatus(session, "failed");
     const details = refResult.result?.error || refResult.summary || "unknown error";
+    const rateLimitCheck = detectRateLimit({
+      stderr: refResult.result?.error || "",
+      stdout: refResult.result?.output || ""
+    });
+
+    if (rateLimitCheck.isRateLimit) {
+      const question = `Agent ${refactorerRole.provider} hit a rate limit: ${rateLimitCheck.message}. Session paused until the token window resets.`;
+      await pauseSession(session, {
+        question,
+        context: { iteration, stage: "refactorer", reason: "rate_limit", agent: refactorerRole.provider, detail: rateLimitCheck.message }
+      });
+      emitProgress(
+        emitter,
+        makeEvent("refactorer:rate_limit", { ...eventBase, stage: "refactorer" }, {
+          status: "paused",
+          message: question,
+          detail: { agent: refactorerRole.provider, rateLimitMessage: rateLimitCheck.message, sessionId: session.id }
+        })
+      );
+      return { action: "pause", result: { paused: true, sessionId: session.id, question, context: "rate_limit" } };
+    }
+
+    await markSessionStatus(session, "failed");
     emitProgress(
       emitter,
       makeEvent("refactorer:end", { ...eventBase, stage: "refactorer" }, {
@@ -318,12 +405,35 @@ export async function runReviewerStage({ reviewerRole, config, logger, emitter,
   });
 
   if (!reviewerExec.execResult || !reviewerExec.execResult.ok) {
-    await markSessionStatus(session, "failed");
     const lastAttempt = reviewerExec.attempts.at(-1);
     const details =
       lastAttempt?.result?.error ||
       lastAttempt?.execResult?.summary ||
       `reviewer=${lastAttempt?.reviewer || "unknown"}`;
+
+    const rateLimitCheck = detectRateLimit({
+      stderr: lastAttempt?.result?.error || "",
+      stdout: lastAttempt?.result?.output || ""
+    });
+
+    if (rateLimitCheck.isRateLimit) {
+      const question = `Reviewer ${reviewerRole.provider} hit a rate limit: ${rateLimitCheck.message}. Session paused until the token window resets.`;
+      await pauseSession(session, {
+        question,
+        context: { iteration, stage: "reviewer", reason: "rate_limit", agent: reviewerRole.provider, detail: rateLimitCheck.message }
+      });
+      emitProgress(
+        emitter,
+        makeEvent("reviewer:rate_limit", { ...eventBase, stage: "reviewer" }, {
+          status: "paused",
+          message: question,
+          detail: { agent: reviewerRole.provider, rateLimitMessage: rateLimitCheck.message, sessionId: session.id }
+        })
+      );
+      return { action: "pause", result: { paused: true, sessionId: session.id, question, context: "rate_limit" } };
+    }
+
+    await markSessionStatus(session, "failed");
     emitProgress(
       emitter,
       makeEvent("reviewer:end", { ...eventBase, stage: "reviewer" }, {

package/src/orchestrator.js

@@ -255,11 +255,17 @@ export async function runFlow({ task, config, logger, flags = {}, emitter = null
     logger.info(`Iteration ${i}/${config.max_iterations}`);
 
     // --- Coder ---
-    await runCoderStage({ coderRoleInstance, coderRole, config, logger, emitter, eventBase, session, plannedTask, trackBudget, iteration: i });
+    const coderResult = await runCoderStage({ coderRoleInstance, coderRole, config, logger, emitter, eventBase, session, plannedTask, trackBudget, iteration: i });
+    if (coderResult?.action === "pause") {
+      return coderResult.result;
+    }
 
     // --- Refactorer ---
     if (refactorerEnabled) {
-      await runRefactorerStage({ refactorerRole, config, logger, emitter, eventBase, session, plannedTask, trackBudget, iteration: i });
+      const refResult = await runRefactorerStage({ refactorerRole, config, logger, emitter, eventBase, session, plannedTask, trackBudget, iteration: i });
+      if (refResult?.action === "pause") {
+        return refResult.result;
+      }
     }
 
     // --- TDD Policy ---
@@ -302,6 +308,9 @@ export async function runFlow({ task, config, logger, flags = {}, emitter = null
         reviewerRole, config, logger, emitter, eventBase, session, trackBudget,
         iteration: i, reviewRules, task, repeatDetector, budgetSummary
       });
+      if (reviewerResult.action === "pause") {
+        return reviewerResult.result;
+      }
       review = reviewerResult.review;
       if (reviewerResult.stalled) {
         return reviewerResult.stalledResult;

package/src/utils/rate-limit-detector.js

@@ -0,0 +1,43 @@
+/**
+ * Detects rate limit / usage cap messages from CLI agent output.
+ * Returns { isRateLimit, agent, message } where agent is the best guess
+ * of which CLI triggered it (or "unknown").
+ */
+
+const RATE_LIMIT_PATTERNS = [
+  // Claude CLI
+  { pattern: /usage limit/i, agent: "claude" },
+  { pattern: /plan's usage limit/i, agent: "claude" },
+  { pattern: /Claude Pro usage limit/i, agent: "claude" },
+
+  // OpenAI / Codex CLI
+  { pattern: /exceeded your current quota/i, agent: "codex" },
+
+  // Gemini CLI
+  { pattern: /resource exhausted/i, agent: "gemini" },
+  { pattern: /quota exceeded/i, agent: "gemini" },
+
+  // Generic (match any agent)
+  { pattern: /rate limit/i, agent: "unknown" },
+  { pattern: /token limit reached/i, agent: "unknown" },
+  { pattern: /\b429\b/, agent: "unknown" },
+  { pattern: /too many requests/i, agent: "unknown" },
+  { pattern: /throttl/i, agent: "unknown" },
+];
+
+export function detectRateLimit({ stderr = "", stdout = "" }) {
+  const combined = `${stderr}\n${stdout}`;
+
+  for (const { pattern, agent } of RATE_LIMIT_PATTERNS) {
+    if (pattern.test(combined)) {
+      const matchedLine = combined.split("\n").find((l) => pattern.test(l)) || combined.trim();
+      return {
+        isRateLimit: true,
+        agent,
+        message: matchedLine.trim()
+      };
+    }
+  }
+
+  return { isRateLimit: false, agent: "", message: "" };
+}