karajan-code 2.4.1 → 2.6.0

package/src/session/journal/summary-writer.js

@@ -0,0 +1,176 @@
+/**
+ * Executive session summary (`summary.md`) — the entry point to the journal
+ * directory. Pulls together every useful signal from the session into a
+ * single scannable Markdown page with links to the rest of the journal.
+ *
+ * Acceptance criterion (KJC-TSK-0289):
+ *   summary.md contains: task, result (approved/rejected/paused), iterations,
+ *   duration, budget, stages + status, list of journal files, commits.
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+
+/**
+ * @typedef {Object} SummaryInput
+ * @property {string} sessionId
+ * @property {string} task
+ * @property {"APPROVED"|"REJECTED"|"PAUSED"|"FAILED"|string} result
+ * @property {number} iterations
+ * @property {number} durationMs
+ * @property {{ total_cost_usd?: number, total_tokens?: number, breakdown_by_role?: Object }} [budget]
+ * @property {Record<string, { ok?: boolean, summary?: string }>} [stages]
+ * @property {Array<{ hash?: string, message?: string, date?: string, author?: string }>} [commits]
+ * @property {string[]} [files]                    - names of other journal files in the same dir
+ * @property {string} [startedAt]                  - ISO timestamp (optional, auto-derived if absent)
+ * @property {string} [finishedAt]                 - ISO timestamp (optional)
+ * @property {number} [solomonInvocations]
+ * @property {number} [brainDecisions]
+ */
+
+function esc(text) {
+  return String(text ?? "").replace(/\|/g, "\\|");
+}
+
+function formatDuration(ms) {
+  if (!Number.isFinite(ms) || ms < 0) return "—";
+  if (ms < 1000) return `${ms}ms`;
+  const s = Math.round(ms / 1000);
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  const rs = s % 60;
+  if (m < 60) return `${m}m ${rs}s`;
+  const h = Math.floor(m / 60);
+  const rm = m % 60;
+  return `${h}h ${rm}m ${rs}s`;
+}
+
+function formatBudget(budget) {
+  if (!budget) return "—";
+  const cost = Number(budget.total_cost_usd ?? 0);
+  const tokens = Number(budget.total_tokens ?? 0);
+  const costStr = `$${cost.toFixed(2)}`;
+  const tokStr = tokens > 0 ? `${tokens.toLocaleString("en-US")} tokens` : "—";
+  return `${costStr} · ${tokStr}`;
+}
+
+function resultBadge(result) {
+  const r = String(result || "").toUpperCase();
+  const map = {
+    APPROVED: "✅ APPROVED",
+    REJECTED: "❌ REJECTED",
+    PAUSED: "⏸ PAUSED",
+    FAILED: "❌ FAILED",
+  };
+  return map[r] || r;
+}
+
+function renderStagesTable(stages) {
+  if (!stages || Object.keys(stages).length === 0) return "_No stages recorded._";
+  const header = "| Stage | Status | Summary |\n|---|---|---|";
+  const rows = Object.entries(stages).map(([name, stageResult]) => {
+    const ok = stageResult?.ok !== false;
+    const status = ok ? "✅ pass" : "❌ fail";
+    const summary = esc(stageResult?.summary || "").slice(0, 120);
+    return `| \`${esc(name)}\` | ${status} | ${summary} |`;
+  });
+  return [header, ...rows].join("\n");
+}
+
+function renderCommits(commits) {
+  if (!Array.isArray(commits) || commits.length === 0) return "_No commits in this session._";
+  return commits
+    .map((c) => {
+      const hash = (c.hash || "").slice(0, 7) || "?";
+      return `- \`${hash}\` ${esc(c.message || "(no message)")}`;
+    })
+    .join("\n");
+}
+
+function renderBreakdownByRole(breakdown) {
+  if (!breakdown || typeof breakdown !== "object") return null;
+  const entries = Object.entries(breakdown)
+    .map(([role, m]) => ({
+      role,
+      tokens: Number(m?.total_tokens || 0),
+      cost: Number(m?.total_cost_usd || 0),
+    }))
+    .filter((e) => e.tokens > 0 || e.cost > 0);
+  if (entries.length === 0) return null;
+  const rows = entries
+    .sort((a, b) => b.cost - a.cost)
+    .map((e) => `| \`${esc(e.role)}\` | ${e.tokens.toLocaleString("en-US")} | $${e.cost.toFixed(4)} |`);
+  return ["| Role | Tokens | Cost |", "|---|---|---|", ...rows].join("\n");
+}
+
+function renderJournalLinks(files) {
+  if (!Array.isArray(files) || files.length === 0) return "_No additional journal files._";
+  return files.map((f) => `- [${esc(f)}](./${f})`).join("\n");
+}
+
+/**
+ * Build the summary.md content.
+ *
+ * @param {SummaryInput} input
+ * @returns {string}
+ */
+export function buildSummaryMarkdown(input) {
+  const sessionId = input.sessionId || "(unknown)";
+  const result = resultBadge(input.result);
+  const startedAt = input.startedAt || "(unknown)";
+  const finishedAt = input.finishedAt || new Date().toISOString();
+
+  const sections = [
+    `# Session summary — ${sessionId}`,
+    "",
+    `- **Result**: ${result}`,
+    `- **Task**: ${esc(input.task || "(no task)")}`,
+    `- **Iterations**: ${input.iterations ?? 0}`,
+    `- **Duration**: ${formatDuration(input.durationMs)}`,
+    `- **Budget**: ${formatBudget(input.budget)}`,
+    `- **Started**: ${startedAt}`,
+    `- **Finished**: ${finishedAt}`,
+  ];
+
+  if (Number.isFinite(input.brainDecisions) && input.brainDecisions > 0) {
+    sections.push(`- **Brain decisions**: ${input.brainDecisions}`);
+  }
+  if (Number.isFinite(input.solomonInvocations) && input.solomonInvocations > 0) {
+    sections.push(`- **Solomon invocations**: ${input.solomonInvocations}`);
+  }
+
+  sections.push("", "---", "", "## Stages", "", renderStagesTable(input.stages));
+
+  const breakdown = renderBreakdownByRole(input.budget?.breakdown_by_role);
+  if (breakdown) {
+    sections.push("", "## Budget breakdown (by role)", "", breakdown);
+  }
+
+  sections.push("", "## Commits", "", renderCommits(input.commits));
+
+  sections.push("", "## Journal files", "", renderJournalLinks(input.files));
+
+  return sections.join("\n") + "\n";
+}
+
+/**
+ * Write summary.md to the given journal directory. Always writes (the file
+ * is the entry point; even a barebones session should have one).
+ *
+ * @param {string} journalDir
+ * @param {SummaryInput} input
+ * @param {{ logger?: Object }} [options]
+ * @returns {Promise<{ written: boolean, path: string|null }>}
+ */
+export async function writeSummaryJournal(journalDir, input, options = {}) {
+  const filePath = path.join(journalDir, "summary.md");
+  try {
+    await fs.mkdir(journalDir, { recursive: true });
+    await fs.writeFile(filePath, buildSummaryMarkdown(input), "utf8");
+    options.logger?.info?.(`Wrote session summary: ${filePath}`);
+    return { written: true, path: filePath };
+  } catch (err) {
+    options.logger?.warn?.(`Failed to write session summary (non-blocking): ${err.message}`);
+    return { written: false, path: null };
+  }
+}

package/src/session/journal/tree-writer.js

@@ -0,0 +1,164 @@
+/**
+ * Build a directory-grouped tree view of files affected during the session,
+ * rendered as `.reviews/{sessionId}/tree.txt`.
+ *
+ * Acceptance criterion (KJC-TSK-0288):
+ *   - Given a kj run that modifies files, when the session finishes, then
+ *     tree.txt contains the tree of affected files (modified/added/deleted)
+ *     grouped by directory, generated from `git diff --name-status` against
+ *     the base ref.
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { runCommand } from "../../utils/process.js";
+
+const STATUS_LABELS = {
+  M: "modified",
+  A: "added",
+  D: "deleted",
+  R: "renamed",
+  C: "copied",
+  T: "typechange",
+  U: "unmerged",
+};
+
+/**
+ * @typedef {Object} DiffEntry
+ * @property {string} file    - path relative to repo root
+ * @property {string} status  - "modified" | "added" | "deleted" | ...
+ */
+
+/**
+ * Parse `git diff --name-status` output into structured entries.
+ *
+ * @param {string} rawDiff
+ * @returns {DiffEntry[]}
+ */
+export function parseNameStatus(rawDiff) {
+  if (!rawDiff || !rawDiff.trim()) return [];
+  const entries = [];
+  for (const line of rawDiff.split("\n")) {
+    if (!line.trim()) continue;
+    const parts = line.split("\t");
+    const status = parts[0];
+    // Renames and copies report "R<score>\told\tnew". Take the new path.
+    const file = parts.length >= 3 ? parts[2] : parts[1];
+    if (!status || !file) continue;
+    const key = status[0];
+    const label = STATUS_LABELS[key] || "other";
+    entries.push({ file, status: label });
+  }
+  return entries;
+}
+
+/**
+ * Group entries into a nested directory tree.
+ * Each node is { name, children: Map<string, node>, entries: DiffEntry[] }.
+ *
+ * @param {DiffEntry[]} entries
+ * @returns {{name:string, children:Map<string, any>, files:DiffEntry[]}}
+ */
+export function buildTree(entries) {
+  const root = { name: "", children: new Map(), files: [] };
+  for (const entry of entries) {
+    const parts = entry.file.split("/");
+    let node = root;
+    for (let i = 0; i < parts.length - 1; i++) {
+      const dir = parts[i];
+      if (!node.children.has(dir)) {
+        node.children.set(dir, { name: dir, children: new Map(), files: [] });
+      }
+      node = node.children.get(dir);
+    }
+    node.files.push({ file: parts.at(-1), status: entry.status });
+  }
+  return root;
+}
+
+/**
+ * Render a tree node as indented text. Directories come before files at each
+ * level; both are sorted alphabetically (case-insensitive).
+ */
+function renderNode(node, depth, lines) {
+  const indent = "  ".repeat(depth);
+  const dirs = Array.from(node.children.values()).sort((a, b) => a.name.localeCompare(b.name, undefined, { sensitivity: "base" }));
+  for (const dir of dirs) {
+    lines.push(`${indent}${dir.name}/`);
+    renderNode(dir, depth + 1, lines);
+  }
+  const files = [...node.files].sort((a, b) => a.file.localeCompare(b.file, undefined, { sensitivity: "base" }));
+  for (const f of files) {
+    lines.push(`${indent}${f.file} [${f.status}]`);
+  }
+}
+
+/**
+ * Render the tree as a self-describing text document.
+ * Returns null when there are no entries.
+ *
+ * @param {DiffEntry[]} entries
+ * @returns {string|null}
+ */
+export function renderTree(entries) {
+  if (!entries || entries.length === 0) return null;
+  const tree = buildTree(entries);
+  const lines = ["# Affected files (grouped by directory)", ""];
+  renderNode(tree, 0, lines);
+  lines.push("");
+
+  // Summary counts at the bottom for quick scanning.
+  const counts = entries.reduce((acc, e) => {
+    acc[e.status] = (acc[e.status] || 0) + 1;
+    return acc;
+  }, {});
+  const summary = Object.entries(counts)
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([status, n]) => `${n} ${status}`)
+    .join(", ");
+  lines.push(`Total: ${entries.length} file${entries.length === 1 ? "" : "s"} — ${summary}`);
+  return lines.join("\n");
+}
+
+/**
+ * Run `git diff --name-status <baseRef>...HEAD` and return structured entries.
+ * Returns [] if git exits with an error or produces no output.
+ *
+ * @param {string} baseRef
+ * @returns {Promise<DiffEntry[]>}
+ */
+export async function collectAffectedFiles(baseRef) {
+  if (!baseRef) return [];
+  try {
+    const result = await runCommand("git", ["diff", "--name-status", `${baseRef}...HEAD`]);
+    if (result.exitCode !== 0) return [];
+    return parseNameStatus(result.stdout || "");
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * High-level: generate the tree content and persist it to `tree.txt` under
+ * the given journal directory. Returns `{ written, path }`.
+ *
+ * @param {string} journalDir
+ * @param {string} baseRef
+ * @param {{ logger?: Object }} [options]
+ * @returns {Promise<{ written: boolean, path: string|null }>}
+ */
+export async function writeTreeJournal(journalDir, baseRef, options = {}) {
+  const entries = await collectAffectedFiles(baseRef);
+  const content = renderTree(entries);
+  if (!content) return { written: false, path: null };
+  const filePath = path.join(journalDir, "tree.txt");
+  try {
+    await fs.mkdir(journalDir, { recursive: true });
+    await fs.writeFile(filePath, content + "\n", "utf8");
+    options.logger?.info?.(`Wrote file tree journal: ${filePath}`);
+    return { written: true, path: filePath };
+  } catch (err) {
+    options.logger?.warn?.(`Failed to write tree journal (non-blocking): ${err.message}`);
+    return { written: false, path: null };
+  }
+}

package/src/skills/semantic-detector.js

@@ -0,0 +1,147 @@
+/**
+ * Semantic skill detection using the triage classifier.
+ *
+ * The regex-based detector (skill-detector.js) is fast but shallow: it only
+ * catches dependencies that name themselves explicitly. A task like
+ * "add a feature flag system" might benefit from an "a/b-testing" skill
+ * that regex cannot guess without an exhaustive keyword list.
+ *
+ * Semantic mode asks the classifier agent to pick skills from a known
+ * catalog given the task text and the skills already detected by regex.
+ * The catalog is intentionally small and curated — we don't hit the
+ * openskills.cc marketplace API (not available). If the classifier is
+ * unavailable (missing provider / missing API key), we return [] and the
+ * pipeline keeps working with the regex-only result.
+ */
+
+import { createAgent } from "../agents/index.js";
+import { resolveRole } from "../config.js";
+
+/**
+ * Curated catalog of skills the classifier is allowed to suggest. Keeping
+ * this small prevents the model from hallucinating non-existent skills and
+ * bounds the tokens spent on the prompt.
+ */
+export const SEMANTIC_CATALOG = [
+  "astro", "nextjs", "react", "vue", "svelte", "angular",
+  "express", "fastify", "nestjs",
+  "java", "kotlin", "go", "rust", "ruby", "php", "dotnet", "elixir",
+  "python", "python-data", "python-ml", "pytest-patterns",
+  "django", "flask", "fastapi",
+  "sql-analysis", "prisma", "mongodb",
+  "owasp-top-10", "security-checklist",
+  "java-code-review", "python-code-review",
+  "frontend-design", "csv-transform", "data-report",
+  "vitest-patterns", "jest-patterns", "playwright-patterns", "cypress-patterns",
+];
+
+const PROMPT = (task, catalog, alreadyDetected) => `You are a classifier that picks which domain skills would help solve a task.
+
+Task:
+"""${task}"""
+
+Already detected skills (do NOT repeat, but consider the task context they imply):
+${alreadyDetected.length > 0 ? alreadyDetected.join(", ") : "(none)"}
+
+From this exact catalog, output a JSON array with the names of 0 to 5 additional skills that would meaningfully help. Output ONLY the JSON array, no prose.
+
+Catalog (pick strict matches only):
+${catalog.join(", ")}
+
+Rules:
+- Only names from the catalog. Do NOT invent.
+- Prefer precision over recall: empty array is a valid answer when nothing fits.
+- Do NOT include already-detected skills.
+- Respond with a single JSON array, e.g. ["python-data","sql-analysis"]
+`;
+
+function tryParseArray(raw) {
+  if (!raw) return [];
+  try {
+    const m = String(raw).match(/\[[^\]]*\]/);
+    if (!m) return [];
+    const parsed = JSON.parse(m[0]);
+    if (!Array.isArray(parsed)) return [];
+    return parsed.filter((s) => typeof s === "string");
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Ask the classifier for additional skills.
+ *
+ * @param {Object} args
+ * @param {string} args.task
+ * @param {string[]} args.alreadyDetected
+ * @param {Object} args.config - Karajan config
+ * @param {Object} [args.logger]
+ * @returns {Promise<string[]>}
+ */
+export async function refineSkillsSemantically({ task, alreadyDetected = [], config, logger }) {
+  if (!task || typeof task !== "string") return [];
+  let provider;
+  try {
+    provider = resolveRole(config, "triage")?.provider
+      || resolveRole(config, "planner")?.provider
+      || resolveRole(config, "coder")?.provider;
+  } catch {
+    provider = null;
+  }
+  if (!provider) {
+    logger?.debug?.("semantic-detector: no classifier provider — skipping");
+    return [];
+  }
+
+  let agent;
+  try {
+    agent = createAgent(provider, config, logger);
+  } catch (err) {
+    logger?.debug?.(`semantic-detector: classifier unavailable (${err.message}) — skipping`);
+    return [];
+  }
+  if (!agent || typeof agent.runTask !== "function") {
+    logger?.debug?.("semantic-detector: classifier agent has no runTask() — skipping");
+    return [];
+  }
+
+  const prompt = PROMPT(task, SEMANTIC_CATALOG, alreadyDetected);
+  let res;
+  try {
+    res = await agent.runTask(prompt, { timeoutMs: 30_000 });
+  } catch (err) {
+    logger?.warn?.(`semantic-detector: classifier call failed (${err.message}) — skipping`);
+    return [];
+  }
+  if (!res?.ok) {
+    logger?.debug?.("semantic-detector: classifier returned not-ok — skipping");
+    return [];
+  }
+
+  const suggested = tryParseArray(res.output || res.result?.raw || "");
+  const allowed = new Set(SEMANTIC_CATALOG);
+  const alreadySet = new Set(alreadyDetected.map((s) => s.toLowerCase()));
+  return suggested
+    .map((s) => String(s).trim())
+    .filter((s) => s && allowed.has(s) && !alreadySet.has(s.toLowerCase()))
+    .slice(0, 5);
+}
+
+/**
+ * Resolve the effective skills mode from config + flags.
+ * Precedence: flags.skillsMode > config.skills.mode > globalThis default > "auto".
+ *
+ * The global default lets the test harness opt out of semantic detection
+ * without each orchestrator test having to mock this module (tests/setup.js
+ * sets globalThis.__KJ_DEFAULT_SKILLS_MODE = "regex").
+ *
+ * @param {Object} config
+ * @param {Object} [flags]
+ * @returns {"auto"|"regex"|"semantic"|"none"}
+ */
+export function resolveSkillsMode(config, flags = {}) {
+  const defaultMode = globalThis.__KJ_DEFAULT_SKILLS_MODE || "auto";
+  const candidate = flags.skillsMode ?? config?.skills?.mode ?? defaultMode;
+  const valid = new Set(["auto", "regex", "semantic", "none"]);
+  return valid.has(candidate) ? candidate : "auto";
+}