@karajan-family/code 4.21.0

package/src/utils/banner.js

@@ -0,0 +1,66 @@
+/**
+ * Karajan Code ASCII banner with brand colors.
+ *
+ * Brand palette:
+ *   #AACCEE  steel blue (primary text)
+ *   #88CC88  green (accents, robot eyes)
+ *   #464000  dark olive
+ *   #444411  charcoal (secondary text)
+ */
+
+const C = {
+  blue:     "\x1b[38;2;170;204;238m",  // #AACCEE
+  green:    "\x1b[38;2;100;190;100m",   // green accents
+  gray:     "\x1b[38;2;140;140;140m",   // borders/dim
+  white:    "\x1b[38;2;220;220;220m",   // bright text
+  charcoal: "\x1b[38;2;100;100;80m",    // #444411 approx
+  bold:     "\x1b[1m",
+  dim:      "\x1b[2m",
+  reset:    "\x1b[0m"
+};
+
+const R = C.reset;
+
+const BANNER_LINES = [
+  ``,
+  `${C.gray}        ╭───────────╮`,
+  `${C.gray}        │  ${C.green}~${C.gray}        │`,
+  `${C.gray}        │  ${C.green}|${C.gray}     ${C.green}|${C.gray}  │  ${C.charcoal}|`,
+  `${C.gray}        |     ${C.green}v${C.gray}     │ ${C.charcoal}/`,
+  `${C.gray}      ${C.charcoal}\\${C.gray} ╰───────────╯${C.charcoal}/`,
+  `${C.charcoal}       \\${C.gray} ╭───${C.white}⋈${C.gray}───╮ ${C.charcoal}/`,
+  `${C.charcoal}        \\${C.gray}        ${C.charcoal}/`,
+  `${C.gray}         ╰───────╯`,
+  ``,
+  `  ${C.bold}${C.blue}╦╔═ ╔═╗ ╦═╗ ╔═╗  ╦ ╔═╗ ╔╗╔${R}`,
+  `  ${C.bold}${C.blue}╠╩╗ ╠═╣ ╠╦╝ ╠═╣  ║ ╠═╣ ║║║${R}`,
+  `  ${C.bold}${C.blue}╩ ╩ ╩ ╩ ╩╚═ ╩ ╩ ╚╝ ╩ ╩ ╝╚╝${R}`,
+  `  ${C.bold}${C.white}        C O D E${R}  %%VERSION%%`,
+  `  ${C.charcoal}multiagent coding orchestrator${R}`,
+  ``,
+];
+
+/**
+ * Print the Karajan Code ASCII banner.
+ * @param {string} version - Package version to display
+ * @param {object} [opts]
+ * @param {boolean} [opts.compact] - Skip mascot, show only text
+ * @param {boolean} [opts.force] - Print even without TTY
+ */
+export function printBanner(version, opts = {}) {
+  if (!opts.force && !process.stdout.isTTY) return;
+
+  const versionTag = `${C.dim}v${version}${R}`;
+
+  if (opts.compact) {
+    console.log();
+    for (const line of BANNER_LINES.slice(10)) {
+      console.log(line.replace("%%VERSION%%", versionTag));
+    }
+    return;
+  }
+
+  for (const line of BANNER_LINES) {
+    console.log(line.replace("%%VERSION%%", versionTag));
+  }
+}

package/src/utils/binary-sources.js

@@ -0,0 +1,70 @@
+// Standalone install routes for tools with no package manager available
+// (KJC-TSK-0607). On a machine with no pipx/brew/go, `kj install-tools`
+// still needs a way to install osv-scanner and semgrep.
+//
+//  · osv-scanner ships a single static binary per platform on its GitHub
+//    releases — we build the /latest/download URL for the current platform.
+//  · semgrep has no single static binary; we offer the most viable concrete
+//    command (Docker image if docker exists, otherwise bootstrapping pipx).
+
+const OSV_BASE = "https://github.com/google/osv-scanner/releases/latest/download";
+
+function osvOs(platform) {
+  if (platform === "linux") return "linux";
+  if (platform === "darwin") return "darwin";
+  if (platform === "win32") return "windows";
+  return null;
+}
+
+function osvArch(arch) {
+  if (arch === "x64") return "amd64";
+  if (arch === "arm64") return "arm64";
+  return null;
+}
+
+/**
+ * Build the osv-scanner static-binary download source for a platform+arch,
+ * or null when the combination has no published asset.
+ *
+ * @returns {{ url: string, name: string }|null}
+ */
+export function osvScannerSource(platform = process.platform, arch = process.arch) {
+  const os = osvOs(platform);
+  const a = osvArch(arch);
+  if (!os || !a) return null;
+  const ext = os === "windows" ? ".exe" : "";
+  return { url: `${OSV_BASE}/osv-scanner_${os}_${a}${ext}`, name: `osv-scanner${ext}` };
+}
+
+/**
+ * Most viable concrete route to install semgrep without a package manager.
+ * Returns a command the user sees before it runs — never a bare docs URL.
+ *
+ * @returns {{ via: "docker"|"pipx", command: string }}
+ */
+export function semgrepFallback(available = {}) {
+  if (available.docker) return { via: "docker", command: "docker pull semgrep/semgrep" };
+  // KJC-BUG-0120 (issue #1256): on Debian/Ubuntu-like systems the system
+  // Python is externally managed (PEP 668) and often ships without pip at
+  // all — `python3 -m pip install --user` is guaranteed to fail there.
+  // pipx must come from the distro's own package manager.
+  if (available.apt) return { via: "apt", command: "sudo apt update && sudo apt install -y pipx && pipx install semgrep" };
+  if (available.dnf) return { via: "dnf", command: "sudo dnf install -y pipx && pipx install semgrep" };
+  return { via: "pipx", command: "python3 -m pip install --user pipx && pipx install semgrep" };
+}
+
+/**
+ * Resolve the standalone route for a tool when no package manager matched.
+ *  · binary  → download a static binary into ~/.local/bin.
+ *  · command → run/show a concrete install command.
+ *
+ * @returns {{ kind: "binary", url: string, name: string }|{ kind: "command", via: string, command: string }|null}
+ */
+export function resolveStandalone(tool, available = {}, platform = process.platform, arch = process.arch) {
+  if (tool === "osv-scanner") {
+    const src = osvScannerSource(platform, arch);
+    return src ? { kind: "binary", ...src } : null;
+  }
+  if (tool === "semgrep") return { kind: "command", ...semgrepFallback(available) };
+  return null;
+}

package/src/utils/board-prompt-bridge.js

@@ -0,0 +1,108 @@
+/**
+ * File-based RPC between a non-interactive Karajan run and the HU
+ * Board. When the runner needs an answer to a question (Solomon
+ * escalation, max-iterations resolution, anything wired to
+ * askQuestion) and stdin is unavailable (the board's ▶ Run plan
+ * spawns with stdio=ignore), it writes a prompt JSON to a known
+ * directory and polls for an "answer" sibling file. The board's
+ * chokidar watcher sees the prompt and surfaces it as a modal; the
+ * user's answer is POSTed back, written as the answer file, and the
+ * runner picks it up and resolves.
+ *
+ * Why files instead of a socket / SSE-back-channel:
+ *   - Zero new server in the runner. A detached child has no listening
+ *     port; opening one would mean discovery + auth + cleanup.
+ *   - Survives a runner restart: if the user kills + resumes, the
+ *     pending prompt is still on disk and the board can re-show it.
+ *   - The board already watches `~/.karajan/`; one more glob is cheap.
+ *
+ * Layout:
+ *   $KJ_HOME/prompts/<promptId>.json         - { sessionId, question, context, createdAt }
+ *   $KJ_HOME/prompts/<promptId>.answer.json  - { answer, answeredAt }    (written by board)
+ *
+ * The bridge owns the lifecycle: write the prompt, poll until the
+ * answer arrives, delete BOTH files, return the answer string (or
+ * null when the user picked "stop"). Aborts cleanly on signal or on
+ * a configurable timeout (default 30 min — long enough for a coffee).
+ */
+
+import { mkdir, writeFile, readFile, unlink, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+
+const POLL_INTERVAL_MS = 500;
+const DEFAULT_TIMEOUT_MS = 30 * 60 * 1000;          // 30 min
+
+// Delegated to src/utils/paths.js so KARAJAN_HOME, KJ_HOME (with
+// deprecation warning), VITEST tmp and the default all share one
+// precedence chain — KJC-TSK-0420.
+import { getPromptsDir } from "./paths.js";
+
+function exists(path) {
+  return stat(path).then(() => true, () => false);
+}
+
+/**
+ * Publish a prompt + wait for the answer. Returns the answer string,
+ * `null` when the user explicitly picked "stop", or rejects on
+ * timeout / abort.
+ *
+ * @param {object} args
+ * @param {string} args.sessionId
+ * @param {string} args.question
+ * @param {object} [args.context]   - serialised verbatim into the prompt JSON
+ * @param {number} [args.timeoutMs]
+ * @param {AbortSignal} [args.signal]
+ * @param {object} [args.logger]    - { info, warn } — optional, for breadcrumbs
+ * @returns {Promise<string|null>}
+ */
+export async function askThroughBoard({ sessionId, question, context = null, timeoutMs = DEFAULT_TIMEOUT_MS, signal = null, logger = null } = {}) {
+  if (!question) throw new Error("askThroughBoard: question is required");
+
+  const dir = getPromptsDir();
+  await mkdir(dir, { recursive: true });
+
+  const promptId = `prompt-${Date.now()}-${randomUUID().slice(0, 8)}`;
+  const promptPath = join(dir, `${promptId}.json`);
+  const answerPath = join(dir, `${promptId}.answer.json`);
+
+  const payload = {
+    promptId,
+    sessionId: sessionId || null,
+    question,
+    context: context || null,
+    createdAt: new Date().toISOString(),
+  };
+  await writeFile(promptPath, JSON.stringify(payload, null, 2), "utf-8");
+  logger?.info?.(`[prompt-bridge] published ${promptId} — waiting for answer via the board`);
+
+  const startedAt = Date.now();
+  try {
+    while (true) {
+      if (signal?.aborted) throw new Error("askThroughBoard: aborted");
+      if (Date.now() - startedAt > timeoutMs) {
+        throw new Error(`askThroughBoard: timed out after ${Math.round(timeoutMs / 1000)}s waiting for answer to ${promptId}`);
+      }
+      if (await exists(answerPath)) {
+        const raw = await readFile(answerPath, "utf-8");
+        let answer;
+        try { ({ answer } = JSON.parse(raw)); } catch { answer = null; }
+        await unlink(answerPath).catch(() => {});
+        await unlink(promptPath).catch(() => {});
+        if (typeof answer === "string" && answer.trim().toLowerCase() === "stop") return null;
+        return typeof answer === "string" ? answer.trim() : null;
+      }
+      await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
+    }
+  } catch (err) {
+    // Best-effort cleanup of the prompt file on error so it doesn't
+    // get stuck pending on the board forever.
+    await unlink(promptPath).catch(() => {});
+    throw err;
+  }
+}
+
+/** Test seam — exposes the resolved prompts dir for assertions. */
+export function _getPromptsDirForTests() {
+  return getPromptsDir();
+}

package/src/utils/budget.js

@@ -0,0 +1,229 @@
+import { calculateUsageCostUsd, DEFAULT_MODEL_PRICING, mergePricing } from "./pricing.js";
+
+/**
+ * Estimate token counts from character lengths when CLIs don't report usage.
+ * Rough heuristic: ~4 characters per token for English text.
+ */
+export function estimateTokens(promptLength, responseLength) {
+  return {
+    tokens_in: Math.ceil((promptLength || 0) / 4),
+    tokens_out: Math.ceil((responseLength || 0) / 4),
+    estimated: true
+  };
+}
+
+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 cached_tokens =
+    result?.cached_tokens ??
+    usage?.cached_tokens ??
+    usage?.cache_read_input_tokens ??
+    usage?.prompt_tokens_details?.cached_tokens ??
+    usage?.cachedContentTokenCount ??
+    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;
+
+  // If no real token data AND no explicit cost, estimate from prompt/output sizes.
+  // Primary: uses result.promptSize when explicitly provided.
+  // Fallback: estimates from result.output or result.error text length.
+  let estimated = false;
+  let finalTokensIn = tokens_in;
+  let finalTokensOut = tokens_out;
+  const hasExplicitCost = cost_usd !== undefined && cost_usd !== null && cost_usd !== "";
+  if (!tokens_in && !tokens_out && !hasExplicitCost) {
+    const outputText = result?.output || result?.error || result?.summary || "";
+    const promptSize = result?.promptSize || 0;
+    const MIN_TEXT_FOR_ESTIMATION = 40;
+    if (promptSize > 0 || outputText.length >= MIN_TEXT_FOR_ESTIMATION) {
+      const est = estimateTokens(promptSize, outputText.length);
+      finalTokensIn = est.tokens_in;
+      finalTokensOut = est.tokens_out;
+      estimated = true;
+    }
+  }
+
+  return { tokens_in: finalTokensIn, tokens_out: finalTokensOut, cached_tokens, cost_usd, model, estimated };
+}
+
+function toSafeNumber(value) {
+  const n = Number(value);
+  if (!Number.isFinite(n) || n < 0) return 0;
+  return n;
+}
+
+function roundUsd(value) {
+  return Number(toSafeNumber(value).toFixed(6));
+}
+
+function normalizeLimit(limit) {
+  if (limit === null || limit === undefined || limit === "") return null;
+  const n = Number(limit);
+  if (!Number.isFinite(n) || n < 0) return null;
+  return n;
+}
+
+function addToBreakdown(map, key, entry) {
+  const current = map[key] || { tokens_in: 0, tokens_out: 0, cached_tokens: 0, total_tokens: 0, total_cost_usd: 0, count: 0 };
+  current.tokens_in += entry.tokens_in;
+  current.tokens_out += entry.tokens_out;
+  current.cached_tokens += entry.cached_tokens || 0;
+  current.total_tokens += entry.tokens_in + entry.tokens_out;
+  current.total_cost_usd = roundUsd(current.total_cost_usd + entry.cost_usd);
+  current.count += 1;
+  map[key] = current;
+}
+
+export class BudgetTracker {
+  constructor(options = {}) {
+    this.entries = [];
+    this.pricing = mergePricing(DEFAULT_MODEL_PRICING, options.pricing || {});
+  }
+
+  record({ role, provider, model, tokens_in, tokens_out, cached_tokens, cost_usd, duration_ms, stage_index, estimated } = {}) {
+    const safeTokensIn = toSafeNumber(tokens_in);
+    const safeTokensOut = toSafeNumber(tokens_out);
+    const safeCached = toSafeNumber(cached_tokens);
+    const hasExplicitCost = cost_usd !== undefined && cost_usd !== null && cost_usd !== "";
+    const modelName = model || provider || null;
+    const computedCost = calculateUsageCostUsd({
+      provider: provider,
+      model: modelName,
+      tokens_in: safeTokensIn,
+      tokens_out: safeTokensOut,
+      pricing: this.pricing
+    });
+    const entry = {
+      role: role || "unknown",
+      provider: provider || "unknown",
+      model: modelName,
+      timestamp: new Date().toISOString(),
+      tokens_in: safeTokensIn,
+      tokens_out: safeTokensOut,
+      cached_tokens: safeCached,
+      cost_usd: roundUsd(hasExplicitCost ? cost_usd : computedCost)
+    };
+    if (duration_ms !== undefined && duration_ms !== null) {
+      entry.duration_ms = toSafeNumber(duration_ms);
+    }
+    if (stage_index !== undefined && stage_index !== null) {
+      entry.stage_index = Number(stage_index);
+    }
+    if (estimated) {
+      entry.estimated = true;
+    }
+    this.entries.push(entry);
+    return entry;
+  }
+
+  total() {
+    return this._aggregate(this.entries);
+  }
+
+  _aggregate(entries) {
+    let tokensIn = 0;
+    let tokensOut = 0;
+    let cached = 0;
+    let totalCost = 0;
+    for (const entry of entries) {
+      tokensIn += entry.tokens_in;
+      tokensOut += entry.tokens_out;
+      cached += entry.cached_tokens || 0;
+      totalCost = roundUsd(totalCost + entry.cost_usd);
+    }
+    return { tokens_in: tokensIn, tokens_out: tokensOut, cached_tokens: cached, cost_usd: totalCost };
+  }
+
+  /**
+   * Snapshot cursor (Φ0-E). Returns an opaque marker pointing at the current
+   * end of the entries log. Pair with `since(cursor)` to compute per-HU deltas
+   * without resetting global accumulators (per-HU isolation).
+   */
+  cursor() {
+    return this.entries.length;
+  }
+
+  since(cursor = 0) {
+    const start = Number.isFinite(cursor) && cursor >= 0 ? Math.min(cursor, this.entries.length) : 0;
+    const slice = this.entries.slice(start);
+    return { ...this._aggregate(slice), count: slice.length };
+  }
+
+  remaining(limit) {
+    const n = normalizeLimit(limit);
+    if (n === null) return Infinity;
+    return roundUsd(n - this.total().cost_usd);
+  }
+
+  isOverBudget(limit) {
+    const n = normalizeLimit(limit);
+    if (n === null) return false;
+    return this.total().cost_usd > n;
+  }
+
+  hasUsageData() {
+    return this.entries.length > 0 && (this.total().tokens_in > 0 || this.total().tokens_out > 0 || this.total().cost_usd > 0);
+  }
+
+  summary() {
+    const totals = this.total();
+    const byRole = {};
+
+    for (const entry of this.entries) {
+      addToBreakdown(byRole, entry.role, entry);
+    }
+
+    const hasEstimates = this.entries.some(e => e.estimated);
+    const result = {
+      total_tokens: totals.tokens_in + totals.tokens_out,
+      total_cached_tokens: totals.cached_tokens,
+      total_cost_usd: totals.cost_usd,
+      breakdown_by_role: byRole,
+      entries: [...this.entries],
+      usage_available: this.hasUsageData()
+    };
+    if (hasEstimates) result.includes_estimates = true;
+    return result;
+  }
+
+  trace() {
+    return this.entries.map((entry, index) => {
+      const item = {
+        index: entry.stage_index ?? index,
+        role: entry.role,
+        provider: entry.provider,
+        model: entry.model,
+        timestamp: entry.timestamp,
+        duration_ms: entry.duration_ms ?? null,
+        tokens_in: entry.tokens_in,
+        tokens_out: entry.tokens_out,
+        cached_tokens: entry.cached_tokens || 0,
+        cost_usd: entry.cost_usd
+      };
+      if (entry.estimated) item.estimated = true;
+      return item;
+    });
+  }
+}

package/src/utils/cli-ask-question.js

@@ -0,0 +1,93 @@
+import readline from "node:readline";
+
+/**
+ * Shared askQuestion factory used by `kj run` and `kj resume`.
+ *
+ * Pre-fix (KJC-BUG-0081 round 1), `src/commands/run.js` got the guard
+ * but `src/commands/resume.js` kept its own copy without the guard, so
+ * `kj resume --yes` in non-TTY mode still hung on the HU Board bridge.
+ * Centralising the three paths here means both commands honour the
+ * same contract and a future fix only needs to land in one place.
+ *
+ * Three paths:
+ *   1. Interactive TTY: prompt via readline (developer terminal).
+ *   2. No TTY + `flags.yes`: caller asked NOT to be prompted → write
+ *      question + context to stderr, return null so the run aborts
+ *      fast and loud (CI / scripted / `kj audit --yes` desatendido).
+ *   3. No TTY without `flags.yes` (HU Board ▶ Run plan with
+ *      `stdio=ignore`): publish through the file-based bridge so the
+ *      board can surface a modal; block until the user answers.
+ *
+ * @param {object} [opts]
+ * @param {string|null} [opts.sessionId]
+ * @param {object} [opts.flags]
+ * @returns {(question: string, context?: object) => Promise<string|null>}
+ */
+export function createCliAskQuestion(opts = {}) {
+  const { sessionId = null, flags = {} } = opts;
+  return async (question, context) => {
+    const stdinReadable = process.stdin && process.stdin.readable !== false;
+    const isInteractive = Boolean(process.stdin?.isTTY) && stdinReadable;
+    // KJC-TSK-0674 (issue #1289): agents and CI enable the same contract
+    // as --yes explicitly, via --non-interactive or KJ_NON_INTERACTIVE=1,
+    // instead of blocking forever on a board modal nobody is watching.
+    // Explicit mode wins even when a (pseudo-)TTY is attached.
+    const forcedNonInteractive = flags?.nonInteractive || process.env.KJ_NON_INTERACTIVE === "1";
+    if (!isInteractive || forcedNonInteractive) {
+      const nonInteractive = forcedNonInteractive || flags?.yes;
+      if (nonInteractive) {
+        // KJC-BUG-0109: a question that declares a safe default is answered
+        // with it — --yes means "press Enter for me", not "abort on any
+        // gate". Questions without a declared default keep failing loud.
+        const fallback = typeof context?.defaultAnswer === "string" && context.defaultAnswer.trim()
+          ? context.defaultAnswer.trim() : null;
+        if (fallback) {
+          process.stderr.write(`\n[non-interactive] Auto-answering with declared default "${fallback}": ${question}\n`);
+          return fallback;
+        }
+        process.stderr.write(
+          `\n[non-interactive] Pipeline asked a question that cannot be auto-answered:\n`
+          + `  ❓ ${question}\n`
+          + (context?.detail ? `  Context: ${JSON.stringify(context.detail)}\n` : "")
+          + `  Stopping the session. Re-run interactively (TTY or HU Board) to answer it,\n`
+          + `  or pass --skip-spec-review / a more complete spec so the question never appears.\n`
+        );
+        return null;
+      }
+      const { askThroughBoard } = await import("./board-prompt-bridge.js");
+      console.log(`\n❓ ${question}`);
+      if (context?.detail) {
+        console.log(`   Context: ${JSON.stringify(context.detail, null, 2)}`);
+      }
+      console.log(
+        "\n[non-interactive] Routing the prompt to the HU Board.\n"
+        + "  Open http://localhost:4000 — a modal will appear asking for your answer.\n"
+        + "  This process is now waiting; closing the board does NOT cancel the run.\n"
+        + "  Running from an agent or CI with nobody watching the board? Re-run with\n"
+        + "  --non-interactive (or KJ_NON_INTERACTIVE=1) to auto-answer safe defaults instead."
+      );
+      try {
+        return await askThroughBoard({ sessionId, question, context });
+      } catch (err) {
+        console.log(`\n[prompt-bridge] ${err.message} — stopping the session.`);
+        return null;
+      }
+    }
+
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => {
+      console.log(`\n❓ ${question}`);
+      if (context?.detail) {
+        console.log(`   Context: ${JSON.stringify(context.detail, null, 2)}`);
+      }
+      rl.question("\n> Your response (or 'stop' to exit): ", (answer) => {
+        rl.close();
+        if (answer.trim().toLowerCase() === "stop") {
+          resolve(null);
+        } else {
+          resolve(answer.trim());
+        }
+      });
+    });
+  };
+}