brain-dev 0.1.2 → 0.3.0

package/bin/lib/context.cjs

@@ -0,0 +1,397 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { estimateTokens } = require('./tokens.cjs');
+
+// Token budgets per agent type
+const CONTEXT_BUDGETS = {
+  executor: 80000,
+  planner: 60000,
+  verifier: 40000,
+  debugger: 60000,
+  researcher: 30000
+};
+
+// Priority tiers for context files
+const PRIORITY_TIERS = {
+  P0_PLAN: 0,
+  P1_STATE: 1,
+  P2_PHASE_CONTEXT: 2,
+  P3_PRIOR_SUMMARIES: 3,
+  P4_RESEARCH: 4,
+  P5_ARCHITECTURE: 5,
+  P6_ADRS: 6,
+  P7_ROADMAP: 7
+};
+
+/**
+ * Find the phase directory for a given phase number.
+ * Mirrors the pattern from stuck.cjs.
+ * @param {string} brainDir
+ * @param {number} phaseNumber
+ * @returns {string|null}
+ */
+function findPhaseDir(brainDir, phaseNumber) {
+  const phasesDir = path.join(brainDir, 'phases');
+  if (!fs.existsSync(phasesDir)) return null;
+  const padded = String(phaseNumber).padStart(2, '0');
+  const dirs = fs.readdirSync(phasesDir).filter(d => d.startsWith(padded + '-'));
+  return dirs.length > 0 ? path.join(phasesDir, dirs[0]) : null;
+}
+
+/**
+ * Safely read a file, returning empty string on any failure.
+ * @param {string} filePath
+ * @returns {string}
+ */
+function safeRead(filePath) {
+  try {
+    return fs.readFileSync(filePath, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Condense a SUMMARY-NN.md to ~80 tokens.
+ * Extracts: status line, key files, key decisions, provides, patterns.
+ * @param {string} summaryContent
+ * @returns {string}
+ */
+function condenseSummary(summaryContent) {
+  if (!summaryContent || typeof summaryContent !== 'string') return '';
+
+  const lines = summaryContent.split('\n');
+  const parts = [];
+
+  // Extract status from frontmatter or first heading
+  const statusMatch = summaryContent.match(/status:\s*(.+)/i);
+  if (statusMatch) parts.push(`Status: ${statusMatch[1].trim()}`);
+
+  // Extract key files (lines with file paths)
+  const fileLines = lines.filter(l => l.match(/^\s*-\s+.*\.(js|ts|cjs|mjs|json|md|sh|yaml|yml)\b/));
+  if (fileLines.length > 0) {
+    parts.push('Files: ' + fileLines.slice(0, 5).map(l => l.trim().replace(/^-\s*/, '')).join(', '));
+  }
+
+  // Extract decisions (lines under ## Decisions or ## Key Decisions)
+  let inDecisions = false;
+  const decisions = [];
+  for (const line of lines) {
+    if (line.match(/^##\s*(Key\s+)?Decisions/i)) { inDecisions = true; continue; }
+    if (inDecisions && line.startsWith('## ')) { inDecisions = false; continue; }
+    if (inDecisions && line.trim().startsWith('- ')) {
+      decisions.push(line.trim());
+    }
+  }
+  if (decisions.length > 0) {
+    parts.push('Decisions: ' + decisions.slice(0, 3).join('; '));
+  }
+
+  // Extract provides/patterns
+  const providesMatch = summaryContent.match(/provides:\s*(.+)/i);
+  if (providesMatch) parts.push(`Provides: ${providesMatch[1].trim()}`);
+
+  const patternsMatch = summaryContent.match(/patterns?:\s*(.+)/i);
+  if (patternsMatch) parts.push(`Patterns: ${patternsMatch[1].trim()}`);
+
+  const condensed = parts.join(' | ');
+  // Truncate to roughly 80 tokens if needed (~320 chars)
+  if (condensed.length > 320) {
+    return condensed.slice(0, 317) + '...';
+  }
+  return condensed;
+}
+
+/**
+ * Collect and condense SUMMARY-NN.md files for plans before planNum.
+ * @param {string} phaseDir
+ * @param {number} upToPlan - Exclusive upper bound (plans 1..upToPlan-1)
+ * @returns {string} Condensed summaries block
+ */
+function collectPriorSummaries(phaseDir, upToPlan) {
+  if (!phaseDir || upToPlan <= 1) return '';
+
+  const summaries = [];
+  for (let i = 1; i < upToPlan; i++) {
+    const padded = String(i).padStart(2, '0');
+    const summaryPath = path.join(phaseDir, `SUMMARY-${padded}.md`);
+    const content = safeRead(summaryPath);
+    if (content) {
+      const condensed = condenseSummary(content);
+      if (condensed) {
+        summaries.push(`Plan ${padded}: ${condensed}`);
+      }
+    }
+  }
+  return summaries.join('\n');
+}
+
+/**
+ * Build a priority-ordered manifest of context files to include.
+ * @param {string} brainDir
+ * @param {string} phaseDir
+ * @param {number} planNum
+ * @returns {Array<{ tier: number, label: string, path: string, required: boolean }>}
+ */
+function buildContextManifest(brainDir, phaseDir, planNum) {
+  const manifest = [];
+  const padded = String(planNum).padStart(2, '0');
+
+  // P0: Plan content (required)
+  if (phaseDir) {
+    manifest.push({
+      tier: PRIORITY_TIERS.P0_PLAN,
+      label: 'Plan',
+      path: path.join(phaseDir, `PLAN-${padded}.md`),
+      required: true
+    });
+  }
+
+  // P1: STATE.md excerpt (required)
+  manifest.push({
+    tier: PRIORITY_TIERS.P1_STATE,
+    label: 'Project State',
+    path: path.join(brainDir, 'STATE.md'),
+    required: true
+  });
+
+  // P2: Phase CONTEXT.md decisions (required)
+  if (phaseDir) {
+    manifest.push({
+      tier: PRIORITY_TIERS.P2_PHASE_CONTEXT,
+      label: 'Phase Decisions',
+      path: path.join(phaseDir, 'CONTEXT.md'),
+      required: true
+    });
+  }
+
+  // P3: Prior summaries (required, synthetic - handled separately)
+  // Represented as a placeholder; actual content assembled by collectPriorSummaries
+  manifest.push({
+    tier: PRIORITY_TIERS.P3_PRIOR_SUMMARIES,
+    label: 'Prior Plan Results',
+    path: '__SYNTHETIC_PRIOR_SUMMARIES__',
+    required: true
+  });
+
+  // P4: Phase RESEARCH.md
+  if (phaseDir) {
+    manifest.push({
+      tier: PRIORITY_TIERS.P4_RESEARCH,
+      label: 'Research',
+      path: path.join(phaseDir, 'RESEARCH.md'),
+      required: false
+    });
+  }
+
+  // P5: codebase/ARCHITECTURE.md
+  manifest.push({
+    tier: PRIORITY_TIERS.P5_ARCHITECTURE,
+    label: 'Architecture',
+    path: path.join(brainDir, 'codebase', 'ARCHITECTURE.md'),
+    required: false
+  });
+
+  // P6: Relevant ADRs
+  const adrDir = path.join(brainDir, 'decisions');
+  try {
+    if (fs.existsSync(adrDir)) {
+      const adrs = fs.readdirSync(adrDir)
+        .filter(f => f.endsWith('.md'))
+        .sort();
+      for (const adr of adrs) {
+        manifest.push({
+          tier: PRIORITY_TIERS.P6_ADRS,
+          label: `ADR: ${adr}`,
+          path: path.join(adrDir, adr),
+          required: false
+        });
+      }
+    }
+  } catch { /* ADR dir may not exist */ }
+
+  // P7: ROADMAP.md excerpt
+  manifest.push({
+    tier: PRIORITY_TIERS.P7_ROADMAP,
+    label: 'Roadmap',
+    path: path.join(brainDir, 'ROADMAP.md'),
+    required: false
+  });
+
+  return manifest;
+}
+
+/**
+ * Calculate the available context token budget for an agent.
+ * Subtracts a complexity overhead from the base budget.
+ * @param {string} agentType - executor|planner|verifier|debugger|researcher
+ * @param {string} planContent - Raw plan content for complexity estimation
+ * @param {object} [brainConfig] - Optional brain config with budget overrides
+ * @returns {number} Available token budget
+ */
+function calculateContextBudget(agentType, planContent, brainConfig) {
+  const baseBudget = (brainConfig && brainConfig.context_budgets && brainConfig.context_budgets[agentType])
+    || CONTEXT_BUDGETS[agentType]
+    || CONTEXT_BUDGETS.executor;
+
+  // Reserve tokens proportional to plan complexity
+  // Larger plans need more room for the agent's own reasoning
+  const planTokens = estimateTokens(planContent || '');
+  const complexityOverhead = Math.min(Math.round(planTokens * 0.1), 5000);
+
+  return baseBudget - complexityOverhead;
+}
+
+/**
+ * Detect whether any manifest files have been modified after a reference timestamp.
+ * @param {Array<{ path: string }>} manifest
+ * @param {string} referenceTimestamp - ISO timestamp of assembly time
+ * @returns {{ stale: boolean, staleFiles: string[] }}
+ */
+function detectStaleContext(manifest, referenceTimestamp) {
+  const refTime = new Date(referenceTimestamp).getTime();
+  const staleFiles = [];
+
+  for (const entry of manifest) {
+    if (entry.path === '__SYNTHETIC_PRIOR_SUMMARIES__') continue;
+    try {
+      const stat = fs.statSync(entry.path);
+      if (stat.mtime.getTime() > refTime) {
+        staleFiles.push(entry.path);
+      }
+    } catch { /* file may not exist */ }
+  }
+
+  return { stale: staleFiles.length > 0, staleFiles };
+}
+
+/**
+ * Main context assembly function.
+ * Reads files in priority order within token budget, returns assembled context block.
+ *
+ * @param {string} brainDir - Path to .brain/ directory
+ * @param {string} phaseDir - Path to the current phase directory (or null)
+ * @param {number} planNum - Current plan number
+ * @param {object} [opts] - Options
+ * @param {string} [opts.agentType='executor'] - Agent type for budget calculation
+ * @param {object} [opts.brainConfig] - Brain config with optional budget overrides
+ * @returns {{ context: string, manifest: Array, tokenEstimate: number, truncated: boolean }}
+ */
+function assembleTaskContext(brainDir, phaseDir, planNum, opts) {
+  const options = opts || {};
+  const agentType = options.agentType || 'executor';
+  const brainConfig = options.brainConfig || null;
+
+  const manifest = buildContextManifest(brainDir, phaseDir, planNum);
+
+  // Read plan content first to calculate budget
+  const planEntry = manifest.find(e => e.tier === PRIORITY_TIERS.P0_PLAN);
+  const planContent = planEntry ? safeRead(planEntry.path) : '';
+  const budget = calculateContextBudget(agentType, planContent, brainConfig);
+
+  const sections = [];
+  let totalTokens = 0;
+  let truncated = false;
+  const includedFiles = [];
+
+  for (const entry of manifest) {
+    let content;
+    let sectionHeader;
+
+    if (entry.path === '__SYNTHETIC_PRIOR_SUMMARIES__') {
+      content = collectPriorSummaries(phaseDir, planNum);
+      sectionHeader = '## Prior Plan Results';
+    } else {
+      content = safeRead(entry.path);
+      if (entry.tier === PRIORITY_TIERS.P0_PLAN) {
+        sectionHeader = '## Current Plan';
+      } else if (entry.tier === PRIORITY_TIERS.P1_STATE) {
+        sectionHeader = '## Project State';
+      } else if (entry.tier === PRIORITY_TIERS.P2_PHASE_CONTEXT) {
+        sectionHeader = '## Phase Decisions';
+      } else if (entry.tier === PRIORITY_TIERS.P4_RESEARCH) {
+        sectionHeader = '## Research';
+      } else if (entry.tier === PRIORITY_TIERS.P5_ARCHITECTURE) {
+        sectionHeader = '## Architecture';
+      } else if (entry.tier === PRIORITY_TIERS.P6_ADRS) {
+        sectionHeader = `## ${entry.label}`;
+      } else if (entry.tier === PRIORITY_TIERS.P7_ROADMAP) {
+        sectionHeader = '## Roadmap';
+      } else {
+        sectionHeader = `## ${entry.label}`;
+      }
+    }
+
+    if (!content) {
+      if (entry.required) {
+        sections.push(`${sectionHeader}\n[Not available]`);
+      }
+      continue;
+    }
+
+    const sectionText = `${sectionHeader}\n${content}`;
+    const sectionTokens = estimateTokens(sectionText);
+
+    if (totalTokens + sectionTokens > budget) {
+      if (entry.required) {
+        // Truncate required content to fit
+        const remaining = budget - totalTokens;
+        const charLimit = remaining * 4; // CHARS_PER_TOKEN = 4
+        if (charLimit > 100) {
+          const truncatedContent = content.slice(0, charLimit - 20) + '\n[...truncated]';
+          sections.push(`${sectionHeader}\n${truncatedContent}`);
+          totalTokens += estimateTokens(`${sectionHeader}\n${truncatedContent}`);
+          truncated = true;
+          includedFiles.push({ ...entry, truncated: true });
+        }
+      } else {
+        truncated = true;
+      }
+      continue;
+    }
+
+    sections.push(sectionText);
+    totalTokens += sectionTokens;
+    includedFiles.push({ ...entry, truncated: false });
+  }
+
+  const assembledAt = new Date().toISOString();
+
+  // Build the wrapped context block
+  const metadata = [
+    '## Context Metadata',
+    `- Assembled: ${assembledAt}`,
+    `- Token estimate: ${totalTokens}`,
+    `- Truncated: ${truncated ? 'yes' : 'no'}`,
+    `- Agent type: ${agentType}`,
+    `- Budget: ${budget}`
+  ].join('\n');
+
+  sections.push(metadata);
+
+  const context = [
+    '---BRAIN-CONTEXT-START---',
+    sections.join('\n\n'),
+    '---BRAIN-CONTEXT-END---'
+  ].join('\n');
+
+  return {
+    context,
+    manifest: includedFiles,
+    tokenEstimate: totalTokens,
+    truncated
+  };
+}
+
+module.exports = {
+  assembleTaskContext,
+  collectPriorSummaries,
+  condenseSummary,
+  buildContextManifest,
+  calculateContextBudget,
+  detectStaleContext,
+  CONTEXT_BUDGETS,
+  PRIORITY_TIERS
+};

package/bin/lib/cost.cjs

@@ -0,0 +1,273 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { atomicWriteSync } = require('./state.cjs');
+const { estimateTokens } = require('./tokens.cjs');
+
+const METRICS_FILE = 'metrics.json';
+
+// Default per-million-token pricing (conservative estimates)
+const DEFAULT_PRICING = {
+  'claude-opus-4-6': { input: 15.00, output: 75.00 },
+  'claude-sonnet-4-6': { input: 3.00, output: 15.00 },
+  'claude-sonnet-4-20250514': { input: 3.00, output: 15.00 },
+  'claude-haiku-4-5-20251001': { input: 0.25, output: 1.25 },
+  'inherit': { input: 15.00, output: 75.00 } // Conservative default
+};
+
+/**
+ * Create a default metrics object for a new brain project.
+ * @returns {object} Default metrics structure
+ */
+function createDefaultMetrics() {
+  return {
+    $schema: 'brain-metrics/v1',
+    budget: { ceiling_usd: null, warn_at_pct: 80, mode: 'warn' },
+    pricing: { ...DEFAULT_PRICING },
+    totals: { input_tokens: 0, output_tokens: 0, estimated_cost_usd: 0.00, agent_invocations: 0 },
+    by_agent: {},
+    by_phase: {},
+    ledger: []
+  };
+}
+
+/**
+ * Read metrics.json from the given directory.
+ * Returns default metrics if file does not exist or is corrupted.
+ * @param {string} brainDir - Path to .brain/ directory
+ * @returns {object} Metrics object
+ */
+function readMetrics(brainDir) {
+  try {
+    const metricsPath = path.join(brainDir, METRICS_FILE);
+    return JSON.parse(fs.readFileSync(metricsPath, 'utf8'));
+  } catch {
+    return createDefaultMetrics();
+  }
+}
+
+/**
+ * Write metrics.json atomically.
+ * @param {string} brainDir - Path to .brain/ directory
+ * @param {object} metrics - Metrics object to write
+ */
+function writeMetrics(brainDir, metrics) {
+  const metricsPath = path.join(brainDir, METRICS_FILE);
+  atomicWriteSync(metricsPath, JSON.stringify(metrics, null, 2));
+}
+
+/**
+ * Estimate cost in USD for a given model invocation.
+ * @param {string} model - Model identifier
+ * @param {number} inputTokens - Number of input tokens
+ * @param {number} outputTokens - Number of output tokens
+ * @param {object} [pricing] - Optional pricing table override
+ * @returns {number} Estimated cost in USD (rounded to 4 decimal places)
+ */
+function estimateCost(model, inputTokens, outputTokens, pricing) {
+  const p = pricing || DEFAULT_PRICING;
+  const modelPricing = p[model] || p['inherit'] || { input: 15.00, output: 75.00 };
+  const inputCost = (inputTokens / 1_000_000) * modelPricing.input;
+  const outputCost = (outputTokens / 1_000_000) * modelPricing.output;
+  return Math.round((inputCost + outputCost) * 10000) / 10000;
+}
+
+/**
+ * Record an agent invocation in the metrics ledger.
+ * Updates totals, by_agent, and by_phase aggregates.
+ * @param {string} brainDir - Path to .brain/ directory
+ * @param {object} entry - Invocation data
+ * @param {string} entry.agent - Agent name (e.g. 'researcher', 'executor')
+ * @param {number} entry.phase - Phase number
+ * @param {string} [entry.plan] - Plan identifier
+ * @param {string} [entry.model] - Model used (defaults to 'inherit')
+ * @param {number} [entry.input_tokens] - Input token count
+ * @param {number} [entry.output_tokens] - Output token count
+ * @returns {object} Ledger entry with budget_status appended
+ */
+function recordInvocation(brainDir, entry) {
+  const metrics = readMetrics(brainDir);
+
+  const cost = estimateCost(
+    entry.model || 'inherit',
+    entry.input_tokens || 0,
+    entry.output_tokens || 0,
+    metrics.pricing
+  );
+
+  const ledgerEntry = {
+    timestamp: new Date().toISOString(),
+    agent: entry.agent,
+    phase: entry.phase,
+    plan: entry.plan || null,
+    model: entry.model || 'inherit',
+    input_tokens: entry.input_tokens || 0,
+    output_tokens: entry.output_tokens || 0,
+    cost_usd: cost,
+    source: 'estimate'
+  };
+
+  metrics.ledger.push(ledgerEntry);
+
+  // Update totals
+  metrics.totals.input_tokens += ledgerEntry.input_tokens;
+  metrics.totals.output_tokens += ledgerEntry.output_tokens;
+  metrics.totals.estimated_cost_usd = Math.round((metrics.totals.estimated_cost_usd + cost) * 10000) / 10000;
+  metrics.totals.agent_invocations += 1;
+
+  // Update by_agent
+  const agentKey = entry.agent || 'unknown';
+  if (!metrics.by_agent[agentKey]) {
+    metrics.by_agent[agentKey] = { invocations: 0, input_tokens: 0, output_tokens: 0, cost_usd: 0 };
+  }
+  metrics.by_agent[agentKey].invocations += 1;
+  metrics.by_agent[agentKey].input_tokens += ledgerEntry.input_tokens;
+  metrics.by_agent[agentKey].output_tokens += ledgerEntry.output_tokens;
+  metrics.by_agent[agentKey].cost_usd = Math.round((metrics.by_agent[agentKey].cost_usd + cost) * 10000) / 10000;
+
+  // Update by_phase
+  const phaseKey = String(entry.phase || 0);
+  if (!metrics.by_phase[phaseKey]) {
+    metrics.by_phase[phaseKey] = { invocations: 0, input_tokens: 0, output_tokens: 0, cost_usd: 0 };
+  }
+  metrics.by_phase[phaseKey].invocations += 1;
+  metrics.by_phase[phaseKey].input_tokens += ledgerEntry.input_tokens;
+  metrics.by_phase[phaseKey].output_tokens += ledgerEntry.output_tokens;
+  metrics.by_phase[phaseKey].cost_usd = Math.round((metrics.by_phase[phaseKey].cost_usd + cost) * 10000) / 10000;
+
+  writeMetrics(brainDir, metrics);
+
+  return { ...ledgerEntry, budget_status: checkBudget(metrics) };
+}
+
+/**
+ * Check budget status against ceiling.
+ * @param {object} metrics - Metrics object
+ * @returns {object} Budget status with within_budget, spent, ceiling, pct_used, remaining, status
+ */
+function checkBudget(metrics) {
+  const ceiling = metrics.budget?.ceiling_usd;
+  const spent = metrics.totals?.estimated_cost_usd || 0;
+
+  if (ceiling === null || ceiling === undefined) {
+    return { within_budget: true, spent, ceiling: null, pct_used: 0, remaining: null, status: 'ok' };
+  }
+
+  const pct_used = ceiling > 0 ? Math.round((spent / ceiling) * 100) : 100;
+  const remaining = Math.round((ceiling - spent) * 10000) / 10000;
+  const warn_at = metrics.budget?.warn_at_pct || 80;
+
+  let status = 'ok';
+  if (pct_used >= 100) status = 'exceeded';
+  else if (pct_used >= warn_at) status = 'warning';
+
+  return { within_budget: pct_used < 100, spent, ceiling, pct_used, remaining, status };
+}
+
+/**
+ * Check whether spending an estimated cost is allowed under the budget.
+ * Respects budget mode: 'warn' (allow with warning), 'hard-stop' (block), 'pause' (block).
+ * @param {string} brainDir - Path to .brain/ directory
+ * @param {number} estimatedCost - Estimated cost of the next operation
+ * @returns {object} { allowed, reason, budget_status }
+ */
+function canSpend(brainDir, estimatedCost) {
+  const metrics = readMetrics(brainDir);
+  const budgetStatus = checkBudget(metrics);
+
+  if (budgetStatus.ceiling === null) {
+    return { allowed: true, reason: null, budget_status: budgetStatus };
+  }
+
+  const wouldExceed = (budgetStatus.spent + estimatedCost) > budgetStatus.ceiling;
+  if (wouldExceed) {
+    const mode = metrics.budget?.mode || 'warn';
+    if (mode === 'hard-stop') {
+      return { allowed: false, reason: `Budget exceeded: $${budgetStatus.spent.toFixed(2)} + ~$${estimatedCost.toFixed(2)} > $${budgetStatus.ceiling.toFixed(2)} ceiling`, budget_status: budgetStatus };
+    }
+    if (mode === 'pause') {
+      return { allowed: false, reason: `Budget would be exceeded. Pausing. Spent: $${budgetStatus.spent.toFixed(2)}, Ceiling: $${budgetStatus.ceiling.toFixed(2)}`, budget_status: budgetStatus };
+    }
+    // 'warn' mode — allowed but with warning
+    return { allowed: true, reason: `WARNING: Budget will be exceeded ($${budgetStatus.spent.toFixed(2)} + ~$${estimatedCost.toFixed(2)} > $${budgetStatus.ceiling.toFixed(2)})`, budget_status: budgetStatus };
+  }
+
+  return { allowed: true, reason: null, budget_status: budgetStatus };
+}
+
+/**
+ * Project remaining cost based on average spend per completed phase.
+ * @param {object} metrics - Metrics object
+ * @param {number} totalPhases - Total planned phases
+ * @param {number} currentPhase - Current phase number
+ * @returns {object} Projection with spent, projected_remaining, projected_total, avg_per_phase, confidence
+ */
+function projectCost(metrics, totalPhases, currentPhase) {
+  const completedPhases = Object.keys(metrics.by_phase).length;
+  const spent = metrics.totals?.estimated_cost_usd || 0;
+
+  if (completedPhases === 0) {
+    return { spent, projected_remaining: 0, projected_total: spent, avg_per_phase: 0, confidence: 'low' };
+  }
+
+  const avg_per_phase = spent / completedPhases;
+  const remainingPhases = Math.max(0, totalPhases - currentPhase);
+  const projected_remaining = Math.round(avg_per_phase * remainingPhases * 100) / 100;
+  const projected_total = Math.round((spent + projected_remaining) * 100) / 100;
+
+  let confidence = 'low';
+  if (completedPhases >= 5) confidence = 'high';
+  else if (completedPhases >= 3) confidence = 'medium';
+
+  return { spent, projected_remaining, projected_total, avg_per_phase: Math.round(avg_per_phase * 100) / 100, confidence };
+}
+
+/**
+ * Get cost breakdown by agent, sorted by cost descending.
+ * @param {object} metrics - Metrics object
+ * @returns {object[]} Array of { agent, cost, pct, invocations }
+ */
+function getAgentBreakdown(metrics) {
+  return Object.entries(metrics.by_agent || {})
+    .map(([agent, data]) => ({
+      agent,
+      cost: data.cost_usd,
+      pct: metrics.totals.estimated_cost_usd > 0 ? Math.round((data.cost_usd / metrics.totals.estimated_cost_usd) * 100) : 0,
+      invocations: data.invocations
+    }))
+    .sort((a, b) => b.cost - a.cost);
+}
+
+/**
+ * Get cost breakdown by phase, sorted by phase number ascending.
+ * @param {object} metrics - Metrics object
+ * @returns {object[]} Array of { phase, cost, invocations, input_tokens, output_tokens }
+ */
+function getPhaseBreakdown(metrics) {
+  return Object.entries(metrics.by_phase || {})
+    .map(([phase, data]) => ({
+      phase: parseInt(phase, 10),
+      cost: data.cost_usd,
+      invocations: data.invocations,
+      input_tokens: data.input_tokens,
+      output_tokens: data.output_tokens
+    }))
+    .sort((a, b) => a.phase - b.phase);
+}
+
+module.exports = {
+  createDefaultMetrics,
+  readMetrics,
+  writeMetrics,
+  estimateCost,
+  estimateTokens,  // re-export for convenience
+  recordInvocation,
+  checkBudget,
+  canSpend,
+  projectCost,
+  getAgentBreakdown,
+  getPhaseBreakdown,
+  DEFAULT_PRICING,
+  METRICS_FILE
+};