@prohost/cli 0.8.3 → 0.10.0

package/dist/usage/quota.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Remaining capacity for every login on this machine, in `POST /v1/usage/reports` shape.
+ *
+ * The probes are the ones `agent run` already uses when idle (see
+ * `runtime_status.ts`): Claude Code's `get_usage` control request and Codex's
+ * `account/rateLimits/read`, each asked of the unmodified CLI with the
+ * account's own config directory, so no model turn is spent and no credential
+ * is read here. Sign-in state comes from `checkAuth` in `accounts.ts`.
+ *
+ * Each account is probed at most once per {@link QUOTA_REFRESH_AFTER_MS}, a
+ * few at a time, and what was learned is kept between probes (and restarts)
+ * so every report carries the latest known numbers with the time they were
+ * observed.
+ */
+import type { AccountBilling, AccountRecord, AccountRuntime, AuthCheck, AuthState, CommandRunner } from '../agent/accounts.js';
+import type { QuotaWindow, RuntimeObservation } from '../agent/runtime_status.js';
+/** Accounts probed at once. Each probe is a short-lived agent CLI process. */
+export declare const PROBE_CONCURRENCY = 3;
+/** What is known about one account between probes. Persisted in the status file. */
+export interface AccountObservation {
+    /** Epoch ms of the last probe attempt, successful or not. */
+    probedAt?: number;
+    /** ISO time the windows were last learned. */
+    observedAt?: string;
+    authState: AuthState;
+    billing?: AccountBilling;
+    planLabel?: string;
+    windows: QuotaWindow[];
+}
+export type ObservationCache = Record<string, AccountObservation>;
+export interface ProbeResult {
+    auth: AuthCheck;
+    observation?: RuntimeObservation;
+}
+export type Prober = (record: AccountRecord) => Promise<ProbeResult>;
+/** Wire window (`RawWindow` in the server contract). */
+export interface RawWindow {
+    kind: string;
+    usedPercent: number;
+    resetsAt: string | null;
+    modelLabel?: string;
+}
+export interface ReportedAccount {
+    accountKey: string;
+    label: string;
+    runtime: AccountRuntime;
+    billing: AccountBilling;
+    planLabel?: string;
+    authState: AuthState;
+    quotaWindows: RawWindow[];
+    observedAt?: string;
+}
+export interface UsageReportFrame {
+    source: 'cli';
+    machineId: string;
+    machine: string;
+    accounts: ReportedAccount[];
+}
+/**
+ * Environment that points the agent CLI at this account. The default login is
+ * the CLI's own directory, so an inherited `CLAUDE_CONFIG_DIR` / `CODEX_HOME`
+ * (a foreground shell that exports one) is cleared rather than followed —
+ * otherwise "default" would probe some other login. Node drops `undefined`
+ * entries from a child's environment.
+ */
+export declare function probeEnv(record: AccountRecord): NodeJS.ProcessEnv;
+/** The probes `agent run` uses, pointed at one account at a time. */
+export declare function defaultProber(options?: {
+    run?: CommandRunner;
+    timeoutMs?: number;
+}): Prober;
+/** Run ``fn`` over ``items`` with at most ``limit`` in flight. Never rejects for one item. */
+export declare function mapLimit<T>(items: T[], limit: number, fn: (item: T) => Promise<void>): Promise<void>;
+/** Accounts due a probe: never probed, or probed {@link QUOTA_REFRESH_AFTER_MS} ago or more. */
+export declare function dueForProbe(records: AccountRecord[], cache: ObservationCache, nowMs: number, refreshAfterMs?: number): AccountRecord[];
+/** Probe every account that is due, folding the answers into ``cache``. */
+export declare function probeAccounts(records: AccountRecord[], cache: ObservationCache, options: {
+    prober: Prober;
+    now?: () => number;
+    concurrency?: number;
+    refreshAfterMs?: number;
+}): Promise<AccountRecord[]>;
+export declare function toRawWindow(window: QuotaWindow): RawWindow;
+/**
+ * The report body. At most {@link MAX_REPORTED_ACCOUNTS} accounts — the
+ * defaults first, then in registry order; `omitted` says how many did not fit.
+ */
+export declare function buildReportFrame(options: {
+    machineId: string;
+    machine: string;
+    records: AccountRecord[];
+    cache: ObservationCache;
+}): {
+    frame: UsageReportFrame;
+    omitted: number;
+};

package/dist/usage/quota.js

@@ -0,0 +1,145 @@
+/**
+ * Remaining capacity for every login on this machine, in `POST /v1/usage/reports` shape.
+ *
+ * The probes are the ones `agent run` already uses when idle (see
+ * `runtime_status.ts`): Claude Code's `get_usage` control request and Codex's
+ * `account/rateLimits/read`, each asked of the unmodified CLI with the
+ * account's own config directory, so no model turn is spent and no credential
+ * is read here. Sign-in state comes from `checkAuth` in `accounts.ts`.
+ *
+ * Each account is probed at most once per {@link QUOTA_REFRESH_AFTER_MS}, a
+ * few at a time, and what was learned is kept between probes (and restarts)
+ * so every report carries the latest known numbers with the time they were
+ * observed.
+ */
+import { DEFAULT_ACCOUNT_LABEL, MAX_REPORTED_ACCOUNTS, checkAuth, defaultCommandRunner } from '../agent/accounts.js';
+import { PROVIDER_TIMEOUT_MS, QUOTA_REFRESH_AFTER_MS, claudeQuotaProvider, codexQuotaProvider, mergeWindows, } from '../agent/runtime_status.js';
+import { CLI_VERSION } from '../version.js';
+/** Accounts probed at once. Each probe is a short-lived agent CLI process. */
+export const PROBE_CONCURRENCY = 3;
+/** Most windows per account the server accepts. */
+const MAX_WINDOWS = 8;
+const MAX_LABEL_CHARS = 60;
+const MAX_MACHINE_CHARS = 120;
+/**
+ * Environment that points the agent CLI at this account. The default login is
+ * the CLI's own directory, so an inherited `CLAUDE_CONFIG_DIR` / `CODEX_HOME`
+ * (a foreground shell that exports one) is cleared rather than followed —
+ * otherwise "default" would probe some other login. Node drops `undefined`
+ * entries from a child's environment.
+ */
+export function probeEnv(record) {
+    const variable = record.runtime === 'claude_code' ? 'CLAUDE_CONFIG_DIR' : 'CODEX_HOME';
+    return { [variable]: record.dir ?? undefined };
+}
+/** The probes `agent run` uses, pointed at one account at a time. */
+export function defaultProber(options = {}) {
+    const baseRun = options.run ?? defaultCommandRunner;
+    return async (record) => {
+        const env = probeEnv(record);
+        // `checkAuth` passes only the account's own variable; the override clears
+        // an inherited one for the default login.
+        const auth = await checkAuth(record, { run: (command, args, extra) => baseRun(command, args, { ...extra, ...env }) });
+        // A signed-out login has nothing to say about capacity.
+        if (auth.state === 'expired')
+            return { auth };
+        const provider = record.runtime === 'claude_code'
+            ? claudeQuotaProvider({ binary: 'claude', timeoutMs: options.timeoutMs ?? PROVIDER_TIMEOUT_MS, env: () => env })
+            : codexQuotaProvider({
+                binary: 'codex',
+                clientVersion: CLI_VERSION,
+                timeoutMs: options.timeoutMs ?? PROVIDER_TIMEOUT_MS,
+                env: () => env,
+            });
+        let observation;
+        try {
+            observation = await provider.refresh();
+        }
+        catch {
+            observation = undefined;
+        }
+        return { auth, observation };
+    };
+}
+/** Run ``fn`` over ``items`` with at most ``limit`` in flight. Never rejects for one item. */
+export async function mapLimit(items, limit, fn) {
+    let next = 0;
+    const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
+        while (next < items.length) {
+            const item = items[next];
+            next += 1;
+            try {
+                await fn(item);
+            }
+            catch {
+                /* one account's failure never stops the others */
+            }
+        }
+    });
+    await Promise.all(workers);
+}
+/** Accounts due a probe: never probed, or probed {@link QUOTA_REFRESH_AFTER_MS} ago or more. */
+export function dueForProbe(records, cache, nowMs, refreshAfterMs = QUOTA_REFRESH_AFTER_MS) {
+    return records.filter((r) => {
+        const probedAt = cache[r.key]?.probedAt;
+        return probedAt === undefined || nowMs - probedAt >= refreshAfterMs;
+    });
+}
+/** Probe every account that is due, folding the answers into ``cache``. */
+export async function probeAccounts(records, cache, options) {
+    const now = options.now ?? Date.now;
+    const due = dueForProbe(records, cache, now(), options.refreshAfterMs);
+    await mapLimit(due, options.concurrency ?? PROBE_CONCURRENCY, async (record) => {
+        const startedAt = now();
+        const previous = cache[record.key] ?? { authState: 'unknown', windows: [] };
+        // Stamped before the probe so a probe that throws still waits its turn.
+        cache[record.key] = { ...previous, probedAt: startedAt };
+        const { auth, observation } = await options.prober(record);
+        const next = { ...previous, probedAt: startedAt, authState: auth.state };
+        if (auth.billing)
+            next.billing = auth.billing;
+        if (observation?.plan_label)
+            next.planLabel = observation.plan_label;
+        if (observation?.quota_windows && observation.quota_windows.length > 0) {
+            next.windows = mergeWindows(previous.windows, observation.quota_windows);
+            next.observedAt = new Date(now()).toISOString();
+        }
+        cache[record.key] = next;
+    });
+    return due;
+}
+export function toRawWindow(window) {
+    return {
+        kind: window.kind,
+        usedPercent: window.used_percent,
+        resetsAt: window.resets_at,
+        ...(window.model_label ? { modelLabel: window.model_label } : {}),
+    };
+}
+/**
+ * The report body. At most {@link MAX_REPORTED_ACCOUNTS} accounts — the
+ * defaults first, then in registry order; `omitted` says how many did not fit.
+ */
+export function buildReportFrame(options) {
+    const ordered = [
+        ...options.records.filter((r) => r.label === DEFAULT_ACCOUNT_LABEL),
+        ...options.records.filter((r) => r.label !== DEFAULT_ACCOUNT_LABEL),
+    ];
+    const accounts = ordered.slice(0, MAX_REPORTED_ACCOUNTS).map((record) => {
+        const seen = options.cache[record.key];
+        return {
+            accountKey: record.key,
+            label: record.label.slice(0, MAX_LABEL_CHARS),
+            runtime: record.runtime,
+            billing: seen?.billing ?? record.billing,
+            ...(seen?.planLabel ? { planLabel: seen.planLabel } : {}),
+            authState: seen?.authState ?? 'unknown',
+            quotaWindows: (seen?.windows ?? []).slice(0, MAX_WINDOWS).map(toRawWindow),
+            ...(seen?.observedAt ? { observedAt: seen.observedAt } : {}),
+        };
+    });
+    return {
+        frame: { source: 'cli', machineId: options.machineId, machine: options.machine.slice(0, MAX_MACHINE_CHARS), accounts },
+        omitted: Math.max(0, ordered.length - MAX_REPORTED_ACCOUNTS),
+    };
+}

package/dist/usage/scanner.d.ts

@@ -0,0 +1,117 @@
+/**
+ * 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 type { AccountRuntime } from '../agent/accounts.js';
+/** How far back the first scan looks, and how long totals are kept locally. */
+export declare const RETENTION_DAYS = 30;
+/** Most rows in one `POST /v1/usage/token-totals`. */
+export declare const MAX_ROWS_PER_BATCH = 2000;
+/** `[input, cachedInput, cacheWrite, output]`. Claude's input excludes cache; Codex's is split to match. */
+export type Totals = [number, number, number, number];
+export interface ScanAccount {
+    key: string;
+    runtime: AccountRuntime;
+    /** The login's config directory. */
+    dir: string;
+}
+interface ClaudeCursor {
+    kind: 'claude';
+    offset: number;
+    size: number;
+    mtimeMs: number;
+}
+interface CodexCursor {
+    kind: 'codex';
+    offset: number;
+    size: number;
+    mtimeMs: number;
+    /** The session's running `total_token_usage` as last seen, raw (input includes cached). */
+    totals: Totals;
+    model?: string;
+    project?: string | null;
+}
+type Cursor = ClaudeCursor | CodexCursor;
+export interface ScanState {
+    version: 1;
+    files: Record<string, Cursor>;
+    /** Bucket key ({@link bucketKey}) → totals. */
+    buckets: Record<string, Totals>;
+    /** Claude response id → the bucket it was credited to and what was credited. */
+    seen: Record<string, [string, number, number, number, number]>;
+    /** `day|accountKey` pairs ({@link pendingKey}) changed since they were last uploaded. */
+    dirty: string[];
+    /** Pending pair → consecutive uploads the server only partly accepted. */
+    strikes: Record<string, number>;
+}
+/** A dirty entry: one account's rows for one day. */
+export declare function pendingKey(day: string, accountKey: string): string;
+/** The day of a dirty entry. */
+export declare function pendingDay(entry: string): string;
+/** Days with anything pending, sorted. */
+export declare function pendingDays(state: ScanState): string[];
+export interface TokenRow {
+    day: string;
+    accountKey: string;
+    runtime: AccountRuntime;
+    model: string;
+    project: string | null;
+    inputTokens: number;
+    cachedInputTokens: number;
+    cacheWriteTokens: number;
+    outputTokens: number;
+}
+export interface ScanOptions {
+    now?: number;
+    /** IANA zone the days are bucketed in. Defaults to this machine's. */
+    timeZone?: string;
+}
+export interface ScanSummary {
+    filesRead: number;
+    /** Days whose totals changed in this pass. */
+    touchedDays: string[];
+}
+export declare function emptyScanState(): ScanState;
+export declare function loadScanState(file: string): ScanState;
+export declare function saveScanState(file: string, state: ScanState): void;
+/** `YYYY-MM-DD` of an instant in a time zone (the machine's by default). */
+export declare function dayKey(ms: number, timeZone?: string): string;
+/** Bucket identity. JSON so it round-trips; the day is first so it can be read cheaply. */
+export declare function bucketKey(day: string, accountKey: string, runtime: AccountRuntime, model: string, project: string | null): string;
+/** Basename of a working directory — the repo or folder name, never the path. */
+export declare function projectName(cwd: unknown): string | null;
+/**
+ * One incremental pass over every account's logs. Mutates and returns
+ * ``state``; the caller persists it.
+ */
+export declare function scanUsage(accounts: ScanAccount[], state: ScanState, options?: ScanOptions): ScanSummary;
+/** The rows for the given days, in upload shape. Zero-token buckets are left out. */
+export declare function rowsForDays(state: ScanState, days: Iterable<string>): TokenRow[];
+/** The rows for the given `day|accountKey` pairs, in upload shape. */
+export declare function rowsForPending(state: ScanState, pairs: Iterable<string>): TokenRow[];
+/** Split rows into upload batches. */
+export declare function batches<T>(rows: T[], size?: number): T[][];
+/** Local totals per account since ``fromDay`` (inclusive), for `usage status`. */
+export declare function localTotals(state: ScanState, fromDay: string): Map<string, Totals>;
+export {};