@prohost/cli 0.9.0 → 0.10.1

package/dist/usage/discovery.js

@@ -0,0 +1,187 @@
+/**
+ * Find the Claude Code and Codex logins already on this machine.
+ *
+ * People who juggle several subscriptions keep each one in its own config
+ * directory — `~/.claude-work`, `~/.codex-personal`, or whatever
+ * `$CLAUDE_CONFIG_DIR` / `$CODEX_HOME` points at. Observer mode reports all of
+ * them, so instead of asking for each one to be re-created under
+ * `~/.prohost-accounts`, it registers the directories that are already there.
+ *
+ * Only directory names and the presence of a few non-secret markers
+ * (`projects/`, `settings.json`, `sessions/`, `config.toml`…) are looked at —
+ * never a file's contents, and never anything that holds a credential.
+ * Whether a login is signed in is asked of the unmodified agent CLI later,
+ * exactly as `accounts.ts` already does.
+ */
+import { existsSync, readdirSync, realpathSync, statSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { AccountError, DEFAULT_ACCOUNT_LABEL, MAX_REPORTED_ACCOUNTS, ensureDefaultAccount, isValidLabel, loadAccounts, registerAccountDir, } from '../agent/accounts.js';
+/** Entries whose presence says "this is a Claude Code config directory". None of them hold a login. */
+const CLAUDE_MARKERS = ['projects', 'settings.json', '.claude.json', 'history.jsonl', 'todos', 'statsig', 'shell-snapshots'];
+/** Same for Codex. `auth.json` is deliberately not one of them. */
+const CODEX_MARKERS = ['sessions', 'archived_sessions', 'config.toml', 'history.jsonl', 'log', 'version.json'];
+const CLAUDE_NAME = /^\.claude(?:[-_.](.+))?$/;
+const CODEX_NAME = /^\.codex(?:[-_.](.+))?$/;
+function homeDir(env) {
+    return env.HOME || os.homedir();
+}
+function resolveReal(dir) {
+    try {
+        return realpathSync(dir);
+    }
+    catch {
+        return path.resolve(dir);
+    }
+}
+function isDirectory(p) {
+    try {
+        return statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function looksLikeConfigDir(dir, runtime) {
+    const markers = runtime === 'claude_code' ? CLAUDE_MARKERS : CODEX_MARKERS;
+    return isDirectory(dir) && markers.some((m) => existsSync(path.join(dir, m)));
+}
+/** The directory an account's logs live in: its own, or the CLI's default under `$HOME`. */
+export function accountConfigDir(record, env = process.env) {
+    if (record.dir)
+        return record.dir;
+    return path.join(homeDir(env), record.runtime === 'claude_code' ? '.claude' : '.codex');
+}
+/**
+ * A registry label from a directory name: `~/.claude-baxy` → `baxy`,
+ * `~/.codex_work` → `work`, `~/.claude` → `default`. Anything a label can't
+ * hold becomes `-`; an empty result falls back to the runtime's name.
+ */
+export function deriveLabel(dirName, runtime) {
+    const base = path.basename(dirName);
+    const match = (runtime === 'claude_code' ? CLAUDE_NAME : CODEX_NAME).exec(base);
+    if (match && match[1] === undefined)
+        return DEFAULT_ACCOUNT_LABEL;
+    const raw = match ? match[1] : base.replace(/^\.+/, '');
+    const cleaned = raw
+        .replace(/[^A-Za-z0-9_-]+/g, '-')
+        .replace(/^[^A-Za-z0-9]+/, '')
+        .replace(/-+$/, '')
+        .slice(0, 32);
+    if (cleaned && isValidLabel(cleaned))
+        return cleaned;
+    return runtime === 'claude_code' ? 'claude' : 'codex';
+}
+/** Make `label` unique among `taken` by appending `-2`, `-3`… (and never `default`). */
+function uniqueLabel(label, taken) {
+    if (!taken.has(label) && label !== DEFAULT_ACCOUNT_LABEL)
+        return label;
+    for (let n = 2;; n += 1) {
+        const suffix = `-${n}`;
+        const candidate = `${label.slice(0, 32 - suffix.length)}${suffix}`;
+        if (!taken.has(candidate))
+            return candidate;
+    }
+}
+/**
+ * Every config directory on this machine, before any registry comparison:
+ * `~/.claude*` / `~/.codex*` that look like config directories, plus
+ * `$CLAUDE_CONFIG_DIR` / `$CODEX_HOME`. Deduplicated by real path.
+ */
+export function findConfigDirs(env = process.env) {
+    const home = homeDir(env);
+    const found = new Map();
+    const defaults = {
+        claude_code: resolveReal(path.join(home, '.claude')),
+        codex: resolveReal(path.join(home, '.codex')),
+    };
+    const consider = (dir, runtime, via) => {
+        if (!looksLikeConfigDir(dir, runtime))
+            return;
+        const real = resolveReal(dir);
+        const key = `${runtime}:${real}`;
+        if (found.has(key))
+            return;
+        const isDefault = real === defaults[runtime];
+        found.set(key, {
+            runtime,
+            dir: real,
+            label: isDefault ? DEFAULT_ACCOUNT_LABEL : deriveLabel(dir, runtime),
+            isDefault,
+            via,
+        });
+    };
+    let entries = [];
+    try {
+        entries = readdirSync(home).sort();
+    }
+    catch {
+        /* no readable home: only the env vars below */
+    }
+    for (const name of entries) {
+        if (CLAUDE_NAME.test(name))
+            consider(path.join(home, name), 'claude_code', 'home');
+        else if (CODEX_NAME.test(name))
+            consider(path.join(home, name), 'codex', 'home');
+    }
+    if (env.CLAUDE_CONFIG_DIR)
+        consider(path.resolve(env.CLAUDE_CONFIG_DIR), 'claude_code', 'CLAUDE_CONFIG_DIR');
+    if (env.CODEX_HOME)
+        consider(path.resolve(env.CODEX_HOME), 'codex', 'CODEX_HOME');
+    return [...found.values()];
+}
+/**
+ * Register every login found by {@link findConfigDirs} that the machine-wide
+ * registry doesn't already know. `dryRun` reports the same answer and writes
+ * nothing.
+ */
+export function discoverAccounts(options = {}, env = process.env) {
+    const result = { added: [], known: [], skipped: [] };
+    const registry = loadAccounts(env);
+    const byDir = new Map();
+    for (const record of registry) {
+        // The implicit default (dir null) compares on the CLI's own directory.
+        byDir.set(`${record.runtime}:${resolveReal(accountConfigDir(record, env))}`, record);
+    }
+    const taken = { claude_code: new Set(), codex: new Set() };
+    for (const record of registry)
+        taken[record.runtime].add(record.label);
+    let room = MAX_REPORTED_ACCOUNTS - 2 - registry.filter((a) => a.label !== DEFAULT_ACCOUNT_LABEL).length;
+    for (const found of findConfigDirs(env)) {
+        const existing = byDir.get(`${found.runtime}:${found.dir}`);
+        if (existing) {
+            result.known.push({ ...found, label: existing.label, record: existing });
+            continue;
+        }
+        if (found.isDefault) {
+            if (options.dryRun)
+                result.added.push(found);
+            else
+                result.added.push({ ...found, record: ensureDefaultAccount(found.runtime, env) });
+            continue;
+        }
+        if (room <= 0) {
+            result.skipped.push({ ...found, reason: `this machine already has ${MAX_REPORTED_ACCOUNTS - 2} accounts` });
+            continue;
+        }
+        const label = uniqueLabel(found.label, taken[found.runtime]);
+        taken[found.runtime].add(label);
+        const candidate = { ...found, label };
+        if (options.dryRun) {
+            result.added.push(candidate);
+            room -= 1;
+            continue;
+        }
+        try {
+            const record = registerAccountDir({ label, runtime: found.runtime, dir: found.dir }, env);
+            result.added.push({ ...candidate, label: record.label, record });
+            room -= 1;
+        }
+        catch (err) {
+            if (!(err instanceof AccountError))
+                throw err;
+            result.skipped.push({ ...candidate, reason: err.message });
+        }
+    }
+    return result;
+}

package/dist/usage/key-input.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Reading an API key for `prohost usage connect` without putting it on the
+ * command line, where it would land in shell history and the process list.
+ *
+ * Two safe paths: piped stdin (`pbpaste | prohost usage connect --key -`) and,
+ * at a terminal, a prompt that does not echo what is typed or pasted.
+ */
+/** The slice of `process.stdin` this module uses, so tests can pass a stream. */
+export interface KeyStdin extends AsyncIterable<string | Buffer> {
+    isTTY?: boolean;
+    setRawMode?(mode: boolean): unknown;
+    setEncoding(encoding: BufferEncoding): unknown;
+    on(event: 'data', listener: (chunk: string | Buffer) => void): unknown;
+    removeListener(event: 'data', listener: (chunk: string | Buffer) => void): unknown;
+    resume(): unknown;
+    pause(): unknown;
+}
+/** Longer than any ProhostAI key; a pipe that runs past it is not a key. */
+export declare const MAX_PIPED_KEY_CHARS = 4096;
+export declare class PipedKeyTooLongError extends Error {
+}
+/**
+ * The first non-empty line of piped stdin, trimmed; `undefined` when there is
+ * none. Returns as soon as that line ends, so a producer that keeps the pipe
+ * open does not hang `connect`, and stops reading past
+ * {@link MAX_PIPED_KEY_CHARS}.
+ *
+ * @throws PipedKeyTooLongError when no line ends within the limit.
+ */
+export declare function readPipedKey(stdin: KeyStdin): Promise<string | undefined>;
+/**
+ * Prompt for a key at a terminal without echoing it. Resolves with the
+ * trimmed key, or `undefined` when nothing was entered or the user pressed
+ * Ctrl-C. The prompt goes to `write` (stderr), keeping stdout clean.
+ */
+export declare function promptHiddenKey(stdin: KeyStdin, write: (text: string) => void, prompt?: string): Promise<string | undefined>;

package/dist/usage/key-input.js

@@ -0,0 +1,79 @@
+/**
+ * Reading an API key for `prohost usage connect` without putting it on the
+ * command line, where it would land in shell history and the process list.
+ *
+ * Two safe paths: piped stdin (`pbpaste | prohost usage connect --key -`) and,
+ * at a terminal, a prompt that does not echo what is typed or pasted.
+ */
+/** Longer than any ProhostAI key; a pipe that runs past it is not a key. */
+export const MAX_PIPED_KEY_CHARS = 4096;
+export class PipedKeyTooLongError extends Error {
+}
+/**
+ * The first non-empty line of piped stdin, trimmed; `undefined` when there is
+ * none. Returns as soon as that line ends, so a producer that keeps the pipe
+ * open does not hang `connect`, and stops reading past
+ * {@link MAX_PIPED_KEY_CHARS}.
+ *
+ * @throws PipedKeyTooLongError when no line ends within the limit.
+ */
+export async function readPipedKey(stdin) {
+    let pending = '';
+    for await (const chunk of stdin) {
+        pending += typeof chunk === 'string' ? chunk : chunk.toString('utf8');
+        let newline = pending.search(/\r?\n/);
+        while (newline !== -1) {
+            // Measured before trimming: padding counts toward the bound too.
+            const raw = pending.slice(0, newline);
+            if (raw.length > MAX_PIPED_KEY_CHARS)
+                throw new PipedKeyTooLongError('piped input is not a key');
+            const line = raw.trim();
+            if (line)
+                return line;
+            pending = pending.slice(newline).replace(/^\r?\n/, '');
+            newline = pending.search(/\r?\n/);
+        }
+        if (pending.length > MAX_PIPED_KEY_CHARS)
+            throw new PipedKeyTooLongError('piped input is not a key');
+    }
+    if (pending.length > MAX_PIPED_KEY_CHARS)
+        throw new PipedKeyTooLongError('piped input is not a key');
+    return pending.trim() || undefined;
+}
+const ENTER = new Set(['\r', '\n', '\u0004']); // Return, or Ctrl-D
+const CTRL_C = '\u0003';
+const BACKSPACE = new Set(['\u007f', '\b']);
+/**
+ * Prompt for a key at a terminal without echoing it. Resolves with the
+ * trimmed key, or `undefined` when nothing was entered or the user pressed
+ * Ctrl-C. The prompt goes to `write` (stderr), keeping stdout clean.
+ */
+export function promptHiddenKey(stdin, write, prompt = 'API key (usage:write scope; input hidden): ') {
+    return new Promise((resolve) => {
+        let value = '';
+        const finish = (result) => {
+            stdin.removeListener('data', onData);
+            stdin.setRawMode?.(false);
+            stdin.pause();
+            write('\n');
+            resolve(result);
+        };
+        const onData = (chunk) => {
+            for (const ch of typeof chunk === 'string' ? chunk : chunk.toString('utf8')) {
+                if (ENTER.has(ch))
+                    return finish(value.trim() || undefined);
+                if (ch === CTRL_C)
+                    return finish(undefined);
+                if (BACKSPACE.has(ch))
+                    value = value.slice(0, -1);
+                else if (ch >= ' ')
+                    value += ch;
+            }
+        };
+        write(prompt);
+        stdin.setRawMode?.(true);
+        stdin.setEncoding('utf8');
+        stdin.on('data', onData);
+        stdin.resume();
+    });
+}

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 {};