karajan-code 3.2.0 → 3.4.0

package/src/prompts/reviewer.js

@@ -1,6 +1,7 @@
 import { buildRtkInstructions } from "./rtk-snippet.js";
 import { loadAvailableSkills, buildSkillSection } from "../skills/skill-loader.js";
 import { getLanguageInstruction } from "../utils/locale.js";
+import { section, buildPromptLayout, joinLayout, STABLE, VOLATILE } from "./prompt-layout.js";
 
 const SUBAGENT_PREAMBLE = [
   "IMPORTANT: You are running as a Karajan sub-agent.",
@@ -24,51 +25,45 @@ const SERENA_INSTRUCTIONS = [
   "Fall back to reading files only when Serena tools are not sufficient."
 ].join("\n");
 
-export async function buildReviewerPrompt({ task, diff, reviewRules, mode, serenaEnabled = false, rtkAvailable = false, productContext = null, domainContext = null, projectDir = null, language = "en", provider = null }) {
+/**
+ * Build the reviewer prompt as a { stable, volatile } layout (Φ1,
+ * KJC-PCS-0057). The stable block (preamble, mode, scope rules, JSON
+ * schema, serena/rtk, contexts, review rules, skills) is identical
+ * across reviews of the same project, so prefix-caching providers hit
+ * on it; the per-review content (task context + git diff, up to 12 KB
+ * and always different) goes last.
+ */
+export async function buildReviewerPromptLayout({ task, diff, reviewRules, mode, serenaEnabled = false, rtkAvailable = false, productContext = null, domainContext = null, projectDir = null, language = "en", provider = null }) {
   const truncatedDiff = diff.length > 12000 ? `${diff.slice(0, 12000)}\n\n[TRUNCATED]` : diff;
 
   const langInstruction = getLanguageInstruction(language);
-  const sections = [
-    serenaEnabled ? SUBAGENT_PREAMBLE_SERENA : SUBAGENT_PREAMBLE,
-    ...(langInstruction ? [langInstruction] : []),
-    `You are a code reviewer in ${mode} mode.`,
-    "CRITICAL SCOPE RULE: Only review changes that are part of the diff below. Do NOT flag issues in unchanged code, missing features planned for future tasks, or improvements outside the scope of this task. If the diff is correct for what the task asks, approve it — even if the broader codebase has other issues.",
-    "Only block approval for issues IN THE DIFF that are bugs, security vulnerabilities, or clear violations of the review rules.",
-    "Return only one valid JSON object and nothing else.",
-    "JSON schema:",
-    '{"approved":boolean,"blocking_issues":[{"id":string,"severity":"critical|high|medium|low","file":string,"line":number,"description":string,"suggested_fix":string}],"non_blocking_suggestions":[string],"summary":string,"confidence":number}'
-  ];
-
-  if (serenaEnabled) {
-    sections.push(SERENA_INSTRUCTIONS);
-  }
-
   const rtkSnippet = buildRtkInstructions({ rtkAvailable });
-  if (rtkSnippet) {
-    sections.push(rtkSnippet);
-  }
-
-  if (productContext) {
-    sections.push(`## Product Context\n${productContext}`);
-  }
-
-  if (domainContext) {
-    sections.push(`## Domain Context\n${domainContext}`);
-  }
-
-  sections.push(
-    `Task context:\n${task}`,
-    `Review rules:\n${reviewRules}`,
-    `Git diff:\n${truncatedDiff}`
-  );
-
+  let skillSection = null;
   if (projectDir) {
     const skills = await loadAvailableSkills(projectDir);
-    const skillSection = buildSkillSection(skills, { provider, role: "reviewer" });
-    if (skillSection) {
-      sections.push(skillSection);
-    }
+    skillSection = buildSkillSection(skills, { provider, role: "reviewer" });
   }
 
-  return sections.join("\n\n");
+  return buildPromptLayout([
+    section(serenaEnabled ? SUBAGENT_PREAMBLE_SERENA : SUBAGENT_PREAMBLE, STABLE),
+    section(langInstruction, STABLE),
+    section(`You are a code reviewer in ${mode} mode.`, STABLE),
+    section("CRITICAL SCOPE RULE: Only review changes that are part of the diff below. Do NOT flag issues in unchanged code, missing features planned for future tasks, or improvements outside the scope of this task. If the diff is correct for what the task asks, approve it — even if the broader codebase has other issues.", STABLE),
+    section("Only block approval for issues IN THE DIFF that are bugs, security vulnerabilities, or clear violations of the review rules.", STABLE),
+    section("Return only one valid JSON object and nothing else.", STABLE),
+    section("JSON schema:", STABLE),
+    section('{"approved":boolean,"blocking_issues":[{"id":string,"severity":"critical|high|medium|low","file":string,"line":number,"description":string,"suggested_fix":string}],"non_blocking_suggestions":[string],"summary":string,"confidence":number}', STABLE),
+    section(serenaEnabled ? SERENA_INSTRUCTIONS : null, STABLE),
+    section(rtkSnippet, STABLE),
+    section(productContext ? `## Product Context\n${productContext}` : null, STABLE),
+    section(domainContext ? `## Domain Context\n${domainContext}` : null, STABLE),
+    section(`Review rules:\n${reviewRules}`, STABLE),
+    section(skillSection, STABLE),
+    section(`Task context:\n${task}`, VOLATILE),
+    section(`Git diff:\n${truncatedDiff}`, VOLATILE),
+  ]);
+}
+
+export async function buildReviewerPrompt(options) {
+  return joinLayout(await buildReviewerPromptLayout(options));
 }

package/src/roles/agent-role.js

@@ -123,12 +123,20 @@ export class AgentRole extends BaseRole {
     const agent = this.createAgentInstance(provider);
 
     const promptResult = await this.buildPrompt(extracted);
-    const { prompt, onOutput } = typeof promptResult === "string"
+    const { prompt, onOutput, stablePrompt, volatilePrompt } = typeof promptResult === "string"
       ? { prompt: promptResult, onOutput: extracted.onOutput }
       : { onOutput: extracted.onOutput, ...promptResult };
 
     const runArgs = { prompt, role: this.name };
     if (onOutput) runArgs.onOutput = onOutput;
+    // Φ1-D (KJC-PCS-0057): roles that build their prompt as a
+    // stable/volatile layout forward both buckets so cache-aware agents
+    // (ClaudeAgent) can ship the stable block as system prompt. Agents
+    // that don't know the fields keep reading `prompt` as before.
+    if (stablePrompt && volatilePrompt) {
+      runArgs.stablePrompt = stablePrompt;
+      runArgs.volatilePrompt = volatilePrompt;
+    }
     // Kill a hung agent: without a silence timeout a coder / reviewer
     // that stalls with no output left `kj run` waiting indefinitely.
     // PlannerRole set this itself; every other role was unprotected.

package/src/roles/coder-role.js

@@ -1,5 +1,6 @@
 import { AgentRole } from "./agent-role.js";
-import { buildCoderPrompt } from "../prompts/coder.js";
+import { buildCoderPromptLayout } from "../prompts/coder.js";
+import { joinLayout } from "../prompts/prompt-layout.js";
 import { isHostAgent } from "../utils/agent-detect.js";
 import { HostAgent } from "../agents/host-agent.js";
 import { detectProjectStack } from "../utils/stack-detect.js";
@@ -66,7 +67,7 @@ export class CoderRole extends AgentRole {
       try { stack = await detectProjectStack(projectDir); } catch { /* best-effort */ }
       try { testFramework = await detectTestFramework(projectDir); } catch { /* best-effort */ }
     }
-    const prompt = await buildCoderPrompt({
+    const layout = await buildCoderPromptLayout({
       task, reviewerFeedback, sonarSummary, deferredContext, acceptanceTests,
       adrs, specSection, reviewerFindings, huId,
       coderRules: this.instructions,
@@ -79,7 +80,9 @@ export class CoderRole extends AgentRole {
       stack, testFramework,
       provider: this._resolvedProvider || (typeof this.resolveProvider === "function" ? this.resolveProvider() : null)
     });
-    return { prompt };
+    // Φ1-D: prompt is the joined layout (identical for every agent);
+    // the buckets ride along so ClaudeAgent can system-split them.
+    return { prompt: joinLayout(layout), stablePrompt: layout.stable, volatilePrompt: layout.volatile };
   }
 
   buildSuccessResult(parsed, provider, agentResult) {

package/src/roles/reviewer-role.js

@@ -1,6 +1,7 @@
 import { AgentRole } from "./agent-role.js";
 import { buildRtkInstructions } from "../prompts/rtk-snippet.js";
 import { extractFirstJson } from "../utils/json-extract.js";
+import { section, buildPromptLayout, joinLayout, STABLE, VOLATILE } from "../prompts/prompt-layout.js";
 
 const MAX_DIFF_LENGTH = 12000;
 
@@ -32,30 +33,26 @@ export class ReviewerRole extends AgentRole {
     };
   }
 
+  // Φ1-E (KJC-PCS-0057): stable block (preamble, instructions, mode,
+  // schema, contexts, rtk, review rules) first; task + diff — different
+  // on every review — last. The buckets ride along so ClaudeAgent can
+  // ship the stable block via --append-system-prompt (Φ1-D).
   async buildPrompt({ task, diff, reviewRules }) {
-    const sections = [SUBAGENT_PREAMBLE];
-    if (this.instructions) sections.push(this.instructions);
-    sections.push(
-      `You are a code reviewer in ${this.config?.review_mode || "standard"} mode.`,
-      "Return only one valid JSON object and nothing else.",
-      "JSON schema:",
-      '{"approved":boolean,"blocking_issues":[{"id":string,"severity":"critical|high|medium|low","file":string,"line":number,"description":string,"suggested_fix":string}],"non_blocking_suggestions":[string],"summary":string,"confidence":number}',
-      `Task context:\n${task}`
-    );
-
-    const pc = this.config?.productContext;
-    if (pc) sections.push(`## Product Context\n${pc}`);
-    const dc = this.config?.domainContext;
-    if (dc) sections.push(`## Domain Context\n${dc}`);
-
-    const rtkSnippet = buildRtkInstructions({
-      rtkAvailable: Boolean(this.config?.rtk?.available)
-    });
-    if (rtkSnippet) sections.push(rtkSnippet);
-    if (reviewRules) sections.push(`Review rules:\n${reviewRules}`);
-    sections.push(`Git diff:\n${truncateDiff(diff)}`);
-
-    return { prompt: sections.join("\n\n") };
+    const layout = buildPromptLayout([
+      section(SUBAGENT_PREAMBLE, STABLE),
+      section(this.instructions, STABLE),
+      section(`You are a code reviewer in ${this.config?.review_mode || "standard"} mode.`, STABLE),
+      section("Return only one valid JSON object and nothing else.", STABLE),
+      section("JSON schema:", STABLE),
+      section('{"approved":boolean,"blocking_issues":[{"id":string,"severity":"critical|high|medium|low","file":string,"line":number,"description":string,"suggested_fix":string}],"non_blocking_suggestions":[string],"summary":string,"confidence":number}', STABLE),
+      section(this.config?.productContext ? `## Product Context\n${this.config.productContext}` : null, STABLE),
+      section(this.config?.domainContext ? `## Domain Context\n${this.config.domainContext}` : null, STABLE),
+      section(buildRtkInstructions({ rtkAvailable: Boolean(this.config?.rtk?.available) }), STABLE),
+      section(reviewRules ? `Review rules:\n${reviewRules}` : null, STABLE),
+      section(`Task context:\n${task}`, VOLATILE),
+      section(`Git diff:\n${truncateDiff(diff)}`, VOLATILE),
+    ]);
+    return { prompt: joinLayout(layout), stablePrompt: layout.stable, volatilePrompt: layout.volatile };
   }
 
   parseOutput(raw) {

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

@@ -18,7 +18,7 @@ import path from "node:path";
  * @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 {{ total_cost_usd?: number, total_tokens?: number, total_cached_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
@@ -107,6 +107,55 @@ function renderBreakdownByRole(breakdown) {
   return ["| Role | Tokens | Cost |", "|---|---|---|", ...rows].join("\n");
 }
 
+/**
+ * Render the Cache hits section (Φ0-F, KJC-TSK-0524). Shows how many input
+ * tokens were served from provider-side prompt caches, per role, plus a
+ * conservative dollar savings estimate.
+ *
+ * Savings formula: cached tokens are billed at ~10% of the input rate (the
+ * Anthropic/OpenAI convention). Per role:
+ *   savings_usd ≈ cost_usd * (cached_tokens / tokens_in) * 0.9
+ * The estimate is approximate (output tokens also contribute to cost_usd)
+ * and labelled with `~$` so users don't read it as exact.
+ *
+ * Returns:
+ *   - null when no budget data is available
+ *   - "cold run" placeholder when cached == 0 across all roles
+ *   - Markdown table sorted by cached tokens desc when there is cache activity
+ */
+function renderCacheHits(budget) {
+  if (!budget) return null;
+  const totalCached = Number(budget.total_cached_tokens ?? 0);
+  const breakdown = budget.breakdown_by_role || {};
+  const entries = Object.entries(breakdown)
+    .map(([role, m]) => ({
+      role,
+      cached: Number(m?.cached_tokens || 0),
+      tokens_in: Number(m?.tokens_in || 0),
+      cost: Number(m?.total_cost_usd || 0),
+    }))
+    .filter((e) => e.cached > 0);
+
+  if (totalCached === 0 && entries.length === 0) {
+    return "_Cache hits: 0 tokens (cold run)._";
+  }
+
+  const rows = entries
+    .sort((a, b) => b.cached - a.cached)
+    .map((e) => {
+      const ratio = e.tokens_in > 0 ? (e.cached / e.tokens_in) * 100 : 0;
+      const savings = e.tokens_in > 0 ? e.cost * (e.cached / e.tokens_in) * 0.9 : 0;
+      return `| \`${esc(e.role)}\` | ${e.cached.toLocaleString("en-US")} | ${ratio.toFixed(1)}% | ~$${savings.toFixed(4)} |`;
+    });
+  const header = "| Role | Cached tokens | Ratio (cached/in) | Est. savings |\n|---|---|---|---|";
+  return [
+    `**Total cached**: ${totalCached.toLocaleString("en-US")} tokens`,
+    "",
+    header,
+    ...rows,
+  ].join("\n");
+}
+
 /**
  * Render the Skills section: which process skills (addyosmani) were resolved
  * for the task, which OpenSkills were installed, and which skills would have
@@ -192,6 +241,11 @@ export function buildSummaryMarkdown(input) {
     sections.push("", "## Budget breakdown (by role)", "", breakdown);
   }
 
+  const cacheHitsSection = renderCacheHits(input.budget);
+  if (cacheHitsSection) {
+    sections.push("", "## Cache hits", "", cacheHitsSection);
+  }
+
   const skillsSection = renderSkills(input.skills);
   if (skillsSection) {
     sections.push("", "## Skills Used", "", skillsSection);

package/src/utils/budget.js

@@ -26,6 +26,13 @@ export function extractUsageMetrics(result, defaultModel = null) {
     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 ??
@@ -58,7 +65,7 @@ export function extractUsageMetrics(result, defaultModel = null) {
     }
   }
 
-  return { tokens_in: finalTokensIn, tokens_out: finalTokensOut, cost_usd, model, estimated };
+  return { tokens_in: finalTokensIn, tokens_out: finalTokensOut, cached_tokens, cost_usd, model, estimated };
 }
 
 function toSafeNumber(value) {
@@ -79,9 +86,10 @@ function normalizeLimit(limit) {
 }
 
 function addToBreakdown(map, key, entry) {
-  const current = map[key] || { tokens_in: 0, tokens_out: 0, total_tokens: 0, total_cost_usd: 0, count: 0 };
+  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;
@@ -94,9 +102,10 @@ export class BudgetTracker {
     this.pricing = mergePricing(DEFAULT_MODEL_PRICING, options.pricing || {});
   }
 
-  record({ role, provider, model, tokens_in, tokens_out, cost_usd, duration_ms, stage_index, estimated } = {}) {
+  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({
@@ -113,6 +122,7 @@ export class BudgetTracker {
       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) {
@@ -129,19 +139,36 @@ export class BudgetTracker {
   }
 
   total() {
+    return this._aggregate(this.entries);
+  }
+
+  _aggregate(entries) {
     let tokensIn = 0;
     let tokensOut = 0;
+    let cached = 0;
     let totalCost = 0;
-    for (const entry of this.entries) {
+    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,
-      cost_usd: totalCost
-    };
+    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) {
@@ -171,6 +198,7 @@ export class BudgetTracker {
     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],
@@ -191,6 +219,7 @@ export class BudgetTracker {
         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;

package/src/utils/telemetry.js

@@ -26,6 +26,49 @@ export function buildTelemetryPayload(eventName, data = {}) {
   };
 }
 
+/**
+ * Φ0-H (KJC-TSK-0526): aggregate cache-hit ratio per role from the budget
+ * summary the orchestrator already builds. Returns `{ cached_pct_coder,
+ * cached_pct_reviewer, cached_pct_total }` with values rounded to one
+ * decimal, or `null` per slot when there is no measurable input (rather
+ * than `0`, so the backend can distinguish "no cache" from "no signal").
+ *
+ * Provider-agnostic by design: the BudgetTracker entries already
+ * normalise `cached_tokens` for Anthropic (`cache_read_input_tokens`),
+ * OpenAI / Codex (`prompt_tokens_details.cached_tokens`), Gemini
+ * (`cachedContentTokenCount`) and the LiteLLM-routed providers
+ * (aider, opencode), so this helper does not need to know which
+ * provider produced the run.
+ *
+ * @param {{ breakdown_by_role?: object, total_cached_tokens?: number } | null | undefined} summary
+ * @returns {{ cached_pct_coder: number|null, cached_pct_reviewer: number|null, cached_pct_total: number|null }}
+ */
+export function computeCachedPct(summary) {
+  const empty = { cached_pct_coder: null, cached_pct_reviewer: null, cached_pct_total: null };
+  if (!summary || typeof summary !== "object") return empty;
+  const ratio = (cached, tokensIn) => {
+    const c = Number(cached);
+    const t = Number(tokensIn);
+    if (!Number.isFinite(c) || !Number.isFinite(t) || t <= 0 || c < 0) return null;
+    return Math.round((c / t) * 1000) / 10;
+  };
+  const byRole = summary.breakdown_by_role || {};
+  const coder = byRole.coder || null;
+  const reviewer = byRole.reviewer || null;
+  let totalCached = 0;
+  let totalIn = 0;
+  for (const role of Object.keys(byRole)) {
+    const r = byRole[role];
+    totalCached += Number(r?.cached_tokens || 0);
+    totalIn += Number(r?.tokens_in || 0);
+  }
+  return {
+    cached_pct_coder: coder ? ratio(coder.cached_tokens, coder.tokens_in) : null,
+    cached_pct_reviewer: reviewer ? ratio(reviewer.cached_tokens, reviewer.tokens_in) : null,
+    cached_pct_total: ratio(totalCached, totalIn)
+  };
+}
+
 /**
  * Send an anonymous telemetry event. Non-blocking, fire-and-forget.
  * Never throws, never blocks the pipeline.