@karajan-family/code 4.21.0

package/src/commands/report.js

@@ -0,0 +1,469 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { exists } from "../utils/fs.js";
+import { getSessionRoot } from "../utils/paths.js";
+import { loadConfig } from "../config.js";
+import { DEFAULTS } from "../config/defaults.js";
+
+function parseBudgetFromActivityLog(logText) {
+  if (!logText) {
+    return { consumed_usd: null, limit_usd: null };
+  }
+
+  const regex = /Budget:\s*\$(\d+(?:\.\d+)?)\s*\/\s*\$(\d+(?:\.\d+)?)/g;
+  let match;
+  let last = null;
+  while ((match = regex.exec(logText)) !== null) {
+    last = match;
+  }
+
+  if (!last) {
+    return { consumed_usd: null, limit_usd: null };
+  }
+
+  return {
+    consumed_usd: Number(last[1]),
+    limit_usd: Number(last[2])
+  };
+}
+
+function summarizeIterations(checkpoints = []) {
+  const byIteration = new Map();
+  for (const checkpoint of checkpoints) {
+    const iteration = Number(checkpoint?.iteration);
+    if (!Number.isFinite(iteration) || iteration <= 0) continue;
+
+    if (!byIteration.has(iteration)) {
+      byIteration.set(iteration, {
+        iteration,
+        coder_runs: 0,
+        reviewer_attempts: 0,
+        reviewer_approved: null
+      });
+    }
+
+    const item = byIteration.get(iteration);
+    if (checkpoint.stage === "coder") {
+      item.coder_runs += 1;
+    } else if (checkpoint.stage === "reviewer-attempt") {
+      item.reviewer_attempts += 1;
+    } else if (checkpoint.stage === "reviewer") {
+      item.reviewer_approved = Boolean(checkpoint.approved);
+    }
+  }
+
+  return [...byIteration.values()].sort((a, b) => a.iteration - b.iteration);
+}
+
+function summarizePlan(checkpoints = []) {
+  const stages = checkpoints
+    .map((checkpoint) => checkpoint.stage)
+    .filter((stage) => typeof stage === "string" && stage.length > 0);
+
+  const uniqueOrdered = [];
+  for (const stage of stages) {
+    if (uniqueOrdered.at(-1) !== stage) {
+      uniqueOrdered.push(stage);
+    }
+  }
+
+  return uniqueOrdered;
+}
+
+function summarizeSonar(checkpoints = []) {
+  const sonarPoints = checkpoints
+    .filter((checkpoint) => checkpoint.stage === "sonar" && typeof checkpoint.open_issues === "number")
+    .map((checkpoint) => checkpoint.open_issues);
+
+  if (sonarPoints.length === 0) {
+    return { initial: null, final: null, resolved: 0 };
+  }
+
+  const initial = sonarPoints[0];
+  const final = sonarPoints.at(-1);
+  return {
+    initial,
+    final,
+    resolved: Math.max(initial - final, 0)
+  };
+}
+
+function summarizeCommits(session, checkpoints = []) {
+  const idsFromSession = Array.isArray(session?.git?.commits)
+    ? session.git.commits.filter((item) => typeof item === "string" && item.length > 0)
+    : [];
+
+  const idsFromCheckpoints = checkpoints
+    .filter((checkpoint) => checkpoint.stage === "git-commit" && checkpoint.committed && checkpoint.commit)
+    .map((checkpoint) => checkpoint.commit)
+    .filter((item) => typeof item === "string" && item.length > 0);
+
+  const ids = [...new Set([...idsFromSession, ...idsFromCheckpoints])];
+  if (ids.length > 0) {
+    return { count: ids.length, ids };
+  }
+
+  const committedCount = checkpoints.filter(
+    (checkpoint) => checkpoint.stage === "git-commit" && checkpoint.committed
+  ).length;
+
+  return { count: committedCount, ids: [] };
+}
+
+async function readActivityLog(sessionDir) {
+  const file = path.join(sessionDir, "activity.log");
+  if (!(await exists(file))) {
+    return "";
+  }
+
+  return fs.readFile(file, "utf8");
+}
+
+async function buildReport(dir, sessionId) {
+  const sessionDir = path.join(dir, sessionId);
+  const sessionFile = path.join(sessionDir, "session.json");
+  if (!(await exists(sessionFile))) {
+    throw new Error(`Session not found: ${sessionId}`);
+  }
+  const content = await fs.readFile(sessionFile, "utf8");
+  const session = JSON.parse(content);
+  const checkpoints = Array.isArray(session.checkpoints) ? session.checkpoints : [];
+  const activityLog = await readActivityLog(sessionDir);
+
+  const sonar = summarizeSonar(checkpoints);
+  const budget = parseBudgetFromActivityLog(activityLog);
+  // KJC-BUG-0114: activity logs written when max_budget_usd was null carry
+  // a phantom "$0.00" ceiling (Number(null) === 0). Resolve the effective
+  // ceiling from the session's config snapshot, falling back to the
+  // shipped default; an explicit 0 means "no ceiling" and drops the suffix.
+  if (budget.limit_usd === 0) {
+    const snapBudget = session.config_snapshot?.max_budget_usd;
+    budget.limit_usd = snapBudget == null ? DEFAULTS.max_budget_usd : (Number(snapBudget) || null);
+  }
+  const commits = summarizeCommits(session, checkpoints);
+
+  const budgetTrace = Array.isArray(session.budget?.trace) ? session.budget.trace : [];
+
+  const report = {
+    session_id: session.id,
+    task_description: session.task || "",
+    plan_executed: summarizePlan(checkpoints),
+    iterations: summarizeIterations(checkpoints),
+    sonar_issues_resolved: {
+      initial_open_issues: sonar.initial,
+      final_open_issues: sonar.final,
+      resolved: sonar.resolved
+    },
+    budget_consumed: budget,
+    budget_trace: budgetTrace,
+    commits_generated: commits,
+    status: session.status || "unknown"
+  };
+  if (session.pg_task_id) report.pg_task_id = session.pg_task_id;
+  if (session.pg_project_id) report.pg_project_id = session.pg_project_id;
+  if (session.rtk_savings) report.rtk_savings = session.rtk_savings;
+  // The session may belong to another workspace: its snapshot knows the
+  // project dir the sentinel state lives in (same source solomon-rules uses).
+  if (session.config_snapshot?.projectDir) report.project_dir = session.config_snapshot.projectDir;
+  return report;
+}
+
+function formatBudgetText(budget) {
+  if (typeof budget?.consumed_usd !== "number") return "N/A";
+  const limitSuffix = typeof budget.limit_usd === "number" ? ` / $${budget.limit_usd.toFixed(2)}` : "";
+  return `$${budget.consumed_usd.toFixed(2)}${limitSuffix}`;
+}
+
+function formatIterationsText(iterations) {
+  if (iterations.length === 0) return "N/A";
+  return iterations
+    .map((item) => `#${item.iteration} coder=${item.coder_runs} reviewer_attempts=${item.reviewer_attempts} approved=${item.reviewer_approved}`)
+    .join("\n");
+}
+
+function formatCommitsText(commits) {
+  return commits.ids.length > 0
+    ? `${commits.count} (${commits.ids.join(", ")})`
+    : String(commits.count);
+}
+
+function printPgCardLine(report) {
+  if (!report.pg_task_id) return;
+  const projectLabel = report.pg_project_id ? ` (${report.pg_project_id})` : "";
+  console.log(`Planning Game Card: ${report.pg_task_id}${projectLabel}`);
+}
+
+function printTextReport(report) {
+  const sonar = report.sonar_issues_resolved;
+
+  console.log(`Session: ${report.session_id}`);
+  printPgCardLine(report);
+  console.log(`Status: ${report.status}`);
+  console.log("Task Description:");
+  console.log(report.task_description || "N/A");
+  console.log("Plan Executed:");
+  console.log(report.plan_executed.length > 0 ? report.plan_executed.join(" -> ") : "N/A");
+  console.log("Iterations (Coder/Reviewer):");
+  console.log(formatIterationsText(report.iterations));
+  console.log("Sonar Issues Resolved:");
+  console.log(`initial=${sonar.initial_open_issues ?? "N/A"} final=${sonar.final_open_issues ?? "N/A"} resolved=${sonar.resolved}`);
+  console.log("Budget Consumed:");
+  console.log(formatBudgetText(report.budget_consumed));
+  console.log("Commits Generated:");
+  console.log(formatCommitsText(report.commits_generated));
+}
+
+/**
+ * KJC-TSK-0715 — escapes are the user's decisions, never the agent's silent
+ * shortcuts: every KJ_ALLOW_* the sentinel honored surfaces in the report.
+ */
+export function formatSentinelEscapes(state) {
+  const events = Array.isArray(state?.escape_events) ? state.escape_events : [];
+  if (events.length === 0) return null;
+  const lines = events.map(
+    (e) => `  ${e.ts ? new Date(e.ts).toISOString() : "?"} ${e.escape} (tool: ${e.tool || "?"}, session: ${e.sid || "?"})`
+  );
+  return `Sentinel escapes used (${events.length}):\n${lines.join("\n")}`;
+}
+
+// The sentinel state is a PROJECT artifact (<project>/.karajan/harness), not
+// a session artifact: the `dir` the report handlers receive is the GLOBAL
+// sessions root (~/.karajan/sessions) and never contains it. `kj report` is
+// run from inside the project, so the project dir is the cwd — overridable
+// for callers reporting on another workspace.
+async function printSentinelEscapes({ projectDir = process.cwd(), format } = {}) {
+  if (format === "json") return;
+  try {
+    const raw = await fs.readFile(path.join(projectDir, ".karajan", "harness", "sentinel-state.json"), "utf8");
+    const text = formatSentinelEscapes(JSON.parse(raw));
+    if (text) {
+      console.log("");
+      console.log(text);
+    }
+  } catch { /* no sentinel state in this project — nothing to report */ }
+}
+
+function formatDuration(ms) {
+  if (ms === null || ms === undefined) return "-";
+  if (ms < 1000) return `${ms}ms`;
+  const seconds = ms / 1000;
+  if (seconds < 60) return `${seconds.toFixed(1)}s`;
+  const minutes = Math.floor(seconds / 60);
+  const remainSeconds = (seconds % 60).toFixed(0);
+  return `${minutes}m${remainSeconds}s`;
+}
+
+function padRight(str, len) {
+  const s = String(str);
+  return s.length >= len ? s : s + " ".repeat(len - s.length);
+}
+
+function padLeft(str, len) {
+  const s = String(str);
+  return s.length >= len ? s : " ".repeat(len - s.length) + s;
+}
+
+function convertCost(costUsd, currency, exchangeRate) {
+  if (currency === "eur") return costUsd * exchangeRate;
+  return costUsd;
+}
+
+function formatCost(cost, currency) {
+  const symbol = currency === "eur" ? "\u20AC" : "$";
+  return `${symbol}${cost.toFixed(4)}`;
+}
+
+function printTraceTable(trace, { currency = "usd", exchangeRate = 0.92 } = {}) {
+  if (!trace || trace.length === 0) {
+    console.log("No trace data available.");
+    return;
+  }
+
+  const currencyLabel = currency.toUpperCase();
+
+  const headers = ["#", "Stage", "Provider", "Model", "Duration", "Tokens In", "Tokens Out", `Cost ${currencyLabel}`];
+  const rows = trace.map((entry) => {
+    const cost = convertCost(entry.cost_usd, currency, exchangeRate);
+    return [
+      String(entry.index ?? "-"),
+      entry.role,
+      entry.provider || "-",
+      entry.model || "-",
+      formatDuration(entry.duration_ms),
+      String(entry.tokens_in),
+      String(entry.tokens_out),
+      formatCost(cost, currency)
+    ];
+  });
+
+  const totals = trace.reduce(
+    (acc, entry) => {
+      acc.tokens_in += entry.tokens_in;
+      acc.tokens_out += entry.tokens_out;
+      acc.cost += entry.cost_usd;
+      acc.duration += entry.duration_ms ?? 0;
+      return acc;
+    },
+    { tokens_in: 0, tokens_out: 0, cost: 0, duration: 0 }
+  );
+
+  const totalRow = [
+    "",
+    "TOTAL",
+    "",
+    "",
+    formatDuration(totals.duration),
+    String(totals.tokens_in),
+    String(totals.tokens_out),
+    formatCost(convertCost(totals.cost, currency, exchangeRate), currency)
+  ];
+
+  const allRows = [headers, ...rows, totalRow];
+  const colWidths = headers.map((_, colIdx) =>
+    Math.max(...allRows.map((row) => String(row[colIdx]).length))
+  );
+
+  const rightAligned = new Set([0, 4, 5, 6, 7]);
+  function formatRow(row) {
+    return row
+      .map((cell, idx) =>
+        rightAligned.has(idx)
+          ? padLeft(cell, colWidths[idx])
+          : padRight(cell, colWidths[idx])
+      )
+      .join("  ");
+  }
+
+  console.log(formatRow(headers));
+  console.log(colWidths.map((w) => "-".repeat(w)).join("  "));
+  for (const row of rows) {
+    console.log(formatRow(row));
+  }
+  console.log(colWidths.map((w) => "-".repeat(w)).join("  "));
+  console.log(formatRow(totalRow));
+}
+
+async function findSessionsByPgTask(dir, pgTask) {
+  const entries = await fs.readdir(dir);
+  const matches = [];
+  for (const entry of entries) {
+    const sessionFile = path.join(dir, entry, "session.json");
+    if (!(await exists(sessionFile))) continue;
+    try {
+      const raw = await fs.readFile(sessionFile, "utf8");
+      const session = JSON.parse(raw);
+      if (session.pg_task_id === pgTask) {
+        matches.push(entry);
+      }
+    } catch { /* skip malformed session files */
+      // skip malformed sessions
+    }
+  }
+  return matches.sort((a, b) => a.localeCompare(b));
+}
+
+async function resolveTraceOptions(currency) {
+  const { config } = await loadConfig();
+  const cur = currency?.toLowerCase() || config?.budget?.currency || "usd";
+  const rate = config?.budget?.exchange_rate_eur ?? 0.92;
+  return { cur, rate };
+}
+
+function printRtkSavings(rtkSavings) {
+  if (!rtkSavings || !rtkSavings.callCount) return;
+  const tokens = rtkSavings.estimatedTokensSaved ?? 0;
+  const ratio = rtkSavings.savedPct ?? 0;
+  const commands = rtkSavings.callCount ?? 0;
+  console.log("");
+  console.log(`RTK Savings: ~${tokens} tokens saved (${ratio}% compression, ${commands} commands)`);
+  console.log(`  Original: ${rtkSavings.originalBytes} bytes, Compressed: ${rtkSavings.rtkBytes} bytes, Saved: ${rtkSavings.savedBytes} bytes`);
+}
+
+function printTraceReport(report, currency, exchangeRate) {
+  console.log(`Session: ${report.session_id}`);
+  printPgCardLine(report);
+  console.log(`Status: ${report.status}`);
+  console.log(`Task: ${report.task_description || "N/A"}`);
+  console.log("");
+  printTraceTable(report.budget_trace, { currency, exchangeRate });
+  printRtkSavings(report.rtk_savings);
+}
+
+async function handlePgTaskReport({ dir, pgTask, list, sessionId, format, trace, currency }) {
+  const matches = await findSessionsByPgTask(dir, pgTask);
+  if (matches.length === 0) {
+    console.log(`No sessions found for card: ${pgTask}`);
+    return;
+  }
+  if (list) {
+    for (const item of matches) console.log(item);
+    return;
+  }
+  const targetId = sessionId || matches.at(-1);
+  const report = await buildReport(dir, targetId);
+  if (format === "json") {
+    console.log(JSON.stringify({ card: pgTask, sessions: matches, report }, null, 2));
+    return;
+  }
+  console.log(`Card ${pgTask}: ${matches.length} session${matches.length === 1 ? "" : "s"}`);
+  for (const m of matches) {
+    const marker = m === targetId ? " <--" : "";
+    console.log(`  ${m}${marker}`);
+  }
+  console.log("");
+  if (trace) {
+    const { cur, rate } = await resolveTraceOptions(currency);
+    printTraceReport(report, cur, rate);
+  } else {
+    printTextReport(report);
+  }
+  await printSentinelEscapes({ projectDir: report.project_dir, format });
+}
+
+async function handleSingleSessionReport({ dir, entries, sessionId, format, trace, currency }) {
+  const ids = [...entries].sort((a, b) => a.localeCompare(b));
+  const selectedSessionId = sessionId || ids.at(-1);
+  if (!selectedSessionId) {
+    console.log("No reports yet");
+    return;
+  }
+  if (sessionId && !ids.includes(sessionId)) {
+    throw new Error(`Session not found: ${sessionId}`);
+  }
+
+  const report = await buildReport(dir, selectedSessionId);
+  if (format === "json") {
+    console.log(JSON.stringify(report, null, 2));
+    return;
+  }
+  if (trace) {
+    const { cur, rate } = await resolveTraceOptions(currency);
+    printTraceReport(report, cur, rate);
+  } else {
+    printTextReport(report);
+  }
+  await printSentinelEscapes({ projectDir: report.project_dir, format });
+}
+
+export async function reportCommand({ list = false, sessionId = null, format = "text", trace = false, currency = "usd", pgTask = null }) {
+  const dir = getSessionRoot();
+  if (!(await exists(dir))) {
+    console.log("No reports yet");
+    return;
+  }
+
+  const entries = await fs.readdir(dir);
+
+  if (pgTask) {
+    return handlePgTaskReport({ dir, pgTask, list, sessionId, format, trace, currency });
+  }
+
+  if (list) {
+    for (const item of entries) console.log(item);
+    return;
+  }
+
+  return handleSingleSessionReport({ dir, entries, sessionId, format, trace, currency });
+}
+
+export { formatDuration, convertCost, formatCost, printTraceTable, buildReport, findSessionsByPgTask };

package/src/commands/researcher.js

@@ -0,0 +1,54 @@
+import { createAgent } from "../agents/index.js";
+import { assertAgentsAvailable } from "../agents/availability.js";
+import { resolveRole } from "../config.js";
+import { createCliProgressReporter } from "../utils/cli-progress.js";
+import { withBrainRecovery } from "../brain/with-brain-recovery.js";
+
+const SUBAGENT_PREAMBLE = [
+  "IMPORTANT: You are running as a Karajan sub-agent.",
+  "Do NOT ask about using Karajan, do NOT mention Karajan, do NOT suggest orchestration.",
+  "Do NOT use any MCP tools. Focus only on researching the codebase."
+].join(" ");
+
+function buildResearchPrompt(task) {
+  return [
+    SUBAGENT_PREAMBLE,
+    "Investigate the codebase for the following task.",
+    "Identify affected files, patterns, constraints, prior decisions, risks, and test coverage.",
+    "Return a single valid JSON object with your findings and nothing else.",
+    '{"affected_files":[string],"patterns":[string],"constraints":[string],"prior_decisions":[string],"risks":[string],"test_coverage":string}',
+    `## Task\n${task}`
+  ].join("\n\n");
+}
+
+export async function researcherCommand({ task, config, logger }) {
+  const { withCliRunLog } = await import("../utils/cli-run-log.js");
+  return withCliRunLog("researcher", { projectDir: config?.projectDir, logger }, async ({ runLog }) => {
+    const researcherRole = resolveRole(config, "researcher");
+    await assertAgentsAvailable([researcherRole.provider]);
+    logger.info(`Researcher (${researcherRole.provider}) starting...`);
+    runLog.logText(`[researcher] provider=${researcherRole.provider}`);
+
+    const agent = createAgent(researcherRole.provider, config, logger);
+    const prompt = buildResearchPrompt(task);
+    const progress = createCliProgressReporter({ role: "researcher" });
+    let result;
+    try {
+      result = await withBrainRecovery({
+        agent, taskArgs: { prompt, onOutput: progress.onOutput, role: "researcher" },
+        role: "researcher", provider: researcherRole.provider, logger,
+      });
+      progress.finish(result.ok ? "done" : (result.action || "failed"));
+    } catch (err) { progress.finish("failed"); throw err; }
+
+    if (!result.ok) {
+      throw new Error(result.error || result.output || "Researcher failed");
+    }
+
+    if (result.output) {
+      console.log(result.output);
+    }
+    logger.info("Researcher completed.");
+    return { ok: true };
+  });
+}

package/src/commands/resume.js

@@ -0,0 +1,68 @@
+import { EventEmitter } from "node:events";
+import { resumeFlow } from "../orchestrator.js";
+import { createActivityLog } from "../activity-log.js";
+import { printEvent } from "../utils/display/event-handlers.js";
+import { withCliRunLog } from "../utils/cli-run-log.js";
+import { registerRun, unregisterRun } from "../utils/run-registry.js";
+import { createCliAskQuestion } from "../utils/cli-ask-question.js";
+
+export async function resumeCommand({ sessionId, answer, config, logger, flags }) {
+  const jsonMode = flags?.json;
+  const quietMode = config.output?.quiet !== false;
+
+  // Same wrapper as every other CLI command — without it `.kj/run.log`
+  // is never opened during the resume and `kj-tail` stays silent
+  // (every line of the resumed run goes only to the per-session
+  // activity log + the local console). Also registers the run so the
+  // HU Board shows it as live and can offer its Stop button.
+  return withCliRunLog("resume", { projectDir: config?.projectDir, logger }, async ({ forwardProgress }) => {
+    const runId = registerRun({
+      pid: process.pid,
+      planId: flags?.plan || null,
+      huIds: null,
+      projectDir: config?.projectDir || process.cwd(),
+      source: "cli-resume",
+    });
+    const cleanupRegistry = () => { if (runId) unregisterRun(runId); };
+    process.once("exit", cleanupRegistry);
+    process.once("SIGTERM", () => { cleanupRegistry(); process.exit(143); });
+    process.once("SIGINT", () => { cleanupRegistry(); process.exit(130); });
+
+    const emitter = new EventEmitter();
+    let activityLog = null;
+    forwardProgress(emitter);
+
+    emitter.on("progress", (event) => {
+      if (!activityLog && event.sessionId) {
+        activityLog = createActivityLog(event.sessionId);
+        logger.onLog((entry) => activityLog.write(entry));
+      }
+      if (activityLog) {
+        activityLog.writeEvent(event);
+      }
+      if (!jsonMode) {
+        printEvent(event, { quiet: quietMode });
+      }
+    });
+
+    // KJC-BUG-0081 round 2 — propagate `flags` so the helper honours
+    // `--yes` here too. Before this fix, `kj resume <id> --yes` in
+    // non-TTY mode still routed every prompt to the HU Board bridge
+    // and hung, exactly the bug the original PR #995 fixed for `kj run`.
+    const askQuestion = createCliAskQuestion({ sessionId, flags });
+    const result = await resumeFlow({
+      sessionId,
+      answer: answer || null,
+      config,
+      logger,
+      flags: flags || {},
+      emitter,
+      askQuestion
+    });
+
+    if (jsonMode || !answer) {
+      console.log(JSON.stringify(result, null, 2));
+    }
+    return result;
+  });
+}