@adecore/agents 0.31.2 → 0.31.3

package/dist/chat/acp-backend.d.ts

@@ -1,5 +1,5 @@
 import { type ModelSelection } from '@adecore/agent-contracts';
-import { type AcpModeMap, type AcpSessionInfo } from './acp-protocol.ts';
+import { type AcpModeMap, type AcpPermissionRequest, type AcpSessionInfo, type AcpTurnUsage } from './acp-protocol.ts';
 import type { ApprovalDecision, BackendHost, BackendLaunch, ChatBackend, TurnInput } from './backend.ts';
 export interface AcpClientInfo {
     name: string;
@@ -16,6 +16,13 @@ export interface AcpAgentSpec {
     client?: AcpClientInfo;
     model?(selection: ModelSelection): string | null;
     onSession?(info: AcpSessionInfo): void;
+    onUsage?(usage: AcpUsageReport): void;
+    autoAllow?(request: AcpPermissionRequest): boolean;
+}
+export interface AcpUsageReport extends AcpTurnUsage {
+    sessionId: string;
+    cwd: string;
+    model: string;
 }
 export declare class AcpBackend implements ChatBackend {
     private readonly launch;
@@ -29,6 +36,7 @@ export declare class AcpBackend implements ChatBackend {
     private replaying;
     private contextPending;
     private prompt;
+    private model;
     constructor(launch: BackendLaunch, host: BackendHost, spec: AcpAgentSpec);
     get running(): boolean;
     get pid(): number | null;
@@ -52,7 +60,9 @@ export declare class AcpBackend implements ChatBackend {
     private respond;
     private fail;
     private handleFrame;
+    private hostAllows;
     private handleExit;
+    private report;
     private emitAll;
     private emit;
 }

package/dist/chat/acp-backend.js

@@ -2,7 +2,7 @@ import { readFileSync } from 'node:fs';
 import { attachmentImageMime } from '@adecore/agent-contracts';
 import { errorText } from '../error-text.js';
 import { MODE_ORDER } from '../modes.js';
-import { ACP_AUTH_REQUIRED, ACP_PROTOCOL_VERSION, AcpProtocol, acpStopWords, autoAllows, parseInitialize, parseSessionInfo, resolveAcpMode, runtimeModeOf, sessionIdOf } from './acp-protocol.js';
+import { ACP_AUTH_REQUIRED, ACP_PROTOCOL_VERSION, AcpProtocol, acpStopWords, autoAllows, parseInitialize, parseSessionInfo, promptUsageOf, resolveAcpMode, runtimeModeOf, sessionIdOf } from './acp-protocol.js';
 import { attachmentNote } from './input.js';
 import { JsonRpcError, JsonRpcTransport } from './json-rpc-transport.js';
 export const DEFAULT_ACP_CLIENT = { name: 'agents', title: 'Agents', version: '0.1.0' };
@@ -30,6 +30,7 @@ export class AcpBackend {
     replaying = false;
     contextPending = null;
     prompt = null;
+    model = null;
     constructor(launch, host, spec) {
         this.launch = launch;
         this.host = host;
@@ -86,6 +87,7 @@ export class AcpBackend {
         const info = await this.openSession(transport, capabilities);
         const modeId = await this.applyMode(transport, info);
         const model = await this.applyModel(transport, info);
+        this.model = model;
         await this.applyThoughtLevel(transport, info);
         this.spec.onSession?.(info);
         this.emit({
@@ -265,6 +267,7 @@ export class AcpBackend {
             .then((result) => {
             if (this.transport === transport && this.prompt === turn) {
                 this.prompt = null;
+                this.report(result);
                 this.emitAll(this.protocol.finish(turn.cancelled ? { stopReason: 'cancelled' } : result, turn.promptId));
             }
         })
@@ -373,7 +376,7 @@ export class AcpBackend {
             }
             return;
         }
-        if (autoAllows(this.launch.runtimeMode, permission.kind)) {
+        if (autoAllows(this.launch.runtimeMode, permission.kind) || this.hostAllows(permission.request)) {
             this.emitAll(permission.events.filter((event) => event.type !== 'approval.requested'));
             const answer = this.protocol.answer(permission.requestId, 'allow');
             if (answer) {
@@ -383,6 +386,14 @@ export class AcpBackend {
         }
         this.emitAll(permission.events);
     }
+    hostAllows(request) {
+        try {
+            return this.spec.autoAllow?.(request) === true;
+        }
+        catch {
+            return false;
+        }
+    }
     handleExit(transport, exitCode, stderr) {
         if (this.transport !== transport) {
             return;
@@ -392,12 +403,23 @@ export class AcpBackend {
         this.protocol.cancelPermissions();
         this.emit({ type: 'exit', exitCode, ...(stderr === null ? {} : { stderr }) });
     }
+    /* A cancelled turn still spent what it reports. */
+    report(result) {
+        const usage = this.spec.onUsage === undefined ? null : promptUsageOf(result);
+        if (usage === null) {
+            return;
+        }
+        this.spec.onUsage?.({ ...usage, sessionId: this.sessionId, cwd: this.launch.cwd, model: this.model ?? this.launch.selection.model });
+    }
     emitAll(events) {
         for (const event of events) {
             this.emit(event);
         }
     }
     emit(event) {
+        if (event.type === 'model') {
+            this.model = event.model;
+        }
         this.host.onEvent(event);
     }
 }

package/dist/chat/acp-protocol.d.ts

@@ -9,6 +9,14 @@ declare const DiffSchema: z.ZodObject<{
     oldText: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     newText: z.ZodString;
 }, z.core.$loose>;
+export interface AcpTurnUsage {
+    input: number;
+    cacheRead: number;
+    cacheWrite: number;
+    output: number;
+    reasoning: number;
+}
+export declare function promptUsageOf(result: unknown): AcpTurnUsage | null;
 export interface AcpAgentInfo {
     name: string;
     title: string | null;
@@ -84,10 +92,16 @@ export declare function toolRow(tool: Pick<ToolState, 'title' | 'name' | 'kind'
     input: Record<string, unknown>;
     changes?: ChatFileChange[];
 };
+export interface AcpPermissionRequest {
+    kind: string | null;
+    title: string | null;
+    commands: string[];
+}
 export interface AcpPermission {
     requestId: string;
     rpcId: number | string;
     kind: string | null;
+    request: AcpPermissionRequest;
     events: BackendEvent[];
 }
 export interface AcpStopWords {

package/dist/chat/acp-protocol.js

@@ -40,6 +40,36 @@ const PermissionRequestSchema = z.looseObject({
 });
 const SessionNotificationSchema = z.looseObject({ sessionId: z.string(), update: z.looseObject({ sessionUpdate: z.string() }) });
 const PromptResponseSchema = z.looseObject({ stopReason: z.string() });
+const tokenCount = z.number().int().nonnegative();
+// Unstable in the protocol (`PromptResponse.usage`); only the three totals are required.
+const PromptUsageSchema = z.looseObject({
+    totalTokens: tokenCount,
+    inputTokens: tokenCount,
+    outputTokens: tokenCount,
+    thoughtTokens: tokenCount.nullish(),
+    cachedReadTokens: tokenCount.nullish(),
+    cachedWriteTokens: tokenCount.nullish()
+});
+/*
+ * The `usage` a `session/prompt` response carries, or null where the agent reports none. The protocol
+ * leaves open whether the input holds the cached part, so the total decides: when the kinds add up
+ * to more than it, the input counted the cache too and loses it here.
+ */
+export function promptUsageOf(result) {
+    const response = z.looseObject({ usage: PromptUsageSchema }).safeParse(result);
+    if (!response.success) {
+        return null;
+    }
+    const usage = response.data.usage;
+    const cacheRead = usage.cachedReadTokens ?? 0;
+    const cacheWrite = usage.cachedWriteTokens ?? 0;
+    const apart = usage.inputTokens + usage.outputTokens + cacheRead + cacheWrite <= usage.totalTokens;
+    const input = apart ? usage.inputTokens : Math.max(0, usage.inputTokens - cacheRead - cacheWrite);
+    if (input + cacheRead + cacheWrite + usage.outputTokens === 0) {
+        return null;
+    }
+    return { input, cacheRead, cacheWrite, output: usage.outputTokens, reasoning: usage.thoughtTokens ?? 0 };
+}
 const ModeStateSchema = z.looseObject({
     currentModeId: z.string(),
     availableModes: z.array(z.unknown())
@@ -416,7 +446,9 @@ export class AcpProtocol {
             description: tool.title === '' ? null : tool.title,
             canAllowAlways: options.some((option) => option.kind === 'allow_always')
         });
-        return { requestId, rpcId, kind: tool.kind, events };
+        const command = rawField(tool.rawInput, 'command', 'cmd');
+        const asked = { kind: tool.kind, title: tool.title === '' ? null : tool.title, commands: [...(command === null ? [] : [command]), ...tool.text] };
+        return { requestId, rpcId, kind: tool.kind, request: asked, events };
     }
     /*
      * The answer to a permission request: allow once, reject, or allow always only when the agent offered it.

package/dist/chat/index.d.ts

@@ -1,5 +1,5 @@
-export { type AcpAgentSpec, type AcpClientInfo, createAcpBackend } from './acp-backend.ts';
-export type { AcpAgentInfo, AcpModel, AcpModelState, AcpMode, AcpModeState, AcpSessionInfo, AcpModeMap } from './acp-protocol.ts';
+export { type AcpAgentSpec, type AcpClientInfo, type AcpUsageReport, createAcpBackend } from './acp-backend.ts';
+export type { AcpAgentInfo, AcpModel, AcpModelState, AcpMode, AcpModeState, AcpPermissionRequest, AcpSessionInfo, AcpModeMap, AcpTurnUsage } from './acp-protocol.ts';
 export { AttachmentStore } from './attachment-store.ts';
 export type { BackendLaunch, TurnInput, ApprovalDecision, BackendEvent, BackendHost, ChatBackend } from './backend.ts';
 export { runningInBackground, type BackgroundWork } from './background-work.ts';

package/dist/providers/acp-provider.d.ts

@@ -21,5 +21,6 @@ export interface AcpProviderSpec extends AcpAgentSpec {
     enabled?(): boolean;
     accountProbe?: boolean;
     adoptModels?: boolean;
+    usageLog?: string;
 }
 export declare function createAcpProvider(spec: AcpProviderSpec): ChatProvider;

package/dist/providers/acp-provider.js

@@ -1,5 +1,6 @@
 import { createAcpBackend } from '../chat/acp-backend.js';
 import { askAcpAccount } from './accounts/acp-account.js';
+import { writeAcpUsage } from './acp-usage-log.js';
 import { detectCli } from './detect.js';
 /*
  * What every ACP agent can do through this backend. A file change comes as the text before and after;
@@ -22,6 +23,8 @@ export const ACP_CAPABILITIES = {
     reportsThinking: true,
     slashCommands: true
 };
+/* Agents whose own usage files the scanner reads; a log of their turns would count every one twice. */
+const OWN_USAGE_FILES = new Set(['grok']);
 /* An agent's model id may reach a command line, so one that reads as a flag is left out. */
 function adoptableModels(info) {
     return (info.models?.models ?? []).filter((model) => model.id !== '' && !model.id.startsWith('-')).map((model) => ({ slug: model.id, name: model.name }));
@@ -34,6 +37,13 @@ export function createAcpProvider(spec) {
         }
         spec.onSession?.(info);
     };
+    const usageLog = spec.usageLog === undefined || OWN_USAGE_FILES.has(spec.kind) ? null : spec.usageLog;
+    const onUsage = usageLog === null
+        ? spec.onUsage
+        : (report) => {
+            writeAcpUsage(usageLog, report, Date.now());
+            spec.onUsage?.(report);
+        };
     return {
         kind: spec.kind,
         name: spec.name,
@@ -63,6 +73,6 @@ export function createAcpProvider(spec) {
                     onSession
                 })
             }),
-        createBackend: createAcpBackend({ ...spec, onSession })
+        createBackend: createAcpBackend({ ...spec, onSession, ...(onUsage === undefined ? {} : { onUsage }) })
     };
 }

package/dist/providers/acp-usage-log.d.ts

@@ -0,0 +1,2 @@
+import type { AcpUsageReport } from '../chat/acp-backend.ts';
+export declare function writeAcpUsage(folder: string, report: AcpUsageReport, at: number): void;

package/dist/providers/acp-usage-log.js

@@ -0,0 +1,21 @@
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { errorText } from '../error-text.js';
+import { hostUsageLine } from '../usage/readers/host-log.js';
+/*
+ * Appends one turn to the session's own file in the folder, so a scan that hashes what it already read
+ * of a file never rereads the log of every other session. Written at once, since it is one line per turn.
+ */
+export function writeAcpUsage(folder, report, at) {
+    const { sessionId, cwd, model, ...tokens } = report;
+    try {
+        mkdirSync(folder, { recursive: true, mode: 0o700 });
+        appendFileSync(join(folder, `${encodeURIComponent(sessionId === '' ? 'session' : sessionId)}.jsonl`), hostUsageLine({ at, model, session: sessionId, cwd, ...tokens }), {
+            mode: 0o600
+        });
+    }
+    catch (e) {
+        // A turn whose line could not be written is missing from the usage page; the chat itself goes on.
+        console.warn('Could not write the usage of an ACP turn:', errorText(e));
+    }
+}

package/dist/providers/index.d.ts

@@ -12,5 +12,6 @@ export { type CodexRules, codexRulesText, codexRulesPathIn, defaultCodexHome, in
 export { codexThreadOptions, codexServiceTier } from './codex.ts';
 export { type CliDetection, detectCli } from './detect.ts';
 export type { ChatProvider, ProviderHome } from './provider.ts';
+export { isOnlyCommands } from './shell-commands.ts';
 export { ProviderRegistry, type ProviderRegistryOptions } from './registry.ts';
 export { MODE_ORDER, narrowerMode, ceilingForOpening, modeFlag } from '../modes.ts';

package/dist/providers/index.js

@@ -10,5 +10,6 @@ export { createCodexProvider } from './codex-provider.js';
 export { codexRulesText, codexRulesPathIn, defaultCodexHome, installCodexRules } from './codex-rules.js';
 export { codexThreadOptions, codexServiceTier } from './codex.js';
 export { detectCli } from './detect.js';
+export { isOnlyCommands } from './shell-commands.js';
 export { ProviderRegistry } from './registry.js';
 export { MODE_ORDER, narrowerMode, ceilingForOpening, modeFlag } from '../modes.js';

package/dist/providers/shell-commands.d.ts

@@ -0,0 +1 @@
+export declare function isOnlyCommands(command: string, allowed: readonly string[]): boolean;

package/dist/providers/shell-commands.js

@@ -0,0 +1,119 @@
+// Unquoted, each of these makes the shell do more than run a word list: a pipe, a redirect, an expansion,
+// a subshell or group, a glob, a comment or a history or negation mark.
+const REFUSED = new Set(['|', '>', '<', '$', '`', '(', ')', '{', '}', '*', '?', '[', '~', '#', '!']);
+/*
+ * Whether a shell command line is only simple commands, joined by `&&`, `||`, `;` or newlines, each of
+ * which starts with one of `allowed`. Anything the tokenizer cannot prove simple answers false, so a
+ * true is safe to act on without a person: a pipe, a redirect, an expansion, a subshell, a background
+ * `&`, an unquoted glob or an unbalanced quote all refuse the whole line.
+ */
+export function isOnlyCommands(command, allowed) {
+    let word = '';
+    let inWord = false;
+    let words = [];
+    let commands = 0;
+    // A separator that still needs a command after it; a trailing `;` or newline needs none.
+    let dangling = false;
+    const endWord = () => {
+        if (inWord) {
+            words.push(word);
+        }
+        word = '';
+        inWord = false;
+    };
+    const endCommand = (separator) => {
+        endWord();
+        if (words.length === 0) {
+            // Blank lines are fine, and so is a newline after `&&` or `||`; an empty command before any other separator is not.
+            return separator === '\n';
+        }
+        if (!allowed.includes(words[0])) {
+            return false;
+        }
+        commands++;
+        words = [];
+        dangling = separator === '&&' || separator === '||';
+        return true;
+    };
+    for (let i = 0; i < command.length; i++) {
+        const char = command[i];
+        const next = command[i + 1];
+        if (char === ' ' || char === '\t') {
+            endWord();
+            continue;
+        }
+        if (char === '\n' || char === ';') {
+            if (!endCommand(char)) {
+                return false;
+            }
+            continue;
+        }
+        if ((char === '&' || char === '|') && next === char) {
+            if (!endCommand(char + next)) {
+                return false;
+            }
+            i++;
+            continue;
+        }
+        if (char === '&' || REFUSED.has(char)) {
+            return false;
+        }
+        if (char === '\\') {
+            if (next === undefined) {
+                return false;
+            }
+            i++;
+            if (next !== '\n') {
+                word += next;
+                inWord = true;
+            }
+            continue;
+        }
+        if (char === "'") {
+            const close = command.indexOf("'", i + 1);
+            if (close === -1) {
+                return false;
+            }
+            word += command.slice(i + 1, close);
+            inWord = true;
+            i = close;
+            continue;
+        }
+        if (char === '"') {
+            inWord = true;
+            let closed = false;
+            for (i++; i < command.length; i++) {
+                const quoted = command[i];
+                if (quoted === '"') {
+                    closed = true;
+                    break;
+                }
+                if (quoted === '$' || quoted === '`') {
+                    return false;
+                }
+                if (quoted === '\\') {
+                    const escaped = command[i + 1];
+                    if (escaped === undefined) {
+                        return false;
+                    }
+                    i++;
+                    if (escaped === '"' || escaped === '\\' || escaped === '$' || escaped === '`') {
+                        word += escaped;
+                    }
+                    else if (escaped !== '\n') {
+                        word += quoted + escaped;
+                    }
+                    continue;
+                }
+                word += quoted;
+            }
+            if (!closed) {
+                return false;
+            }
+            continue;
+        }
+        word += char;
+        inWord = true;
+    }
+    return endCommand('\n') && commands > 0 && !dangling;
+}

package/dist/testing/fake-acp.d.ts

@@ -6,6 +6,7 @@ export interface FakeAcpOptions {
     modes?: readonly string[];
     legacyModels?: boolean;
     closeSession?: boolean;
+    turnUsage?: Record<string, number>;
 }
 export declare function fakeAcpWith(options: FakeAcpOptions): FakeCli;
 export declare const fakeAcp: FakeCli;

package/dist/testing/fake-acp.js

@@ -33,7 +33,7 @@ export function fakeAcpWith(options) {
                 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;
         };
         const sessionState = () => {

package/dist/usage/aggregate.js

@@ -47,7 +47,7 @@ function foldBucket(buckets, slot, record, account, price, cost) {
     }
     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);
@@ -64,14 +64,15 @@ function foldModel(models, record, account, lookup, cost) {
             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, record, cost) {
     project.totals = addTotals(project.totals, record.totals);
@@ -111,7 +112,7 @@ export async function aggregate(records, payload, prices, known) {
             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/dist/usage/index-file.js

@@ -23,21 +23,27 @@ export function encodeIndex(index) {
     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
-    ];
+    const row = (record) => {
+        const counted = [
+            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,
@@ -62,10 +68,11 @@ export function encodeIndex(index) {
 }
 function isRow(row, version) {
     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'));
 }
 /*
  * A row that does not read back costs a cold parse of the file it belonged to, never a wrong total,
@@ -119,6 +126,7 @@ export function decodeIndex(text) {
                     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/dist/usage/limits/monitor.js

@@ -10,6 +10,8 @@ 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 = USAGE_PROVIDERS;
+/* The CLIs the probes know how to ask; any other provider has a plan only through the host's `plans`. */
+const PROBED = ['claude', 'codex'];
 function blank(kind) {
     return {
         kind,
@@ -106,6 +108,9 @@ export class UsageMonitor {
     listed() {
         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/dist/usage/readers/grok.d.ts

@@ -0,0 +1,3 @@
+import { type UsageRecord } from '../record.ts';
+export declare const GROK_USAGE_FILE = "usage.json";
+export declare function parseGrokUsage(text: string, path: string): UsageRecord[] | null;

package/dist/usage/readers/grok.js

@@ -0,0 +1,85 @@
+import { basename, dirname } from 'node:path';
+import { asObject, asString, int } from '../record.js';
+/* 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) {
+    try {
+        return decodeURIComponent(basename(dirname(dirname(path))));
+    }
+    catch {
+        return '';
+    }
+}
+function recordOf(counts, model, base, turn) {
+    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, path) {
+    let parsed;
+    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 = [];
+    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', timestampMs, sessionId, cwd };
+        const byModel = asObject(turn.modelUsage);
+        const models = byModel === null
+            ? [[asString(turn.primaryModelId), turn]]
+            : Object.entries(byModel).flatMap(([model, counts]) => {
+                const object = asObject(counts);
+                return object === null ? [] : [[model, object]];
+            });
+        for (const [model, counts] of models) {
+            const record = model === '' ? null : recordOf(counts, model, base, number);
+            if (record !== null) {
+                records.push(record);
+            }
+        }
+    }
+    return records;
+}

package/dist/usage/record.d.ts

@@ -7,6 +7,7 @@ export interface UsageRecord {
     cwd: string;
     account?: string;
     totals: UsageTotals;
+    costUsd?: number;
     dedupeKey: string | null;
 }
 export declare function int(value: unknown): number;