@adecore/agents 0.31.1 → 0.31.3

package/src/testing/fake-acp.ts

@@ -20,6 +20,10 @@ export interface FakeAcpOptions {
     modes?: readonly string[];
     // Reports models the way agents did before config options: `models` and `session/set_model`.
     legacyModels?: boolean;
+    // Advertises and answers `session/close`.
+    closeSession?: boolean;
+    // The `usage` every `session/prompt` response carries; absent reports none.
+    turnUsage?: Record<string, number>;
 }
 
 export function fakeAcpWith(options: FakeAcpOptions): FakeCli {
@@ -61,7 +65,7 @@ export function fakeAcpWith(options: FakeAcpOptions): FakeCli {
                 return;
             }
             update({ sessionUpdate: 'usage_update', used: 1200, size: 200000, cost: { amount: 0.01, currency: 'USD' } });
-            respond(prompt.rpcId, { stopReason });
+            respond(prompt.rpcId, { stopReason, ...(options.turnUsage === undefined ? {} : { usage: options.turnUsage }) });
             prompt = null;
         };
 
@@ -212,7 +216,7 @@ export function fakeAcpWith(options: FakeAcpOptions): FakeCli {
                         agentCapabilities: {
                             loadSession: options.loadSession ?? true,
                             promptCapabilities: { image: true, audio: false, embeddedContext: false },
-                            sessionCapabilities: options.resumeSession ? { resume: {} } : {}
+                            sessionCapabilities: { ...(options.resumeSession ? { resume: {} } : {}), ...(options.closeSession ? { close: {} } : {}) }
                         },
                         authMethods: options.authMethod === undefined ? [] : [{ id: options.authMethod, name: 'Sign in' }],
                         agentInfo: { name: 'fake-acp', title: 'Fake ACP', version: '0.0.1' }
@@ -252,6 +256,14 @@ export function fakeAcpWith(options: FakeAcpOptions): FakeCli {
                     respond(id, sessionState());
                     return;
                 }
+                case 'session/close':
+                    if (!options.closeSession) {
+                        refuse(id, -32601, 'Method not found: session/close');
+                        return;
+                    }
+                    sessionHistory.delete(String(params.sessionId));
+                    respond(id, {});
+                    return;
                 case 'session/set_mode':
                     mode = String(params.modeId);
                     respond(id, {});

package/src/usage/aggregate.ts

@@ -112,7 +112,7 @@ function foldBucket(
     }
     bucket.totals = addTotals(bucket.totals, record.totals);
     bucket.costUsd += cost;
-    bucket.priced ||= price !== null;
+    bucket.priced ||= price !== null || record.costUsd !== undefined;
     bucket.cacheSavingsUsd += price === null ? 0 : cacheSavingsOf(record.totals, price);
     if (record.sessionId !== '') {
         bucket.sessions.add(record.sessionId);
@@ -130,14 +130,15 @@ function foldModel(models: Map<string, ModelRow>, record: UsageRecord, account:
             totals: emptyTotals(),
             costUsd: 0,
             priced: false,
-            basis: lookup.basis,
-            pricedAs: lookup.pricedAs
+            // A cost the CLI reported is the bill itself, not a price looked up for the model.
+            basis: record.costUsd === undefined ? lookup.basis : 'exact',
+            pricedAs: record.costUsd === undefined ? lookup.pricedAs : null
         };
         models.set(key, model);
     }
     model.totals = addTotals(model.totals, record.totals);
     model.costUsd += cost;
-    model.priced ||= lookup.price !== null;
+    model.priced ||= lookup.price !== null || record.costUsd !== undefined;
 }
 
 function foldProject(project: ProjectAccumulator, record: UsageRecord, cost: number): void {
@@ -186,7 +187,7 @@ export async function aggregate(
             continue;
         }
         const lookup = prices.look(record.model);
-        const cost = lookup.price === null ? 0 : costOf(record.totals, lookup.price);
+        const cost = record.costUsd ?? (lookup.price === null ? 0 : costOf(record.totals, lookup.price));
         foldBucket(buckets, slot, record, account, lookup.price, cost);
         foldModel(models, record, account, lookup, cost);
         if (record.sessionId !== '') {

package/src/usage/index-file.ts

@@ -30,8 +30,9 @@ export type UsageIndex = Map<string, IndexedFile>;
  * 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.
+ * A cost the CLI reported itself rides last, only on a row that has one, so every other row keeps its length.
  */
-type RecordRow = [number, number, number, number, number, number, number, number, number, number, number, string | 0, number?];
+type RecordRow = [number, number, number, number, number, number, number, number, number, number, number, string | 0, number?, number?];
 
 interface FileRow {
     p: UsageProvider;
@@ -75,21 +76,27 @@ export function encodeIndex(index: UsageIndex): string {
     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
-    ];
+    const row = (record: UsageRecord): RecordRow => {
+        const counted: 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
+        ];
+        if (record.costUsd !== undefined) {
+            counted.push(record.costUsd);
+        }
+        return counted;
+    };
     for (const [path, file] of index) {
         files[path] = {
             p: file.provider,
@@ -116,10 +123,11 @@ export function encodeIndex(index: UsageIndex): string {
 function isRow(row: unknown, version: number): row is RecordRow {
     return (
         Array.isArray(row) &&
-        row.length === (version === ACCOUNTLESS_VERSION ? 12 : 13) &&
+        (version === ACCOUNTLESS_VERSION ? row.length === 12 : row.length === 13 || row.length === 14) &&
         row.slice(0, 11).every((value) => typeof value === 'number') &&
         (typeof row[11] === 'string' || row[11] === 0) &&
-        (version === ACCOUNTLESS_VERSION || typeof row[12] === 'number')
+        (version === ACCOUNTLESS_VERSION || typeof row[12] === 'number') &&
+        (row.length < 14 || typeof row[13] === 'number')
     );
 }
 
@@ -176,6 +184,7 @@ export function decodeIndex(text: string): UsageIndex {
                     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] },
+                    ...(row[13] === undefined ? {} : { costUsd: row[13] }),
                     dedupeKey: row[11] === 0 ? null : row[11]
                 });
             }

package/src/usage/limits/monitor.ts

@@ -15,6 +15,8 @@ const MAX_BACKOFF_MS = 60 * 60_000;
 const RECENT_USE_MS = 24 * 60 * 60_000;
 
 const PROVIDERS: readonly UsageProvider[] = USAGE_PROVIDERS;
+/* The CLIs the probes know how to ask; any other provider has a plan only through the host's `plans`. */
+const PROBED: readonly UsageProvider[] = ['claude', 'codex'];
 
 export type ProbeEnv = Record<string, string>;
 
@@ -167,6 +169,9 @@ export class UsageMonitor {
     private listed(): LimitAccount[] {
         const accounts = this.accounts?.list() ?? PROVIDERS.map((kind) => ({ id: kind, kind, label: kind, isDefault: true }));
         return PROVIDERS.flatMap((kind) => {
+            if (!PROBED.includes(kind) && this.plans[kind] === undefined) {
+                return [];
+            }
             const own = accounts.filter((account) => account.kind === kind);
             return [...own.filter((account) => account.isDefault), ...own.filter((account) => !account.isDefault)];
         });

package/src/usage/readers/grok.ts

@@ -0,0 +1,89 @@
+import { basename, dirname } from 'node:path';
+import { asObject, asString, int, type UsageRecord } from '../record.ts';
+
+/* The file Grok keeps the counts of a session in, beside its other files in the session's folder. */
+export const GROK_USAGE_FILE = 'usage.json';
+
+// `costUsdTicks` counts in ticks of 10^-10 USD, as Grok's own docs on `grok usage` say.
+const TICKS_PER_USD = 1e10;
+
+/* The folder above a session's is its working directory, URL-encoded into one name. */
+function cwdOf(path: string): string {
+    try {
+        return decodeURIComponent(basename(dirname(dirname(path))));
+    } catch {
+        return '';
+    }
+}
+
+function recordOf(counts: Record<string, unknown>, model: string, base: Omit<UsageRecord, 'model' | 'totals' | 'dedupeKey'>, turn: string): UsageRecord | null {
+    const cacheRead = int(counts.cachedReadTokens);
+    const cacheWrite = int(counts.cacheCreationTokens);
+    const totals = {
+        calls: int(counts.modelCalls),
+        // Grok's input holds both cache kinds: its total is input plus output.
+        input: Math.max(0, int(counts.inputTokens) - cacheRead - cacheWrite),
+        cacheRead,
+        cacheWrite,
+        cacheWrite1h: 0,
+        output: int(counts.outputTokens),
+        reasoning: int(counts.reasoningTokens)
+    };
+    if (totals.input + totals.cacheRead + totals.cacheWrite + totals.output === 0) {
+        return null;
+    }
+    const ticks = int(counts.costUsdTicks);
+    return {
+        ...base,
+        model,
+        totals,
+        // A missing or zero cost is one Grok did not report, which the price table then estimates.
+        ...(ticks === 0 ? {} : { costUsd: ticks / TICKS_PER_USD }),
+        dedupeKey: `grok\0${base.sessionId}\0${turn}\0${model}`
+    };
+}
+
+/*
+ * A session's `usage.json` under `$GROK_HOME/sessions/<cwd>/<session id>/`, which Grok rewrites whole
+ * at the end of every turn. One record per turn per model the turn called; null when the file does not
+ * read as one, which leaves what the scanner held of it.
+ */
+export function parseGrokUsage(text: string, path: string): UsageRecord[] | null {
+    let parsed: unknown;
+    try {
+        parsed = JSON.parse(text);
+    } catch {
+        return null;
+    }
+    const file = asObject(parsed);
+    if (file === null || !Array.isArray(file.turns)) {
+        return null;
+    }
+    const sessionId = asString(file.sessionId) || basename(dirname(path));
+    const cwd = cwdOf(path);
+    const records: UsageRecord[] = [];
+    for (const entry of file.turns) {
+        const turn = asObject(entry);
+        const timestampMs = turn === null ? Number.NaN : Date.parse(asString(turn.endedAt));
+        if (turn === null || Number.isNaN(timestampMs)) {
+            continue;
+        }
+        const number = typeof turn.turnNumber === 'number' ? String(turn.turnNumber) : asString(turn.endedAt);
+        const base = { provider: 'grok' as const, timestampMs, sessionId, cwd };
+        const byModel = asObject(turn.modelUsage);
+        const models: Array<[string, Record<string, unknown>]> =
+            byModel === null
+                ? [[asString(turn.primaryModelId), turn]]
+                : Object.entries(byModel).flatMap(([model, counts]) => {
+                      const object = asObject(counts);
+                      return object === null ? [] : [[model, object] as [string, Record<string, unknown>]];
+                  });
+        for (const [model, counts] of models) {
+            const record = model === '' ? null : recordOf(counts, model, base, number);
+            if (record !== null) {
+                records.push(record);
+            }
+        }
+    }
+    return records;
+}

package/src/usage/record.ts

@@ -11,6 +11,8 @@ export interface UsageRecord {
     /* The account the call was made under; absent is the default account of the CLI. */
     account?: string;
     totals: UsageTotals;
+    /* What the CLI itself says the call cost, which wins over a price from the table; absent where it says nothing. */
+    costUsd?: number;
     /* What identifies the message this line reports on, or null when nothing does. */
     dedupeKey: string | null;
 }
@@ -54,7 +56,11 @@ export function foldByKey(records: readonly UsageRecord[]): UsageRecord[] {
             folded.push({ ...record, totals: { ...record.totals } });
             continue;
         }
-        maxTotals(folded[seen]!.totals, record.totals);
+        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

@@ -10,14 +10,19 @@ export interface UsageRootPath {
 }
 
 /* Where in its config folder each CLI leaves its transcripts. A provider with no CLI has a log its host passes as a root of its own. */
-const TRANSCRIPTS: Partial<Record<UsageProvider, string>> & Record<'claude' | 'codex', string> = { claude: 'projects', codex: 'sessions' };
+const TRANSCRIPTS: Partial<Record<UsageProvider, string>> & Record<'claude' | 'codex' | 'grok', string> = {
+    claude: 'projects',
+    codex: 'sessions',
+    grok: 'sessions'
+};
 
 /* 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) }
+        { provider: 'codex', path: join(env.CODEX_HOME ?? join(home, '.codex'), TRANSCRIPTS.codex) },
+        { provider: 'grok', path: join(env.GROK_HOME ?? join(home, '.grok'), TRANSCRIPTS.grok) }
     ];
 }
 

package/src/usage/scanner.ts

@@ -7,6 +7,7 @@ import { isNotFound, writeAtomic } from '../fs.ts';
 import { decodeIndex, encodeIndex, type IndexedFile, type UsageIndex } from './index-file.ts';
 import { foldByKey, type UsageRecord } from './record.ts';
 import { claudeMightCarryUsage, parseClaudeLine } from './readers/claude.ts';
+import { GROK_USAGE_FILE, parseGrokUsage } from './readers/grok.ts';
 import { hostLogMightCarryUsage, parseHostUsageLine } from './readers/host-log.ts';
 import { cloneCodexState, codexMightCarryUsage, createCodexState, parseCodexLine, type CodexParserState } from './readers/codex.ts';
 import { usageRoots, type UsageRootPath } from './roots.ts';
@@ -75,7 +76,16 @@ interface ParsedFile {
     codex: CodexParserState | null;
 }
 
-async function listJsonl(dir: string, out: string[] = []): Promise<string[]> {
+/* A log of lines for every provider but Grok, which keeps one JSON file per session that it rewrites whole. */
+function readsWhole(provider: UsageProvider): boolean {
+    return provider === 'grok';
+}
+
+function isUsageFile(provider: UsageProvider, name: string): boolean {
+    return readsWhole(provider) ? name === GROK_USAGE_FILE : name.endsWith('.jsonl');
+}
+
+async function listUsageFiles(dir: string, provider: UsageProvider, out: string[] = []): Promise<string[]> {
     let entries;
     try {
         entries = await readdir(dir, { withFileTypes: true });
@@ -86,8 +96,8 @@ async function listJsonl(dir: string, out: string[] = []): Promise<string[]> {
     for (const entry of entries) {
         const path = join(dir, entry.name);
         if (entry.isDirectory()) {
-            await listJsonl(path, out);
-        } else if (entry.isFile() && entry.name.endsWith('.jsonl')) {
+            await listUsageFiles(path, provider, out);
+        } else if (entry.isFile() && isUsageFile(provider, entry.name)) {
             out.push(path);
         }
     }
@@ -128,7 +138,7 @@ function parseChunk(text: string, provider: UsageProvider, from: number, state:
                 }
                 continue;
             }
-            // Claude Code and Codex write transcripts of their own; every other provider is a log its host keeps.
+            // Claude Code and Codex write transcripts of their own, Grok a file read whole; every other provider is a log its host keeps.
             if (hostLogMightCarryUsage(line)) {
                 const record = parseHostUsageLine(line, provider);
                 if (record !== null) {
@@ -245,7 +255,7 @@ export class UsageScanner {
             }
             let failure: string | null = null;
             const accountOf = accountResolver(root, sessionAccounts);
-            for (const path of await listJsonl(root.path)) {
+            for (const path of await listUsageFiles(root.path, root.provider)) {
                 files += 1;
                 try {
                     if (await this.readFileInto(path, root.provider, accountOf)) {
@@ -282,6 +292,9 @@ export class UsageScanner {
         if (known !== undefined && known.provider === provider && known.size === info.size && known.mtimeMs === info.mtimeMs) {
             return false;
         }
+        if (readsWhole(provider)) {
+            return this.readWholeInto(path, provider, accountOf, info);
+        }
         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.
@@ -308,4 +321,28 @@ export class UsageScanner {
         this.dirty = true;
         return true;
     }
+
+    /*
+     * A file rewritten as a whole replaces what the index held of it, so a turn it still lists is never
+     * counted twice. One that does not parse, such as one caught halfway through a write, keeps the
+     * records it had and is read again on the next scan.
+     */
+    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,
+            mtimeMs: info.mtimeMs,
+            offset: info.size,
+            records: foldByKey(withAccount(records, accountOf)),
+            tail: [],
+            codex: null,
+            head: null
+        });
+        this.dirty = true;
+        return true;
+    }
 }