@adecore/agents 0.0.1 → 0.17.0-beta.1

package/src/usage/exchange.ts

@@ -0,0 +1,93 @@
+import { mkdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import type { UsageRate } from '@adecore/agent-contracts';
+import { isNotFound, writeAtomic } from '../fs.ts';
+import { errorText } from '../error-text.ts';
+
+export const FRANKFURTER_URL = 'https://api.frankfurter.app/latest';
+
+/* The bank publishes one rate a day, so a rate a day old is the rate. */
+const TTL_MS = 24 * 60 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 10_000;
+
+/* The one currency the page offers next to dollars. Every price the host knows is in dollars. */
+export const TARGET_CURRENCY = 'EUR';
+
+export function parseRate(document: unknown, currency: string): Omit<UsageRate, 'fetchedAt'> | null {
+    const body = typeof document === 'object' && document !== null ? (document as Record<string, unknown>) : null;
+    const rates = body === null || typeof body.rates !== 'object' || body.rates === null ? null : (body.rates as Record<string, unknown>);
+    const rate = rates === null ? undefined : rates[currency];
+    if (typeof rate !== 'number' || !Number.isFinite(rate) || rate <= 0 || typeof body?.date !== 'string') {
+        return null;
+    }
+    return { currency, rate, date: body.date };
+}
+
+/*
+ * What a dollar is worth in euros, asked of the ECB through frankfurter.app once a day and kept on
+ * disk between runs. It is the same shape as the price table: the page works without it and simply
+ * stays in dollars, so nothing here is allowed to hold up a scan or fail one.
+ */
+export class ExchangeRates {
+    private readonly home: string;
+    private readonly allowFetch: boolean;
+    private rate: UsageRate | null = null;
+    private loadedFromDisk = false;
+    private inFlight: Promise<void> | null = null;
+
+    constructor(home: string, allowFetch = true) {
+        this.home = home;
+        this.allowFetch = allowFetch;
+    }
+
+    get current(): UsageRate | null {
+        return this.rate;
+    }
+
+    /* Refreshes at most one rate at a time; a second caller waits for the first one's answer. */
+    ensure(): Promise<void> {
+        this.inFlight ??= this.refresh().finally(() => {
+            this.inFlight = null;
+        });
+        return this.inFlight;
+    }
+
+    private get file(): string {
+        return join(this.home, 'usage', 'exchange-rate.json');
+    }
+
+    private async refresh(): Promise<void> {
+        if (!this.loadedFromDisk) {
+            this.loadedFromDisk = true;
+            try {
+                const stored = JSON.parse(await readFile(this.file, 'utf8')) as UsageRate;
+                if (stored?.currency === TARGET_CURRENCY && typeof stored.rate === 'number' && stored.rate > 0) {
+                    this.rate = stored;
+                }
+            } catch (e) {
+                if (!isNotFound(e)) {
+                    console.warn('The stored exchange rate would not read; asking for a new one:', errorText(e));
+                }
+            }
+        }
+        if (!this.allowFetch || (this.rate !== null && Date.now() - this.rate.fetchedAt < TTL_MS)) {
+            return;
+        }
+        try {
+            const response = await fetch(`${FRANKFURTER_URL}?from=USD&to=${TARGET_CURRENCY}`, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+            if (!response.ok) {
+                throw new Error(`frankfurter.app answered ${response.status}`);
+            }
+            const parsed = parseRate(await response.json(), TARGET_CURRENCY);
+            if (parsed === null) {
+                throw new Error(`The answer carried no ${TARGET_CURRENCY} rate`);
+            }
+            this.rate = { ...parsed, fetchedAt: Date.now() };
+            await mkdir(join(this.home, 'usage'), { recursive: true, mode: 0o700 });
+            await writeAtomic(this.file, JSON.stringify(this.rate));
+        } catch (e) {
+            // Yesterday's rate still converts; a rate that could not be refreshed is not a failure.
+            console.warn('Could not refresh the exchange rate:', errorText(e));
+        }
+    }
+}

package/src/usage/index-file.ts

@@ -0,0 +1,178 @@
+import type { UsageProvider } from '@adecore/agent-contracts';
+import type { UsageRecord } from './record.ts';
+import type { CodexParserState } from './readers/codex.ts';
+
+/* Another version is thrown away rather than migrated, since rebuilding costs one cold scan; version 1 is read as it is. */
+const INDEX_VERSION = 2;
+/* Before accounts: every record was the default account's, so it reads as that without a scan. */
+const ACCOUNTLESS_VERSION = 1;
+
+export interface IndexedFile {
+    provider: UsageProvider;
+    size: number;
+    mtimeMs: number;
+    /* Just past the last newline that was read, so a file that grew is read from there. */
+    offset: number;
+    records: UsageRecord[];
+    /* What the line still being written at the end of the file says; read again on the next scan,
+       so it is kept apart from the records the offset has already accounted for. */
+    tail: UsageRecord[];
+    /* What the reader has to remember to carry on halfway through a Codex file. */
+    codex: CodexParserState | null;
+}
+
+export type UsageIndex = Map<string, IndexedFile>;
+
+/*
+ * The index is a few hundred thousand records of seven numbers each, and the same model, session,
+ * directory and account strings over and over. Interning those and writing a record as a tuple is
+ * what keeps the file at a few megabytes instead of tens of them. The account is one past its place
+ * in its table, and 0 for the default account, which is also what a version 1 row without it means.
+ */
+type RecordRow = [number, number, number, number, number, number, number, number, number, number, number, string | 0, number?];
+
+interface FileRow {
+    p: UsageProvider;
+    s: number;
+    m: number;
+    o: number;
+    r: RecordRow[];
+    t: RecordRow[];
+    c: CodexParserState | null;
+}
+
+interface IndexFile {
+    version: number;
+    models: string[];
+    sessions: string[];
+    folders: string[];
+    accounts?: string[];
+    files: Record<string, FileRow>;
+}
+
+class Interner {
+    readonly values: string[] = [];
+    private readonly at = new Map<string, number>();
+
+    index(value: string): number {
+        const seen = this.at.get(value);
+        if (seen !== undefined) {
+            return seen;
+        }
+        const next = this.values.length;
+        this.values.push(value);
+        this.at.set(value, next);
+        return next;
+    }
+}
+
+export function encodeIndex(index: UsageIndex): string {
+    const models = new Interner();
+    const sessions = new Interner();
+    const folders = new Interner();
+    const accounts = new Interner();
+    const files: Record<string, FileRow> = {};
+    const row = (record: UsageRecord): RecordRow => [
+        record.timestampMs,
+        models.index(record.model),
+        sessions.index(record.sessionId),
+        folders.index(record.cwd),
+        record.totals.calls,
+        record.totals.input,
+        record.totals.cacheRead,
+        record.totals.cacheWrite,
+        record.totals.cacheWrite1h,
+        record.totals.output,
+        record.totals.reasoning,
+        record.dedupeKey ?? 0,
+        record.account === undefined ? 0 : accounts.index(record.account) + 1
+    ];
+    for (const [path, file] of index) {
+        files[path] = { p: file.provider, s: file.size, m: file.mtimeMs, o: file.offset, c: file.codex, r: file.records.map(row), t: file.tail.map(row) };
+    }
+    const document: IndexFile = {
+        version: INDEX_VERSION,
+        models: models.values,
+        sessions: sessions.values,
+        folders: folders.values,
+        accounts: accounts.values,
+        files
+    };
+    return JSON.stringify(document);
+}
+
+function isRow(row: unknown, version: number): row is RecordRow {
+    return (
+        Array.isArray(row) &&
+        row.length === (version === ACCOUNTLESS_VERSION ? 12 : 13) &&
+        row.slice(0, 11).every((value) => typeof value === 'number') &&
+        (typeof row[11] === 'string' || row[11] === 0) &&
+        (version === ACCOUNTLESS_VERSION || typeof row[12] === 'number')
+    );
+}
+
+/*
+ * A row that does not read back costs a cold parse of the file it belonged to, never a wrong total,
+ * so anything unexpected drops that file's entry rather than being repaired.
+ */
+export function decodeIndex(text: string): UsageIndex {
+    const index: UsageIndex = new Map();
+    let document: IndexFile;
+    try {
+        document = JSON.parse(text) as IndexFile;
+    } catch {
+        return index;
+    }
+    const version = document?.version;
+    if (
+        (version !== INDEX_VERSION && version !== ACCOUNTLESS_VERSION) ||
+        !Array.isArray(document.models) ||
+        !Array.isArray(document.sessions) ||
+        !Array.isArray(document.folders)
+    ) {
+        return index;
+    }
+    const accounts = Array.isArray(document.accounts) ? document.accounts : [];
+    const name = (table: string[], at: number): string | null => (typeof table[at] === 'string' ? table[at] : null);
+    for (const [path, file] of Object.entries(document.files ?? {})) {
+        if (file.p !== 'claude' && file.p !== 'codex') {
+            continue;
+        }
+        if (typeof file.s !== 'number' || typeof file.m !== 'number' || typeof file.o !== 'number' || file.o < 0 || !Array.isArray(file.r)) {
+            continue;
+        }
+        let broken = false;
+        const decode = (rows: RecordRow[]): UsageRecord[] => {
+            const records: UsageRecord[] = [];
+            for (const row of rows) {
+                const valid = isRow(row, version);
+                const model = valid ? name(document.models, row[1]) : null;
+                const sessionId = valid ? name(document.sessions, row[2]) : null;
+                const cwd = valid ? name(document.folders, row[3]) : null;
+                const accountAt = valid ? (row[12] ?? 0) : 0;
+                const account = accountAt === 0 ? undefined : name(accounts, accountAt - 1);
+                if (!valid || model === null || sessionId === null || cwd === null || account === null) {
+                    broken = true;
+                    return records;
+                }
+                records.push({
+                    provider: file.p,
+                    timestampMs: row[0],
+                    model,
+                    sessionId,
+                    cwd,
+                    ...(account === undefined ? {} : { account }),
+                    totals: { calls: row[4], input: row[5], cacheRead: row[6], cacheWrite: row[7], cacheWrite1h: row[8], output: row[9], reasoning: row[10] },
+                    dedupeKey: row[11] === 0 ? null : row[11]
+                });
+            }
+            return records;
+        };
+        const records = decode(file.r);
+        const tail = decode(Array.isArray(file.t) ? file.t : []);
+        if (!broken) {
+            index.set(path, { provider: file.p, size: file.s, mtimeMs: file.m, offset: file.o, records, tail, codex: file.c ?? null });
+        }
+    }
+    return index;
+}

package/src/usage/limits/monitor.ts

@@ -0,0 +1,239 @@
+import type { UsageLimitsProvider, UsageLimitsSnapshot, UsageProvider } from '@adecore/agent-contracts';
+import { definedEnv } from '../../providers/accounts/launch.ts';
+import type { ProviderRegistry } from '../../providers/registry.ts';
+import type { AgentEvent, AgentSink } from '../../events.ts';
+import { mergeWindows, type LimitsUpdate } from './normalize.ts';
+import type { CodexClientInfo } from '../../chat/codex-transport.ts';
+import { probeClaude, probeCodex, type ProbeResult } from './probe.ts';
+import { ClientSinks } from '../../client-sinks.ts';
+import { errorText } from '../../error-text.ts';
+
+/* Often enough that a bar is never far behind, rarely enough that two CLIs are not started all day. */
+const PROBE_INTERVAL_MS = 5 * 60_000;
+const MAX_BACKOFF_MS = 60 * 60_000;
+/* An account other than the default one that nobody started a CLI under for this long is only read when a person asks. */
+const RECENT_USE_MS = 24 * 60 * 60_000;
+
+const PROVIDERS: readonly UsageProvider[] = ['claude', 'codex'];
+
+export type ProbeEnv = Record<string, string>;
+
+/* An account whose plan is read. The default account of a CLI has the CLI's kind as its id. */
+export interface LimitAccount {
+    id: string;
+    kind: UsageProvider;
+    label: string;
+    color?: string;
+    isDefault: boolean;
+}
+
+export interface LimitAccounts {
+    /* The default account of every CLI, and every other account that is on and signed in. */
+    list(): LimitAccount[];
+    /* The environment a probe of this account runs in. Throws for an account this machine cannot start. */
+    envFor(kind: UsageProvider, id: string): ProbeEnv;
+    /* When a chat or a terminal last started under this account; null when none did since the host started. */
+    lastUsedAt(id: string): number | null;
+}
+
+interface ProviderState {
+    kind: UsageProvider;
+    published: UsageLimitsProvider;
+    /* How long to wait after a failure; it doubles up to an hour and resets on the first answer. */
+    backoffMs: number;
+    nextAt: number;
+}
+
+function blank(kind: UsageProvider): UsageLimitsProvider {
+    return {
+        kind,
+        plan: null,
+        checkedAt: 0,
+        source: 'probe',
+        windows: [],
+        cost: null,
+        unavailable: null
+    };
+}
+
+export interface UsageMonitorOptions {
+    providers: ProviderRegistry;
+    /* The accounts to read; absent reads the default account of every CLI and names none. */
+    accounts?: LimitAccounts;
+    /* How to ask; a test answers without starting a CLI. */
+    probe?: (kind: UsageProvider, command: readonly string[], env: ProbeEnv) => Promise<ProbeResult>;
+    now?: () => number;
+    // How the host names itself to the app-server a probe opens.
+    client?: CodexClientInfo;
+}
+
+/*
+ * What is left of each plan, per account. Two sources feed it: a read of our own every five minutes,
+ * which starts the CLI, asks and ends it, and the events a running turn streams in between, which
+ * cost nothing and arrive the moment a number moves. Neither reads a credential: both CLIs already
+ * hold their own login and answer the question themselves.
+ */
+export class UsageMonitor {
+    private readonly registry: ProviderRegistry;
+    private readonly accounts: LimitAccounts | null;
+    private readonly probe: NonNullable<UsageMonitorOptions['probe']>;
+    private readonly now: () => number;
+    private readonly sinks = new ClientSinks<AgentEvent>();
+    // By account id, so the default account of a CLI is under the CLI's kind.
+    private readonly states = new Map<string, ProviderState>();
+    private inFlight: Promise<void> | null = null;
+    private timer: ReturnType<typeof setInterval> | null = null;
+
+    constructor(options: UsageMonitorOptions) {
+        this.registry = options.providers;
+        this.accounts = options.accounts ?? null;
+        this.probe = options.probe ?? ((kind, command, env) => (kind === 'claude' ? probeClaude(command, env) : probeCodex(command, env, options.client)));
+        this.now = options.now ?? Date.now;
+        for (const kind of PROVIDERS) {
+            this.stateOf(kind, kind);
+        }
+    }
+
+    subscribe(clientId: string, sink: AgentSink): () => void {
+        return this.sinks.subscribe(clientId, sink);
+    }
+
+    /* Per CLI its default account first, in the shape an entry had before accounts, then its other accounts. */
+    snapshot(): UsageLimitsSnapshot {
+        const providers = this.listed().map(({ id, kind, label, color }) => {
+            const published = this.stateOf(kind, id).published;
+            return this.accounts === null ? published : { ...published, account: { id, label, ...(color === undefined ? {} : { color }) } };
+        });
+        return { providers };
+    }
+
+    /* Starts the five minute pass. The first read runs at once, so a fresh host has numbers. */
+    start(): void {
+        this.timer ??= setInterval(() => void this.refresh(false), PROBE_INTERVAL_MS);
+        void this.refresh(false);
+    }
+
+    stop(): void {
+        if (this.timer !== null) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+
+    /* One pass at a time; a second caller waits for the first one's answer rather than starting a CLI. */
+    refresh(force: boolean): Promise<void> {
+        this.inFlight ??= this.runAll(force).finally(() => {
+            this.inFlight = null;
+        });
+        return this.inFlight;
+    }
+
+    /* An account came, went, was renamed or signed in: the list a client holds is drawn again. */
+    accountsChanged(): void {
+        this.emit();
+    }
+
+    /*
+     * A number a running turn reported, on the account the turn ran under. It lands on the row a full
+     * read drew, keeping the reset and the length the event leaves out, so the bar moves without
+     * waiting for the next pass.
+     */
+    applyLive(update: LimitsUpdate): void {
+        if (update.windows.length === 0) {
+            return;
+        }
+        const state = this.stateOf(update.kind, update.account ?? update.kind);
+        state.published = {
+            ...state.published,
+            plan: update.plan ?? state.published.plan,
+            checkedAt: this.now(),
+            source: 'event',
+            windows: mergeWindows(state.published.windows, update.windows),
+            unavailable: null
+        };
+        this.emit();
+    }
+
+    /* Every account of a CLI whose plan is read, the default one first. */
+    private listed(): LimitAccount[] {
+        const accounts = this.accounts?.list() ?? PROVIDERS.map((kind) => ({ id: kind, kind, label: kind, isDefault: true }));
+        return PROVIDERS.flatMap((kind) => {
+            const own = accounts.filter((account) => account.kind === kind);
+            return [...own.filter((account) => account.isDefault), ...own.filter((account) => !account.isDefault)];
+        });
+    }
+
+    private stateOf(kind: UsageProvider, id: string): ProviderState {
+        let state = this.states.get(id);
+        if (state === undefined || state.kind !== kind) {
+            state = { kind, published: blank(kind), backoffMs: PROBE_INTERVAL_MS, nextAt: 0 };
+            this.states.set(id, state);
+        }
+        return state;
+    }
+
+    /* The default account on the clock; another only while it is in use, since every read starts its CLI. */
+    private due(account: LimitAccount, state: ProviderState, force: boolean): boolean {
+        if (force) {
+            return true;
+        }
+        if (this.now() < state.nextAt) {
+            return false;
+        }
+        if (account.isDefault) {
+            return true;
+        }
+        const used = this.accounts?.lastUsedAt(account.id) ?? null;
+        return used !== null && this.now() - used < RECENT_USE_MS;
+    }
+
+    private async runAll(force: boolean): Promise<void> {
+        const installed = await this.registry.list();
+        let changed = false;
+        for (const account of this.listed()) {
+            const { kind } = account;
+            const state = this.stateOf(kind, account.id);
+            if (!this.due(account, state, force)) {
+                continue;
+            }
+            const info = installed.find((provider) => provider.kind === kind);
+            if (info === undefined || !info.installed) {
+                state.published = { ...blank(kind), checkedAt: this.now(), unavailable: { reason: 'not-installed', message: null } };
+                state.nextAt = this.now() + PROBE_INTERVAL_MS;
+                changed = true;
+                continue;
+            }
+            const result = await this.read(account);
+            const failed = 'unavailable' in result && result.unavailable?.reason === 'failed';
+            state.backoffMs = failed ? Math.min(MAX_BACKOFF_MS, state.backoffMs * 2) : PROBE_INTERVAL_MS;
+            state.nextAt = this.now() + state.backoffMs;
+            if (failed && state.published.windows.length > 0) {
+                // A pass that could not reach the CLI leaves the last good numbers where they are.
+                continue;
+            }
+            state.published =
+                'unavailable' in result
+                    ? { ...blank(kind), checkedAt: this.now(), unavailable: result.unavailable }
+                    : { kind, plan: result.plan, checkedAt: this.now(), source: 'probe', windows: result.windows, cost: result.cost, unavailable: null };
+            changed = true;
+        }
+        if (changed) {
+            this.emit();
+        }
+    }
+
+    private async read(account: LimitAccount): Promise<ProbeResult> {
+        let env: ProbeEnv;
+        try {
+            env = this.accounts === null ? definedEnv(process.env) : this.accounts.envFor(account.kind, account.id);
+        } catch (e) {
+            return { unavailable: { reason: 'failed', message: errorText(e) } };
+        }
+        return this.probe(account.kind, this.registry.get(account.kind).command, env);
+    }
+
+    private emit(): void {
+        const event: AgentEvent = { event: 'usage.limitsChanged', payload: this.snapshot() };
+        this.sinks.emit(event);
+    }
+}