@prohost/cli 0.8.3 → 0.10.0

package/dist/usage/scanner.js

@@ -0,0 +1,438 @@
+/**
+ * Token totals from the session logs Claude Code and Codex already write.
+ *
+ * Aggregates only: tokens per (local day, account, runtime, model, project),
+ * where the project is the basename of the working directory the log names.
+ * No prompt, reply, tool call or file path ever leaves this module — lines are
+ * parsed for their usage counters and nothing else is kept.
+ *
+ * - **Claude Code** writes `<config dir>/projects/<project>/<session>.jsonl`.
+ *   Each assistant line carries the API response's `message.usage`; one
+ *   response is split over several lines (one per content block) that repeat
+ *   the same usage, and a resumed session can copy earlier lines into a new
+ *   file. So usage is keyed on `message.id` across every file: the first
+ *   sighting counts, a later one only adds what grew.
+ * - **Codex** writes `$CODEX_HOME/sessions/YYYY/MM/DD/rollout-*.jsonl` (moved
+ *   to `archived_sessions/` when archived). Its `token_count` events carry the
+ *   session's running `total_token_usage`; usage is the growth of that total
+ *   between events, credited to the model of the latest `turn_context`. Its
+ *   `input_tokens` include the cached ones, so they are split apart here.
+ *
+ * Incremental: a cursor per file (byte offset, size, mtime) lives in the scan
+ * state, so each pass reads only what was appended. The first pass looks back
+ * {@link RETENTION_DAYS} days. Every (day, account) a pass changes is marked dirty and is
+ * re-sent whole — the server replaces a day's rows, so a resend is harmless.
+ */
+import { closeSync, fstatSync, openSync, readFileSync, readSync, readdirSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { writePrivateFile } from './config.js';
+/** How far back the first scan looks, and how long totals are kept locally. */
+export const RETENTION_DAYS = 30;
+/** Most rows in one `POST /v1/usage/token-totals`. */
+export const MAX_ROWS_PER_BATCH = 2000;
+const DAY_MS = 86_400_000;
+const READ_CHUNK_BYTES = 4 * 1024 * 1024;
+/** Deepest directory level walked under `projects/` or `sessions/`. */
+const MAX_WALK_DEPTH = 6;
+const MAX_PROJECT_CHARS = 120;
+const MAX_MODEL_CHARS = 120;
+/** A dirty entry: one account's rows for one day. */
+export function pendingKey(day, accountKey) {
+    return `${day}|${accountKey}`;
+}
+/** The day of a dirty entry. */
+export function pendingDay(entry) {
+    return entry.slice(0, 10);
+}
+/** Days with anything pending, sorted. */
+export function pendingDays(state) {
+    return [...new Set(state.dirty.map(pendingDay))].sort();
+}
+export function emptyScanState() {
+    return { version: 1, files: {}, buckets: {}, seen: {}, dirty: [], strikes: {} };
+}
+export function loadScanState(file) {
+    try {
+        const parsed = JSON.parse(readFileSync(file, 'utf8'));
+        if (parsed?.version !== 1)
+            return emptyScanState();
+        return {
+            version: 1,
+            files: parsed.files && typeof parsed.files === 'object' ? parsed.files : {},
+            buckets: parsed.buckets && typeof parsed.buckets === 'object' ? parsed.buckets : {},
+            seen: parsed.seen && typeof parsed.seen === 'object' ? parsed.seen : {},
+            dirty: Array.isArray(parsed.dirty) ? parsed.dirty.filter((d) => typeof d === 'string' && d.includes('|')) : [],
+            strikes: parsed.strikes && typeof parsed.strikes === 'object' ? parsed.strikes : {},
+        };
+    }
+    catch {
+        return emptyScanState();
+    }
+}
+export function saveScanState(file, state) {
+    writePrivateFile(file, JSON.stringify(state));
+}
+const formatters = new Map();
+/** `YYYY-MM-DD` of an instant in a time zone (the machine's by default). */
+export function dayKey(ms, timeZone) {
+    const zone = timeZone ?? '';
+    let formatter = formatters.get(zone);
+    if (!formatter) {
+        formatter = new Intl.DateTimeFormat('en-CA', {
+            ...(timeZone ? { timeZone } : {}),
+            year: 'numeric',
+            month: '2-digit',
+            day: '2-digit',
+        });
+        formatters.set(zone, formatter);
+    }
+    const parts = formatter.formatToParts(new Date(ms));
+    const get = (type) => parts.find((p) => p.type === type)?.value ?? '';
+    return `${get('year')}-${get('month')}-${get('day')}`;
+}
+/** Bucket identity. JSON so it round-trips; the day is first so it can be read cheaply. */
+export function bucketKey(day, accountKey, runtime, model, project) {
+    return JSON.stringify([day, accountKey, runtime, model, project]);
+}
+function dayOfBucket(key) {
+    return key.slice(2, 12);
+}
+/** Basename of a working directory — the repo or folder name, never the path. */
+export function projectName(cwd) {
+    if (typeof cwd !== 'string' || !cwd.trim())
+        return null;
+    const base = path.basename(cwd.trim().replace(/[\\/]+$/, ''));
+    return base ? base.slice(0, MAX_PROJECT_CHARS) : null;
+}
+function asObject(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+}
+function count(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
+}
+function text(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+function parse(line) {
+    try {
+        return asObject(JSON.parse(line));
+    }
+    catch {
+        return undefined;
+    }
+}
+function isZero(t) {
+    return t[0] === 0 && t[1] === 0 && t[2] === 0 && t[3] === 0;
+}
+/** Files under ``root`` matching ``accept``, at most {@link MAX_WALK_DEPTH} levels down. */
+function walk(root, accept) {
+    const out = [];
+    const visit = (dir, depth) => {
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (depth < MAX_WALK_DEPTH)
+                    visit(full, depth + 1);
+            }
+            else if (entry.isFile() && accept(entry.name)) {
+                out.push(full);
+            }
+        }
+    };
+    visit(root, 0);
+    return out.sort();
+}
+/**
+ * Feed every complete line appended since ``offset`` to ``onLine``. Returns the
+ * offset just past the last complete line, so a line still being written is
+ * read whole next time.
+ */
+function readAppended(file, offset, onLine) {
+    const fd = openSync(file, 'r');
+    try {
+        const size = fstatSync(fd).size;
+        const buffer = Buffer.alloc(READ_CHUNK_BYTES);
+        let position = offset;
+        let carry = Buffer.alloc(0);
+        while (position < size) {
+            const read = readSync(fd, buffer, 0, Math.min(READ_CHUNK_BYTES, size - position), position);
+            if (read <= 0)
+                break;
+            position += read;
+            const data = carry.length > 0 ? Buffer.concat([carry, buffer.subarray(0, read)]) : buffer.subarray(0, read);
+            let start = 0;
+            for (let newline = data.indexOf(10, start); newline !== -1; newline = data.indexOf(10, start)) {
+                onLine(data.toString('utf8', start, newline));
+                start = newline + 1;
+            }
+            carry = Buffer.from(data.subarray(start));
+        }
+        return position - carry.length;
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+class Pass {
+    state;
+    cutoffDay;
+    timeZone;
+    touched = new Set();
+    filesRead = 0;
+    constructor(state, cutoffDay, timeZone) {
+        this.state = state;
+        this.cutoffDay = cutoffDay;
+        this.timeZone = timeZone;
+    }
+    credit(key, t) {
+        const bucket = this.state.buckets[key] ?? [0, 0, 0, 0];
+        for (let i = 0; i < 4; i += 1)
+            bucket[i] = bucket[i] + t[i];
+        this.state.buckets[key] = bucket;
+        this.touched.add(key);
+    }
+    claudeLine(account, line) {
+        // Cheap pre-filter: most lines are prompts, tool results and file snapshots.
+        if (!line.includes('"usage"') || !line.includes('"assistant"'))
+            return;
+        const entry = parse(line);
+        if (entry?.type !== 'assistant')
+            return;
+        const message = asObject(entry.message);
+        const usage = asObject(message?.usage);
+        if (!message || !usage)
+            return;
+        const id = text(message.id) ?? text(entry.requestId);
+        const model = text(message.model)?.slice(0, MAX_MODEL_CHARS);
+        const at = typeof entry.timestamp === 'string' ? Date.parse(entry.timestamp) : Number.NaN;
+        // `<synthetic>` marks a locally made message (an interruption, an API
+        // error) that no model produced.
+        if (!id || !model || model === '<synthetic>' || Number.isNaN(at))
+            return;
+        const observed = [
+            count(usage.input_tokens),
+            count(usage.cache_read_input_tokens),
+            count(usage.cache_creation_input_tokens),
+            count(usage.output_tokens),
+        ];
+        if (isZero(observed))
+            return;
+        const previous = this.state.seen[id];
+        if (!previous) {
+            const day = dayKey(at, this.timeZone);
+            if (day < this.cutoffDay)
+                return;
+            const key = bucketKey(day, account.key, 'claude_code', model, projectName(entry.cwd));
+            this.credit(key, observed);
+            this.state.seen[id] = [key, ...observed];
+            return;
+        }
+        // Seen before: a later line of the same response. Credit only growth.
+        const [key, ...credited] = previous;
+        const grown = [0, 0, 0, 0];
+        for (let i = 0; i < 4; i += 1)
+            grown[i] = Math.max(0, observed[i] - credited[i]);
+        if (isZero(grown))
+            return;
+        this.credit(key, grown);
+        this.state.seen[id] = [key, ...credited.map((c, i) => c + grown[i])];
+    }
+    codexLine(account, cursor, line) {
+        if (line.includes('"session_meta"') || line.includes('"turn_context"')) {
+            const entry = parse(line);
+            const payload = asObject(entry?.payload);
+            if (!payload)
+                return;
+            if (entry?.type === 'turn_context') {
+                cursor.model = text(payload.model)?.slice(0, MAX_MODEL_CHARS) ?? cursor.model;
+                if (payload.cwd !== undefined)
+                    cursor.project = projectName(payload.cwd);
+            }
+            else if (entry?.type === 'session_meta' && cursor.project === undefined) {
+                cursor.project = projectName(payload.cwd);
+            }
+            return;
+        }
+        if (!line.includes('"token_count"'))
+            return;
+        const entry = parse(line);
+        const payload = asObject(entry?.payload);
+        if (payload?.type !== 'token_count')
+            return;
+        const total = asObject(asObject(payload.info)?.total_token_usage);
+        if (!total)
+            return;
+        const now = [
+            count(total.input_tokens),
+            count(total.cached_input_tokens),
+            count(total.cache_write_input_tokens),
+            count(total.output_tokens),
+        ];
+        // Growth since the last event. Never negative, and the high-water mark
+        // only rises — so a rewritten or re-read file can't count anything twice.
+        const grown = [0, 0, 0, 0];
+        for (let i = 0; i < 4; i += 1) {
+            grown[i] = Math.max(0, now[i] - cursor.totals[i]);
+            cursor.totals[i] = Math.max(cursor.totals[i], now[i]);
+        }
+        if (isZero(grown))
+            return;
+        const at = typeof entry?.timestamp === 'string' ? Date.parse(entry.timestamp) : Number.NaN;
+        if (Number.isNaN(at))
+            return;
+        const day = dayKey(at, this.timeZone);
+        if (day < this.cutoffDay)
+            return;
+        const [input, cached, cacheWrite, output] = grown;
+        const key = bucketKey(day, account.key, 'codex', cursor.model ?? 'unknown', cursor.project ?? null);
+        this.credit(key, [Math.max(0, input - cached - cacheWrite), cached, cacheWrite, output]);
+    }
+}
+function claudeFiles(dir) {
+    return walk(path.join(dir, 'projects'), (name) => name.endsWith('.jsonl'));
+}
+function codexFiles(dir) {
+    const accept = (name) => name.startsWith('rollout-') && name.endsWith('.jsonl');
+    return [...walk(path.join(dir, 'sessions'), accept), ...walk(path.join(dir, 'archived_sessions'), accept)];
+}
+/**
+ * One incremental pass over every account's logs. Mutates and returns
+ * ``state``; the caller persists it.
+ */
+export function scanUsage(accounts, state, options = {}) {
+    const nowMs = options.now ?? Date.now();
+    const cutoffMs = nowMs - RETENTION_DAYS * DAY_MS;
+    const pass = new Pass(state, dayKey(cutoffMs, options.timeZone), options.timeZone);
+    for (const account of accounts) {
+        const isClaude = account.runtime === 'claude_code';
+        for (const file of isClaude ? claudeFiles(account.dir) : codexFiles(account.dir)) {
+            // A Codex rollout keeps its name when it is archived, so it is keyed by
+            // name and follows the move; a Claude log is keyed by path.
+            const id = isClaude ? `claude:${account.key}:${file}` : `codex:${account.key}:${path.basename(file)}`;
+            let stat;
+            try {
+                stat = statSync(file);
+            }
+            catch {
+                continue;
+            }
+            const existing = state.files[id];
+            if (!existing && stat.mtimeMs < cutoffMs)
+                continue;
+            if (existing && existing.size === stat.size && existing.mtimeMs === stat.mtimeMs)
+                continue;
+            const cursor = existing ?? (isClaude
+                ? { kind: 'claude', offset: 0, size: 0, mtimeMs: 0 }
+                : { kind: 'codex', offset: 0, size: 0, mtimeMs: 0, totals: [0, 0, 0, 0] });
+            // Shrunk: rewritten from scratch. Read it again; dedupe keeps it honest.
+            if (stat.size < cursor.offset)
+                cursor.offset = 0;
+            try {
+                cursor.offset = readAppended(file, cursor.offset, (line) => {
+                    if (cursor.kind === 'claude')
+                        pass.claudeLine(account, line);
+                    else
+                        pass.codexLine(account, cursor, line);
+                });
+            }
+            catch {
+                continue; // unreadable now; the cursor is unchanged and it is retried next pass
+            }
+            cursor.size = stat.size;
+            cursor.mtimeMs = stat.mtimeMs;
+            state.files[id] = cursor;
+            pass.filesRead += 1;
+        }
+    }
+    prune(state, pass.cutoffDay, cutoffMs);
+    const touchedPairs = [...pass.touched]
+        .filter((key) => dayOfBucket(key) >= pass.cutoffDay)
+        .map((key) => {
+        const [day, accountKey] = JSON.parse(key);
+        return pendingKey(day, accountKey);
+    });
+    // New usage for a pair starts its strike count over.
+    for (const pair of touchedPairs)
+        delete state.strikes[pair];
+    state.dirty = [...new Set([...state.dirty, ...touchedPairs])].filter((d) => pendingDay(d) >= pass.cutoffDay).sort();
+    for (const pair of Object.keys(state.strikes))
+        if (!state.dirty.includes(pair))
+            delete state.strikes[pair];
+    return { filesRead: pass.filesRead, touchedDays: [...new Set(touchedPairs.map(pendingDay))].sort() };
+}
+/**
+ * Drop what has aged out of the retention window. A cursor goes only once its
+ * file has been untouched that long — never merely because a pass could not
+ * list it: a Codex cursor holds the session's running total, and losing it
+ * would count the whole session again.
+ */
+function prune(state, cutoffDay, cutoffMs) {
+    for (const key of Object.keys(state.buckets)) {
+        if (dayOfBucket(key) < cutoffDay)
+            delete state.buckets[key];
+    }
+    for (const [id, entry] of Object.entries(state.seen)) {
+        if (dayOfBucket(entry[0]) < cutoffDay)
+            delete state.seen[id];
+    }
+    for (const [id, cursor] of Object.entries(state.files)) {
+        if (cursor.mtimeMs < cutoffMs)
+            delete state.files[id];
+    }
+}
+/** The rows for the given days, in upload shape. Zero-token buckets are left out. */
+export function rowsForDays(state, days) {
+    const wanted = new Set(days);
+    const rows = [];
+    for (const [key, totals] of Object.entries(state.buckets)) {
+        if (!wanted.has(dayOfBucket(key)) || isZero(totals))
+            continue;
+        const [day, accountKey, runtime, model, project] = JSON.parse(key);
+        rows.push({
+            day,
+            accountKey,
+            runtime,
+            model,
+            project,
+            inputTokens: totals[0],
+            cachedInputTokens: totals[1],
+            cacheWriteTokens: totals[2],
+            outputTokens: totals[3],
+        });
+    }
+    return rows.sort((a, b) => (a.day === b.day ? a.accountKey.localeCompare(b.accountKey) : a.day.localeCompare(b.day)));
+}
+/** The rows for the given `day|accountKey` pairs, in upload shape. */
+export function rowsForPending(state, pairs) {
+    const wanted = new Set(pairs);
+    const days = new Set([...wanted].map(pendingDay));
+    return rowsForDays(state, days).filter((r) => wanted.has(pendingKey(r.day, r.accountKey)));
+}
+/** Split rows into upload batches. */
+export function batches(rows, size = MAX_ROWS_PER_BATCH) {
+    const out = [];
+    for (let i = 0; i < rows.length; i += size)
+        out.push(rows.slice(i, i + size));
+    return out;
+}
+/** Local totals per account since ``fromDay`` (inclusive), for `usage status`. */
+export function localTotals(state, fromDay) {
+    const out = new Map();
+    for (const [key, totals] of Object.entries(state.buckets)) {
+        if (dayOfBucket(key) < fromDay)
+            continue;
+        const accountKey = JSON.parse(key)[1];
+        const sum = out.get(accountKey) ?? [0, 0, 0, 0];
+        for (let i = 0; i < 4; i += 1)
+            sum[i] = sum[i] + totals[i];
+        out.set(accountKey, sum);
+    }
+    return out;
+}

package/dist/usage/service.d.ts

@@ -0,0 +1,122 @@
+/**
+ * The `prohost usage start` loop: every five minutes, report each login's
+ * remaining capacity and upload the token totals that changed.
+ *
+ * Built to run unattended for weeks. Nothing in a tick can throw out of it:
+ * a missing key, an unreachable server, a 404 from a server that doesn't have
+ * the routes yet, a probe that hangs — each is logged once, backed off
+ * (see `backoff.ts`), and the loop carries on.
+ */
+import { Backoff } from './backoff.js';
+import type { ObservationCache, Prober } from './quota.js';
+export declare const REPORTS_PATH = "/v1/usage/reports";
+export declare const TOKEN_TOTALS_PATH = "/v1/usage/token-totals";
+/** Tick cadence. */
+export declare const USAGE_INTERVAL_MS: number;
+/** Partial uploads of one day's rows for one account before they are given up on. */
+export declare const MAX_PARTIAL_STRIKES = 3;
+/**
+ * Why the server skipped an account (`skipped[].reason`):
+ * - `not_owned` / `other_source` — the account belongs to another user, or is
+ *   reported by another kind of source. It will never be accepted from here.
+ * - `out_of_range` (totals) — the day is outside what the server keeps. Never accepted either.
+ * - `not_reported` (totals) — the server hasn't taken a report for it yet.
+ * - `throttled` — too soon after the last frame; nothing is wrong.
+ * Anything else is treated like an unexplained skip.
+ */
+export type SkipReason = 'not_owned' | 'other_source' | 'out_of_range' | 'not_reported' | 'throttled' | string;
+export interface Acceptance {
+    /** How many the server took. A 2xx without the field is read as all of them. */
+    accepted: number;
+    /** Which accounts it took, when the server says (newer servers). */
+    keys?: Set<string>;
+    /** Accounts it skipped, and why (newer servers). */
+    skipped?: Map<string, SkipReason>;
+}
+/** Read `{accepted, acceptedAccountKeys?, skipped?}` from a 2xx body. */
+export declare function parseAcceptance(body: string | undefined, sent: number): Acceptance;
+export interface CallRecord {
+    at: string;
+    ok: boolean;
+    /** HTTP status, 0 for no response. */
+    status: number;
+    /** Accounts in the report, or rows in the upload. */
+    count?: number;
+    /** What the server said it accepted of those. */
+    accepted?: number;
+}
+/** What `usage status` reads. Written after every tick. */
+export interface UsageStatus {
+    version: 1;
+    pid?: number;
+    lastTickAt?: string;
+    lastReport?: CallRecord;
+    lastTotals?: CallRecord;
+    accounts: ObservationCache;
+}
+export declare function scanStatePath(env?: NodeJS.ProcessEnv): string;
+export declare function statusPath(env?: NodeJS.ProcessEnv): string;
+export declare function loadStatus(env?: NodeJS.ProcessEnv): UsageStatus;
+export interface UsageServiceOptions {
+    env?: NodeJS.ProcessEnv;
+    log?: (line: string) => void;
+    fetchImpl?: typeof fetch;
+    prober?: Prober;
+    now?: () => number;
+    /** Machine name shown in ProhostAI. Defaults to the hostname. */
+    machine?: string;
+    /** IANA zone for day buckets. Defaults to this machine's. */
+    timeZone?: string;
+}
+export interface TickResult {
+    reported: boolean;
+    uploadedRows: number;
+    skipped?: 'no_key' | 'no_machine_id';
+}
+/** One process's reporter. Holds the backoff state and the scan cursor in memory. */
+export declare class UsageService {
+    private readonly options;
+    private readonly env;
+    private readonly log;
+    private readonly now;
+    private readonly prober;
+    readonly reportBackoff: Backoff;
+    readonly totalsBackoff: Backoff;
+    private scan;
+    private status;
+    private warned;
+    /**
+     * Accounts whose report the server has accepted from this process. The
+     * server takes token totals only for accounts this machine has already
+     * reported (and skips the rest), so totals for any other account wait —
+     * which also makes the first tick, and the tick after a login is
+     * discovered, report before it uploads. Kept in memory only: a restart
+     * always reports first anyway.
+     */
+    private readonly reportedKeys;
+    constructor(options?: UsageServiceOptions);
+    private warnOnce;
+    /** One full pass. Never throws. */
+    tick(): Promise<TickResult>;
+    /**
+     * Upload pending (day, account) rows in batches, for reported accounts only.
+     *
+     * A pair is done once the server takes it (its account is in
+     * `acceptedAccountKeys`, or — from an older server that only counts — its
+     * whole batch was accepted). A skip with a reason is handled by reason:
+     * `not_owned` / `other_source` / `out_of_range` will never be accepted, so
+     * the pair is done (logged once); `throttled` is retried next tick as is;
+     * `not_reported` waits for the next accepted report. Any other skip, and
+     * `not_reported`, costs a strike; after {@link MAX_PARTIAL_STRIKES} the pair
+     * is given up on (logged once), so nothing is resent forever. Pairs whose
+     * account has never been reported wait without a strike, and are not sent.
+     */
+    private uploadDirty;
+    private note;
+    private callRecord;
+}
+/** Tick until aborted. */
+export declare function runUsageLoop(service: UsageService, options?: {
+    signal?: AbortSignal;
+    intervalMs?: number;
+}): Promise<void>;