Skip to content

an open-source alternative to the dots, bots and muses of the world, run an office of claude code/codex like agents on your laptop, sandboxes or anywhere, uses your existing subscriptions

17.0 KB
Raw Blame
import { closeSync, cpSync, existsSync, fstatSync, mkdirSync, openSync, readSync, readdirSync, readFileSync, statSync } from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import { estimateCostUsd, normalizeModel } from './pricing';

/** Claude Code's project key: the absolute cwd with EVERY non-alphanumeric
 *  character turned into a dash — the leading slash and any dots included.
 *  /Users/me/app → -Users-me-app, /Users/me/MDv0.3.0 → -Users-me-MDv0-3-0,
 *  C:\Users\me\app → C--Users-me-app.
 *
 *  One rule for every platform. The Windows branch always used it; POSIX had its
 *  own narrower spelling, and that divergence is what broke — see projectDir. */
function projectKey(cwd: string): string {
  return cwd.replace(/[^a-zA-Z0-9]/g, '-');
}

/** The pre-2026 POSIX key: leading slash DROPPED, only slashes dashed, so dots
 *  survived (/Users/me/MDv0.3.0 → Users-me-MDv0.3.0). Kept solely so transcripts
 *  written before the change stay readable. */
function legacyProjectKey(cwd: string): string {
  return process.platform === 'win32'
    ? projectKey(cwd)
    : cwd.replace(/^\//, '').replaceAll('/', '-');
}

/** Resolve the Claude Code transcript directory for a given working directory:
 *  ~/.claude/projects keyed by cwd.
 *
 *  We used to emit the legacy key unconditionally on POSIX, which silently
 *  stopped matching once Claude Code moved to dashing every non-alphanumeric.
 *  Nothing errored — every caller reads an absent directory as "no transcripts
 *  yet" — so the miss cost months of dead memory condensation (a long run of
 *  `condense-abort`s with zero successes) and a usage reconciler quietly reading
 *  nothing at all.
 *
 *  Prefer the CURRENT spelling; fall back to the legacy one only when it exists
 *  and the current one does not, so pre-change installs stay readable. That order
 *  is not cosmetic: this harness itself created legacy-named directories by
 *  copying transcripts into them, so a fallback-first resolver would keep reading
 *  our own stale copies forever. When neither exists we return the CURRENT
 *  spelling, because callers that go on to create the directory must create the
 *  one Claude Code will actually read. */
export function projectDir(cwd: string): string {
  const root = path.join(os.homedir(), '.claude/projects');
  const current = path.join(root, projectKey(cwd));
  if (existsSync(current)) return current;
  // For cwd '/' the legacy key is the empty string, and path.join(root, '')
  // collapses to the projects ROOT — which always exists, so the fallback would
  // hand back a directory holding every project rather than one, and callers
  // would read/seed `~/.claude/projects/<session>.jsonl`. An empty key is not a
  // project name; treat it as no legacy candidate at all.
  const legacyKey = legacyProjectKey(cwd);
  if (!legacyKey) return current;
  const legacy = path.join(root, legacyKey);
  return existsSync(legacy) ? legacy : current;
}

/** Ensure session `<sessionId>.jsonl` exists in `cwd`'s Claude project dir so a
 *  `claude --resume <sessionId>` spawn in that cwd can find it. Claude keys
 *  transcripts by cwd, so a session started elsewhere is invisible until its
 *  `.jsonl` is seeded across.
 *
 *  - Already present in the target project dir → no-op, returns true.
 *  - Found under a DIFFERENT project dir (resumed from another cwd — the Add
 *    Agent "resume session" flow, #2) → copied across, returns true.
 *  - Not found anywhere → returns false, so the caller can fall back to a fresh
 *    session instead of launching a broken `--resume`.
 *
 *  Best-effort: any fs error yields false rather than throwing into the spawn. */
/** A Claude session id is a UUID. Renderer-supplied ids flow into `path.join`, so
 *  reject anything outside this charset before using one as a path component (a
 *  crafted id like `../../x` would otherwise traverse out of the project dirs). */
const VALID_SESSION_ID = /^[A-Za-z0-9_-]+$/;

export function seedSessionTranscript(cwd: string, sessionId: string): boolean {
  try {
    if (!sessionId || !VALID_SESSION_ID.test(sessionId)) return false;
    const target = path.join(projectDir(cwd), `${sessionId}.jsonl`);
    if (existsSync(target)) return true;
    const projectsRoot = path.join(os.homedir(), '.claude/projects');
    if (!existsSync(projectsRoot)) return false;
    for (const dir of readdirSync(projectsRoot)) {
      const candidate = path.join(projectsRoot, dir, `${sessionId}.jsonl`);
      if (existsSync(candidate)) {
        mkdirSync(path.dirname(target), { recursive: true });
        cpSync(candidate, target);
        return true;
      }
    }
    return false;
  } catch {
    return false;
  }
}

/** Resolve a session id to the ORIGINAL working directory it ran in, for the Add
 *  Agent "resume session" auto-fill. The cwd is read from a transcript RECORD
 *  (every line carries a `cwd` field) — deliberately NOT by un-dashing the
 *  project-dir name, which is lossy when the path itself contains dashes. Searches
 *  every `~/.claude/projects/<dir>/<sessionId>.jsonl`; if more than one matches
 *  (shouldn't — session ids are unique UUIDs) the most-recently-modified wins.
 *  Returns the cwd string, or null if not found / unreadable / no cwd record. */
export function resolveSessionCwd(sessionId: string): string | null {
  try {
    if (!sessionId || !VALID_SESSION_ID.test(sessionId)) return null;
    const projectsRoot = path.join(os.homedir(), '.claude/projects');
    if (!existsSync(projectsRoot)) return null;
    let best: { file: string; mtime: number } | null = null;
    for (const dir of readdirSync(projectsRoot)) {
      const candidate = path.join(projectsRoot, dir, `${sessionId}.jsonl`);
      try {
        const st = statSync(candidate);
        if (!best || st.mtimeMs > best.mtime) best = { file: candidate, mtime: st.mtimeMs };
      } catch { /* not present in this project dir */ }
    }
    if (!best) return null;
    const text = readFileSync(best.file, 'utf8');
    for (const line of text.split('\n')) {
      const trimmed = line.trim();
      if (!trimmed) continue;
      try {
        const rec = JSON.parse(trimmed) as { cwd?: unknown };
        if (typeof rec.cwd === 'string' && rec.cwd) return rec.cwd;
      } catch { /* skip a malformed line */ }
    }
    return null;
  } catch {
    return null;
  }
}

export interface AgentUsage {
  inputTokens: number;
  outputTokens: number;
  cacheReadTokens: number;
  cacheWriteTokens: number;
  estimatedCostUsd: number;
  /** The most-recently-seen model id (normalized, e.g. `claude-opus-4-8`), or
   *  undefined if no priced record was found. Lets the UI label the row. */
  model?: string;
}

function zero(): AgentUsage {
  return { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0, estimatedCostUsd: 0 };
}

export interface ReadUsageOptions {
  /** When set, only transcripts whose records carry this `sessionId` are summed.
   *  This is how the co-located-agents double-count (bug #2) is avoided: two
   *  agents sharing a cwd each filter to their own session instead of summing
   *  every `.jsonl` under the shared project dir. When unset, all are summed
   *  (the legacy behavior, used when the agent's session id isn't yet known). */
  sessionId?: string;
}

/** Per-file incremental parse state for the usage cache. Transcripts are
 *  append-only JSONL, so a parsed byte range's totals never change — repeat
 *  reads only stat the file and parse the appended tail. One entry per
 *  physical file (keyed by dir|file), shared across every sessionId that
 *  queries it — `all` is the unfiltered sum, `perSession` breaks the same
 *  parsed data out per record's own sessionId so a filtered caller never
 *  triggers its own re-read/re-parse of a file another agent already primed. */
interface FileUsageEntry {
  size: number;
  mtimeMs: number;
  /** Bytes parsed so far — always ends on a newline boundary, so a torn
   *  trailing line is simply re-read once the writer completes it. */
  offset: number;
  all: AgentUsage;
  /** Bounded at one entry per file in practice: Claude Code writes one
   *  transcript per session, named for that session id, and only ever appends
   *  that session's records to it. Measured across 2172 top-level transcripts
   *  in `~/.claude/projects`: every one holds exactly one distinct sessionId,
   *  and it always equals the filename stem. (Subagent transcripts CAN carry
   *  two — the parent's and the resumed parent's — but they live in a nested
   *  `<session>/subagents/` dir that the non-recursive readdir below never
   *  reads.) So the refresh-path clone is O(1), not O(sessions-ever-seen), and
   *  needs no pruning of its own; USAGE_CACHE_MAX bounds the file count. */
  perSession: Map<string, AgentUsage>;
}

const usageCache = new Map<string, FileUsageEntry>();
/** Soft bound; when crossed, the oldest-inserted half is dropped (entries
 *  rebuild on demand). Real fleets have tens of transcripts, not thousands. */
const USAGE_CACHE_MAX = 2048;

/** Parse complete JSONL lines, accumulating into BOTH `entry.all` (unfiltered)
 *  and the per-session bucket each record's OWN sessionId maps to.
 *
 *  This used to take a sessionId FILTER and skip non-matching records — which
 *  meant a file was independently re-read and re-parsed once per distinct
 *  agent querying it (cache was keyed per (file, sessionId), not per file).
 *  With N agents sharing a cwd, one file's new bytes got JSON-parsed N times
 *  on every write instead of once — cheap at idle, but scales with active
 *  agent count, which is exactly when it must stay cheap. Parsing every
 *  record into every bucket it belongs to, once, up front, means a filtered
 *  query is a Map lookup instead of a re-parse. */
function parseUsageLines(text: string, entry: FileUsageEntry): void {
  for (const line of text.split('\n')) {
    const trimmed = line.trim();
    if (!trimmed) continue;
    let rec: {
      type?: unknown;
      sessionId?: unknown;
      message?: { model?: unknown; usage?: Record<string, unknown> };
    };
    try {
      rec = JSON.parse(trimmed);
    } catch {
      continue;
    }
    if (rec.type !== 'assistant') continue;
    const u = rec.message?.usage;
    if (!u) continue;
    const model = typeof rec.message?.model === 'string' ? normalizeModel(rec.message.model) : undefined;
    const rIn = num(u.input_tokens);
    const rOut = num(u.output_tokens);
    const rCacheWrite = num(u.cache_creation_input_tokens);
    const rCacheRead = num(u.cache_read_input_tokens);
    // Price THIS record by its own model, then accumulate — so a mixed-model
    // agent (rare) is still costed correctly rather than at one flat rate.
    const cost = estimateCostUsd(model, {
      inputTokens: rIn,
      outputTokens: rOut,
      cacheReadTokens: rCacheRead,
      cacheWriteTokens: rCacheWrite
    });
    const targets: AgentUsage[] = [entry.all];
    if (typeof rec.sessionId === 'string' && rec.sessionId) {
      let bucket = entry.perSession.get(rec.sessionId);
      if (!bucket) {
        bucket = zero();
        entry.perSession.set(rec.sessionId, bucket);
      }
      targets.push(bucket);
    }
    for (const acc of targets) {
      if (model) acc.model = model;
      acc.inputTokens += rIn;
      acc.outputTokens += rOut;
      acc.cacheWriteTokens += rCacheWrite;
      acc.cacheReadTokens += rCacheRead;
      acc.estimatedCostUsd += cost;
    }
  }
}

/** Cached totals for one transcript file, refreshed incrementally: unchanged
 *  size+mtime → cache hit (no read at all); grown → parse only the appended
 *  tail; shrunk (rewritten) → full re-parse. Null when the file vanished.
 *
 *  Keyed by dir|file ONLY — one cache entry per physical file, shared by
 *  every agent that queries it, regardless of sessionId filter (see
 *  parseUsageLines for why keying by filter was the bug). */
function readFileUsage(dir: string, file: string): FileUsageEntry | null {
  const key = `${dir}|${file}`;
  const full = path.join(dir, file);
  let st: { size: number; mtimeMs: number };
  try { st = statSync(full); } catch { usageCache.delete(key); return null; }
  const cached = usageCache.get(key);
  if (cached && cached.size === st.size && cached.mtimeMs === st.mtimeMs) return cached;
  const fromScratch = !cached || st.size < cached.offset;
  const entry: FileUsageEntry = fromScratch
    ? { size: st.size, mtimeMs: st.mtimeMs, offset: 0, all: zero(), perSession: new Map() }
    : {
        size: st.size,
        mtimeMs: st.mtimeMs,
        offset: cached!.offset,
        all: { ...cached!.all },
        perSession: new Map(Array.from(cached!.perSession, ([k, v]) => [k, { ...v }]))
      };
  try {
    const fd = openSync(full, 'r');
    try {
      const len = st.size - entry.offset;
      if (len > 0) {
        const buf = Buffer.alloc(len);
        const read = readSync(fd, buf, 0, len, entry.offset);
        const text = buf.subarray(0, read).toString('utf8');
        // Consume only up to the last complete line; a torn trailing line
        // stays unparsed (offset holds at the newline) until the writer
        // finishes it — it is then counted exactly once.
        const lastNl = text.lastIndexOf('\n');
        if (lastNl !== -1) {
          const complete = text.slice(0, lastNl + 1);
          parseUsageLines(complete, entry);
          entry.offset += Buffer.byteLength(complete, 'utf8');
        }
      }
    } finally { closeSync(fd); }
  } catch {
    // Unreadable right now — keep what we have; totals refresh on the next call.
  }
  usageCache.set(key, entry);
  if (usageCache.size > USAGE_CACHE_MAX) {
    let drop = usageCache.size - USAGE_CACHE_MAX / 2;
    for (const k of usageCache.keys()) { if (drop-- <= 0) break; usageCache.delete(k); }
  }
  return entry;
}

/** Sum real token usage across Claude Code transcripts for `cwd`, pricing each
 *  assistant record by ITS OWN model (fixes cost bug #1 — no more Sonnet for
 *  everyone) via the fallback price table. Optionally filtered to one session
 *  (fixes bug #2). Resilient by design: any unreadable file or malformed line is
 *  skipped, and any unexpected failure yields a zeroed result rather than
 *  throwing into the IPC handler. This is the OFFLINE reconciler / fallback —
 *  the live source is the OTel collector (`telemetry.ts`).
 *
 *  Called from the ~30s breaker/cost beat for every agent without live OTel, so
 *  it must stay cheap on multi-MB transcript dirs: per-file incremental caching
 *  above means a steady-state call is a readdir + one stat per file. */
export function readAgentUsage(cwd: string, opts: ReadUsageOptions = {}): AgentUsage {
  const usage = zero();
  try {
    const dir = projectDir(cwd);
    if (!existsSync(dir)) return usage;
    const files = readdirSync(dir).filter((f) => f.endsWith('.jsonl'));
    let lastModel: string | undefined;
    for (const file of files) {
      const entry = readFileUsage(dir, file);
      if (!entry) continue;
      const totals = opts.sessionId ? entry.perSession.get(opts.sessionId) : entry.all;
      if (!totals) continue;
      usage.inputTokens += totals.inputTokens;
      usage.outputTokens += totals.outputTokens;
      usage.cacheWriteTokens += totals.cacheWriteTokens;
      usage.cacheReadTokens += totals.cacheReadTokens;
      usage.estimatedCostUsd += totals.estimatedCostUsd;
      if (totals.model) lastModel = totals.model;
    }
    if (lastModel) usage.model = lastModel;
    return usage;
  } catch {
    return zero();
  }
}

function num(v: unknown): number {
  return typeof v === 'number' && Number.isFinite(v) ? v : 0;
}

/** Current context size (tokens) of a live session: the token accounting of the
 *  LAST assistant message in its transcript — input + cache read/write is what
 *  the model just consumed as context, plus its output which joins the context
 *  for the next turn. Tail-reads the file (transcripts grow to many MB), so a
 *  poll stays cheap. Returns null when the transcript is missing/unreadable or
 *  holds no assistant message yet. */
const CONTEXT_TAIL_BYTES = 256 * 1024;

export function readContextTokens(transcriptPath: string): number | null {
  try {
    if (!existsSync(transcriptPath)) return null;
    const fd = openSync(transcriptPath, 'r');
    try {
      const size = fstatSync(fd).size;
      const len = Math.min(size, CONTEXT_TAIL_BYTES);
      if (len === 0) return null;
      const buf = Buffer.alloc(len);
      readSync(fd, buf, 0, len, size - len);
      const lines = buf.toString('utf8').split('\n');
      // Scan from the end; the very first chunk line may be cut mid-record and
      // simply fails to parse, which is fine.
      for (let i = lines.length - 1; i >= 0; i--) {
        const trimmed = lines[i].trim();
        if (!trimmed) continue;
        let rec: { type?: unknown; message?: { usage?: Record<string, unknown> } };
        try {
          rec = JSON.parse(trimmed);
        } catch {
          continue;
        }
        if (rec.type !== 'assistant') continue;
        const u = rec.message?.usage;
        if (!u) continue;
        return num(u.input_tokens) + num(u.output_tokens)
          + num(u.cache_creation_input_tokens) + num(u.cache_read_input_tokens);
      }
      return null;
    } finally {
      closeSync(fd);
    }
  } catch {
    return null;
  }
}