@adecore/agents 0.39.0 → 0.40.1

package/src/usage/readers/host-log.ts

@@ -1,5 +1,5 @@
 import type { UsageProvider } from '@adecore/agent-contracts';
-import { asObject, asString, int, type UsageRecord } from '../record.ts';
+import { asString, countsTokens, int, parseObject, type UsageRecord } from '../record.ts';
 
 /*
  * One call to an API a host makes itself, a line of the usage log it keeps. Such an API has no CLI and so
@@ -32,21 +32,19 @@ export function hostLogMightCarryUsage(line: string): boolean {
 
 /* The provider is the root's, so one reader serves every API a host logs. */
 export function parseHostUsageLine(line: string, provider: UsageProvider): UsageRecord | null {
-    let parsed: unknown;
-    try {
-        parsed = JSON.parse(line);
-    } catch {
-        return null;
-    }
-    const entry = asObject(parsed);
+    const entry = parseObject(line);
+
     if (entry === null) {
         return null;
     }
+
     const model = asString(entry.model);
     const timestampMs = typeof entry.at === 'number' && Number.isFinite(entry.at) ? entry.at : Number.NaN;
+
     if (model === '' || Number.isNaN(timestampMs)) {
         return null;
     }
+
     const totals = {
         calls: 1,
         input: int(entry.input),
@@ -56,9 +54,11 @@ export function parseHostUsageLine(line: string, provider: UsageProvider): Usage
         output: int(entry.output),
         reasoning: int(entry.reasoning)
     };
-    if (totals.input + totals.cacheRead + totals.cacheWrite + totals.output === 0) {
+
+    if (!countsTokens(totals)) {
         return null;
     }
+
     return {
         provider,
         timestampMs,

package/src/usage/record.ts

@@ -28,6 +28,20 @@ export function asObject(value: unknown): Record<string, unknown> | null {
     return typeof value === 'object' && value !== null ? (value as Record<string, unknown>) : null;
 }
 
+/* A line or file of a transcript as a JSON object, or null for anything else. */
+export function parseObject(text: string): Record<string, unknown> | null {
+    try {
+        return asObject(JSON.parse(text));
+    } catch {
+        return null;
+    }
+}
+
+/* Whether a call moved any tokens at all; one that moved none is not a call worth a record. */
+export function countsTokens(totals: UsageTotals): boolean {
+    return totals.input + totals.cacheRead + totals.cacheWrite + totals.output !== 0;
+}
+
 export function asString(value: unknown): string {
     return typeof value === 'string' ? value : '';
 }
@@ -46,22 +60,30 @@ function maxTotals(into: UsageTotals, from: UsageTotals): void {
 export function foldByKey(records: readonly UsageRecord[]): UsageRecord[] {
     const folded: UsageRecord[] = [];
     const at = new Map<string, number>();
+
     for (const record of records) {
         if (record.dedupeKey === null) {
             folded.push(record);
+
             continue;
         }
+
         const seen = at.get(record.dedupeKey);
+
         if (seen === undefined) {
             at.set(record.dedupeKey, folded.length);
             folded.push({ ...record, totals: { ...record.totals } });
+
             continue;
         }
+
         const into = folded[seen]!;
         maxTotals(into.totals, record.totals);
+
         if (record.costUsd !== undefined) {
             into.costUsd = Math.max(into.costUsd ?? 0, record.costUsd);
         }
     }
+
     return folded;
 }

package/src/usage/roots.ts

@@ -19,6 +19,7 @@ const TRANSCRIPTS: Partial<Record<UsageProvider, string>> & Record<'claude' | 'c
 /* The transcripts of the default accounts, found through the variables the CLIs themselves read. */
 export function usageRoots(env: Record<string, string | undefined> = process.env): UsageRootPath[] {
     const home = homeFolder(env);
+
     return [
         { provider: 'claude', path: join(env.CLAUDE_CONFIG_DIR ?? join(home, '.claude'), TRANSCRIPTS.claude) },
         { provider: 'codex', path: join(env.CODEX_HOME ?? join(home, '.codex'), TRANSCRIPTS.codex) },
@@ -29,19 +30,24 @@ export function usageRoots(env: Record<string, string | undefined> = process.env
 /* The transcripts of every account, once per folder: Codex accounts over one home share its sessions. */
 export function accountRoots(folders: ReadonlyArray<{ id: string; kind: UsageProvider; folder: string }>): UsageRootPath[] {
     const roots = new Map<string, UsageRootPath & { accounts: string[] }>();
+
     for (const { id, kind, folder } of folders) {
         const transcripts = TRANSCRIPTS[kind];
+
         if (transcripts === undefined) {
             continue;
         }
+
         const path = join(folder, transcripts);
         const key = `${kind}\0${path}`;
         const root = roots.get(key);
+
         if (root === undefined) {
             roots.set(key, { provider: kind, path, accounts: [id] });
         } else {
             root.accounts.push(id);
         }
     }
+
     return [...roots.values()];
 }

package/src/usage/scanner.ts

@@ -23,17 +23,22 @@ const NEWLINE = 0x0a;
 /* Hashes the first `length` bytes of a file into `hash`, a chunk at a time. */
 async function hashPrefix(path: string, length: number, hash: Hash): Promise<Hash> {
     const handle = await open(path, 'r');
+
     try {
         const chunk = Buffer.alloc(Math.min(length, HASH_CHUNK_BYTES));
         let offset = 0;
+
         while (offset < length) {
             const { bytesRead } = await handle.read(chunk, 0, Math.min(chunk.length, length - offset), offset);
+
             if (bytesRead === 0) {
                 break;
             }
+
             hash.update(chunk.subarray(0, bytesRead));
             offset += bytesRead;
         }
+
         return hash;
     } finally {
         await handle.close();
@@ -54,10 +59,12 @@ export interface LineRead {
 export async function forEachLine(chunks: AsyncIterable<Uint8Array>, hash: Hash, onLine: (line: string) => void): Promise<LineRead> {
     let consumed = 0;
     let pending: Buffer[] = [];
+
     for await (const piece of chunks) {
         const chunk = Buffer.from(piece.buffer, piece.byteOffset, piece.byteLength);
         let start = 0;
         let newline = chunk.indexOf(NEWLINE, start);
+
         while (newline !== -1) {
             const end = newline + 1;
             const line = pending.length === 0 ? chunk.subarray(start, end) : Buffer.concat([...pending, chunk.subarray(start, end)]);
@@ -68,11 +75,13 @@ export async function forEachLine(chunks: AsyncIterable<Uint8Array>, hash: Hash,
             start = end;
             newline = chunk.indexOf(NEWLINE, start);
         }
+
         if (start < chunk.length) {
             // A copy: the stream may hand the same memory out again for its next chunk.
             pending.push(Buffer.from(chunk.subarray(start)));
         }
     }
+
     return { consumed, rest: Buffer.concat(pending).toString('utf8') };
 }
 
@@ -108,35 +117,43 @@ function isUsageFile(provider: UsageProvider, name: string): boolean {
 
 async function listUsageFiles(dir: string, provider: UsageProvider, out: string[] = []): Promise<string[]> {
     let entries;
+
     try {
         entries = await readdir(dir, { withFileTypes: true });
     } catch {
         // A directory that cannot be read is one the scan walks past; the root itself reports status.
         return out;
     }
+
     for (const entry of entries) {
         const path = join(dir, entry.name);
+
         if (entry.isDirectory()) {
             await listUsageFiles(path, provider, out);
         } else if (entry.isFile() && isUsageFile(provider, entry.name)) {
             out.push(path);
         }
     }
+
     return out;
 }
 
 /* The bytes of a file from `from` to its end, a chunk at a time. */
 async function* fileChunks(path: string, from: number): AsyncGenerator<Uint8Array> {
     const handle = await open(path, 'r');
+
     try {
         let position = from;
+
         for (;;) {
             // A buffer per chunk: a decompressor may still hold the one before.
             const chunk = Buffer.alloc(READ_CHUNK_BYTES);
             const { bytesRead } = await handle.read(chunk, 0, chunk.length, position);
+
             if (bytesRead === 0) {
                 return;
             }
+
             position += bytesRead;
             yield chunk.subarray(0, bytesRead);
         }
@@ -150,24 +167,30 @@ function readBytes(path: string, from: number, compressed: boolean): AsyncIterab
     if (!compressed) {
         return fileChunks(path, from);
     }
+
     const source = Readable.from(fileChunks(path, from));
     const decompressed = createZstdDecompress();
     source.on('error', (error) => decompressed.destroy(error));
+
     return source.pipe(decompressed);
 }
 
 /* The usage record of one transcript line, when it carries one. */
 function parseLine(raw: string, provider: UsageProvider, codex: CodexParserState | null): UsageRecord | null {
     const line = raw.endsWith('\r') ? raw.slice(0, -1) : raw;
+
     if (line === '') {
         return null;
     }
+
     if (provider === 'claude') {
         return claudeMightCarryUsage(line) ? parseClaudeLine(line) : null;
     }
+
     if (provider === 'codex') {
         return codex !== null && codexMightCarryUsage(line) ? parseCodexLine(line, codex) : null;
     }
+
     // Claude Code and Codex write transcripts of their own, Grok a file read whole; every other provider is a log its host keeps.
     return hostLogMightCarryUsage(line) ? parseHostUsageLine(line, provider) : null;
 }
@@ -186,14 +209,18 @@ async function parseLines(
 ): Promise<ParsedFile> {
     const codex = provider === 'codex' ? (state ?? createCodexState()) : null;
     const records: UsageRecord[] = [];
+
     const read = await forEachLine(chunks, hash, (line) => {
         const record = parseLine(line, provider, codex);
+
         if (record !== null) {
             records.push(record);
         }
     });
+
     const committed = codex === null ? null : cloneCodexState(codex);
     const tail = parseLine(read.rest, provider, codex);
+
     return { records, tail: tail === null ? [] : [tail], offset: from + read.consumed, codex: committed };
 }
 
@@ -211,14 +238,20 @@ type AccountOf = (record: UsageRecord) => string | undefined;
  */
 export function accountResolver(root: UsageRootPath, sessionAccounts: () => ReadonlyMap<string, string>): AccountOf {
     const accounts = root.accounts ?? [root.provider];
+
     const stored = (id: string): string | undefined => (id === root.provider ? undefined : id);
+
     if (accounts.length === 1) {
         const only = stored(accounts[0]!);
+
         return () => only;
     }
+
     const fallback = accounts.includes(root.provider) ? root.provider : accounts[0]!;
+
     return (record) => {
         const ran = sessionAccounts().get(`${root.provider}\0${record.sessionId}`);
+
         return stored(ran !== undefined && accounts.includes(ran) ? ran : fallback);
     };
 }
@@ -226,6 +259,7 @@ export function accountResolver(root: UsageRootPath, sessionAccounts: () => Read
 function withAccount(records: UsageRecord[], accountOf: AccountOf): UsageRecord[] {
     return records.map((record) => {
         const account = accountOf(record);
+
         return account === undefined ? record : { ...record, account };
     });
 }
@@ -257,7 +291,9 @@ export class UsageScanner {
         if (this.loaded) {
             return;
         }
+
         this.loaded = true;
+
         try {
             this.index = decodeIndex(await readFile(this.file, 'utf8'));
         } catch (e) {
@@ -274,37 +310,47 @@ export class UsageScanner {
         let files = 0;
         let changedFiles = 0;
         let sessions: ReadonlyMap<string, string> | null = null;
+
         const sessionAccounts = (): ReadonlyMap<string, string> => {
             sessions ??= this.sessionAccounts();
+
             return sessions;
         };
 
         for (const root of this.roots()) {
             try {
                 const info = await stat(root.path);
+
                 if (!info.isDirectory()) {
                     roots.push({ provider: root.provider, path: root.path, status: 'missing', message: null });
+
                     continue;
                 }
             } catch (e) {
                 const missing = isNotFound(e);
+
                 roots.push({
                     provider: root.provider,
                     path: root.path,
                     status: missing ? 'missing' : 'failed',
                     message: missing ? null : errorText(e)
                 });
+
                 continue;
             }
+
             let failure: string | null = null;
             const accountOf = accountResolver(root, sessionAccounts);
             const paths = await listUsageFiles(root.path, root.provider);
             const plain = new Set(paths);
+
             for (const path of paths) {
                 if (root.provider === 'codex' && path.endsWith('.jsonl.zst') && plain.has(path.slice(0, -4))) {
                     continue;
                 }
+
                 files += 1;
+
                 try {
                     if (await this.readFileInto(path, root.provider, accountOf)) {
                         changedFiles += 1;
@@ -314,6 +360,7 @@ export class UsageScanner {
                     failure ??= errorText(e);
                 }
             }
+
             roots.push({ provider: root.provider, path: root.path, status: failure === null ? 'ok' : 'failed', message: failure });
         }
 
@@ -322,15 +369,18 @@ export class UsageScanner {
             await mkdir(join(this.home, 'usage'), { recursive: true, mode: 0o700 });
             await writeAtomic(this.file, encodeIndex(this.index));
         }
+
         return { at: Date.now(), files, changedFiles, durationMs: Date.now() - started, roots };
     }
 
     /* Every record the index holds, with the copies one message left in several transcripts folded. */
     records(): UsageRecord[] {
         const all: UsageRecord[] = [];
+
         for (const file of this.index.values()) {
             all.push(...file.records, ...file.tail);
         }
+
         return foldByKey(all);
     }
 
@@ -340,6 +390,7 @@ export class UsageScanner {
         const key = compressed ? path.slice(0, -4) : path;
         const known = this.index.get(key);
         const currentParser = provider !== 'codex' || known?.parserVersion === CODEX_PARSER_VERSION;
+
         if (
             currentParser &&
             known !== undefined &&
@@ -350,9 +401,11 @@ export class UsageScanner {
         ) {
             return false;
         }
+
         if (readsWhole(provider)) {
             return this.readWholeInto(path, provider, accountOf, info);
         }
+
         const appended =
             !compressed &&
             currentParser &&
@@ -361,6 +414,7 @@ export class UsageScanner {
             known.provider === provider &&
             info.size > known.size &&
             known.head?.startsWith('sha256:') === true;
+
         // A file only counts as grown while it starts the way it did; one rewritten larger is read again from the start.
         const prefix = appended ? await hashPrefix(path, known.offset, createHash('sha256')) : null;
         const grown = prefix !== null && known !== undefined && headOf(prefix) === known.head ? known : null;
@@ -368,6 +422,7 @@ export class UsageScanner {
         const from = grown?.offset ?? 0;
         const parsed = await parseLines(readBytes(path, from, compressed), hash, provider, from, grown?.codex ?? null);
         const before = grown?.records ?? [];
+
         const entry: IndexedFile = {
             provider,
             size: info.size,
@@ -380,8 +435,10 @@ export class UsageScanner {
             head: headOf(hash),
             ...(provider === 'codex' ? { parserVersion: CODEX_PARSER_VERSION, compressed } : {})
         };
+
         this.index.set(key, entry);
         this.dirty = true;
+
         return true;
     }
 
@@ -392,9 +449,11 @@ export class UsageScanner {
      */
     private async readWholeInto(path: string, provider: UsageProvider, accountOf: AccountOf, info: { size: number; mtimeMs: number }): Promise<boolean> {
         const records = parseGrokUsage(await readFile(path, 'utf8'), path);
+
         if (records === null) {
             return false;
         }
+
         this.index.set(path, {
             provider,
             size: info.size,
@@ -405,7 +464,9 @@ export class UsageScanner {
             codex: null,
             head: null
         });
+
         this.dirty = true;
+
         return true;
     }
 }

package/src/usage/usage-service.ts

@@ -30,13 +30,16 @@ export interface UsageServiceOptions {
 function withRecordAccounts(accounts: UsageAccount[], records: readonly UsageRecord[]): UsageAccount[] {
     const listed = new Set(accounts.map((account) => account.id));
     const gone: UsageAccount[] = [];
+
     for (const record of records) {
         const id = accountOfRecord(record);
+
         if (!listed.has(id)) {
             listed.add(id);
             gone.push({ id, kind: record.provider, label: id });
         }
     }
+
     return [...accounts, ...gone];
 }
 
@@ -76,6 +79,7 @@ export class UsageService {
     /* The page is open here: keep the numbers moving until it closes or the socket does. */
     follow(clientId: string): void {
         this.followers.add(clientId);
+
         this.timer ??= setInterval(() => {
             void this.rescan();
         }, SCAN_TTL_MS);
@@ -83,6 +87,7 @@ export class UsageService {
 
     unfollow(clientId: string): void {
         this.followers.delete(clientId);
+
         if (this.followers.size === 0 && this.timer !== null) {
             clearInterval(this.timer);
             this.timer = null;
@@ -93,8 +98,10 @@ export class UsageService {
         if (Date.now() - this.report.at > SCAN_TTL_MS) {
             await this.rescan();
         }
+
         const records = this.scanner.records();
         const { buckets, models, projects, sessions } = await aggregate(records, payload, this.prices, await this.knownProjects());
+
         return {
             from: payload.from,
             to: payload.to,
@@ -131,6 +138,7 @@ export class UsageService {
         this.inFlight ??= this.runScan().finally(() => {
             this.inFlight = null;
         });
+
         return this.inFlight;
     }
 
@@ -141,20 +149,26 @@ export class UsageService {
                 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.load(),
             this.rates.load()
         ]);
+
         this.failed = report === null;
+
         if (report === null) {
             // The last good numbers stay on screen; only the moment of the scan is not moved on.
             return;
         }
+
         this.report = report;
+
         if (report.changedFiles > 0) {
             this.sinks.emit({ event: 'usage.changed', payload: { scannedAt: report.at } });
         }

package/src/watch-seam.ts

@@ -29,6 +29,7 @@ export const SYSTEM_WATCH: WatchSeams = {
     watch: (path, options, listener) => watch(path, options, listener),
     schedule: (callback, ms) => {
         const timer = setTimeout(callback, ms);
+
         return () => clearTimeout(timer);
     }
 };
@@ -46,11 +47,14 @@ export interface Settled {
  */
 export function settled(seams: WatchSeams, ms: number, run: () => unknown): Settled {
     let cancel: (() => void) | null = null;
+
     return {
         nudge: () => {
             cancel?.();
+
             cancel = seams.schedule(() => {
                 cancel = null;
+
                 return run();
             }, ms);
         },
@@ -92,11 +96,14 @@ export class PerClientWatches<TState> {
     remove(clientId: string, key: string): void {
         const watches = this.byClient.get(clientId);
         const state = watches?.get(key);
+
         if (!watches || state === undefined) {
             return;
         }
+
         this.stop(state);
         watches.delete(key);
+
         if (watches.size === 0) {
             this.byClient.delete(clientId);
         }
@@ -106,6 +113,7 @@ export class PerClientWatches<TState> {
         for (const state of this.byClient.get(clientId)?.values() ?? []) {
             this.stop(state);
         }
+
         this.byClient.delete(clientId);
     }
 }

package/src/windows-command.ts

@@ -25,14 +25,19 @@ const CMD_SPECIAL = /([()\][%!^"`<>&|;, *?])/g;
  */
 export function spawnTarget(command: string, args: readonly string[], options: SpawnTargetOptions = {}): SpawnTarget {
     const { env = process.env, platform = process.platform, isFile = existingFile } = options;
+
     if (platform !== 'win32') {
         return { file: command, args: [...args] };
     }
+
     const resolved = findOnPath(command, env, isFile) ?? command;
+
     if (!/\.(cmd|bat)$/i.test(resolved)) {
         return { file: resolved, args: [...args] };
     }
+
     const line = [escapeForCmd(resolved), ...args.map((arg) => escapeForCmd(escapeForCmd(quoteArgument(arg))))].join(' ');
+
     return { file: variable(env, 'ComSpec') ?? 'cmd.exe', args: ['/d', '/s', '/c', `"${line}"`], windowsVerbatimArguments: true };
 }
 
@@ -41,27 +46,33 @@ function findOnPath(command: string, env: Record<string, string | undefined>, is
         .split(';')
         .map((extension) => extension.trim().toLowerCase())
         .filter((extension) => extension !== '');
+
     const hasExtension = extensions.includes(win32.extname(command).toLowerCase());
+
     const folders = /[\\/]/.test(command)
         ? ['']
         : (variable(env, 'PATH') ?? '')
               .split(';')
               .map((folder) => folder.trim().replace(/^"(.*)"$/, '$1'))
               .filter((folder) => folder !== '');
+
     for (const folder of folders) {
         const base = folder === '' ? command : win32.join(folder, command);
         const candidates = hasExtension ? [base] : extensions.map((extension) => `${base}${extension}`);
         const found = candidates.find((candidate) => isFile(candidate));
+
         if (found !== undefined) {
             return found;
         }
     }
+
     return null;
 }
 
 // Windows treats variable names case-insensitively, and an environment often carries `Path`.
 function variable(env: Record<string, string | undefined>, name: string): string | undefined {
     const key = Object.keys(env).find((candidate) => candidate.toUpperCase() === name.toUpperCase());
+
     return key === undefined ? undefined : env[key];
 }
 
@@ -70,6 +81,7 @@ function quoteArgument(arg: string): string {
     if (/[\r\n]/.test(arg)) {
         throw new Error('An argument to a batch file cannot hold a line break');
     }
+
     return `"${arg.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\*)$/, '$1$1')}"`;
 }