@adecore/agents 0.23.1 → 0.24.1

package/src/usage/exchange.ts

@@ -32,8 +32,8 @@ 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;
+    private stored: Promise<void> | null = null;
+    private inFlight: Promise<boolean> | null = null;
 
     constructor(home: string, allowFetch = true) {
         this.home = home;
@@ -44,11 +44,19 @@ export class ExchangeRates {
         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;
-        });
+    /* Reads the rate an earlier run stored, once; asking for a new one is left to `ensure`. */
+    load(): Promise<void> {
+        this.stored ??= this.readStored();
+        return this.stored;
+    }
+
+    /* Refreshes at most one rate at a time, a second caller waiting for the first one's answer; true when a newer rate came in. */
+    ensure(): Promise<boolean> {
+        this.inFlight ??= this.load()
+            .then(() => this.fetchFresh())
+            .finally(() => {
+                this.inFlight = null;
+            });
         return this.inFlight;
     }
 
@@ -56,23 +64,24 @@ export class ExchangeRates {
         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));
-                }
+    private async readStored(): Promise<void> {
+        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));
             }
         }
+    }
+
+    private async fetchFresh(): Promise<boolean> {
         if (!this.allowFetch || (this.rate !== null && Date.now() - this.rate.fetchedAt < TTL_MS)) {
-            return;
+            return false;
         }
+        let changed = false;
         try {
             const response = await fetch(`${FRANKFURTER_URL}?from=USD&to=${TARGET_CURRENCY}`, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
             if (!response.ok) {
@@ -83,11 +92,13 @@ export class ExchangeRates {
                 throw new Error(`The answer carried no ${TARGET_CURRENCY} rate`);
             }
             this.rate = { ...parsed, fetchedAt: Date.now() };
+            changed = true;
             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));
         }
+        return changed;
     }
 }

package/src/usage/index-file.ts

@@ -19,6 +19,8 @@ export interface IndexedFile {
     tail: UsageRecord[];
     /* What the reader has to remember to carry on halfway through a Codex file. */
     codex: CodexParserState | null;
+    /* A versioned hash of all bytes before the offset; absent in indexes that cannot verify an append. */
+    head: string | null;
 }
 
 export type UsageIndex = Map<string, IndexedFile>;
@@ -39,6 +41,7 @@ interface FileRow {
     r: RecordRow[];
     t: RecordRow[];
     c: CodexParserState | null;
+    h?: string;
 }
 
 interface IndexFile {
@@ -88,7 +91,16 @@ export function encodeIndex(index: UsageIndex): string {
         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) };
+        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),
+            ...(file.head === null ? {} : { h: file.head })
+        };
     }
     const document: IndexFile = {
         version: INDEX_VERSION,
@@ -171,7 +183,16 @@ export function decodeIndex(text: string): UsageIndex {
         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 });
+            index.set(path, {
+                provider: file.p,
+                size: file.s,
+                mtimeMs: file.m,
+                offset: file.o,
+                records,
+                tail,
+                codex: file.c ?? null,
+                head: typeof file.h === 'string' ? file.h : null
+            });
         }
     }
     return index;

package/src/usage/index.ts

@@ -0,0 +1,10 @@
+// Public API: exports.test.ts snapshots this list, so a name added or dropped here is an API change.
+export { usageAccountsOf, usageRootsOf, limitAccountsOf, chatSessionAccounts } from './accounts.ts';
+export { UsageMonitor, type ProbeEnv, type LimitAccount, type LimitAccounts, type UsageMonitorOptions } from './limits/monitor.ts';
+export type { LimitsUpdate, ProviderReading } from './limits/normalize.ts';
+export type { ProbeResult } from './limits/probe.ts';
+export { LITELLM_URL } from './pricing.ts';
+export type { KnownProject } from './projects.ts';
+export { type UsageRootPath, usageRoots } from './roots.ts';
+export type { UsageScannerOptions } from './scanner.ts';
+export { UsageService, type UsageServiceOptions } from './usage-service.ts';

package/src/usage/limits/normalize.ts

@@ -1,4 +1,5 @@
 import type { UsageLimitsProvider, UsageProvider, UsageWindow } from '@adecore/agent-contracts';
+import { isRecord } from '@adecore/agent-contracts';
 
 /* Everything a full read of a provider says about its plan, ready to be published as it is. */
 export interface ProviderReading {
@@ -21,10 +22,6 @@ const FIVE_HOURS_MS = 5 * 60 * MINUTE_MS;
 const WEEK_MS = 7 * 24 * 60 * MINUTE_MS;
 const MONTH_MS = 30 * 24 * 60 * MINUTE_MS;
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
 function num(value: unknown): number | null {
     return typeof value === 'number' && Number.isFinite(value) ? value : null;
 }

package/src/usage/pricing.ts

@@ -164,8 +164,8 @@ export class PriceBook {
     private table: PriceTable;
     private source: UsagePricing['source'] = 'snapshot';
     private fetchedAt: number | null = null;
-    private loadedFromDisk = false;
-    private inFlight: Promise<void> | null = null;
+    private stored: Promise<void> | null = null;
+    private inFlight: Promise<boolean> | null = null;
 
     constructor(home: string, allowFetch = true) {
         this.home = home;
@@ -181,11 +181,19 @@ export class PriceBook {
         return lookupPrice(this.table, model);
     }
 
-    /* Refreshes at most one table at a time; a second caller waits for the first one's answer. */
-    ensure(): Promise<void> {
-        this.inFlight ??= this.refresh().finally(() => {
-            this.inFlight = null;
-        });
+    /* Reads the table an earlier run stored, once; asking LiteLLM is left to `ensure`. */
+    load(): Promise<void> {
+        this.stored ??= this.readStored();
+        return this.stored;
+    }
+
+    /* Refreshes at most one table at a time, a second caller waiting for the first one's answer; true when a newer table came in. */
+    ensure(): Promise<boolean> {
+        this.inFlight ??= this.load()
+            .then(() => this.fetchFresh())
+            .finally(() => {
+                this.inFlight = null;
+            });
         return this.inFlight;
     }
 
@@ -193,26 +201,27 @@ export class PriceBook {
         return join(this.home, 'usage', 'prices.json');
     }
 
-    private async refresh(): Promise<void> {
-        if (!this.loadedFromDisk) {
-            this.loadedFromDisk = true;
-            try {
-                const snapshot = JSON.parse(await readFile(this.file, 'utf8')) as Snapshot;
-                const table = parsePriceTable(snapshot?.document);
-                if (table.size > 0 && typeof snapshot.fetchedAt === 'number') {
-                    this.table = table;
-                    this.source = 'litellm';
-                    this.fetchedAt = snapshot.fetchedAt;
-                }
-            } catch (e) {
-                if (!isNotFound(e)) {
-                    console.warn('The stored price table would not read; using the bundled one:', errorText(e));
-                }
+    private async readStored(): Promise<void> {
+        try {
+            const snapshot = JSON.parse(await readFile(this.file, 'utf8')) as Snapshot;
+            const table = parsePriceTable(snapshot?.document);
+            if (table.size > 0 && typeof snapshot.fetchedAt === 'number') {
+                this.table = table;
+                this.source = 'litellm';
+                this.fetchedAt = snapshot.fetchedAt;
+            }
+        } catch (e) {
+            if (!isNotFound(e)) {
+                console.warn('The stored price table would not read; using the bundled one:', errorText(e));
             }
         }
+    }
+
+    private async fetchFresh(): Promise<boolean> {
         if (!this.allowFetch || (this.fetchedAt !== null && Date.now() - this.fetchedAt < TTL_MS)) {
-            return;
+            return false;
         }
+        let changed = false;
         try {
             const response = await fetch(LITELLM_URL, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
             if (!response.ok) {
@@ -226,11 +235,13 @@ export class PriceBook {
             this.table = table;
             this.source = 'litellm';
             this.fetchedAt = Date.now();
+            changed = true;
             await mkdir(join(this.home, 'usage'), { recursive: true, mode: 0o700 });
             await writeAtomic(this.file, JSON.stringify({ fetchedAt: this.fetchedAt, document } satisfies Snapshot));
         } catch (e) {
             // Whatever is loaded keeps pricing; a table that could not be refreshed is not a failure.
             console.warn('Could not refresh the price table:', errorText(e));
         }
+        return changed;
     }
 }

package/src/usage/scanner.ts

@@ -1,3 +1,4 @@
+import { createHash, type Hash } from 'node:crypto';
 import { mkdir, open, readFile, readdir, stat } from 'node:fs/promises';
 import { join } from 'node:path';
 import type { UsageRoot } from '@adecore/agent-contracts';
@@ -9,26 +10,55 @@ import { claudeMightCarryUsage, parseClaudeLine } from './readers/claude.ts';
 import { cloneCodexState, codexMightCarryUsage, createCodexState, parseCodexLine, type CodexParserState } from './readers/codex.ts';
 import { usageRoots, type UsageRootPath } from './roots.ts';
 
-/* What a file holds from `from` to its end, as it is at the read. */
-async function readFrom(path: string, from: number): Promise<string> {
+const HASH_CHUNK_BYTES = 65536;
+
+interface HashedRead {
+    /* Everything from `from` to the end of the file, as it is at the read. */
+    bytes: Buffer;
+    /* Over the bytes before `from`, left open so the caller can carry it on over `bytes`. */
+    hash: Hash;
+}
+
+/*
+ * Hashes the bytes before `from` and returns the rest, in one pass over one handle, so verifying
+ * what a transcript committed and parsing what it added never reads a byte twice.
+ */
+async function readHashed(path: string, from: number): Promise<HashedRead> {
     const handle = await open(path, 'r');
     try {
+        const hash = createHash('sha256');
+        const chunk = Buffer.alloc(Math.min(from, HASH_CHUNK_BYTES));
+        let offset = 0;
+        while (offset < from) {
+            const { bytesRead } = await handle.read(chunk, 0, Math.min(chunk.length, from - offset), offset);
+            if (bytesRead === 0) {
+                break;
+            }
+            hash.update(chunk.subarray(0, bytesRead));
+            offset += bytesRead;
+        }
         const { size } = await handle.stat();
-        const buffer = Buffer.alloc(Math.max(0, size - from));
+        const bytes = Buffer.alloc(Math.max(0, size - from));
         let filled = 0;
-        while (filled < buffer.length) {
-            const { bytesRead } = await handle.read(buffer, filled, buffer.length - filled, from + filled);
+        while (filled < bytes.length) {
+            const { bytesRead } = await handle.read(bytes, filled, bytes.length - filled, from + filled);
             if (bytesRead === 0) {
                 break;
             }
             filled += bytesRead;
         }
-        return buffer.subarray(0, filled).toString('utf8');
+        return { bytes: bytes.subarray(0, filled), hash };
     } finally {
         await handle.close();
     }
 }
 
+/* Covers every committed byte, since a transcript can be rewritten after an unchanged session header. */
+function headOf(hash: Hash): string {
+    // Older indexes hashed only the first 4 KB; they cannot establish that the rest stayed unchanged.
+    return `sha256:${hash.copy().digest('base64')}`;
+}
+
 export interface ScanReport {
     at: number;
     files: number;
@@ -137,7 +167,7 @@ function withAccount(records: UsageRecord[], accountOf: AccountOf): UsageRecord[
 }
 
 /*
- * Reads only what a transcript appended since the last scan, and starts a file over once it was
+ * Parses only what a transcript appended since the last scan, and starts a file over once it was
  * rewritten or cut. A deleted transcript keeps its totals, since its usage still happened.
  */
 export class UsageScanner {
@@ -241,10 +271,16 @@ export class UsageScanner {
         if (known !== undefined && known.provider === provider && known.size === info.size && known.mtimeMs === info.mtimeMs) {
             return false;
         }
-        const grown = known !== undefined && known.provider === provider && info.size > known.size;
+        const appended = known !== undefined && known.provider === provider && info.size > known.size && known.head?.startsWith('sha256:') === true;
+        let read = await readHashed(path, appended ? known.offset : 0);
+        // A file only counts as grown while it starts the way it did; one rewritten larger is read again from the start.
+        const grown = appended && headOf(read.hash) === known.head;
+        if (appended && !grown) {
+            read = await readHashed(path, 0);
+        }
         const from = grown ? known.offset : 0;
-        const text = await readFrom(path, from);
-        const parsed = parseChunk(text, provider, from, grown ? known.codex : null);
+        const parsed = parseChunk(read.bytes.toString('utf8'), provider, from, grown ? known.codex : null);
+        read.hash.update(read.bytes.subarray(0, parsed.offset - from));
         const before = grown ? known.records : [];
         const entry: IndexedFile = {
             provider,
@@ -254,7 +290,8 @@ export class UsageScanner {
             // Folding here keeps the streaming copies of one message out of the index entirely.
             records: foldByKey([...before, ...withAccount(parsed.records, accountOf)]),
             tail: withAccount(parsed.tail, accountOf),
-            codex: parsed.codex
+            codex: parsed.codex,
+            head: headOf(read.hash)
         };
         this.index.set(path, entry);
         this.dirty = true;

package/src/usage/usage-service.ts

@@ -135,14 +135,19 @@ export class UsageService {
     }
 
     private async runScan(): Promise<void> {
-        // The table and the rate are fetched beside the walk, so a slow answer never holds up the scan.
+        // A fetch never holds up the scan or the answer waiting on it; a table or rate it brings in is announced on its own.
+        void Promise.all([this.prices.ensure(), this.rates.ensure()]).then((fetched) => {
+            if (fetched.includes(true)) {
+                this.sinks.emit({ event: 'usage.changed', payload: { scannedAt: this.report.at } });
+            }
+        });
         const [report] = await Promise.all([
             this.scanner.scan().catch((e: unknown) => {
                 console.error('The usage scan failed:', errorText(e));
                 return null;
             }),
-            this.prices.ensure(),
-            this.rates.ensure()
+            this.prices.load(),
+            this.rates.load()
         ]);
         this.failed = report === null;
         if (report === null) {