@adecore/agents 0.0.1 → 0.17.0-beta.2

package/src/usage/pricing.ts

@@ -0,0 +1,236 @@
+import { mkdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import type { UsagePriceBasis, UsagePricing, UsageTotals } from '@adecore/agent-contracts';
+import { isNotFound, writeAtomic } from '../fs.ts';
+import { errorText } from '../error-text.ts';
+import bundled from './prices-snapshot.json' with { type: 'json' };
+
+export const LITELLM_URL = 'https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json';
+
+/* A table a day old still prices everything anyone ran today, and nobody has to be online for it. */
+const TTL_MS = 24 * 60 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 10_000;
+
+/* What Anthropic charges over the base input rate when the table itself says nothing. */
+const CACHE_READ_SHARE = 0.1;
+const CACHE_WRITE_SHARE = 1.25;
+const CACHE_WRITE_1H_SHARE = 2;
+
+export interface ModelPrice {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    cacheWrite1h: number;
+}
+
+export type PriceTable = Map<string, ModelPrice>;
+
+export interface PriceLookup {
+    price: ModelPrice | null;
+    basis: UsagePriceBasis;
+    /* The key the price was found under, when that is not the model's own name. */
+    pricedAs: string | null;
+}
+
+/* A bare family name prices nothing: `opus` and `sonnet` are several models with several prices. */
+const AMBIGUOUS = new Set(['opus', 'sonnet', 'haiku', 'fable', 'gpt', 'codex', 'synthetic', '<synthetic>']);
+
+const PROVIDERS = new Set(['anthropic', 'openai']);
+const MODES = new Set(['chat', 'responses']);
+
+interface LiteLlmEntry {
+    input_cost_per_token?: unknown;
+    output_cost_per_token?: unknown;
+    cache_read_input_token_cost?: unknown;
+    cache_creation_input_token_cost?: unknown;
+    litellm_provider?: unknown;
+    mode?: unknown;
+}
+
+function rate(value: unknown): number | null {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : null;
+}
+
+/*
+ * The LiteLLM table as this app needs it: the Anthropic and OpenAI chat and responses models, keyed
+ * by the lowercase name and by the bare name behind a provider prefix. A model priced on one side
+ * only is dropped, because half a price reads as a cheap model rather than an unknown one.
+ */
+export function parsePriceTable(document: unknown): PriceTable {
+    const table: PriceTable = new Map();
+    if (typeof document !== 'object' || document === null) {
+        return table;
+    }
+    for (const [name, value] of Object.entries(document as Record<string, LiteLlmEntry>)) {
+        if (typeof value !== 'object' || value === null) {
+            continue;
+        }
+        if (typeof value.litellm_provider !== 'string' || !PROVIDERS.has(value.litellm_provider)) {
+            continue;
+        }
+        if (typeof value.mode !== 'string' || !MODES.has(value.mode)) {
+            continue;
+        }
+        const input = rate(value.input_cost_per_token);
+        const output = rate(value.output_cost_per_token);
+        if (input === null || output === null) {
+            continue;
+        }
+        const price: ModelPrice = {
+            input,
+            output,
+            cacheRead: rate(value.cache_read_input_token_cost) ?? input * CACHE_READ_SHARE,
+            cacheWrite: rate(value.cache_creation_input_token_cost) ?? input * CACHE_WRITE_SHARE,
+            cacheWrite1h: input * CACHE_WRITE_1H_SHARE
+        };
+        const key = name.trim().toLowerCase();
+        table.set(key, price);
+        const bare = key.slice(key.lastIndexOf('/') + 1);
+        if (bare !== key && !table.has(bare)) {
+            table.set(bare, price);
+        }
+    }
+    return table;
+}
+
+/* `claude-opus-4-5-20251101` is the same model as `claude-opus-4-5`, dated. */
+function withoutDate(key: string): string | null {
+    const match = /^(.*)-\d{6,8}$/.exec(key);
+    return match === null ? null : match[1]!;
+}
+
+/*
+ * Exact first, then the same name without its date, then the longest family the table knows. A name
+ * nobody prices is left unpriced rather than guessed at: `$0.00` for a model that costs money is a
+ * worse answer than a question mark.
+ */
+export function lookupPrice(table: PriceTable, model: string): PriceLookup {
+    const key = model.trim().toLowerCase().split('[')[0]!;
+    const bare = key.slice(key.lastIndexOf('/') + 1);
+    if (bare === '' || AMBIGUOUS.has(bare)) {
+        return { price: null, basis: 'unknown', pricedAs: null };
+    }
+    const exact = table.get(key) ?? table.get(bare);
+    if (exact !== undefined) {
+        return { price: exact, basis: 'exact', pricedAs: null };
+    }
+    const dated = withoutDate(bare);
+    const undated = dated === null ? undefined : table.get(dated);
+    if (undated !== undefined && dated !== null) {
+        return { price: undated, basis: 'exact', pricedAs: dated };
+    }
+    for (let family = dated ?? bare; family.includes('-');) {
+        family = family.slice(0, family.lastIndexOf('-'));
+        const found = AMBIGUOUS.has(family) ? undefined : table.get(family);
+        if (found !== undefined) {
+            return { price: found, basis: 'family', pricedAs: family };
+        }
+    }
+    return { price: null, basis: 'unknown', pricedAs: null };
+}
+
+/* Reasoning tokens are a part of the output and are never charged a second time. */
+export function costOf(totals: UsageTotals, price: ModelPrice): number {
+    return (
+        totals.input * price.input +
+        totals.cacheRead * price.cacheRead +
+        Math.max(0, totals.cacheWrite - totals.cacheWrite1h) * price.cacheWrite +
+        totals.cacheWrite1h * price.cacheWrite1h +
+        totals.output * price.output
+    );
+}
+
+/* What reading from the cache saved against sending the same tokens again. The premium a write
+   costs is not taken off: it was paid for the turn that wrote, not for the ones that read. */
+export function cacheSavingsOf(totals: UsageTotals, price: ModelPrice): number {
+    return totals.cacheRead * (price.input - price.cacheRead);
+}
+
+interface Snapshot {
+    fetchedAt: number;
+    document: unknown;
+}
+
+/*
+ * One price table for the whole host. It starts on the snapshot that ships with the app, so the
+ * first page ever opened already carries prices, then reads the newer copy on disk, then asks
+ * LiteLLM once a day. Every step is optional: with the fetch off and nothing on disk the bundled
+ * table is what prices everything.
+ */
+export class PriceBook {
+    private readonly home: string;
+    private readonly allowFetch: boolean;
+    private table: PriceTable;
+    private source: UsagePricing['source'] = 'snapshot';
+    private fetchedAt: number | null = null;
+    private loadedFromDisk = false;
+    private inFlight: Promise<void> | null = null;
+
+    constructor(home: string, allowFetch = true) {
+        this.home = home;
+        this.allowFetch = allowFetch;
+        this.table = parsePriceTable(bundled);
+    }
+
+    get pricing(): UsagePricing {
+        return { source: this.table.size === 0 ? 'none' : this.source, fetchedAt: this.fetchedAt, models: this.table.size };
+    }
+
+    look(model: string): PriceLookup {
+        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;
+        });
+        return this.inFlight;
+    }
+
+    private get file(): string {
+        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));
+                }
+            }
+        }
+        if (!this.allowFetch || (this.fetchedAt !== null && Date.now() - this.fetchedAt < TTL_MS)) {
+            return;
+        }
+        try {
+            const response = await fetch(LITELLM_URL, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+            if (!response.ok) {
+                throw new Error(`LiteLLM answered ${response.status}`);
+            }
+            const document: unknown = await response.json();
+            const table = parsePriceTable(document);
+            if (table.size === 0) {
+                throw new Error('The LiteLLM table held no model this app prices');
+            }
+            this.table = table;
+            this.source = 'litellm';
+            this.fetchedAt = Date.now();
+            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));
+        }
+    }
+}

package/src/usage/projects.ts

@@ -0,0 +1,65 @@
+import { readFile, stat } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+
+export interface KnownProject {
+    projectId: string;
+    name: string;
+    folder: string;
+}
+
+export interface ResolvedProject {
+    folder: string;
+    name: string;
+    projectId: string | null;
+}
+
+/*
+ * A checkout that is a worktree keeps its `.git` in a file pointing back into the repository it
+ * belongs to. The work done there is the same repository's work, so both fold to the one folder.
+ */
+async function mainCheckoutOf(gitPath: string): Promise<string | null> {
+    const text = await readFile(gitPath, 'utf8');
+    const match = /^gitdir:\s*(.+)$/m.exec(text);
+    const gitDir = match?.[1]?.trim();
+    const at = gitDir?.indexOf('/.git/worktrees/') ?? -1;
+    return gitDir !== undefined && at > 0 ? gitDir.slice(0, at) : null;
+}
+
+/*
+ * Which folder a directory's work belongs to: the repository it sits in, or the directory itself
+ * when it is in none. Every answer is remembered, because one scan asks about the same handful of
+ * directories tens of thousands of times.
+ */
+export class ProjectResolver {
+    private readonly known: Map<string, KnownProject>;
+    private readonly roots = new Map<string, string>();
+
+    constructor(known: readonly KnownProject[]) {
+        this.known = new Map(known.flatMap((project) => (project.folder === '' ? [] : [[project.folder, project] as const])));
+    }
+
+    async resolve(cwd: string): Promise<ResolvedProject> {
+        const folder = cwd === '' ? '' : await this.rootOf(cwd);
+        const project = this.known.get(folder);
+        return { folder, name: project?.name ?? (folder === '' ? 'Elsewhere' : basename(folder)), projectId: project?.projectId ?? null };
+    }
+
+    private async rootOf(cwd: string): Promise<string> {
+        const cached = this.roots.get(cwd);
+        if (cached !== undefined) {
+            return cached;
+        }
+        let root = cwd;
+        for (let at = cwd; at !== dirname(at); at = dirname(at)) {
+            try {
+                const info = await stat(join(at, '.git'));
+                root = (info.isFile() ? await mainCheckoutOf(join(at, '.git')) : null) ?? at;
+                break;
+            } catch {
+                // Not a checkout at this level; the one above it may be.
+            }
+        }
+        this.roots.set(cwd, root);
+        return root;
+    }
+}

package/src/usage/readers/claude.ts

@@ -0,0 +1,60 @@
+import { asObject, asString, int, type UsageRecord } from '../record.ts';
+
+/* Only a line with this in it can carry counts, which keeps `JSON.parse` off about two thirds of them. */
+export function claudeMightCarryUsage(line: string): boolean {
+    return line.includes('"usage"');
+}
+
+/*
+ * One line of `~/.claude/projects/**\/*.jsonl`. An assistant line carries `message.usage` with the
+ * counts of the call that produced it; every other kind of line has nothing to price. The counts are
+ * Anthropic's, so `input_tokens` already excludes what was read from or written to the cache.
+ */
+export function parseClaudeLine(line: string): UsageRecord | null {
+    let parsed: unknown;
+    try {
+        parsed = JSON.parse(line);
+    } catch {
+        return null;
+    }
+    const record = asObject(parsed);
+    if (record === null || record.type !== 'assistant') {
+        return null;
+    }
+    const message = asObject(record.message);
+    const usage = message === null ? null : asObject(message.usage);
+    if (message === null || usage === null) {
+        return null;
+    }
+    const model = asString(message.model);
+    const timestampMs = Date.parse(asString(record.timestamp));
+    // `<synthetic>` is what Claude Code writes for a message it made up itself, an error or an
+    // interruption. It never reached the API, and its counts are zero, so it is not a call.
+    if (model === '' || model === '<synthetic>' || Number.isNaN(timestampMs)) {
+        return null;
+    }
+    const creation = asObject(usage.cache_creation);
+    const outputDetails = asObject(usage.output_tokens_details);
+    const messageId = asString(message.id);
+    const totals = {
+        calls: 1,
+        input: int(usage.input_tokens),
+        cacheRead: int(usage.cache_read_input_tokens),
+        cacheWrite: int(usage.cache_creation_input_tokens),
+        cacheWrite1h: creation === null ? 0 : int(creation.ephemeral_1h_input_tokens),
+        output: int(usage.output_tokens),
+        reasoning: outputDetails === null ? 0 : int(outputDetails.thinking_tokens)
+    };
+    if (totals.input + totals.cacheRead + totals.cacheWrite + totals.output === 0) {
+        return null;
+    }
+    return {
+        provider: 'claude',
+        timestampMs,
+        model,
+        sessionId: asString(record.sessionId),
+        cwd: asString(record.cwd),
+        totals,
+        dedupeKey: messageId === '' ? null : messageId
+    };
+}

package/src/usage/readers/codex.ts

@@ -0,0 +1,196 @@
+import { asObject, asString, int, type UsageRecord } from '../record.ts';
+
+/* A `token_count` line carries the counts; the other two carry the model and the directory they belong to. */
+export function codexMightCarryUsage(line: string): boolean {
+    return line.includes('token_count') || line.includes('turn_context') || line.includes('session_meta');
+}
+
+/* A fork replays its ancestors' events into the new file the moment it is created, so anything this
+   close to the file's own start is a copy of work that was already counted somewhere else. */
+const FORK_COPY_MAX_GAP_MS = 1_000;
+
+interface CodexCounts {
+    input: number;
+    cached: number;
+    cacheWrite: number;
+    output: number;
+    reasoning: number;
+}
+
+/*
+ * What one file's reader has to remember between lines. A `token_count` line names neither the model
+ * nor the directory, and its totals are cumulative, so a scan that resumes halfway through a file
+ * needs all of it back. Everything here is JSON, so the index can store it verbatim.
+ */
+export interface CodexParserState {
+    model: string | null;
+    sessionId: string;
+    cwd: string;
+    /* The running cumulative total of the last line, which the next line is a delta against. */
+    total: CodexCounts | null;
+    sawSessionMeta: boolean;
+    /* Whether this file opened as a fork or a sub-agent thread, and where its replayed prefix is. */
+    suppressing: boolean;
+    anchorMs: number;
+    /* The last counts as they were written, so a line repeated verbatim is not counted twice. */
+    lastSignature: string | null;
+}
+
+export function createCodexState(): CodexParserState {
+    return {
+        model: null,
+        sessionId: '',
+        cwd: '',
+        total: null,
+        sawSessionMeta: false,
+        suppressing: false,
+        anchorMs: 0,
+        lastSignature: null
+    };
+}
+
+export function cloneCodexState(state: CodexParserState): CodexParserState {
+    return { ...state, total: state.total === null ? null : { ...state.total } };
+}
+
+function countsOf(usage: Record<string, unknown>): CodexCounts {
+    return {
+        input: int(usage.input_tokens),
+        cached: int(usage.cached_input_tokens),
+        cacheWrite: int(usage.cache_write_input_tokens),
+        output: int(usage.output_tokens),
+        reasoning: int(usage.reasoning_output_tokens)
+    };
+}
+
+function deltaOf(total: CodexCounts, previous: CodexCounts | null): CodexCounts | null {
+    if (previous === null) {
+        return total;
+    }
+    const delta: CodexCounts = {
+        input: total.input - previous.input,
+        cached: total.cached - previous.cached,
+        cacheWrite: total.cacheWrite - previous.cacheWrite,
+        output: total.output - previous.output,
+        reasoning: total.reasoning - previous.reasoning
+    };
+    // A compaction or a resume restarts the count, so anything falling is not a delta at all.
+    return delta.input < 0 || delta.cached < 0 || delta.cacheWrite < 0 || delta.output < 0 || delta.reasoning < 0 ? null : delta;
+}
+
+/* A thread that was forked or spawned repeats its parent's events before its own work starts. */
+function isForkOrSubagent(payload: Record<string, unknown>): boolean {
+    if (typeof payload.forked_from_id === 'string' || typeof payload.parent_thread_id === 'string') {
+        return true;
+    }
+    const spawn = asObject(asObject(payload.source)?.subagent)?.thread_spawn;
+    return typeof asObject(spawn)?.parent_thread_id === 'string';
+}
+
+/*
+ * One line of `~/.codex/sessions/**\/*.jsonl`, against the state of the file it came from. Codex
+ * reports a cumulative total per turn, so the call is the difference with the line before it; when
+ * that difference falls the run started over and `last_token_usage` is the turn on its own. Codex
+ * counts cache reads and writes inside `input_tokens`, unlike Anthropic, so what is left after
+ * taking both out is the input that was actually paid for at the full rate.
+ */
+export function parseCodexLine(line: string, state: CodexParserState): UsageRecord | null {
+    let parsed: unknown;
+    try {
+        parsed = JSON.parse(line);
+    } catch {
+        return null;
+    }
+    const record = asObject(parsed);
+    const payload = record === null ? null : asObject(record.payload);
+    if (record === null || payload === null) {
+        return null;
+    }
+
+    if (record.type === 'session_meta') {
+        // A fork carries its ancestors' metas as well; only the file's own says what the file is.
+        if (state.sawSessionMeta) {
+            return null;
+        }
+        state.sawSessionMeta = true;
+        state.sessionId = asString(payload.id) || asString(payload.session_id);
+        state.cwd = asString(payload.cwd);
+        if (isForkOrSubagent(payload)) {
+            state.suppressing = true;
+            state.anchorMs = Date.parse(asString(record.timestamp)) || 0;
+        }
+        return null;
+    }
+
+    if (record.type === 'turn_context') {
+        const model = asString(payload.model);
+        if (model !== '') {
+            state.model = model;
+        }
+        const cwd = asString(payload.cwd);
+        if (cwd !== '') {
+            state.cwd = cwd;
+        }
+        return null;
+    }
+
+    if (payload.type !== 'token_count') {
+        return null;
+    }
+    const info = asObject(payload.info);
+    const total = info === null ? null : asObject(info.total_token_usage);
+    if (info === null || total === null || state.model === null) {
+        return null;
+    }
+    const timestampMs = Date.parse(asString(record.timestamp));
+    if (Number.isNaN(timestampMs)) {
+        return null;
+    }
+
+    const signature = JSON.stringify(info.total_token_usage);
+    if (signature === state.lastSignature) {
+        return null;
+    }
+    state.lastSignature = signature;
+
+    const cumulative = countsOf(total);
+    const last = asObject(info.last_token_usage);
+    const counts = deltaOf(cumulative, state.total) ?? (last === null ? null : countsOf(last));
+    state.total = cumulative;
+    if (counts === null) {
+        return null;
+    }
+
+    if (state.suppressing) {
+        if (timestampMs - state.anchorMs <= FORK_COPY_MAX_GAP_MS) {
+            state.anchorMs = timestampMs;
+            return null;
+        }
+        // The first event that is not part of the replayed burst is this thread's own work.
+        state.suppressing = false;
+    }
+
+    const uncached = Math.max(0, counts.input - counts.cached - counts.cacheWrite);
+    const totals = {
+        calls: 1,
+        input: uncached,
+        cacheRead: counts.cached,
+        cacheWrite: counts.cacheWrite,
+        cacheWrite1h: 0,
+        output: counts.output,
+        reasoning: Math.min(counts.output, counts.reasoning)
+    };
+    if (uncached + counts.cached + counts.cacheWrite + counts.output === 0) {
+        return null;
+    }
+    return {
+        provider: 'codex',
+        timestampMs,
+        model: state.model,
+        sessionId: state.sessionId,
+        cwd: state.cwd,
+        totals,
+        // Fork copies are gone by here, so every event that is left is a call of its own.
+        dedupeKey: null
+    };
+}

package/src/usage/record.ts

@@ -0,0 +1,60 @@
+import type { UsageProvider, UsageTotals } from '@adecore/agent-contracts';
+
+/* One priced call, as a reader found it on a line. The scanner keeps these; the aggregator sums them. */
+export interface UsageRecord {
+    provider: UsageProvider;
+    timestampMs: number;
+    model: string;
+    sessionId: string;
+    /* The directory the call was made in, which is what a per-project breakdown folds. */
+    cwd: string;
+    /* The account the call was made under; absent is the default account of the CLI. */
+    account?: string;
+    totals: UsageTotals;
+    /* What identifies the message this line reports on, or null when nothing does. */
+    dedupeKey: string | null;
+}
+
+/* A count on the wire is a whole non-negative number, whatever a transcript put in the field. */
+export function int(value: unknown): number {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0 ? Math.trunc(value) : 0;
+}
+
+/* A field a transcript wrote as anything; a reader takes what it can use and nothing else. */
+export function asObject(value: unknown): Record<string, unknown> | null {
+    return typeof value === 'object' && value !== null ? (value as Record<string, unknown>) : null;
+}
+
+export function asString(value: unknown): string {
+    return typeof value === 'string' ? value : '';
+}
+
+function maxTotals(into: UsageTotals, from: UsageTotals): void {
+    into.calls = Math.max(into.calls, from.calls);
+    into.input = Math.max(into.input, from.input);
+    into.cacheRead = Math.max(into.cacheRead, from.cacheRead);
+    into.cacheWrite = Math.max(into.cacheWrite, from.cacheWrite);
+    into.cacheWrite1h = Math.max(into.cacheWrite1h, from.cacheWrite1h);
+    into.output = Math.max(into.output, from.output);
+    into.reasoning = Math.max(into.reasoning, from.reasoning);
+}
+
+// Claude repeats growing usage per message and across resumed transcripts; keep each field's maximum.
+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;
+        }
+        maxTotals(folded[seen]!.totals, record.totals);
+    }
+    return folded;
+}

package/src/usage/roots.ts

@@ -0,0 +1,39 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import type { UsageProvider } from '@adecore/agent-contracts';
+
+export interface UsageRootPath {
+    provider: UsageProvider;
+    path: string;
+    /* The accounts whose CLI writes here, by id, the default one under its kind; absent is the default account alone. */
+    accounts?: string[];
+}
+
+/* Where in its config folder each CLI leaves its transcripts. */
+const TRANSCRIPTS: Record<UsageProvider, string> = { claude: 'projects', codex: 'sessions' };
+
+/* Where each CLI leaves its transcripts. The same environment variables the hooks installer reads,
+   so the scanner and the installer never disagree about where a CLI keeps its things. */
+export function usageRoots(env: Record<string, string | undefined> = process.env): UsageRootPath[] {
+    const home = env.HOME ?? homedir();
+    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) }
+    ];
+}
+
+/* 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 path = join(folder, TRANSCRIPTS[kind]);
+        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()];
+}