@adecore/agents 0.0.1 → 0.17.0-beta.2

package/dist/usage/aggregate.d.ts

@@ -0,0 +1,12 @@
+import type { UsageBucket, UsageModel, UsageProject, UsageSummaryPayload } from '@adecore/agent-contracts';
+import { type PriceBook } from './pricing.ts';
+import { type KnownProject } from './projects.ts';
+import type { UsageRecord } from './record.ts';
+export interface Aggregation {
+    buckets: UsageBucket[];
+    models: UsageModel[];
+    projects: UsageProject[];
+    sessions: number;
+}
+export declare function accountOfRecord(record: UsageRecord): string;
+export declare function aggregate(records: readonly UsageRecord[], payload: UsageSummaryPayload, prices: PriceBook, known: readonly KnownProject[]): Promise<Aggregation>;

package/dist/usage/aggregate.js

@@ -0,0 +1,154 @@
+import { addTotals, EMPTY_TOTALS, totalTokensOf } from '@adecore/agent-contracts';
+import { cacheSavingsOf, costOf } from './pricing.js';
+import { ProjectResolver } from './projects.js';
+/*
+ * The calendar day a moment falls in, as the viewer's clock reads it. The host may stand in
+ * another zone than the person looking, so the zone travels with the request and every boundary
+ * here is local wall clock, never UTC.
+ */
+function slotFormatter(timeZone, resolution) {
+    const options = resolution === 'hour'
+        ? { timeZone, year: 'numeric', month: '2-digit', day: '2-digit', hour: '2-digit', hourCycle: 'h23' }
+        : { timeZone, year: 'numeric', month: '2-digit', day: '2-digit' };
+    try {
+        return new Intl.DateTimeFormat('en-CA', options);
+    }
+    catch {
+        // A zone this machine does not know degrades to UTC rather than failing the whole request.
+        return new Intl.DateTimeFormat('en-CA', { ...options, timeZone: 'UTC' });
+    }
+}
+/* `2026-09-10` for a day, `2026-09-10T14` for an hour: the day is always the first ten characters. */
+function slotOf(format, timestampMs, resolution) {
+    const parts = format.formatToParts(new Date(timestampMs));
+    const at = (type) => parts.find((part) => part.type === type)?.value ?? '';
+    const day = `${at('year')}-${at('month')}-${at('day')}`;
+    return resolution === 'hour' ? `${day}T${at('hour')}` : day;
+}
+function emptyTotals() {
+    return { ...EMPTY_TOTALS };
+}
+/* The account a record was made under, the default one under its CLI's kind. */
+export function accountOfRecord(record) {
+    return record.account ?? record.provider;
+}
+/*
+ * Every record of the period folded three ways at once: per slot for the chart, per model for the
+ * breakdown and its price basis, and per folder for the projects. The three cannot be derived from
+ * one another without a bucket per slot times model times project, which is a table nobody reads.
+ */
+export async function aggregate(records, payload, prices, known) {
+    const format = slotFormatter(payload.timeZone, payload.resolution);
+    const buckets = new Map();
+    const models = new Map();
+    /* The basis of the first record of a model prices the whole row: a model has one price. */
+    const modelBasis = new Map();
+    const projects = new Map();
+    const sessions = new Set();
+    const resolver = new ProjectResolver(known);
+    const folders = new Map();
+    // A filter splits buckets and models per account; without one they fold the way they did before accounts.
+    const only = payload.accounts === undefined ? null : new Set(payload.accounts);
+    for (const record of records) {
+        const account = only === null ? null : accountOfRecord(record);
+        if (only !== null && !only.has(account)) {
+            continue;
+        }
+        const slot = slotOf(format, record.timestampMs, payload.resolution);
+        const day = slot.slice(0, 10);
+        if (day < payload.from || day > payload.to) {
+            continue;
+        }
+        const { price, basis, pricedAs } = prices.look(record.model);
+        const cost = price === null ? 0 : costOf(record.totals, price);
+        const bucketKey = `${slot}\0${record.provider}\0${record.model}\0${account ?? ''}`;
+        let bucket = buckets.get(bucketKey);
+        if (bucket === undefined) {
+            bucket = {
+                slot,
+                provider: record.provider,
+                model: record.model,
+                account,
+                totals: emptyTotals(),
+                costUsd: 0,
+                priced: false,
+                cacheSavingsUsd: 0,
+                sessions: new Set()
+            };
+            buckets.set(bucketKey, bucket);
+        }
+        bucket.totals = addTotals(bucket.totals, record.totals);
+        bucket.costUsd += cost;
+        bucket.priced ||= price !== null;
+        bucket.cacheSavingsUsd += price === null ? 0 : cacheSavingsOf(record.totals, price);
+        if (record.sessionId !== '') {
+            bucket.sessions.add(record.sessionId);
+            sessions.add(`${record.provider}\0${record.sessionId}`);
+        }
+        const modelKey = `${record.provider}\0${record.model}\0${account ?? ''}`;
+        let model = models.get(modelKey);
+        if (model === undefined) {
+            model = { provider: record.provider, model: record.model, account, totals: emptyTotals(), costUsd: 0, priced: false };
+            models.set(modelKey, model);
+            modelBasis.set(modelKey, { basis, pricedAs });
+        }
+        model.totals = addTotals(model.totals, record.totals);
+        model.costUsd += cost;
+        model.priced ||= price !== null;
+        let folder = folders.get(record.cwd);
+        if (folder === undefined) {
+            const resolved = await resolver.resolve(record.cwd);
+            folder = resolved.folder;
+            folders.set(record.cwd, folder);
+            if (!projects.has(folder)) {
+                projects.set(folder, { folder, name: resolved.name, projectId: resolved.projectId, byProvider: new Map(), totals: emptyTotals(), costUsd: 0 });
+            }
+        }
+        const project = projects.get(folder);
+        project.totals = addTotals(project.totals, record.totals);
+        project.costUsd += cost;
+        const share = project.byProvider.get(record.provider) ?? { costUsd: 0, tokens: 0 };
+        share.costUsd += cost;
+        share.tokens += totalTokensOf(record.totals);
+        project.byProvider.set(record.provider, share);
+    }
+    return {
+        buckets: [...buckets.values()]
+            .map((bucket) => ({
+            slot: bucket.slot,
+            provider: bucket.provider,
+            model: bucket.model,
+            ...(bucket.account === null ? {} : { account: bucket.account }),
+            totals: bucket.totals,
+            costUsd: bucket.priced ? bucket.costUsd : null,
+            cacheSavingsUsd: bucket.cacheSavingsUsd,
+            sessions: bucket.sessions.size
+        }))
+            .sort((a, b) => a.slot.localeCompare(b.slot) ||
+            a.provider.localeCompare(b.provider) ||
+            a.model.localeCompare(b.model) ||
+            (a.account ?? '').localeCompare(b.account ?? '')),
+        models: [...models.entries()]
+            .map(([key, model]) => ({
+            provider: model.provider,
+            model: model.model,
+            ...(model.account === null ? {} : { account: model.account }),
+            totals: model.totals,
+            costUsd: model.priced ? model.costUsd : null,
+            priceBasis: modelBasis.get(key)?.basis ?? 'unknown',
+            pricedAs: modelBasis.get(key)?.pricedAs ?? null
+        }))
+            .sort((a, b) => (b.costUsd ?? -1) - (a.costUsd ?? -1)),
+        projects: [...projects.values()]
+            .map((project) => ({
+            folder: project.folder,
+            name: project.name,
+            projectId: project.projectId,
+            byProvider: Object.fromEntries(project.byProvider),
+            totals: project.totals,
+            costUsd: project.costUsd
+        }))
+            .sort((a, b) => b.costUsd - a.costUsd),
+        sessions: sessions.size
+    };
+}

package/dist/usage/exchange.d.ts

@@ -0,0 +1,16 @@
+import type { UsageRate } from '@adecore/agent-contracts';
+export declare const FRANKFURTER_URL = "https://api.frankfurter.app/latest";
+export declare const TARGET_CURRENCY = "EUR";
+export declare function parseRate(document: unknown, currency: string): Omit<UsageRate, 'fetchedAt'> | null;
+export declare class ExchangeRates {
+    private readonly home;
+    private readonly allowFetch;
+    private rate;
+    private loadedFromDisk;
+    private inFlight;
+    constructor(home: string, allowFetch?: boolean);
+    get current(): UsageRate | null;
+    ensure(): Promise<void>;
+    private get file();
+    private refresh;
+}

package/dist/usage/exchange.js

@@ -0,0 +1,84 @@
+import { mkdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { isNotFound, writeAtomic } from '../fs.js';
+import { errorText } from '../error-text.js';
+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, currency) {
+    const body = typeof document === 'object' && document !== null ? document : null;
+    const rates = body === null || typeof body.rates !== 'object' || body.rates === null ? null : body.rates;
+    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 {
+    home;
+    allowFetch;
+    rate = null;
+    loadedFromDisk = false;
+    inFlight = null;
+    constructor(home, allowFetch = true) {
+        this.home = home;
+        this.allowFetch = allowFetch;
+    }
+    get current() {
+        return this.rate;
+    }
+    /* Refreshes at most one rate at a time; a second caller waits for the first one's answer. */
+    ensure() {
+        this.inFlight ??= this.refresh().finally(() => {
+            this.inFlight = null;
+        });
+        return this.inFlight;
+    }
+    get file() {
+        return join(this.home, 'usage', 'exchange-rate.json');
+    }
+    async refresh() {
+        if (!this.loadedFromDisk) {
+            this.loadedFromDisk = true;
+            try {
+                const stored = JSON.parse(await readFile(this.file, 'utf8'));
+                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/dist/usage/index-file.d.ts

@@ -0,0 +1,15 @@
+import type { UsageProvider } from '@adecore/agent-contracts';
+import type { UsageRecord } from './record.ts';
+import type { CodexParserState } from './readers/codex.ts';
+export interface IndexedFile {
+    provider: UsageProvider;
+    size: number;
+    mtimeMs: number;
+    offset: number;
+    records: UsageRecord[];
+    tail: UsageRecord[];
+    codex: CodexParserState | null;
+}
+export type UsageIndex = Map<string, IndexedFile>;
+export declare function encodeIndex(index: UsageIndex): string;
+export declare function decodeIndex(text: string): UsageIndex;

package/dist/usage/index-file.js

@@ -0,0 +1,123 @@
+/* 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;
+class Interner {
+    values = [];
+    at = new Map();
+    index(value) {
+        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) {
+    const models = new Interner();
+    const sessions = new Interner();
+    const folders = new Interner();
+    const accounts = new Interner();
+    const files = {};
+    const row = (record) => [
+        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 = {
+        version: INDEX_VERSION,
+        models: models.values,
+        sessions: sessions.values,
+        folders: folders.values,
+        accounts: accounts.values,
+        files
+    };
+    return JSON.stringify(document);
+}
+function isRow(row, version) {
+    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) {
+    const index = new Map();
+    let document;
+    try {
+        document = JSON.parse(text);
+    }
+    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, at) => (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) => {
+            const records = [];
+            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/dist/usage/limits/monitor.d.ts

@@ -0,0 +1,50 @@
+import type { UsageLimitsSnapshot, UsageProvider } from '@adecore/agent-contracts';
+import type { ProviderRegistry } from '../../providers/registry.ts';
+import type { AgentSink } from '../../events.ts';
+import { type LimitsUpdate } from './normalize.ts';
+import type { CodexClientInfo } from '../../chat/codex-transport.ts';
+import { type ProbeResult } from './probe.ts';
+export type ProbeEnv = Record<string, string>;
+export interface LimitAccount {
+    id: string;
+    kind: UsageProvider;
+    label: string;
+    color?: string;
+    isDefault: boolean;
+}
+export interface LimitAccounts {
+    list(): LimitAccount[];
+    envFor(kind: UsageProvider, id: string): ProbeEnv;
+    lastUsedAt(id: string): number | null;
+}
+export interface UsageMonitorOptions {
+    providers: ProviderRegistry;
+    accounts?: LimitAccounts;
+    probe?: (kind: UsageProvider, command: readonly string[], env: ProbeEnv) => Promise<ProbeResult>;
+    now?: () => number;
+    client?: CodexClientInfo;
+}
+export declare class UsageMonitor {
+    private readonly registry;
+    private readonly accounts;
+    private readonly probe;
+    private readonly now;
+    private readonly sinks;
+    private readonly states;
+    private inFlight;
+    private timer;
+    constructor(options: UsageMonitorOptions);
+    subscribe(clientId: string, sink: AgentSink): () => void;
+    snapshot(): UsageLimitsSnapshot;
+    start(): void;
+    stop(): void;
+    refresh(force: boolean): Promise<void>;
+    accountsChanged(): void;
+    applyLive(update: LimitsUpdate): void;
+    private listed;
+    private stateOf;
+    private due;
+    private runAll;
+    private read;
+    private emit;
+}

package/dist/usage/limits/monitor.js

@@ -0,0 +1,179 @@
+import { definedEnv } from '../../providers/accounts/launch.js';
+import { mergeWindows } from './normalize.js';
+import { probeClaude, probeCodex } from './probe.js';
+import { ClientSinks } from '../../client-sinks.js';
+import { errorText } from '../../error-text.js';
+/* 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 = ['claude', 'codex'];
+function blank(kind) {
+    return {
+        kind,
+        plan: null,
+        checkedAt: 0,
+        source: 'probe',
+        windows: [],
+        cost: null,
+        unavailable: null
+    };
+}
+/*
+ * 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 {
+    registry;
+    accounts;
+    probe;
+    now;
+    sinks = new ClientSinks();
+    // By account id, so the default account of a CLI is under the CLI's kind.
+    states = new Map();
+    inFlight = null;
+    timer = null;
+    constructor(options) {
+        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, sink) {
+        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() {
+        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() {
+        this.timer ??= setInterval(() => void this.refresh(false), PROBE_INTERVAL_MS);
+        void this.refresh(false);
+    }
+    stop() {
+        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) {
+        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() {
+        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) {
+        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. */
+    listed() {
+        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)];
+        });
+    }
+    stateOf(kind, id) {
+        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. */
+    due(account, state, force) {
+        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;
+    }
+    async runAll(force) {
+        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();
+        }
+    }
+    async read(account) {
+        let env;
+        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);
+    }
+    emit() {
+        const event = { event: 'usage.limitsChanged', payload: this.snapshot() };
+        this.sinks.emit(event);
+    }
+}

package/dist/usage/limits/normalize.d.ts

@@ -0,0 +1,21 @@
+import type { UsageLimitsProvider, UsageProvider, UsageWindow } from '@adecore/agent-contracts';
+export interface ProviderReading {
+    plan: string | null;
+    windows: UsageWindow[];
+    cost: {
+        sessionUsd: number;
+    } | null;
+}
+export interface LimitsUpdate {
+    kind: UsageProvider;
+    account?: string;
+    plan?: string | null;
+    windows: Partial<UsageWindow>[];
+}
+export declare function kindOfDuration(durationMs: number | null): UsageWindow['kind'];
+export declare function readClaudeUsage(response: unknown): ProviderReading | {
+    unavailable: UsageLimitsProvider['unavailable'];
+};
+export declare function readClaudeEvent(info: unknown): LimitsUpdate | null;
+export declare function readCodexLimits(snapshot: unknown): ProviderReading | null;
+export declare function mergeWindows(known: readonly UsageWindow[], updates: readonly Partial<UsageWindow>[]): UsageWindow[];