@karajan-family/code 4.21.0

package/src/mcp/handlers/direct-handlers.js

@@ -0,0 +1,486 @@
+/**
+ * Direct role handler logic (code, review, plan, audit, discover, triage, researcher, architect, impeccable).
+ * Extracted from server-handlers.js for maintainability.
+ */
+
+import fs from "node:fs/promises";
+import { resolveRole } from "../../config.js";
+import { createLogger } from "../../utils/logger.js";
+import { assertAgentsAvailable } from "../../agents/availability.js";
+import { createAgent } from "../../agents/index.js";
+import { buildPlannerPrompt } from "../../prompts/planner.js";
+import { buildCoderPrompt } from "../../prompts/coder.js";
+import { buildReviewerPrompt } from "../../prompts/reviewer.js";
+import { parseMaybeJsonString } from "../../review/parser.js";
+import { computeBaseRef, generateDiff } from "../../review/diff-generator.js";
+import { resolveReviewProfile } from "../../review/profiles.js";
+import { createRunLog } from "../../utils/run-log.js";
+import { createStallDetector } from "../../utils/stall-detector.js";
+import { sendTrackerLog } from "../progress.js";
+import { runDirectRole } from "../direct-role-runner.js";
+import { isPreflightAcked, ackPreflight, getSessionOverrides } from "../preflight.js";
+import { ensureBootstrap } from "../../bootstrap.js";
+import { loadConfig } from "../../config.js";
+import {
+  resolveProjectDir,
+  failPayload,
+  assertNotOnBaseBranch,
+  buildConfig,
+  buildDirectEmitter,
+  ensureTaskFromFile,
+} from "../shared-helpers.js";
+
+/**
+ * Run bootstrap gate: validate all environment prerequisites before execution.
+ */
+async function runBootstrapGate(server, a) {
+  const projectDir = await resolveProjectDir(server, a.projectDir);
+  const { config } = await loadConfig(projectDir);
+  await ensureBootstrap(projectDir, config);
+}
+
+function applySessionOverrides(a, roleKeys) {
+  const sessionOvr = getSessionOverrides();
+  for (const key of roleKeys) {
+    if (sessionOvr[key] !== undefined) { a[key] = sessionOvr[key]; }
+  }
+}
+
+export async function handlePlanDirect(a, server, extra) {
+  // KJC-PCS-0048 PR 3b: same `specReviewMode: skip` → skipSpecReview
+  // mapping as kj_run. Default "auto" keeps the reviewer enabled.
+  if (a.specReviewMode === "skip") a.skipSpecReview = true;
+  const { normalizePlanArgs } = await import("../tool-arg-normalizers.js");
+  const options = normalizePlanArgs(a);
+  const config = await buildConfig(options, "plan");
+  const logger = createLogger(config.output.log_level, "mcp");
+
+  const plannerRole = resolveRole(config, "planner");
+  await assertAgentsAvailable([plannerRole.provider]);
+
+  const projectDir = await resolveProjectDir(server, a.projectDir);
+  await ensureTaskFromFile(a, projectDir);
+  const runLog = createRunLog(projectDir);
+  const silenceTimeoutMs = Number(config?.session?.max_agent_silence_minutes) > 0
+    ? Math.round(Number(config.session.max_agent_silence_minutes) * 60 * 1000)
+    : undefined;
+  const plannerTimeoutMs = Number(config?.session?.max_planner_minutes) > 0
+    ? Math.round(Number(config.session.max_planner_minutes) * 60 * 1000)
+    : undefined;
+  const silenceLabel = silenceTimeoutMs ? `${Math.round(silenceTimeoutMs / 1000)}s` : "disabled";
+  const runtimeLabel = plannerTimeoutMs ? `${Math.round(plannerTimeoutMs / 1000)}s` : "disabled";
+  runLog.logText(
+    `[kj_plan] started — provider=${plannerRole.provider}, max_silence=${silenceLabel}, max_runtime=${runtimeLabel}`
+  );
+  const emitter = buildDirectEmitter(server, runLog, extra);
+  const eventBase = { sessionId: null, iteration: 0, startedAt: Date.now() };
+
+  // --- Phase 1: Researcher (codebase context) ---
+  let researchContext = null;
+  try {
+    const { ResearcherRole } = await import("../../roles/researcher-role.js");
+    const researcherRole = resolveRole(config, "researcher");
+    const researcherOnOutput = ({ stream, line }) => {
+      emitter.emit("progress", { type: "agent:output", stage: "researcher", message: line, detail: { stream, agent: researcherRole.provider } });
+    };
+    const researcherStall = createStallDetector({
+      onOutput: researcherOnOutput, emitter, eventBase, stage: "researcher", provider: researcherRole.provider
+    });
+
+    sendTrackerLog(server, "researcher", "running", researcherRole.provider);
+    runLog.logText(`[researcher] agent launched for plan context...`);
+    const researcher = new ResearcherRole({ config, logger, emitter });
+    await researcher.init({ task: a.task });
+    let researchOutput;
+    try {
+      researchOutput = await researcher.run({ task: a.task, onOutput: researcherStall.onOutput });
+    } finally {
+      researcherStall.stop();
+    }
+    if (researchOutput.ok) {
+      researchContext = researchOutput.result;
+      sendTrackerLog(server, "researcher", "done");
+      runLog.logText(`[researcher] completed — context available`);
+    } else {
+      sendTrackerLog(server, "researcher", "failed");
+      runLog.logText(`[researcher] failed: ${researchOutput.summary || "unknown"}`);
+    }
+  } catch (err) {
+    logger.warn(`Researcher phase skipped: ${err.message}`);
+  }
+
+  // --- Phase 2: Architect (solution design) ---
+  let architectContext = null;
+  try {
+    const { ArchitectRole } = await import("../../roles/architect-role.js");
+    const architectRole = resolveRole(config, "architect");
+    const architectOnOutput = ({ stream, line }) => {
+      emitter.emit("progress", { type: "agent:output", stage: "architect", message: line, detail: { stream, agent: architectRole.provider } });
+    };
+    const architectStall = createStallDetector({
+      onOutput: architectOnOutput, emitter, eventBase, stage: "architect", provider: architectRole.provider
+    });
+
+    sendTrackerLog(server, "architect", "running", architectRole.provider);
+    runLog.logText(`[architect] agent launched for plan context...`);
+    const architect = new ArchitectRole({ config, logger, emitter });
+    await architect.init({ task: a.task });
+    let architectOutput;
+    try {
+      architectOutput = await architect.run({ task: a.task, researchContext, onOutput: architectStall.onOutput });
+    } finally {
+      architectStall.stop();
+    }
+    if (architectOutput.ok) {
+      architectContext = architectOutput.result;
+      sendTrackerLog(server, "architect", "done");
+      runLog.logText(`[architect] completed — context available`);
+    } else {
+      sendTrackerLog(server, "architect", "failed");
+      runLog.logText(`[architect] failed: ${architectOutput.summary || "unknown"}`);
+    }
+  } catch (err) {
+    logger.warn(`Architect phase skipped: ${err.message}`);
+  }
+
+  // --- Phase 3: Planner (with research + architecture context) ---
+  const onOutput = ({ stream, line }) => {
+    emitter.emit("progress", { type: "agent:output", stage: "planner", message: line, detail: { stream, agent: plannerRole.provider } });
+  };
+  const stallDetector = createStallDetector({
+    onOutput, emitter, eventBase, stage: "planner", provider: plannerRole.provider
+  });
+
+  const planner = createAgent(plannerRole.provider, config, logger);
+  const prompt = buildPlannerPrompt({ task: a.task, context: a.context, architectContext });
+  sendTrackerLog(server, "planner", "running", plannerRole.provider);
+  runLog.logText(`[planner] agent launched, waiting for response...`);
+  let result;
+  let plannerStats;
+  try {
+    result = await planner.runTask({
+      prompt,
+      role: "planner",
+      onOutput: stallDetector.onOutput,
+      silenceTimeoutMs,
+      timeoutMs: plannerTimeoutMs
+    });
+  } finally {
+    stallDetector.stop();
+    plannerStats = stallDetector.stats();
+    runLog.logText(
+      `[planner] finished — lines=${plannerStats.lineCount}, bytes=${plannerStats.bytesReceived}, elapsed=${Math.round(plannerStats.elapsedMs / 1000)}s`
+    );
+    runLog.close();
+  }
+
+  if (!result.ok) {
+    sendTrackerLog(server, "planner", "failed");
+    const baseError = result.error || result.output || "Planner failed";
+    const statsSuffix = plannerStats
+      ? ` [lines=${plannerStats.lineCount}, bytes=${plannerStats.bytesReceived}, elapsed=${Math.round(plannerStats.elapsedMs / 1000)}s]`
+      : "";
+    throw new Error(`${baseError}${statsSuffix}`);
+  }
+
+  sendTrackerLog(server, "planner", "done");
+  const parsed = parseMaybeJsonString(result.output);
+
+  // --- Persist plan ---
+  let planId = null;
+  try {
+    const { savePlan } = await import("../../plan/plan-store.js");
+    planId = await savePlan(projectDir, {
+      task: a.task,
+      researchContext,
+      architectContext,
+      plan: parsed || result.output,
+      raw: result.output
+    });
+    runLog.logText(`[kj_plan] plan persisted — planId=${planId}`);
+  } catch (err) {
+    logger.warn(`Plan persistence failed (non-blocking): ${err.message}`);
+  }
+
+  return { ok: true, plan: parsed || result.output, raw: result.output, planId, researchContext, architectContext };
+}
+
+export async function handleCodeDirect(a, server, extra) {
+  const config = await buildConfig(a, "code");
+  await assertNotOnBaseBranch(config);
+  const logger = createLogger(config.output.log_level, "mcp");
+
+  const coderRole = resolveRole(config, "coder");
+  await assertAgentsAvailable([coderRole.provider]);
+
+  const projectDir = await resolveProjectDir(server, a.projectDir);
+  await ensureTaskFromFile(a, projectDir);
+  const runLog = createRunLog(projectDir);
+  runLog.logText(`[kj_code] started — provider=${coderRole.provider}`);
+  const emitter = buildDirectEmitter(server, runLog, extra);
+  const eventBase = { sessionId: null, iteration: 0, startedAt: Date.now() };
+  const onOutput = ({ stream, line }) => {
+    emitter.emit("progress", { type: "agent:output", stage: "coder", message: line, detail: { stream, agent: coderRole.provider } });
+  };
+  const stallDetector = createStallDetector({
+    onOutput, emitter, eventBase, stage: "coder", provider: coderRole.provider
+  });
+
+  const coder = createAgent(coderRole.provider, config, logger);
+  let coderRules = null;
+  if (config.coder_rules) {
+    try {
+      coderRules = await fs.readFile(config.coder_rules, "utf8");
+    } catch { /* configured coder_rules path not found */
+      try { coderRules = await fs.readFile("coder-rules.md", "utf8"); } catch { /* no coder rules file */ }
+    }
+  }
+  const prompt = await buildCoderPrompt({ task: a.task, coderRules, methodology: config.development?.methodology || "tdd" });
+  sendTrackerLog(server, "coder", "running", coderRole.provider);
+  runLog.logText(`[coder] agent launched, waiting for response...`);
+  let result;
+  try {
+    result = await coder.runTask({ prompt, role: "coder", onOutput: stallDetector.onOutput });
+  } finally {
+    stallDetector.stop();
+    const stats = stallDetector.stats();
+    runLog.logText(`[coder] finished — lines=${stats.lineCount}, bytes=${stats.bytesReceived}, elapsed=${Math.round(stats.elapsedMs / 1000)}s`);
+    runLog.close();
+  }
+
+  if (!result.ok) {
+    sendTrackerLog(server, "coder", "failed");
+    throw new Error(result.error || result.output || `Coder failed (exit ${result.exitCode})`);
+  }
+
+  sendTrackerLog(server, "coder", "done");
+  return { ok: true, output: result.output, exitCode: result.exitCode };
+}
+
+export async function handleReviewDirect(a, server, extra) {
+  const config = await buildConfig(a, "review");
+  await assertNotOnBaseBranch(config);
+  const logger = createLogger(config.output.log_level, "mcp");
+
+  const reviewerRole = resolveRole(config, "reviewer");
+  await assertAgentsAvailable([reviewerRole.provider]);
+
+  const projectDir = await resolveProjectDir(server, a.projectDir);
+  await ensureTaskFromFile(a, projectDir);
+  const runLog = createRunLog(projectDir);
+  runLog.logText(`[kj_review] started — provider=${reviewerRole.provider}`);
+  const emitter = buildDirectEmitter(server, runLog, extra);
+  const eventBase = { sessionId: null, iteration: 0, startedAt: Date.now() };
+  const onOutput = ({ stream, line }) => {
+    emitter.emit("progress", { type: "agent:output", stage: "reviewer", message: line, detail: { stream, agent: reviewerRole.provider } });
+  };
+  const stallDetector = createStallDetector({
+    onOutput, emitter, eventBase, stage: "reviewer", provider: reviewerRole.provider
+  });
+
+  const reviewer = createAgent(reviewerRole.provider, config, logger);
+  const resolvedBase = await computeBaseRef({ baseBranch: config.base_branch, baseRef: a.baseRef });
+  const diff = await generateDiff({ baseRef: resolvedBase });
+  const { rules } = await resolveReviewProfile({ mode: config.review_mode, projectDir: process.cwd() });
+
+  const prompt = await buildReviewerPrompt({ task: a.task, diff, reviewRules: rules, mode: config.review_mode });
+  sendTrackerLog(server, "reviewer", "running", reviewerRole.provider);
+  runLog.logText(`[reviewer] agent launched, waiting for response...`);
+  let result;
+  try {
+    result = await reviewer.reviewTask({ prompt, role: "reviewer", onOutput: stallDetector.onOutput });
+  } finally {
+    stallDetector.stop();
+    const stats = stallDetector.stats();
+    runLog.logText(`[reviewer] finished — lines=${stats.lineCount}, bytes=${stats.bytesReceived}, elapsed=${Math.round(stats.elapsedMs / 1000)}s`);
+    runLog.close();
+  }
+
+  if (!result.ok) {
+    sendTrackerLog(server, "reviewer", "failed");
+    throw new Error(result.error || result.output || `Reviewer failed (exit ${result.exitCode})`);
+  }
+
+  sendTrackerLog(server, "reviewer", "done");
+  const parsed = parseMaybeJsonString(result.output);
+  return { ok: true, review: parsed || result.output, raw: result.output };
+}
+
+export async function handleDiscoverDirect(a, server, extra) {
+  // Build context from pgTask if provided
+  let context = a.context || null;
+  if (a.pgTask && a.pgProject) {
+    try {
+      const pgContext = `Planning Game card: ${a.pgTask} (project: ${a.pgProject})`;
+      context = context ? `${context}\n\n${pgContext}` : pgContext;
+    } catch { /* PG not available — proceed without */ }
+  }
+
+  return runDirectRole({
+    roleName: "discover",
+    importRole: async () => {
+      const { DiscoverRole } = await import("../../roles/discover-role.js");
+      return { RoleClass: DiscoverRole };
+    },
+    initContext: { task: a.task },
+    runInput: { task: a.task, mode: a.mode || "gaps", context },
+    logStartMsg: `[kj_discover] started — mode=${a.mode || "gaps"}`,
+    args: a, server, extra,
+    resolveProjectDir, buildConfig, buildDirectEmitter
+  });
+}
+
+export async function handleTriageDirect(a, server, extra) {
+  return runDirectRole({
+    roleName: "triage",
+    importRole: async () => {
+      const { TriageRole } = await import("../../roles/triage-role.js");
+      return { RoleClass: TriageRole };
+    },
+    initContext: { task: a.task },
+    runInput: { task: a.task },
+    args: a, server, extra,
+    resolveProjectDir, buildConfig, buildDirectEmitter
+  });
+}
+
+export async function handleResearcherDirect(a, server, extra) {
+  return runDirectRole({
+    roleName: "researcher",
+    importRole: async () => {
+      const { ResearcherRole } = await import("../../roles/researcher-role.js");
+      return { RoleClass: ResearcherRole };
+    },
+    initContext: { task: a.task },
+    runInput: { task: a.task },
+    args: a, server, extra,
+    resolveProjectDir, buildConfig, buildDirectEmitter
+  });
+}
+
+export async function handleAuditDirect(a, server, extra) {
+  const task = a.task || "Analyze the full codebase";
+  return runDirectRole({
+    roleName: "audit",
+    importRole: async () => {
+      const { AuditRole } = await import("../../roles/audit-role.js");
+      return { RoleClass: AuditRole };
+    },
+    initContext: { task },
+    runInput: { task, dimensions: a.dimensions || null },
+    logStartMsg: `[kj_audit] started — dimensions=${a.dimensions || "all"}`,
+    args: a, server, extra,
+    resolveProjectDir, buildConfig, buildDirectEmitter
+  });
+}
+
+export async function handleArchitectDirect(a, server, extra) {
+  return runDirectRole({
+    roleName: "architect",
+    importRole: async () => {
+      const { ArchitectRole } = await import("../../roles/architect-role.js");
+      return { RoleClass: ArchitectRole };
+    },
+    initContext: { task: a.task },
+    runInput: { task: a.task, researchContext: a.context || null },
+    args: a, server, extra,
+    resolveProjectDir, buildConfig, buildDirectEmitter
+  });
+}
+
+export async function handleCode(a, server, extra) {
+  if (!a.task) {
+    return failPayload("Missing required field: task");
+  }
+  await runBootstrapGate(server, a);
+  if (!isPreflightAcked()) {
+    // Auto-acknowledge with defaults for autonomous operation
+    ackPreflight({});
+    const logger = createLogger("info", "mcp");
+    logger.info("Preflight auto-acknowledged with default agent config");
+  }
+  applySessionOverrides(a, ["coder"]);
+  return handleCodeDirect(a, server, extra);
+}
+
+export async function handleReview(a, server, extra) {
+  if (!a.task) {
+    return failPayload("Missing required field: task");
+  }
+  await runBootstrapGate(server, a);
+  return handleReviewDirect(a, server, extra);
+}
+
+export async function handlePlan(a, server, extra) {
+  if (!a.task) {
+    return failPayload("Missing required field: task");
+  }
+  await runBootstrapGate(server, a);
+  return handlePlanDirect(a, server, extra);
+}
+
+export async function handleDiscover(a, server, extra) {
+  if (!a.task) {
+    return failPayload("Missing required field: task");
+  }
+  const validModes = new Set(["gaps", "momtest", "wendel", "classify", "jtbd"]);
+  if (a.mode && !validModes.has(a.mode)) {
+    return failPayload(`Invalid mode "${a.mode}". Valid values: ${[...validModes].join(", ")}`);
+  }
+  await runBootstrapGate(server, a);
+  return handleDiscoverDirect(a, server, extra);
+}
+
+export async function handleTriage(a, server, extra) {
+  if (!a.task) {
+    return failPayload("Missing required field: task");
+  }
+  await runBootstrapGate(server, a);
+  return handleTriageDirect(a, server, extra);
+}
+
+export async function handleResearcher(a, server, extra) {
+  if (!a.task) {
+    return failPayload("Missing required field: task");
+  }
+  await runBootstrapGate(server, a);
+  return handleResearcherDirect(a, server, extra);
+}
+
+export async function handleArchitect(a, server, extra) {
+  if (!a.task) {
+    return failPayload("Missing required field: task");
+  }
+  await runBootstrapGate(server, a);
+  return handleArchitectDirect(a, server, extra);
+}
+
+export async function handleAudit(a, server, extra) {
+  await runBootstrapGate(server, a);
+  const result = await handleAuditDirect(a, server, extra);
+
+  // Return compact summary for MCP (full details in session log)
+  if (result?.ok && result?.summary) {
+    const compact = {
+      ok: true,
+      overallHealth: result.summary?.overallHealth || result.summary,
+      totalFindings: result.summary?.totalFindings,
+      critical: result.summary?.critical,
+      high: result.summary?.high,
+      topRecommendations: (result.topRecommendations || []).slice(0, 5).map(r => ({
+        priority: r.priority,
+        dimension: r.dimension,
+        action: r.action,
+        impact: r.impact
+      })),
+      textSummary: result.textSummary || result.summary,
+      basalCost: result.basalCost ? {
+        totalLines: result.basalCost.totalLines,
+        totalFiles: result.basalCost.totalFiles,
+        dependencies: result.basalCost.dependencies
+      } : undefined
+    };
+    return { content: [{ type: "text", text: JSON.stringify(compact, null, 2) }] };
+  }
+  return result;
+}

package/src/mcp/handlers/hu-handlers.js

@@ -0,0 +1,93 @@
+/**
+ * HU, Skills, and Suggest handler logic.
+ * Extracted from server-handlers.js for maintainability.
+ */
+
+import { handleSuggestion } from "../suggest-handler.js";
+import {
+  resolveProjectDir,
+  failPayload,
+} from "../shared-helpers.js";
+
+export async function handleHu(a, server) {
+  const action = a.action;
+  if (!action) return failPayload("Missing required field: action");
+
+  const projectDir = await resolveProjectDir(server, a.projectDir);
+  const { createManualHu, listHus, getHu, updateHuStatus } = await import("../../hu/store.js");
+
+  switch (action) {
+    case "create": {
+      if (!a.title) return failPayload("Missing required field: title (required for create)");
+      const hu = await createManualHu(projectDir, {
+        title: a.title,
+        description: a.description,
+        status: a.status,
+        acceptanceCriteria: a.acceptanceCriteria
+      });
+      return { ok: true, hu };
+    }
+    case "list": {
+      const hus = await listHus(projectDir);
+      return { ok: true, hus };
+    }
+    case "get": {
+      if (!a.huId) return failPayload("Missing required field: huId (required for get)");
+      const hu = await getHu(projectDir, a.huId);
+      return { ok: true, hu };
+    }
+    case "update": {
+      if (!a.huId) return failPayload("Missing required field: huId (required for update)");
+      if (!a.status) return failPayload("Missing required field: status (required for update)");
+      const hu = await updateHuStatus(projectDir, a.huId, a.status);
+      return { ok: true, hu };
+    }
+    default:
+      return failPayload(`Unknown hu action: ${action}`);
+  }
+}
+
+export async function handleSkills(a) {
+  const action = a.action;
+  if (!action) return failPayload("Missing required field: action");
+
+  const { isOpenSkillsAvailable, installSkill, removeSkill, listSkills, readSkill } =
+    await import("../../skills/openskills-client.js");
+
+  const opts = { projectDir: a.projectDir || null };
+
+  switch (action) {
+    case "install": {
+      if (!a.source) return failPayload("Missing required field: source (required for install)");
+      const available = await isOpenSkillsAvailable();
+      if (!available) {
+        return failPayload("OpenSkills CLI is not available. Install it with: npm install -g openskills");
+      }
+      return installSkill(a.source, { ...opts, global: a.global || false });
+    }
+    case "remove": {
+      if (!a.name) return failPayload("Missing required field: name (required for remove)");
+      return removeSkill(a.name, opts);
+    }
+    case "list": {
+      return listSkills(opts);
+    }
+    case "read": {
+      if (!a.name) return failPayload("Missing required field: name (required for read)");
+      return readSkill(a.name, opts);
+    }
+    default:
+      return failPayload(`Unknown skills action: ${action}`);
+  }
+}
+
+export async function handleSuggest(a) {
+  if (!a.suggestion) {
+    return failPayload("Missing required field: suggestion");
+  }
+  return handleSuggestion({
+    suggestion: a.suggestion,
+    context: a.context || null,
+    projectDir: a.projectDir || null
+  });
+}