karajan-code 2.8.0 → 2.9.0

package/src/prompts/audit.js

@@ -1,4 +1,12 @@
 import { extractFirstJson } from "../utils/json-extract.js";
+import { groupIssuesBySeverity } from "../audit/sonar-findings.js";
+import { groupVulnerabilitiesBySeverity } from "../audit/osv-findings.js";
+import { groupFindingsBySeverity as groupSemgrepBySeverity } from "../audit/semgrep-findings.js";
+import { formatCwvVerdict } from "../audit/webperf-input.js";
+
+const MAX_SONAR_ISSUES_IN_PROMPT = 50;
+const MAX_OSV_VULNS_IN_PROMPT = 50;
+const MAX_SEMGREP_FINDINGS_IN_PROMPT = 50;
 
 const SUBAGENT_PREAMBLE = [
   "IMPORTANT: You are running as a Karajan sub-agent.",
@@ -7,14 +15,20 @@ const SUBAGENT_PREAMBLE = [
   "DO NOT modify any files — this is a read-only analysis. Only use: Read, Grep, Glob, Bash (for analysis commands like wc, find, git log, du, npm ls)."
 ].join(" ");
 
-export const AUDIT_DIMENSIONS = ["security", "codeQuality", "performance", "architecture", "testing"];
+export const AUDIT_DIMENSIONS = ["security", "codeQuality", "performance", "architecture", "testing", "accessibility"];
+
+// Dimensions that only apply to frontend / fullstack projects. Auto-dropped
+// from the default dimension list when stack detection knows the project
+// is backend-only — preserves activation when the user explicitly opts in
+// via --dimensions=accessibility (KJC-TSK-0359).
+const FRONTEND_ONLY_DIMENSIONS = new Set(["accessibility"]);
 
 const VALID_HEALTH = new Set(["good", "fair", "poor", "critical"]);
 const VALID_SCORES = new Set(["A", "B", "C", "D", "F"]);
 const VALID_SEVERITIES = new Set(["critical", "high", "medium", "low"]);
 const VALID_IMPACT = new Set(["high", "medium", "low"]);
 
-export function buildAuditPrompt({ task, instructions, dimensions = null, context = null, basalCost = null, growthDelta = null }) {
+export function buildAuditPrompt({ task, instructions, dimensions = null, context = null, basalCost = null, growthDelta = null, stack = null, sonarFindings = null, webperf = null, osvFindings = null, semgrepFindings = null }) {
   const sections = [SUBAGENT_PREAMBLE];
 
   if (instructions) {
@@ -27,9 +41,46 @@ export function buildAuditPrompt({ task, instructions, dimensions = null, contex
     "DO NOT modify any files. This is a READ-ONLY analysis."
   );
 
-  const activeDimensions = dimensions
-    ? dimensions.filter(d => AUDIT_DIMENSIONS.includes(d))
-    : AUDIT_DIMENSIONS;
+  // Stack hint — when detected, tells the LLM what kind of project this is
+  // so it can filter out irrelevant heuristics (e.g. don't flag bundle size
+  // in an Express-only API; don't flag N+1 queries in a static Astro site).
+  // Detected by src/utils/stack-detect.js — KJC-TSK-0358.
+  if (stack && (stack.frameworks?.length > 0 || stack.language || stack.isFrontend || stack.isBackend)) {
+    const stackLines = ["## Project Stack"];
+    if (stack.language) stackLines.push(`- Language: ${stack.language}`);
+    if (stack.frameworks?.length) stackLines.push(`- Frameworks: ${stack.frameworks.join(", ")}`);
+    const tier = stack.isFullstack
+      ? "fullstack (frontend + backend)"
+      : stack.isFrontend
+        ? "frontend-only"
+        : stack.isBackend
+          ? "backend-only"
+          : "unknown";
+    stackLines.push(`- Tier: ${tier}`);
+    if (stack.isFullstack) {
+      stackLines.push("Apply BOTH backend heuristics (queries, sync I/O, caching) AND frontend heuristics (bundle size, lazy loading, render-blocking) where each layer applies.");
+    } else if (stack.isFrontend) {
+      stackLines.push("This project is frontend-only. SKIP findings about N+1 queries, sync file I/O in request handlers, missing pagination on list endpoints, and other backend-specific patterns. Focus on bundle size, lazy loading, render-blocking resources, image optimisation, and accessibility hints.");
+    } else if (stack.isBackend) {
+      stackLines.push("This project is backend-only. SKIP findings about bundle size, lazy loading, render-blocking resources, image optimisation, and frontend accessibility. Focus on queries, sync I/O, pagination, caching, auth/authz, and dependency hygiene.");
+    }
+    sections.push(stackLines.join("\n"));
+  }
+
+  // When dimensions are explicit, honour them verbatim — even frontend-only
+  // dimensions on a backend project (the user knows what they want).
+  // When dimensions are absent, default to all but drop frontend-only
+  // dimensions if the stack is provably backend-only. Unknown stack falls
+  // back to the full list (no false negatives — better an extra section
+  // than a missing one).
+  let activeDimensions;
+  if (dimensions) {
+    activeDimensions = dimensions.filter(d => AUDIT_DIMENSIONS.includes(d));
+  } else if (stack && stack.isBackend && !stack.isFrontend) {
+    activeDimensions = AUDIT_DIMENSIONS.filter(d => !FRONTEND_ONLY_DIMENSIONS.has(d));
+  } else {
+    activeDimensions = AUDIT_DIMENSIONS;
+  }
 
   if (activeDimensions.includes("security")) {
     sections.push(
@@ -105,9 +156,32 @@ export function buildAuditPrompt({ task, instructions, dimensions = null, contex
     );
   }
 
+  if (activeDimensions.includes("accessibility")) {
+    sections.push(
+      "## Accessibility Analysis (WCAG 2.x)",
+      [
+        "- Missing alt text on <img> tags (decorative images need empty alt=\"\", not absent)",
+        "- Form inputs without associated <label> or aria-label",
+        "- Heading hierarchy violations (h1 → h3 skipping h2; multiple h1 per page)",
+        "- Buttons / links containing only icons without aria-label or visually-hidden text",
+        "- Interactive elements built from <div>/<span> without role + keyboard handlers",
+        "- ARIA roles misused (presentation on focusable elements, redundant on native semantics)",
+        "- Focus management gaps (modals without focus trap, no visible :focus styles, tabindex misuse)",
+        "- Colour-only signalling (status indicated by red/green only, no icon or text)",
+        "- Static contrast — flag suspicious low-contrast colour pairs in CSS variables / token files",
+        "- Missing lang attribute on <html>, missing skip-to-content link, missing landmarks"
+      ].join("\n"),
+      "Skip findings about colour contrast that require runtime rendering (e.g. computed styles); flag the suspect CSS values and recommend an axe-core/Lighthouse runtime check."
+    );
+  }
+
+  // JSON schema — keep the per-dimension entries in sync with AUDIT_DIMENSIONS.
+  const schemaDimensions = AUDIT_DIMENSIONS
+    .map(d => `"${d}":{"score":"A|B|C|D|F","findings":[]}`)
+    .join(",");
   sections.push(
     "Return a single valid JSON object and nothing else.",
-    'JSON schema: {"ok":true,"result":{"summary":{"overallHealth":"good|fair|poor|critical","totalFindings":number,"critical":number,"high":number,"medium":number,"low":number},"dimensions":{"security":{"score":"A|B|C|D|F","findings":[]},"codeQuality":{"score":"A|B|C|D|F","findings":[]},"performance":{"score":"A|B|C|D|F","findings":[]},"architecture":{"score":"A|B|C|D|F","findings":[]},"testing":{"score":"A|B|C|D|F","findings":[]}},"topRecommendations":[{"priority":number,"dimension":string,"action":string,"impact":"high|medium|low","effort":"high|medium|low"}]},"summary":string}',
+    `JSON schema: {"ok":true,"result":{"summary":{"overallHealth":"good|fair|poor|critical","totalFindings":number,"critical":number,"high":number,"medium":number,"low":number},"dimensions":{${schemaDimensions}},"topRecommendations":[{"priority":number,"dimension":string,"action":string,"impact":"high|medium|low","effort":"high|medium|low"}]},"summary":string}`,
     'Each finding: {"severity":"critical|high|medium|low","file":string,"line":number,"rule":string,"description":string,"recommendation":string}',
     `Only include dimensions you were asked to analyze: ${activeDimensions.join(", ")}`
   );
@@ -146,6 +220,132 @@ export function buildAuditPrompt({ task, instructions, dimensions = null, contex
     sections.push(lines.join("\n"));
   }
 
+  // Sonar findings — KJC-TSK-0361. Deterministic input from a tool the
+  // codebase already runs (kj run + SonarStage). The audit reads existing
+  // open issues + quality-gate state instead of re-scanning. Capped at
+  // MAX_SONAR_ISSUES_IN_PROMPT total entries (50) across all severities to
+  // bound prompt size; the LLM is told the truncated count so it can
+  // prioritise.
+  if (sonarFindings?.available && (sonarFindings.total > 0 || sonarFindings.qualityGate)) {
+    const lines = ["## SonarQube Findings"];
+    if (sonarFindings.qualityGate?.status) {
+      lines.push(`- Quality gate: ${sonarFindings.qualityGate.status}`);
+    }
+    if (sonarFindings.total > 0) {
+      lines.push(`- Total open issues: ${sonarFindings.total}`);
+      const groups = groupIssuesBySeverity(sonarFindings.issues);
+      let remaining = MAX_SONAR_ISSUES_IN_PROMPT;
+      for (const [severity, issues] of Object.entries(groups)) {
+        if (issues.length === 0) continue;
+        lines.push("");
+        lines.push(`### ${severity} (${issues.length})`);
+        const slice = issues.slice(0, Math.max(0, remaining));
+        for (const issue of slice) {
+          const loc = issue.component ? `${issue.component}${issue.line ? `:${issue.line}` : ""}` : "";
+          const rule = issue.rule ? ` [${issue.rule}]` : "";
+          lines.push(`  - ${loc}${rule} ${issue.message || ""}`.trim());
+        }
+        if (issues.length > slice.length) {
+          lines.push(`  - ... and ${issues.length - slice.length} more in ${severity}`);
+        }
+        remaining -= slice.length;
+      }
+    }
+    lines.push("");
+    lines.push("Cross-reference these with your own findings. When your finding overlaps a Sonar rule, mention the rule ID in the `rule` field — that's a high-confidence match. Findings the LLM raises that Sonar can't see (architecture, naming, API design) are still valuable; mark them with rule names like \"AUDIT-ARCH-N\".");
+    sections.push(lines.join("\n"));
+  }
+
+  // WebPerf — KJC-TSK-0360. Two modes: a real CWV measurement when one is
+  // surfaced via config.webperf.lastResult (future `kj webperf` command)
+  // OR static frontend-perf hints for the LLM to look at the source code
+  // when no live measurement is available. Backend-only projects skip the
+  // section entirely (collectWebPerfInput returns available:false).
+  if (webperf?.available) {
+    const lines = ["## WebPerf — Frontend Performance"];
+    if (webperf.mode === "cwv-result") {
+      lines.push("Live Core Web Vitals measurement available — incorporate the verdict below into the performance dimension findings:");
+      lines.push("");
+      lines.push(formatCwvVerdict(webperf));
+      lines.push("");
+      lines.push("If a metric is `poor`, recommend a concrete code change (preconnect, lazy-load, image format, critical CSS, defer script). Cite the offending file or pattern when you can find it in the source.");
+    } else {
+      lines.push("No live CWV measurement was provided. Audit the source for these static frontend-perf patterns and include findings under the `performance` dimension:");
+      lines.push("");
+      lines.push("- Render-blocking `<link rel=\"stylesheet\">` or `<script>` without `defer`/`async` in `<head>`");
+      lines.push("- Large JavaScript bundles imported eagerly that could be `await import(...)` or split by route");
+      lines.push("- Non-modern image formats (only .jpg/.png) where webp/avif are widely supported");
+      lines.push("- `<img>` without `width`/`height` attributes (causes CLS)");
+      lines.push("- `<img>` without `loading=\"lazy\"` for off-screen images, or videos auto-playing without `preload=\"metadata\"`");
+      lines.push("- Web fonts loaded without `font-display: swap` or without `<link rel=\"preconnect\">` to the font origin");
+      lines.push("- Whole-library imports for one helper (e.g. `import _ from 'lodash'` instead of `lodash/get`)");
+      lines.push("- Missing critical CSS extraction or above-the-fold inlining strategy in build config");
+      lines.push("- Large third-party scripts (analytics, A/B, chat widgets) without defer + facade pattern");
+      lines.push("- Unbounded list rendering without virtualisation for very long collections");
+    }
+    sections.push(lines.join("\n"));
+  }
+
+  // OSV vulnerabilities — KJC-TSK-0365. Deterministic CVE/GHSA findings
+  // from osv-scanner across the dependency manifest. Capped at
+  // MAX_OSV_VULNS_IN_PROMPT entries; the LLM is told the truncated count.
+  // Findings fold into the `security` dimension with the upstream
+  // identifier (CVE-/GHSA-) as the rule.
+  if (osvFindings?.available && (osvFindings.total > 0)) {
+    const lines = ["## OSV Vulnerabilities"];
+    lines.push(`- Total open vulnerabilities in dependencies: ${osvFindings.total}`);
+    const groups = groupVulnerabilitiesBySeverity(osvFindings.vulnerabilities);
+    let remaining = MAX_OSV_VULNS_IN_PROMPT;
+    for (const [severity, vulns] of Object.entries(groups)) {
+      if (vulns.length === 0) continue;
+      lines.push("");
+      lines.push(`### ${severity} (${vulns.length})`);
+      const slice = vulns.slice(0, Math.max(0, remaining));
+      for (const vuln of slice) {
+        const where = vuln.package ? `${vuln.package}@${vuln.version || "?"}` : "(unknown package)";
+        const fixed = vuln.fixed ? ` → fixed in ${vuln.fixed}` : "";
+        lines.push(`  - ${vuln.id} ${where}${fixed}: ${vuln.summary || ""}`.trim());
+      }
+      if (vulns.length > slice.length) {
+        lines.push(`  - ... and ${vulns.length - slice.length} more in ${severity}`);
+      }
+      remaining -= slice.length;
+    }
+    lines.push("");
+    lines.push("These CVE/GHSA findings are GROUND TRUTH — incorporate them into the `security` dimension. Use the OSV id (CVE-XXXX-XXXX or GHSA-xxxx-xxxx-xxxx) as the `rule` field. Recommend the fixed version when available.");
+    sections.push(lines.join("\n"));
+  }
+
+  // Semgrep SAST findings — KJC-TSK-0366. Static analysis catches what
+  // sonar/CVE-DBs miss: SQL/Cmd injection, XSS, hardcoded secrets,
+  // taint flow, language-specific anti-patterns. Capped at
+  // MAX_SEMGREP_FINDINGS_IN_PROMPT entries; LLM is told these are
+  // deterministic and asked to use rule IDs as-is in findings.
+  if (semgrepFindings?.available && semgrepFindings.total > 0) {
+    const lines = ["## Semgrep SAST Findings"];
+    lines.push(`- Total findings: ${semgrepFindings.total}`);
+    const groups = groupSemgrepBySeverity(semgrepFindings.findings);
+    let remaining = MAX_SEMGREP_FINDINGS_IN_PROMPT;
+    for (const [severity, findings] of Object.entries(groups)) {
+      if (findings.length === 0) continue;
+      lines.push("");
+      lines.push(`### ${severity} (${findings.length})`);
+      const slice = findings.slice(0, Math.max(0, remaining));
+      for (const f of slice) {
+        const loc = f.file ? `${f.file}${f.line ? `:${f.line}` : ""}` : "";
+        const cwe = f.cwe ? ` (${Array.isArray(f.cwe) ? f.cwe.join(", ") : f.cwe})` : "";
+        lines.push(`  - ${loc} [${f.rule}]${cwe}: ${f.message || ""}`.trim());
+      }
+      if (findings.length > slice.length) {
+        lines.push(`  - ... and ${findings.length - slice.length} more in ${severity}`);
+      }
+      remaining -= slice.length;
+    }
+    lines.push("");
+    lines.push("These SAST findings are GROUND TRUTH — fold ERROR-severity ones into the `security` dimension as critical/high findings. Use the semgrep rule id (e.g. javascript.express.security.audit.xss.direct-response-write) verbatim in the `rule` field; that lets the developer look it up in the semgrep registry.");
+    sections.push(lines.join("\n"));
+  }
+
   if (context) {
     sections.push(`## Context\n${context}`);
   }

package/src/prompts/rtk-snippet.js

@@ -2,7 +2,7 @@
  * RTK (Rust Token Killer) prompt instruction snippet.
  * Injected into coder/reviewer prompts when RTK is detected.
  */
-export const RTK_INSTRUCTIONS = [
+const RTK_INSTRUCTIONS = [
   "## Token Optimization (RTK detected)",
   "RTK is installed. Prefix ALL Bash tool calls with `rtk` to reduce token usage:",
   "- Use `rtk git status` instead of `git status`",

package/src/roles/audit-role.js

@@ -1,6 +1,11 @@
 import { AgentRole } from "./agent-role.js";
 import { buildAuditPrompt, parseAuditOutput, AUDIT_DIMENSIONS } from "../prompts/audit.js";
 import { measureBasalCost, loadPreviousAudit, saveAuditSnapshot, computeGrowthDelta } from "../audit/basal-cost.js";
+import { detectProjectStack } from "../utils/stack-detect.js";
+import { collectSonarFindings } from "../audit/sonar-findings.js";
+import { collectWebPerfInput } from "../audit/webperf-input.js";
+import { collectOsvFindings } from "../audit/osv-findings.js";
+import { collectSemgrepFindings } from "../audit/semgrep-findings.js";
 
 function parseDimensions(dimensionsStr) {
   if (!dimensionsStr || dimensionsStr === "all") return null;
@@ -26,37 +31,98 @@ export class AuditRole extends AgentRole {
     super({ ...opts, name: "audit" });
   }
 
-  async execute(input) {
-    const task = typeof input === "string" ? input : input?.task || this.context?.task || "";
-    const onOutput = typeof input === "string" ? null : input?.onOutput || null;
-    const rawDimensions = typeof input === "object" ? input?.dimensions || null : null;
-    const context = typeof input === "object" ? input?.context || null : null;
-    const dimensions = typeof rawDimensions === "string" ? parseDimensions(rawDimensions) : rawDimensions;
-
+  /**
+   * Run the deterministic side of an audit — basalCost, stack detection,
+   * Sonar issues, WebPerf input — without invoking the LLM. Cheap (no
+   * tokens, no API call). KJC-TSK-0364 splits the original execute() into
+   * this collector + executeWithDeterministic() so the CLI can show
+   * deterministic findings first and ask the user before paying for the
+   * LLM phase.
+   *
+   * @param {object|string} input - same shape execute() accepts
+   * @returns {Promise<object>} deterministic context (the same data
+   *   execute() would gather internally)
+   */
+  async collectDeterministic(input) {
+    const noSonar = typeof input === "object" ? Boolean(input?.noSonar) : false;
+    const noOsv = typeof input === "object" ? Boolean(input?.noOsv) : false;
+    const noSemgrep = typeof input === "object" ? Boolean(input?.noSemgrep) : false;
     const projectDir = this.config?.projectDir || process.cwd();
     let basalCost = null;
     let growthDelta = null;
+    let stack = null;
+    let sonarFindings = null;
+    let webperf = null;
+    let osvFindings = null;
+    let semgrepFindings = null;
     try {
       basalCost = await measureBasalCost(projectDir);
       const previous = await loadPreviousAudit(projectDir);
       growthDelta = computeGrowthDelta(basalCost, previous);
     } catch { /* basal cost is best-effort */ }
+    try {
+      stack = await detectProjectStack(projectDir);
+    } catch { /* stack detect is best-effort */ }
+    if (!noSonar) {
+      try {
+        sonarFindings = await collectSonarFindings(this.config, this.logger);
+      } catch { /* sonar fetch is best-effort */ }
+    }
+    try {
+      webperf = collectWebPerfInput(stack, this.config);
+    } catch { /* webperf input is best-effort */ }
+    // OSV vulnerabilities — KJC-TSK-0365. Best-effort: missing
+    // osv-scanner binary returns available:false and the audit
+    // continues without the section.
+    if (!noOsv) {
+      try {
+        osvFindings = await collectOsvFindings(projectDir, this.logger);
+      } catch { /* osv-scanner is best-effort */ }
+    }
+    // Semgrep SAST — KJC-TSK-0366. Best-effort: missing semgrep binary
+    // returns available:false and the audit continues without the section.
+    if (!noSemgrep) {
+      try {
+        semgrepFindings = await collectSemgrepFindings(projectDir, this.logger);
+      } catch { /* semgrep is best-effort */ }
+    }
+    return { projectDir, basalCost, growthDelta, stack, sonarFindings, webperf, osvFindings, semgrepFindings };
+  }
+
+  /**
+   * Run the LLM phase of an audit using a pre-collected deterministic
+   * context. KJC-TSK-0364: separated from execute() so the CLI can run
+   * collectDeterministic() first, show findings, prompt, and only then
+   * call this if the user wants to spend tokens.
+   */
+  async executeWithDeterministic(input, deterministicCtx) {
+    const task = typeof input === "string" ? input : input?.task || this.context?.task || "";
+    const onOutput = typeof input === "string" ? null : input?.onOutput || null;
+    const rawDimensions = typeof input === "object" ? input?.dimensions || null : null;
+    const context = typeof input === "object" ? input?.context || null : null;
+    const dimensions = typeof rawDimensions === "string" ? parseDimensions(rawDimensions) : rawDimensions;
+
+    const { projectDir, basalCost, growthDelta, stack, sonarFindings, webperf, osvFindings, semgrepFindings } = deterministicCtx;
 
     const provider = this.resolveProvider();
     const agent = this.createAgentInstance(provider);
-    const prompt = buildAuditPrompt({ task, instructions: this.instructions, dimensions, context, basalCost, growthDelta });
+    const prompt = buildAuditPrompt({ task, instructions: this.instructions, dimensions, context, basalCost, growthDelta, stack, sonarFindings, webperf, osvFindings, semgrepFindings });
     const runArgs = { prompt, role: "audit" };
     if (onOutput) runArgs.onOutput = onOutput;
+    const startedAt = Date.now();
     const result = await agent.runTask(runArgs);
+    const durationMs = Date.now() - startedAt;
+
+    const usage = extractUsage(result, { provider, durationMs });
 
     if (!result.ok) {
-      return { ok: false, result: { error: result.error || result.output || "Audit failed", provider }, summary: `Audit failed: ${result.error || "unknown error"}`, usage: result.usage };
+      return { ok: false, result: { error: result.error || result.output || "Audit failed", provider }, summary: `Audit failed: ${result.error || "unknown error"}`, usage };
     }
 
     try {
       const parsed = parseAuditOutput(result.output);
       if (!parsed) {
-        return { ok: true, result: { raw: result.output, provider }, summary: "Audit complete (unstructured output)", usage: result.usage };
+        return { ok: true, result: { raw: result.output, provider }, summary: "Audit complete (unstructured output)", usage };
       }
       if (basalCost) { try { await saveAuditSnapshot(projectDir, basalCost); } catch { /* best-effort */ } }
 
@@ -65,13 +131,59 @@ export class AuditRole extends AgentRole {
         result: {
           summary: parsed.summary, dimensions: parsed.dimensions,
           topRecommendations: parsed.topRecommendations,
-          basalCost: basalCost || undefined, growthDelta: growthDelta || undefined, provider
+          textSummary: parsed.textSummary || undefined,
+          basalCost: basalCost || undefined, growthDelta: growthDelta || undefined,
+          stack: stack || undefined,
+          sonarFindings: sonarFindings?.available ? sonarFindings : undefined,
+          webperf: webperf?.available ? webperf : undefined,
+          osvFindings: osvFindings?.available ? osvFindings : undefined,
+          semgrepFindings: semgrepFindings?.available ? semgrepFindings : undefined,
+          provider
         },
         summary: buildSummary(parsed),
-        usage: result.usage
+        usage
       };
     } catch {
-      return { ok: true, result: { raw: result.output, provider }, summary: "Audit complete (unstructured output)", usage: result.usage };
+      return { ok: true, result: { raw: result.output, provider }, summary: "Audit complete (unstructured output)", usage };
     }
   }
+
+  /**
+   * Convenience: run both phases in one call. Identical to the previous
+   * (single-phase) execute() so MCP and pipeline callers don't change.
+   */
+  async execute(input) {
+    const deterministicCtx = await this.collectDeterministic(input);
+    return this.executeWithDeterministic(input, deterministicCtx);
+  }
+}
+
+/**
+ * Consolidate the usage telemetry the agent spreads across its top-level
+ * result fields. Returns a single object so consumers (CLI formatter,
+ * report-file writer, MCP) don't need to know about the spread shape.
+ *
+ * @param {object} result - raw agent.runTask() return
+ * @param {{provider: string, durationMs: number}} ctx
+ * @returns {{available: boolean, provider: string, model?: string, tokens_in?: number, tokens_out?: number, total_tokens?: number, cost_usd?: number, durationMs: number, reason?: string}}
+ */
+function extractUsage(result, { provider, durationMs }) {
+  if (!result || typeof result !== "object") {
+    return { available: false, provider, durationMs, reason: "no agent result" };
+  }
+  const tokens_in = Number.isFinite(result.tokens_in) ? result.tokens_in : null;
+  const tokens_out = Number.isFinite(result.tokens_out) ? result.tokens_out : null;
+  if (tokens_in === null && tokens_out === null) {
+    return { available: false, provider, model: result.model, durationMs, reason: `provider "${provider}" did not report token usage` };
+  }
+  return {
+    available: true,
+    provider,
+    model: result.model,
+    tokens_in: tokens_in ?? 0,
+    tokens_out: tokens_out ?? 0,
+    total_tokens: (tokens_in ?? 0) + (tokens_out ?? 0),
+    cost_usd: typeof result.cost_usd === "number" ? result.cost_usd : null,
+    durationMs,
+  };
 }

package/src/sonar/api.js

@@ -3,7 +3,7 @@ import { withRetry } from "../utils/retry.js";
 import { resolveSonarProjectKey } from "./project-key.js";
 import { resolveSonarToken } from "./config-resolver.js";
 
-export class SonarApiError extends Error {
+class SonarApiError extends Error {
   constructor(message, { url, httpStatus, hint } = {}) {
     super(message);
     this.name = "SonarApiError";

package/src/utils/display/event-handlers.js

@@ -342,7 +342,7 @@ export const EVENT_HANDLERS = {
 };
 
 /** Event types suppressed in quiet mode (internal/noise events). */
-export const QUIET_SUPPRESSED = new Set([
+const QUIET_SUPPRESSED = new Set([
   "agent:output",
   "agent:stall",
   "pipeline:simplify",

package/src/utils/display/header.js

@@ -8,7 +8,7 @@ import { ANSI } from "./formatters.js";
 const DISPLAY_PKG_PATH = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../../package.json");
 const DISPLAY_VERSION = JSON.parse(readFileSync(DISPLAY_PKG_PATH, "utf8")).version;
 
-export const BAR = `${ANSI.dim}\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500${ANSI.reset}`;
+const BAR = `${ANSI.dim}\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500${ANSI.reset}`;
 
 /**
  * Print task, configuration and pipeline header

package/src/utils/display/session-summary.js

@@ -15,7 +15,7 @@ export function printSessionStages(stages) {
   printSessionSonar(stages.sonar);
 }
 
-export function printSessionPlanner(planner) {
+function printSessionPlanner(planner) {
   if (!planner?.title && !planner?.approach && !planner?.completedSteps?.length) return;
   const planParts = [];
   if (planner.title) planParts.push(planner.title);
@@ -26,7 +26,7 @@ export function printSessionPlanner(planner) {
   }
 }
 
-export function printSessionSonar(sonar) {
+function printSessionSonar(sonar) {
   if (!sonar) return;
   const gateLabel = sonar.gateStatus === "OK" ? ANSI.green : ANSI.red;
   console.log(`  ${ANSI.dim}\ud83d\udd0d Sonar: ${gateLabel}${sonar.gateStatus}${ANSI.reset}${ANSI.dim} (${sonar.openIssues ?? 0} issues)${ANSI.reset}`);
@@ -55,7 +55,7 @@ export function printSessionGit(git) {
   }
 }
 
-export function isBudgetUnavailable(budget) {
+function isBudgetUnavailable(budget) {
   return budget.usage_available === false ||
     (budget.total_tokens === 0 && budget.total_cost_usd === 0 && Object.keys(budget.breakdown_by_role || {}).length > 0);
 }

package/src/utils/display/solomon.js

@@ -1,6 +1,6 @@
 import { ANSI } from "./formatters.js";
 
-export const SOLOMON_RULING_HANDLERS = {
+const SOLOMON_RULING_HANDLERS = {
   approve(detail, elapsed) {
     const dismissedCount = detail?.dismissed?.length || 0;
     const dismissedSuffix = dismissedCount > 0 ? ` (${dismissedCount} dismissed)` : "";

package/src/utils/role-assigner.js

@@ -128,4 +128,4 @@ export function applyRoleAssignments(config, assignments) {
   return config;
 }
 
-export { CAPABILITY_TIERS, ROLE_PREFERENCES };
+export { CAPABILITY_TIERS };