Skip to content

armgit / ECC

Public Imported from GitHub
0

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

11.6 KB
Raw Blame
#!/usr/bin/env node
/**
 * Cost Tracker Hook (v2)
 *
 * Reads transcript_path from Stop hook stdin, sums usage across all
 * assistant turns in the session JSONL, and appends one row to
 * ~/.claude/metrics/costs.jsonl. It also atomically publishes the latest
 * cumulative row under metrics/cost-snapshots/ so frequent PostToolUse
 * hooks do not need to rescan the unbounded history.
 *
 * Stop hook stdin payload: { session_id, transcript_path, cwd, hook_event_name, ... }
 * The Stop payload does NOT include `usage` or `model` directly. The previous
 * version of this hook expected those fields and silently produced zero-filled
 * rows (verified: 2,340 rows captured with 0.0% non-zero token rate over 52
 * days). The fix is to read the transcript file Claude Code already passes us.
 *
 * JSONL assistant entry shape (per Claude Code):
 *   { type: "assistant", message: { model, usage: { input_tokens, output_tokens,
 *     cache_creation_input_tokens, cache_read_input_tokens } } }
 *
 * Cumulative behavior: Stop fires per assistant response, not per session.
 * Each row therefore represents the cumulative session total up to that point.
 * To get per-session cost, take the last row per session_id. To get per-day
 * spend, aggregate.
 *
 * Harness-cost contract (optional, opt-in by the statusline):
 *   If the user's statusline (which receives `cost.total_cost_usd` directly
 *   from Claude Code) writes `{ts, cost_usd}` to
 *   `<os.tmpdir()>/harness-cost-<session_id>.json` on each render, this hook
 *   prefers that authoritative value over the transcript-sum estimate when
 *   the cache is fresh (≤ 300s). The transcript-sum is kept as a safe
 *   fallback because:
 *     - the hard-coded rate table cannot represent Opus 4.7's >200K-token
 *       2x tier or the 1h-cache 2x tier (under-counts on long sessions);
 *     - summing the full transcript double-counts work done across
 *       `--resume` boundaries while `cost.total_cost_usd` is per-process.
 *   Absent a writer, behavior is unchanged.
 */

'use strict';

const fs = require('fs');
const os = require('os');
const path = require('path');
const { ensureDir, getClaudeDir } = require('../lib/utils');
const { sanitizeSessionId } = require('../lib/session-bridge');
const {
  appendSessionCostRow,
  warnSessionCostSnapshotFailure
} = require('../lib/session-cost-snapshot');

const HARNESS_COST_MAX_AGE_SECONDS = 300;

/**
 * Read authoritative harness cost from the per-session cache file.
 * @param {string} sessionId
 * @param {number} maxAgeSeconds
 * @returns {number|null} cost in USD, or null on miss / stale / parse error
 */
function readHarnessCost(sessionId, maxAgeSeconds) {
  if (!sessionId) return null;
  try {
    const fp = path.join(os.tmpdir(), `harness-cost-${sessionId}.json`);
    if (!fs.existsSync(fp)) return null;
    const obj = JSON.parse(fs.readFileSync(fp, 'utf8'));
    const ts = Number(obj && obj.ts);
    const cost = Number(obj && obj.cost_usd);
    if (!Number.isFinite(ts) || !Number.isFinite(cost) || cost < 0) return null;
    const age = Math.floor(Date.now() / 1000) - ts;
    if (age < 0 || age > maxAgeSeconds) return null;
    return cost;
  } catch {
    return null;
  }
}

// Approximate per-1M-token billing rates (USD).
// Five-minute cache creation: 1.25x input rate. Cache read: usually 0.1x;
// Opus/Sonnet 5.5 use 0.05x. The harness cost remains authoritative for 1h writes.
// Source: https://platform.claude.com/docs/en/about-claude/pricing
// Current-generation list prices: Fable/Mythos 5 $10/$50, Opus 5 and
// Opus 4.5-4.8 $5/$25, Sonnet 5 $2/$10, Sonnet 4.6 $3/$15, and Haiku 4.5
// $1/$5. Opus 4.0/4.1 and Opus 3 stay on the legacy $15/$75 tier.
// Opus 5.5 is $4/$20; Haiku 5.5 is $0.10/$0.50 at <=100K prompt tokens
// and $0.50/$2.50 above 100K. Sonnet 5.5 retains $2/$10 with $0.10 cache reads.
const RATE_TABLE = {
  haiku:      { in: 1.00,  out: 5.0,  cacheWrite: 1.25,  cacheRead: 0.10 },
  haiku55:    { in: 0.10,  out: 0.5,  cacheWrite: 0.125, cacheRead: 0.01 },
  haiku55Long: { in: 0.50, out: 2.5,  cacheWrite: 0.625, cacheRead: 0.05 },
  sonnet:     { in: 3.00,  out: 15.0, cacheWrite: 3.75,  cacheRead: 0.30 },
  sonnet5:    { in: 2.00,  out: 10.0, cacheWrite: 2.50,  cacheRead: 0.20 },
  sonnet55:   { in: 2.00,  out: 10.0, cacheWrite: 2.50,  cacheRead: 0.10 },
  opus:       { in: 5.00,  out: 25.0, cacheWrite: 6.25,  cacheRead: 0.50 },
  opus55:     { in: 4.00,  out: 20.0, cacheWrite: 5.00, cacheRead: 0.20 },
  opusLegacy: { in: 15.00, out: 75.0, cacheWrite: 18.75, cacheRead: 1.50 },
  fable:      { in: 10.00, out: 50.0, cacheWrite: 12.50, cacheRead: 1.00 }
};

// Opus 4.0's dated snapshot omits the minor segment, so an `opus-4-0`
// substring check alone misses `claude-opus-4-20250514`.
const LEGACY_OPUS_RE = /3-opus|opus-4-0(?!\d)|opus-4-1(?!\d)|opus-4[-@]\d{8}/;

function getRates(model, usage = {}) {
  const m = String(model || '').toLowerCase();
  if (m.includes('fable') || m.includes('mythos')) return RATE_TABLE.fable;
  if (/(?:^|[^a-z0-9])haiku-5-5(?:[^a-z0-9]|$)/.test(m)) {
    const promptTokens = toNumber(usage.input_tokens) +
      toNumber(usage.cache_creation_input_tokens) + toNumber(usage.cache_read_input_tokens);
    return promptTokens > 100000 ? RATE_TABLE.haiku55Long : RATE_TABLE.haiku55;
  }
  if (m.includes('haiku')) return RATE_TABLE.haiku;
  if (/(?:^|[^a-z0-9])sonnet-5-5(?:[^a-z0-9]|$)/.test(m)) return RATE_TABLE.sonnet55;
  if (isSonnet5(m)) return RATE_TABLE.sonnet5;
  if (LEGACY_OPUS_RE.test(m)) return RATE_TABLE.opusLegacy;
  if (/(?:^|[^a-z0-9])opus-5-5(?:[^a-z0-9]|$)/.test(m)) return RATE_TABLE.opus55;
  if (m.includes('opus'))  return RATE_TABLE.opus;
  return RATE_TABLE.sonnet;
}

function isSonnet5(model) {
  return /(?:^|[^a-z0-9])sonnet-5(?:[^a-z0-9]|$)/.test(model);
}

function toNumber(v) {
  const n = Number(v);
  return Number.isFinite(n) && n >= 0 ? n : 0;
}

function normalizeUsageTotals(totals) {
  return {
    inputTokens: toNumber(totals.inputTokens),
    outputTokens: toNumber(totals.outputTokens),
    cacheWriteTokens: toNumber(totals.cacheWriteTokens),
    cacheReadTokens: toNumber(totals.cacheReadTokens),
    model: totals.model
  };
}

/**
 * Scan the session JSONL and sum token usage across all assistant turns.
 * Returns { inputTokens, outputTokens, cacheWriteTokens, cacheReadTokens, model }
 * or null on read failure.
 *
 * Claude Code writes one JSONL line per content block, so a single API
 * response (one message.id) spans multiple assistant lines that each repeat
 * the same message.usage. Summing every line inflates totals ~2.5-3x
 * (verified: a session with 704 assistant lines had only 286 unique
 * message.ids — $867 line-summed vs $333 deduped). Usage is therefore
 * counted once per message.id, keeping the last line seen for each id.
 */
function sumUsageFromTranscript(transcriptPath) {
  let content;
  try {
    content = fs.readFileSync(transcriptPath, 'utf8');
  } catch {
    return null;
  }

  const usageById = new Map();
  let syntheticKey = 0;
  let model = 'unknown';

  for (const line of content.split('\n')) {
    if (!line.trim()) continue;
    let entry;
    try { entry = JSON.parse(line); } catch { continue; }

    if (entry.type !== 'assistant') continue;
    const msg = entry.message;
    if (!msg || !msg.usage) continue;

    // Lines without a message.id (older transcript shapes) keep the previous
    // per-line behavior via a synthetic key.
    const key = (typeof msg.id === 'string' && msg.id)
      ? msg.id
      : `__line_${++syntheticKey}`;
    const previous = usageById.get(key);
    const requestModel = msg.model && msg.model !== 'unknown'
      ? msg.model
      : previous && previous.model;
    usageById.set(key, { usage: msg.usage, model: requestModel });

    if (msg.model && msg.model !== 'unknown') model = msg.model;
  }

  let inputTokens = 0;
  let outputTokens = 0;
  let cacheWriteTokens = 0;
  let cacheReadTokens = 0;
  let costUsd = 0;

  for (const entry of usageById.values()) {
    const u = entry.usage;
    const rates = getRates(entry.model && entry.model !== 'unknown' ? entry.model : model, u);
    inputTokens      += toNumber(u.input_tokens);
    outputTokens     += toNumber(u.output_tokens);
    cacheWriteTokens += toNumber(u.cache_creation_input_tokens);
    cacheReadTokens  += toNumber(u.cache_read_input_tokens);
    // Long-prompt pricing applies per API request, not to session totals.
    costUsd += (toNumber(u.input_tokens) * rates.in + toNumber(u.output_tokens) * rates.out +
      toNumber(u.cache_creation_input_tokens) * rates.cacheWrite +
      toNumber(u.cache_read_input_tokens) * rates.cacheRead) / 1e6;
  }

  return {
    ...normalizeUsageTotals({ inputTokens, outputTokens, cacheWriteTokens, cacheReadTokens, model }),
    costUsd: toNumber(costUsd)
  };
}

// 1MB, matching the other Stop hooks. The Stop payload carries
// last_assistant_message, which routinely exceeded the old 64KB cap and
// made this hook echo a JSON document cut mid-stream (#2090).
const MAX_STDIN = 1024 * 1024;
let raw = '';
let truncated = false;

process.stdin.setEncoding('utf8');
process.stdin.on('data', chunk => {
  if (raw.length < MAX_STDIN) {
    const remaining = MAX_STDIN - raw.length;
    raw += chunk.substring(0, remaining);
    if (chunk.length > remaining) truncated = true;
  } else {
    truncated = true;
  }
});

process.stdin.on('end', () => {
  try {
    const input = raw.trim() ? JSON.parse(raw) : {};

    const transcriptPath = (typeof input.transcript_path === 'string' && input.transcript_path)
      ? input.transcript_path
      : process.env.CLAUDE_TRANSCRIPT_PATH || null;

    const sessionId =
      sanitizeSessionId(input.session_id) ||
      sanitizeSessionId(process.env.ECC_SESSION_ID) ||
      sanitizeSessionId(process.env.CLAUDE_SESSION_ID) ||
      'default';

    let usageTotals = null;
    if (transcriptPath && fs.existsSync(transcriptPath)) {
      usageTotals = sumUsageFromTranscript(transcriptPath);
    }

    const {
      inputTokens = 0,
      outputTokens = 0,
      cacheWriteTokens = 0,
      cacheReadTokens = 0,
      model = 'unknown'
    } = usageTotals || {};

    const transcriptCostUsd = Math.round((usageTotals ? usageTotals.costUsd : 0) * 1e6) / 1e6;

    // Prefer the harness's authoritative `cost.total_cost_usd` when the
    // statusline has written it to the per-session cache (see contract in
    // the file header). The harness number reflects API-billed truth
    // (correct rates, 1h-cache 2x, >200K tier 2x) and is per-process so it
    // does not drift across `--resume`. Cache miss → transcript-sum.
    const harnessCost = readHarnessCost(sessionId, HARNESS_COST_MAX_AGE_SECONDS);
    const estimatedCostUsd = harnessCost !== null
      ? Math.round(harnessCost * 1e6) / 1e6
      : transcriptCostUsd;

    const metricsDir = path.join(getClaudeDir(), 'metrics');
    ensureDir(metricsDir);

    const row = {
      timestamp:          new Date().toISOString(),
      session_id:         sessionId,
      transcript_path:    transcriptPath || '',
      model,
      input_tokens:       inputTokens,
      output_tokens:      outputTokens,
      cache_write_tokens: cacheWriteTokens,
      cache_read_tokens:  cacheReadTokens,
      estimated_cost_usd: estimatedCostUsd
    };

    try {
      appendSessionCostRow(metricsDir, sessionId, row);
    } catch (error) {
      warnSessionCostSnapshotFailure('publication', metricsDir, sessionId, error);
    }
  } catch {
    // Non-blocking — never fail the Stop hook.
  }

  // Pass stdin through (ECC hook convention) — but never echo truncated
  // stdin: invalid JSON on stdout is reported as a Stop hook failure (#2090).
  if (truncated) {
    process.stderr.write('[Hook] cost-tracker: stdin exceeded 1MB; suppressing pass-through (fail-open)\n');
    return;
  }
  process.stdout.write(raw);
});