karajan-code 1.2.2 → 1.3.0

package/src/planning-game/client.js

@@ -9,6 +9,8 @@
  * Requires planning_game.api_url in config or PG_API_URL env var.
  */
 
+import { withRetry, isTransientError } from "../utils/retry.js";
+
 const DEFAULT_API_URL = "http://localhost:3000/api";
 const DEFAULT_TIMEOUT_MS = 10000;
 
@@ -20,10 +22,20 @@ async function fetchWithTimeout(url, options = {}, timeoutMs = DEFAULT_TIMEOUT_M
   const controller = new AbortController();
   const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
   try {
-    return await fetch(url, { ...options, signal: controller.signal });
+    const response = await fetch(url, { ...options, signal: controller.signal });
+    if (!response.ok) {
+      const err = new Error(`Planning Game API error: ${response.status} ${response.statusText}`);
+      err.httpStatus = response.status;
+      err.retryAfter = response.headers?.get?.("retry-after") || null;
+      throw err;
+    }
+    return response;
   } catch (error) {
+    if (error?.httpStatus) throw error;
     if (error?.name === "AbortError") {
-      throw new Error(`Planning Game API timeout after ${timeoutMs}ms`);
+      const err = new Error(`Planning Game API timeout after ${timeoutMs}ms`);
+      err.httpStatus = 408;
+      throw err;
     }
     throw new Error(`Planning Game network error: ${error?.message || "unknown error"}`);
   } finally {
@@ -31,6 +43,13 @@ async function fetchWithTimeout(url, options = {}, timeoutMs = DEFAULT_TIMEOUT_M
   }
 }
 
+async function fetchWithRetry(url, options = {}, timeoutMs = DEFAULT_TIMEOUT_MS, retryOpts = {}) {
+  return withRetry(
+    () => fetchWithTimeout(url, options, timeoutMs),
+    { maxAttempts: 3, initialBackoffMs: 1000, ...retryOpts }
+  );
+}
+
 async function parseJsonResponse(response) {
   try {
     return await response.json();
@@ -41,10 +60,7 @@ async function parseJsonResponse(response) {
 
 export async function fetchCard({ projectId, cardId, timeoutMs = DEFAULT_TIMEOUT_MS }) {
   const url = `${getApiUrl()}/projects/${encodeURIComponent(projectId)}/cards/${encodeURIComponent(cardId)}`;
-  const response = await fetchWithTimeout(url, {}, timeoutMs);
-  if (!response.ok) {
-    throw new Error(`Planning Game API error: ${response.status} ${response.statusText}`);
-  }
+  const response = await fetchWithRetry(url, {}, timeoutMs);
   const data = await parseJsonResponse(response);
   return data?.card || data;
 }
@@ -55,27 +71,21 @@ export async function getCard({ projectId, cardId, timeoutMs = DEFAULT_TIMEOUT_M
 
 export async function listCards({ projectId, timeoutMs = DEFAULT_TIMEOUT_MS }) {
   const url = `${getApiUrl()}/projects/${encodeURIComponent(projectId)}/cards`;
-  const response = await fetchWithTimeout(url, {}, timeoutMs);
-  if (!response.ok) {
-    throw new Error(`Planning Game API error: ${response.status} ${response.statusText}`);
-  }
+  const response = await fetchWithRetry(url, {}, timeoutMs);
   const data = await parseJsonResponse(response);
   return data?.cards || data;
 }
 
 export async function updateCard({ projectId, cardId, firebaseId, updates, timeoutMs = DEFAULT_TIMEOUT_MS }) {
   const url = `${getApiUrl()}/projects/${encodeURIComponent(projectId)}/cards/${encodeURIComponent(firebaseId)}`;
-  const response = await fetchWithTimeout(
+  const response = await fetchWithRetry(
     url,
     {
-    method: "PATCH",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({ updates })
+      method: "PATCH",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ updates })
     },
     timeoutMs
   );
-  if (!response.ok) {
-    throw new Error(`Planning Game API error: ${response.status} ${response.statusText}`);
-  }
   return parseJsonResponse(response);
 }

package/src/plugins/loader.js

@@ -0,0 +1,67 @@
+/**
+ * Plugin loader: discovers and loads plugins from .karajan/plugins/ directories.
+ *
+ * Plugins are JS files that export a `register(api)` function.
+ * The `api` object provides: registerAgent, registerModel.
+ *
+ * Discovery order (all are loaded, not first-wins):
+ *   1. <project>/.karajan/plugins/*.js
+ *   2. ~/.karajan/plugins/*.js
+ */
+
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { getKarajanHome } from "../utils/paths.js";
+import { registerAgent } from "../agents/index.js";
+
+async function listPluginFiles(dir) {
+  try {
+    const { readdir } = await import("node:fs/promises");
+    const entries = await readdir(dir, { withFileTypes: true });
+    return entries
+      .filter((e) => e.isFile() && e.name.endsWith(".js"))
+      .map((e) => path.join(dir, e.name));
+  } catch {
+    return [];
+  }
+}
+
+async function loadPlugin(filePath, api, logger) {
+  try {
+    const mod = await import(pathToFileURL(filePath).href);
+    const registerFn = mod.register || mod.default?.register;
+    if (typeof registerFn !== "function") {
+      logger?.warn?.(`Plugin ${filePath}: no register() export found, skipping`);
+      return null;
+    }
+    const meta = registerFn(api);
+    const name = meta?.name || path.basename(filePath, ".js");
+    logger?.debug?.(`Plugin loaded: ${name} (${filePath})`);
+    return { name, path: filePath, meta };
+  } catch (error) {
+    logger?.warn?.(`Plugin ${filePath} failed to load: ${error.message}`);
+    return null;
+  }
+}
+
+export async function loadPlugins({ projectDir, logger } = {}) {
+  const dirs = [];
+
+  if (projectDir) {
+    dirs.push(path.join(projectDir, ".karajan", "plugins"));
+  }
+  dirs.push(path.join(getKarajanHome(), "plugins"));
+
+  const api = { registerAgent };
+
+  const loaded = [];
+  for (const dir of dirs) {
+    const files = await listPluginFiles(dir);
+    for (const file of files) {
+      const result = await loadPlugin(file, api, logger);
+      if (result) loaded.push(result);
+    }
+  }
+
+  return loaded;
+}

package/src/prompts/planner.js

@@ -1,3 +1,54 @@
+export function parsePlannerOutput(output) {
+  const text = String(output || "").trim();
+  if (!text) return null;
+
+  const lines = text
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean);
+
+  let title = null;
+  let approach = null;
+  const steps = [];
+
+  for (const line of lines) {
+    if (!title) {
+      const titleMatch = line.match(/^title\s*:\s*(.+)$/i);
+      if (titleMatch) {
+        title = titleMatch[1].trim();
+        continue;
+      }
+    }
+
+    if (!approach) {
+      const approachMatch = line.match(/^(approach|strategy)\s*:\s*(.+)$/i);
+      if (approachMatch) {
+        approach = approachMatch[2].trim();
+        continue;
+      }
+    }
+
+    const numberedStep = line.match(/^\d+[\).:-]\s*(.+)$/);
+    if (numberedStep) {
+      steps.push(numberedStep[1].trim());
+      continue;
+    }
+
+    const bulletStep = line.match(/^[-*]\s+(.+)$/);
+    if (bulletStep) {
+      steps.push(bulletStep[1].trim());
+      continue;
+    }
+  }
+
+  if (!title) {
+    const firstFreeLine = lines.find((line) => !/^(approach|strategy)\s*:/i.test(line) && !/^\d+[\).:-]\s*/.test(line));
+    title = firstFreeLine || null;
+  }
+
+  return { title, approach, steps };
+}
+
 export function buildPlannerPrompt({ task, context }) {
   const parts = [
     "You are an expert software architect. Create an implementation plan for the following task.",

package/src/repeat-detector.js

@@ -40,6 +40,17 @@ function parseThreshold(value) {
   return DEFAULT_THRESHOLD;
 }
 
+export function getRepeatThreshold(config) {
+  const raw =
+    config?.failFast?.repeatThreshold ??
+    config?.session?.repeat_detection_threshold ??
+    config?.session?.fail_fast_repeats ??
+    2;
+  const value = Number(raw);
+  if (Number.isFinite(value) && value > 0) return value;
+  return 2;
+}
+
 export class RepeatDetector {
   constructor({ threshold = DEFAULT_THRESHOLD } = {}) {
     this.threshold = parseThreshold(threshold);

package/src/roles/coder-role.js

@@ -29,7 +29,8 @@ export class CoderRole extends BaseRole {
       reviewerFeedback: reviewerFeedback || null,
       sonarSummary: sonarSummary || null,
       coderRules: this.instructions,
-      methodology: this.config?.development?.methodology || "tdd"
+      methodology: this.config?.development?.methodology || "tdd",
+      serenaEnabled: Boolean(this.config?.serena?.enabled)
     });
 
     const coderArgs = { prompt, role: "coder" };
@@ -41,6 +42,7 @@ export class CoderRole extends BaseRole {
       return {
         ok: false,
         result: {
+          ...result,
           error: result.error || result.output || "Coder failed",
           provider
         },
@@ -51,6 +53,7 @@ export class CoderRole extends BaseRole {
     return {
       ok: true,
       result: {
+        ...result,
         output: result.output || "",
         provider
       },

package/src/roles/planner-role.js

@@ -66,7 +66,7 @@ export class PlannerRole extends BaseRole {
     if (!result.ok) {
       return {
         ok: false,
-        result: { error: result.error || result.output || "Planner agent failed", plan: null },
+        result: { ...result, error: result.error || result.output || "Planner agent failed", plan: null },
         summary: `Planner failed: ${result.error || "unknown error"}`
       };
     }
@@ -74,7 +74,7 @@ export class PlannerRole extends BaseRole {
     const plan = result.output?.trim() || "";
     return {
       ok: true,
-      result: { plan, provider },
+      result: { ...result, plan, provider },
       summary: plan ? `Plan generated (${plan.split("\n").length} lines)` : "Empty plan generated"
     };
   }

package/src/roles/refactorer-role.js

@@ -47,6 +47,7 @@ export class RefactorerRole extends BaseRole {
       return {
         ok: false,
         result: {
+          ...result,
           error: result.error || result.output || "Refactorer failed",
           provider
         },
@@ -57,6 +58,7 @@ export class RefactorerRole extends BaseRole {
     return {
       ok: true,
       result: {
+        ...result,
         output: result.output?.trim() || "",
         provider
       },

package/src/roles/reviewer-role.js

@@ -101,29 +101,36 @@ export class ReviewerRole extends BaseRole {
 
     try {
       const parsed = parseReviewOutput(result.output);
-      const approved = Boolean(parsed.approved);
       const blockingIssues = parsed.blocking_issues || [];
 
       return {
         ok: true,
         result: {
-          approved,
+          ...result,
+          approved: parsed.approved,
           blocking_issues: blockingIssues,
           non_blocking_suggestions: parsed.non_blocking_suggestions || [],
           confidence: parsed.confidence ?? null,
           raw_summary: parsed.summary || ""
         },
-        summary: approved
+        summary: parsed.approved
           ? `Approved: ${parsed.summary || "no issues found"}`
           : `Rejected: ${blockingIssues.length} blocking issue(s) — ${parsed.summary || ""}`
       };
     } catch (err) {
       return {
-        ok: false,
+        ok: true,
         result: {
-          error: `Failed to parse reviewer output: ${err.message}`,
+          ...result,
           approved: false,
-          blocking_issues: []
+          blocking_issues: [{
+            id: "PARSE_ERROR",
+            severity: "high",
+            description: `Reviewer output could not be parsed: ${err.message}`
+          }],
+          non_blocking_suggestions: [],
+          confidence: 0,
+          raw_summary: `Parse error: ${err.message}`
         },
         summary: `Reviewer output parse error: ${err.message}`
       };

package/src/session-cleanup.js

@@ -0,0 +1,63 @@
+/**
+ * Automatic cleanup of expired sessions.
+ * Removes session directories older than session.expiry_days (default: 30).
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { getSessionRoot } from "./utils/paths.js";
+
+const DEFAULT_EXPIRY_DAYS = 30;
+
+export async function cleanupExpiredSessions({ config, logger } = {}) {
+  const expiryDays = config?.session?.expiry_days ?? DEFAULT_EXPIRY_DAYS;
+  if (expiryDays <= 0) return { removed: 0, errors: [] };
+
+  const sessionRoot = getSessionRoot();
+  const cutoff = Date.now() - expiryDays * 24 * 60 * 60 * 1000;
+
+  let entries;
+  try {
+    entries = await fs.readdir(sessionRoot, { withFileTypes: true });
+  } catch {
+    return { removed: 0, errors: [] };
+  }
+
+  const dirs = entries.filter((e) => e.isDirectory() && e.name.startsWith("s_"));
+  const removed = [];
+  const errors = [];
+
+  for (const dir of dirs) {
+    const sessionDir = path.join(sessionRoot, dir.name);
+    const sessionFile = path.join(sessionDir, "session.json");
+
+    try {
+      const raw = await fs.readFile(sessionFile, "utf8");
+      const session = JSON.parse(raw);
+      const updatedAt = new Date(session.updated_at || session.created_at).getTime();
+
+      if (updatedAt < cutoff) {
+        await fs.rm(sessionDir, { recursive: true, force: true });
+        removed.push(dir.name);
+        logger?.debug?.(`Session expired and removed: ${dir.name}`);
+      }
+    } catch (error) {
+      const stat = await fs.stat(sessionDir).catch(() => null);
+      if (stat && stat.mtimeMs < cutoff) {
+        try {
+          await fs.rm(sessionDir, { recursive: true, force: true });
+          removed.push(dir.name);
+          logger?.debug?.(`Orphan session dir removed: ${dir.name}`);
+        } catch (rmErr) {
+          errors.push({ session: dir.name, error: rmErr.message });
+        }
+      }
+    }
+  }
+
+  if (removed.length > 0) {
+    logger?.info?.(`Cleaned up ${removed.length} expired session(s)`);
+  }
+
+  return { removed: removed.length, errors };
+}

package/src/sonar/api.js

@@ -1,4 +1,5 @@
 import { runCommand } from "../utils/process.js";
+import { withRetry } from "../utils/retry.js";
 import { resolveSonarProjectKey } from "./project-key.js";
 
 export class SonarApiError extends Error {
@@ -22,16 +23,18 @@ function parseHttpResponse(stdout) {
   return { httpCode, body };
 }
 
-async function sonarFetch(config, urlPath) {
+async function sonarFetchOnce(config, urlPath) {
   const token = tokenFromConfig(config);
   const url = `${config.sonarqube.host}${urlPath}`;
   const res = await runCommand("curl", ["-s", "-w", "\n%{http_code}", "-u", `${token}:`, url]);
 
   if (res.exitCode !== 0) {
-    throw new SonarApiError(
+    const err = new SonarApiError(
       `SonarQube is not reachable at ${config.sonarqube.host}. Check that SonarQube is running ('kj sonar start').`,
       { url, hint: "Run 'kj sonar start' or verify Docker is running." }
     );
+    err.httpStatus = 503;
+    throw err;
   }
 
   const { httpCode, body } = parseHttpResponse(res.stdout);
@@ -44,15 +47,25 @@ async function sonarFetch(config, urlPath) {
   }
 
   if (httpCode >= 400) {
-    throw new SonarApiError(
+    const err = new SonarApiError(
       `SonarQube API returned HTTP ${httpCode} for ${url}.`,
       { url, httpStatus: httpCode }
     );
+    err.httpStatus = httpCode;
+    throw err;
   }
 
   return body;
 }
 
+async function sonarFetch(config, urlPath) {
+  const maxAttempts = config.sonarqube?.max_scan_retries ?? 3;
+  return withRetry(
+    () => sonarFetchOnce(config, urlPath),
+    { maxAttempts, initialBackoffMs: 2000, maxBackoffMs: 15000 }
+  );
+}
+
 export async function getQualityGateStatus(config, projectKey = null) {
   const effectiveProjectKey = await resolveSonarProjectKey(config, { projectKey });
   const body = await sonarFetch(config, `/api/qualitygates/project_status?projectKey=${effectiveProjectKey}`);

package/src/utils/budget.js

@@ -1,5 +1,35 @@
 import { calculateUsageCostUsd, DEFAULT_MODEL_PRICING, mergePricing } from "./pricing.js";
 
+export function extractUsageMetrics(result, defaultModel = null) {
+  const usage = result?.usage || result?.metrics || {};
+  const tokens_in =
+    result?.tokens_in ??
+    usage?.tokens_in ??
+    usage?.input_tokens ??
+    usage?.prompt_tokens ??
+    0;
+  const tokens_out =
+    result?.tokens_out ??
+    usage?.tokens_out ??
+    usage?.output_tokens ??
+    usage?.completion_tokens ??
+    0;
+  const cost_usd =
+    result?.cost_usd ??
+    usage?.cost_usd ??
+    usage?.usd_cost ??
+    usage?.cost;
+  const model =
+    result?.model ??
+    usage?.model ??
+    usage?.model_name ??
+    usage?.model_id ??
+    defaultModel ??
+    null;
+
+  return { tokens_in, tokens_out, cost_usd, model };
+}
+
 function toSafeNumber(value) {
   const n = Number(value);
   if (!Number.isFinite(n) || n < 0) return 0;

package/src/utils/pricing.js

@@ -1,16 +1,6 @@
-export const DEFAULT_MODEL_PRICING = {
-  "claude": { input_per_million: 3, output_per_million: 15 },
-  "claude/sonnet": { input_per_million: 3, output_per_million: 15 },
-  "claude/opus": { input_per_million: 15, output_per_million: 75 },
-  "claude/haiku": { input_per_million: 0.25, output_per_million: 1.25 },
-  "codex": { input_per_million: 1.5, output_per_million: 4 },
-  "codex/o4-mini": { input_per_million: 1.5, output_per_million: 4 },
-  "codex/o3": { input_per_million: 10, output_per_million: 40 },
-  "gemini": { input_per_million: 1.25, output_per_million: 5 },
-  "gemini/pro": { input_per_million: 1.25, output_per_million: 5 },
-  "gemini/flash": { input_per_million: 0.075, output_per_million: 0.3 },
-  "aider": { input_per_million: 3, output_per_million: 15 }
-};
+import { buildDefaultPricingTable } from "../agents/model-registry.js";
+
+export const DEFAULT_MODEL_PRICING = buildDefaultPricingTable();
 
 export function calculateUsageCostUsd({ model, tokens_in, tokens_out, pricing }) {
   const table = pricing || DEFAULT_MODEL_PRICING;

package/src/utils/retry.js

@@ -0,0 +1,88 @@
+/**
+ * Generic retry utility with exponential backoff and jitter.
+ * Handles transient errors (429, 502, 503, timeouts) automatically.
+ */
+
+const TRANSIENT_HTTP_CODES = new Set([408, 429, 500, 502, 503, 504]);
+
+const TRANSIENT_ERROR_PATTERNS = [
+  "ETIMEDOUT", "ECONNREFUSED", "ECONNRESET", "EPIPE",
+  "ENETUNREACH", "EAI_AGAIN", "EHOSTUNREACH",
+  "socket hang up", "network error", "fetch failed"
+];
+
+const DEFAULT_OPTIONS = {
+  maxAttempts: 3,
+  initialBackoffMs: 1000,
+  maxBackoffMs: 30000,
+  backoffMultiplier: 2,
+  jitterFactor: 0.1,
+  onRetry: null
+};
+
+export function isTransientError(error) {
+  if (!error) return false;
+
+  if (error.httpStatus && TRANSIENT_HTTP_CODES.has(error.httpStatus)) return true;
+  if (error.status && TRANSIENT_HTTP_CODES.has(error.status)) return true;
+
+  const msg = (error.message || String(error)).toLowerCase();
+  return TRANSIENT_ERROR_PATTERNS.some((p) => msg.includes(p.toLowerCase()));
+}
+
+export function parseRetryAfter(headerValue) {
+  if (!headerValue) return null;
+  const seconds = Number(headerValue);
+  if (!Number.isNaN(seconds) && seconds > 0) return seconds * 1000;
+
+  const date = Date.parse(headerValue);
+  if (!Number.isNaN(date)) {
+    const delayMs = date - Date.now();
+    return delayMs > 0 ? delayMs : null;
+  }
+  return null;
+}
+
+export function calculateBackoff(attempt, options = {}) {
+  const { initialBackoffMs = 1000, maxBackoffMs = 30000, backoffMultiplier = 2, jitterFactor = 0.1 } = options;
+
+  const base = initialBackoffMs * Math.pow(backoffMultiplier, attempt);
+  const capped = Math.min(base, maxBackoffMs);
+  const jitter = capped * jitterFactor * (Math.random() * 2 - 1);
+  return Math.max(0, Math.round(capped + jitter));
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export async function withRetry(fn, options = {}) {
+  const opts = { ...DEFAULT_OPTIONS, ...options };
+  let lastError;
+
+  for (let attempt = 0; attempt < opts.maxAttempts; attempt++) {
+    try {
+      return await fn(attempt);
+    } catch (error) {
+      lastError = error;
+
+      if (attempt >= opts.maxAttempts - 1) break;
+      if (!isTransientError(error)) break;
+
+      let delayMs = calculateBackoff(attempt, opts);
+
+      const retryAfterMs = parseRetryAfter(error.retryAfter || error.headers?.get?.("retry-after"));
+      if (retryAfterMs) {
+        delayMs = Math.min(retryAfterMs, opts.maxBackoffMs);
+      }
+
+      if (opts.onRetry) {
+        opts.onRetry({ attempt, error, delayMs, maxAttempts: opts.maxAttempts });
+      }
+
+      await sleep(delayMs);
+    }
+  }
+
+  throw lastError;
+}