@karajan-family/code 4.21.0

package/src/mcp/shared-helpers.js

@@ -0,0 +1,297 @@
+/**
+ * Shared helpers used by MCP handler sub-modules.
+ * Extracted from server-handlers.js to break circular import chains
+ * (server-handlers.js ↔ handlers/*.js).
+ *
+ * Sub-handlers MUST import from here, NOT from server-handlers.js.
+ * server-handlers.js re-exports everything for external consumers.
+ */
+
+import { EventEmitter } from "node:events";
+import fs from "node:fs/promises";
+import { loadConfig, applyRunOverrides, validateConfig } from "../config.js";
+import { currentBranch } from "../utils/git.js";
+import { buildProgressNotifier } from "./progress.js";
+import { compressResponse, compactStringify } from "./response-compressor.js";
+import { classifyError } from "./error-classifiers.js";
+
+export { classifyError } from "./error-classifiers.js";
+
+/**
+ * Resolve the user's project directory.
+ * Priority: 1) explicit projectDir param, 2) MCP roots, 3) error with instructions.
+ */
+/**
+ * Resolve the `task` argument for MCP handlers. If the caller passed
+ * `a.taskFile` (instead of or in addition to `a.task`), read the file and
+ * set `a.task` to its trimmed content. When both are given, the explicit
+ * `a.task` wins (symmetric with CLI `resolveTaskInput`).
+ *
+ * Mutates `a` in place so downstream handlers keep reading `a.task`
+ * without any change. Returns `a` for convenience.
+ *
+ * @param {Object} a
+ * @param {string} [projectDir]  - used to resolve relative file paths
+ * @returns {Promise<Object>}    - the same `a`, with `a.task` filled in
+ */
+export async function ensureTaskFromFile(a, projectDir) {
+  if (!a) return a;
+  const hasTask = typeof a.task === "string" && a.task.trim().length > 0;
+  const hasFile = typeof a.taskFile === "string" && a.taskFile.trim().length > 0;
+  if (hasTask || !hasFile) return a;
+  const { readTaskFile } = await import("../utils/task-file.js");
+  a.task = await readTaskFile(a.taskFile, { projectDir });
+  return a;
+}
+
+export async function resolveProjectDir(server, explicitProjectDir) {
+  if (explicitProjectDir) return explicitProjectDir;
+
+  try {
+    const { roots } = await server.listRoots();
+    if (roots?.length > 0) {
+      const uri = roots[0].uri;
+      if (uri.startsWith("file://")) return new URL(uri).pathname;
+      return uri;
+    }
+  } catch { /* client may not support roots */ }
+
+  const cwd = process.cwd();
+  try {
+    const hasGit = await fs.access(`${cwd}/.git`).then(() => true).catch(() => false);
+    const hasPkg = await fs.access(`${cwd}/package.json`).then(() => true).catch(() => false);
+    if (hasGit || hasPkg) return cwd;
+  } catch { /* ignore */ }
+
+  throw new Error(
+    `Cannot determine project directory. The MCP server is running from "${cwd}" which does not appear to be your project. ` +
+    `Fix: pass the "projectDir" parameter with the absolute path to your project (e.g., projectDir: "/home/user/my-project"), ` +
+    `or run "kj init" inside your project directory.`
+  );
+}
+
+export function asObject(value) {
+  if (value && typeof value === "object") return value;
+  return {};
+}
+
+export function responseText(payload) {
+  const compressed = compressResponse(payload);
+  return {
+    content: [{ type: "text", text: compactStringify(compressed) }]
+  };
+}
+
+export function failPayload(message, details = {}) {
+  return {
+    ok: false,
+    error: message,
+    ...details
+  };
+}
+
+export async function assertNotOnBaseBranch(config, { allowForRun = false } = {}) {
+  const baseBranch = config?.base_branch || "main";
+  let branch;
+  try {
+    branch = await currentBranch();
+  } catch {
+    return; // No git repo or no commits — bootstrap/orchestrator will handle it
+  }
+  if (branch === baseBranch) {
+    // kj_run creates its own branch via prepareGitAutomation — allow it
+    if (allowForRun) return;
+    throw new Error(
+      `You are on the base branch '${baseBranch}'. Karajan needs a feature branch to compute the diff for review. ` +
+      `Create a new branch first (e.g. 'git checkout -b feat/<task-description>') and then run this command again. ` +
+      `Do NOT run kj_code directly — create the branch first so the full pipeline (code + review) works correctly.`
+    );
+  }
+}
+
+export function enrichedFailPayload(error, toolName) {
+  const msg = error?.message || String(error);
+  const { category, suggestion } = classifyError(error);
+  const payload = {
+    ok: false,
+    error: msg,
+    tool: toolName,
+    category
+  };
+  if (suggestion) payload.suggestion = suggestion;
+  return payload;
+}
+
+export async function buildConfig(options, commandName = "run") {
+  const { config } = await loadConfig();
+  const merged = applyRunOverrides(config, options || {});
+  validateConfig(merged, commandName);
+  return merged;
+}
+
+/**
+ * Parse a structured response from free-text input.
+ * Exported for testing.
+ * @param {string} raw — user's raw text answer
+ * @param {string} type — question type: "multi-select" | "select" | "confirm" | "text"
+ * @param {Array<{id: string, label: string}>} [options] — available options (for select types)
+ * @returns {string[]|string|boolean|null} parsed response
+ */
+export function parseStructuredResponse(raw, type, options = []) {
+  const trimmed = (raw || "").trim();
+  const lower = trimmed.toLowerCase();
+
+  if (type === "confirm") {
+    return ["yes", "y", "si", "sí", "1", "true"].includes(lower) ? true : false;
+  }
+
+  if (type === "text") {
+    return trimmed;
+  }
+
+  if (type === "select") {
+    const num = parseInt(trimmed, 10);
+    if (!isNaN(num) && num >= 1 && num <= options.length) {
+      return options[num - 1].id;
+    }
+    // Try matching by id directly
+    const match = options.find(o => o.id.toLowerCase() === lower);
+    return match ? match.id : (options[0]?.id || null);
+  }
+
+  if (type === "multi-select") {
+    if (lower === "all") return options.map(o => o.id);
+    if (lower === "none" || lower === "0") return [];
+
+    // Parse comma-separated numbers or ids
+    const parts = trimmed.split(/[,;\s]+/).map(p => p.trim()).filter(Boolean);
+    const selected = [];
+
+    for (const part of parts) {
+      const num = parseInt(part, 10);
+      if (!isNaN(num) && num >= 1 && num <= options.length) {
+        selected.push(options[num - 1].id);
+      } else {
+        const match = options.find(o => o.id.toLowerCase() === part.toLowerCase());
+        if (match) selected.push(match.id);
+      }
+    }
+
+    return selected;
+  }
+
+  return trimmed || null;
+}
+
+/**
+ * Format a structured question into a text message for elicitInput.
+ * @param {Object} question
+ * @returns {string}
+ */
+function formatStructuredQuestion(question) {
+  const lines = [question.message, ""];
+
+  if (question.options?.length) {
+    for (let i = 0; i < question.options.length; i++) {
+      const opt = question.options[i];
+      const marker = opt.default ? "*" : " ";
+      lines.push(`  ${i + 1}.${marker} ${opt.label}`);
+    }
+    lines.push("");
+  }
+
+  if (question.type === "multi-select") {
+    lines.push("(Enter numbers separated by commas, 'all', or 'none')");
+  } else if (question.type === "select") {
+    lines.push("(Enter a number)");
+  } else if (question.type === "confirm") {
+    lines.push("(yes/no)");
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Build an askQuestion function from an MCP server.
+ * Detects host capabilities and adapts behavior accordingly.
+ *
+ * The returned function has an `.interactive` boolean property indicating
+ * whether the host supports elicitation.
+ *
+ * Accepts both plain string questions (backward compatible) and structured
+ * question objects ({message, type, options, defaults}).
+ *
+ * @param {Object} server — MCP server instance
+ * @returns {Function & {interactive: boolean}}
+ */
+export function buildAskQuestion(server) {
+  const canElicit = Boolean(server.getClientCapabilities?.()?.elicitation);
+
+  const askQuestion = async (question) => {
+    const isStructured = question && typeof question === "object" && question.message;
+
+    // Non-interactive: return defaults or null
+    if (!canElicit) {
+      if (!isStructured) return null;
+      if (question.defaults) return question.defaults;
+      if (question.type === "confirm") return false;
+      return null;
+    }
+
+    // Build the message text
+    const message = isStructured
+      ? formatStructuredQuestion(question)
+      : question;
+
+    // Call elicitInput
+    let rawAnswer;
+    try {
+      const result = await server.elicitInput({
+        message,
+        requestedSchema: {
+          type: "object",
+          properties: {
+            answer: { type: "string", description: "Your response" }
+          },
+          required: ["answer"]
+        }
+      });
+      rawAnswer = result.action === "accept" ? result.content?.answer || null : null;
+    } catch {
+      return isStructured && question.defaults ? question.defaults : null;
+    }
+
+    if (rawAnswer === null) {
+      return isStructured && question.defaults ? question.defaults : null;
+    }
+
+    // Parse structured response
+    if (isStructured && question.type) {
+      return parseStructuredResponse(rawAnswer, question.type, question.options);
+    }
+
+    return rawAnswer;
+  };
+
+  askQuestion.interactive = canElicit;
+  return askQuestion;
+}
+
+const EVENT_LOG_LEVELS = {
+  "agent:stall": "warning",
+  "agent:heartbeat": "info"
+};
+
+export function buildDirectEmitter(server, runLog, extra) {
+  const emitter = new EventEmitter();
+  emitter.on("progress", (event) => {
+    try {
+      const level = EVENT_LOG_LEVELS[event.type] || "debug";
+      server.sendLoggingMessage({ level, logger: "karajan", data: event });
+    } catch { /* best-effort */ }
+    if (runLog) runLog.logEvent(event);
+  });
+  const progressNotifier = buildProgressNotifier(extra);
+  if (progressNotifier) emitter.on("progress", progressNotifier);
+  return emitter;
+}

package/src/mcp/sovereignty-guard.js

@@ -0,0 +1,112 @@
+/**
+ * Sovereignty guard for MCP inputs.
+ *
+ * Validates kj_run parameters and rejects host-AI attempts to override
+ * pipeline decisions that Karajan makes internally (triage, hu-reviewer, etc.).
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+/** Parameters that the host AI is allowed to pass through without restriction. */
+const ALLOWED_PARAMS = new Set([
+  "task", "projectDir", "pgTask", "pgProject",
+  "planner", "coder", "reviewer", "refactorer",
+  "plannerModel", "coderModel", "reviewerModel", "refactorerModel",
+  "enablePlanner", "enableReviewer", "enableRefactorer", "enableResearcher",
+  "enableTester", "enableSecurity", "enableImpeccable", "enablePerf",
+  "enableDiscover", "enableArchitect",
+  "architectModel", "huFile",
+  "enableSerena", "enableCi",
+  "reviewerFallback", "reviewerRetries",
+  "mode", "maxIterations", "maxIterationMinutes", "maxTotalMinutes",
+  "baseBranch", "baseRef", "methodology",
+  "autoCommit", "autoPush", "autoPr", "autoRebase", "branchPrefix",
+  "autoSimplify", "smartModels", "checkpointInterval",
+  "taskType", "quiet", "noSonar", "enableSonarcloud",
+  "kjHome", "sonarToken", "timeoutMs", "domain",
+  // Sovereign flags — validated below but still "known"
+  "enableTriage", "enableHuReviewer",
+]);
+
+const MIN_ITERATIONS = 1;
+const MAX_ITERATIONS = 10;
+const ACTIVE_SESSION_THRESHOLD_MS = 60_000;
+
+/**
+ * Check if a pipeline is already running for this project.
+ * Looks at .kj/run.log modification time.
+ *
+ * @param {string} projectDir - Project root directory
+ * @returns {{ active: boolean, message?: string }}
+ */
+export function checkActiveSession(projectDir) {
+  if (!projectDir) return { active: false };
+  const logPath = path.join(projectDir, ".kj", "run.log");
+  try {
+    const stat = fs.statSync(logPath);
+    const ageMs = Date.now() - stat.mtimeMs;
+    if (ageMs < ACTIVE_SESSION_THRESHOLD_MS) {
+      return {
+        active: true,
+        message:
+          "A pipeline is already running for this project. " +
+          "Wait for it to complete or use kj_status to check progress.",
+      };
+    }
+  } catch {
+    // File doesn't exist or can't be read — no active session
+  }
+  return { active: false };
+}
+
+/**
+ * Validate and sanitise kj_run parameters.
+ *
+ * @param {Record<string, unknown>} params - Raw parameters from the MCP call
+ * @param {{ projectDir?: string }} context - Runtime context
+ * @returns {{ params: Record<string, unknown>, warnings: string[], error?: string }}
+ */
+export function validateSovereignty(params, context = {}) {
+  const warnings = [];
+  const sanitized = { ...params };
+
+  // 1. Strip unknown parameters
+  for (const key of Object.keys(sanitized)) {
+    if (!ALLOWED_PARAMS.has(key)) {
+      warnings.push(`Unknown parameter "${key}" stripped`);
+      delete sanitized[key];
+    }
+  }
+
+  // 2. Sovereign flags — pipeline decides, not the host AI
+  if (sanitized.enableHuReviewer === false) {
+    warnings.push("Pipeline decides hu-reviewer activation, ignoring override");
+    delete sanitized.enableHuReviewer;
+  }
+
+  if (sanitized.enableTriage === false) {
+    warnings.push("Triage is mandatory, ignoring override");
+    delete sanitized.enableTriage;
+  }
+
+  // 3. Clamp maxIterations to [1, 10]
+  if (sanitized.maxIterations !== undefined) {
+    const n = Number(sanitized.maxIterations);
+    if (!Number.isFinite(n) || n < MIN_ITERATIONS) {
+      warnings.push(`maxIterations ${sanitized.maxIterations} clamped to ${MIN_ITERATIONS}`);
+      sanitized.maxIterations = MIN_ITERATIONS;
+    } else if (n > MAX_ITERATIONS) {
+      warnings.push(`maxIterations ${sanitized.maxIterations} clamped to ${MAX_ITERATIONS}`);
+      sanitized.maxIterations = MAX_ITERATIONS;
+    }
+  }
+
+  // 4. Active session detection
+  const session = checkActiveSession(context.projectDir);
+  if (session.active) {
+    return { params: sanitized, warnings, error: session.message };
+  }
+
+  return { params: sanitized, warnings };
+}

package/src/mcp/suggest-handler.js

@@ -0,0 +1,92 @@
+/**
+ * Handler for kj_suggest MCP tool.
+ * Allows the host AI to propose observations to Solomon without override power.
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { getSessionRoot } from "../utils/paths.js";
+import { setSuggestions, touch } from "../session/mutators.js";
+
+/**
+ * Find the most recent running session for a given projectDir.
+ * If projectDir is not provided, returns the most recent running session overall.
+ */
+async function findActiveSession(projectDir) {
+  const sessionRoot = getSessionRoot();
+  let entries;
+  try {
+    entries = await fs.readdir(sessionRoot, { withFileTypes: true });
+  } catch { /* session root dir may not exist */
+    return null;
+  }
+
+  const dirs = entries.filter(e => e.isDirectory()).map(e => e.name).sort();
+  // Walk backwards (most recent first)
+  for (let i = dirs.length - 1; i >= 0; i--) {
+    try {
+      const raw = await fs.readFile(path.join(sessionRoot, dirs[i], "session.json"), "utf8");
+      const session = JSON.parse(raw);
+      if (session.status !== "running") continue;
+      if (projectDir && session.projectDir && session.projectDir !== projectDir) continue;
+      return session;
+    } catch { /* session.json missing or malformed */
+      continue;
+    }
+  }
+  return null;
+}
+
+/**
+ * Handle a suggestion from the host AI.
+ * Logs it to the active session's suggestions array for Solomon to evaluate.
+ *
+ * @param {object} params
+ * @param {string} params.suggestion - The observation or proposal
+ * @param {string} [params.context] - Additional context
+ * @param {string} [params.projectDir] - Project directory to scope session lookup
+ * @returns {Promise<object>} Result with accepted status and message
+ */
+export async function handleSuggestion({ suggestion, context, projectDir }) {
+  if (!suggestion || typeof suggestion !== "string" || suggestion.trim() === "") {
+    return {
+      accepted: false,
+      reason: "Suggestion text is required and must be a non-empty string."
+    };
+  }
+
+  const session = await findActiveSession(projectDir);
+
+  if (!session) {
+    return {
+      accepted: false,
+      reason: "No active pipeline session. Suggestions are only evaluated during pipeline execution."
+    };
+  }
+
+  // Initialize suggestions array if not present
+  if (!Array.isArray(session.suggestions)) {
+    setSuggestions(session, []);
+  }
+
+  const entry = {
+    suggestion: suggestion.trim(),
+    context: context || null,
+    timestamp: new Date().toISOString()
+  };
+
+  session.suggestions.push(entry);
+
+  // Persist the updated session
+  const sessionRoot = getSessionRoot();
+  const sessionFile = path.join(sessionRoot, session.id, "session.json");
+  touch(session);
+  await fs.writeFile(sessionFile, JSON.stringify(session, null, 2), "utf8");
+
+  return {
+    accepted: true,
+    status: "logged",
+    sessionId: session.id,
+    message: "Suggestion logged for Solomon evaluation in next iteration. Solomon will decide whether to act on it."
+  };
+}

package/src/mcp/tool-arg-normalizers.js

@@ -0,0 +1,16 @@
+export function normalizePlanArgs(args = {}) {
+  const normalized = { ...args };
+
+  if (!normalized.planner && normalized.coder) {
+    normalized.planner = normalized.coder;
+  }
+
+  if (!normalized.plannerModel && normalized.coderModel) {
+    normalized.plannerModel = normalized.coderModel;
+  }
+
+  delete normalized.coder;
+  delete normalized.coderModel;
+
+  return normalized;
+}