@itookit/dsht 0.3.0 → 0.3.3

package/dist/controller/memory-log.d.ts

@@ -0,0 +1,35 @@
+import { type ObjectValue } from '../transport/wire.ts';
+/** Append-only memory log; the file never exceeds twice `KEEP_SAMPLES` lines.
+ *
+ * The log exists to answer "is retained content growing, or is this just V8's high-water mark",
+ * so each sample records the process counters next to the client's retained window and the
+ * controller state that decides whether that window is being reclaimed. Samples contain counts
+ * and sizes only, never prompt, tool, or session text. A failing log stops itself instead of
+ * breaking the client.
+ */
+export declare class MemoryLog {
+    readonly path: string | undefined;
+    private readonly sampleSource;
+    private timer;
+    private appended;
+    private writing;
+    /** Last write failure, when the log stopped itself. */
+    error: string | undefined;
+    constructor(path: string | undefined, sampleSource: () => ObjectValue);
+    /** Write the header into a new file, then sample once; a missing or unwritable path is reported
+     * by that first sample instead of here.
+     */
+    private begin;
+    /** Sample once now and then every `SAMPLE_INTERVAL_MS`; absent when no path was configured. */
+    start(): void;
+    /** Stop sampling and rewrite the file with its retained window. */
+    stop(): Promise<void>;
+    /** Append one sample line, skipping overlapping calls.
+     *
+     * A repeated failure would be noise, so the first one stops the timer and leaves the client
+     * running; the log is diagnostics, not a feature the terminal depends on.
+     */
+    sample(): Promise<void>;
+    /** Rewrite the file with the header and the newest kept lines, bounding its size. */
+    private compact;
+}

package/dist/controller/memory-log.js

@@ -0,0 +1,95 @@
+/** Runtime memory samples appended to one bounded local file for diagnosing growth over a long run. */
+import { appendPrivateFile, createPrivateFile, writePrivateFile } from "../storage/index.js";
+import { errorText } from "../transport/wire.js";
+/** Time between automatic samples. */
+const SAMPLE_INTERVAL_MS = 30_000;
+/** Samples kept; reaching the cap rewrites the file with just these lines. */
+const KEEP_SAMPLES = 1000;
+/** First line of the file, so an empty or rewritten log still explains itself. */
+const HEADER = '# dsht memory samples: one JSON object per line, oldest first\n';
+/** Append-only memory log; the file never exceeds twice `KEEP_SAMPLES` lines.
+ *
+ * The log exists to answer "is retained content growing, or is this just V8's high-water mark",
+ * so each sample records the process counters next to the client's retained window and the
+ * controller state that decides whether that window is being reclaimed. Samples contain counts
+ * and sizes only, never prompt, tool, or session text. A failing log stops itself instead of
+ * breaking the client.
+ */
+export class MemoryLog {
+    path;
+    sampleSource;
+    timer;
+    appended = [];
+    writing = false;
+    /** Last write failure, when the log stopped itself. */
+    error;
+    constructor(path, sampleSource) {
+        this.path = path;
+        this.sampleSource = sampleSource;
+    }
+    /** Write the header into a new file, then sample once; a missing or unwritable path is reported
+     * by that first sample instead of here.
+     */
+    async begin() {
+        if (this.path === undefined)
+            return;
+        try {
+            await createPrivateFile(this.path, HEADER);
+        }
+        catch { /* the sample below reports it */ }
+        await this.sample();
+    }
+    /** Sample once now and then every `SAMPLE_INTERVAL_MS`; absent when no path was configured. */
+    start() {
+        if (this.path === undefined || this.timer !== undefined)
+            return;
+        void this.begin();
+        this.timer = setInterval(() => { void this.sample(); }, SAMPLE_INTERVAL_MS);
+    }
+    /** Stop sampling and rewrite the file with its retained window. */
+    async stop() {
+        clearInterval(this.timer);
+        this.timer = undefined;
+        await this.compact();
+    }
+    /** Append one sample line, skipping overlapping calls.
+     *
+     * A repeated failure would be noise, so the first one stops the timer and leaves the client
+     * running; the log is diagnostics, not a feature the terminal depends on.
+     */
+    async sample() {
+        if (this.path === undefined || this.writing)
+            return;
+        this.writing = true;
+        try {
+            const line = `${JSON.stringify(this.sampleSource())}\n`;
+            await appendPrivateFile(this.path, line);
+            this.appended.push(line);
+            this.error = undefined;
+            if (this.appended.length >= KEEP_SAMPLES)
+                await this.compact();
+        }
+        catch (error) {
+            this.error = errorText(error);
+            clearInterval(this.timer);
+            this.timer = undefined;
+        }
+        finally {
+            this.writing = false;
+        }
+    }
+    /** Rewrite the file with the header and the newest kept lines, bounding its size. */
+    async compact() {
+        if (this.path === undefined || this.appended.length === 0)
+            return;
+        const lines = this.appended.slice(-KEEP_SAMPLES);
+        try {
+            await writePrivateFile(this.path, HEADER + lines.join(''));
+            this.appended = lines;
+        }
+        catch (error) {
+            // Appending continues to the existing file, so a failed rewrite only delays the bound.
+            this.error = errorText(error);
+        }
+    }
+}

package/dist/cost/config.d.ts

@@ -0,0 +1,17 @@
+import type { PriceVersion } from './types.ts';
+/** Load the price table, seeding the file on first use and refreshing a copy the user never edited.
+ *
+ * `prices.json` overrides the shipped table, so a correction to the shipped rates would otherwise
+ * never reach an install that already had the file — which is how a superseded Flash table kept
+ * charging 1.5x for input after it was fixed. The stamp records the seeded bytes: while the file
+ * still hashes to them the tool owns it and follows the shipped table, and the first edit makes the
+ * file authoritative, so no rate the user chose is ever overwritten.
+ * @param directory - Configuration directory holding `prices.json`.
+ * @param shipped - Table this build ships, seeded on first use and followed while the file is untouched.
+ * @returns The validated table, and whether it came from a file the user maintains.
+ * @throws when the file exists but is not a valid table.
+ */
+export declare function loadPrices(directory: string, shipped?: PriceVersion[]): Promise<{
+    prices: PriceVersion[];
+    custom: boolean;
+}>;

package/dist/cost/config.js

@@ -0,0 +1,68 @@
+/** Seed, migrate and load the price configuration that overrides the shipped table. */
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+import { createPrivateFile, readText, writePrivateFile } from "../storage/index.js";
+import { DEFAULT_PRICES, PRICES_REVISION, isUncorrectedSeed, pricesFrom } from "./pricing.js";
+/** Load the price table, seeding the file on first use and refreshing a copy the user never edited.
+ *
+ * `prices.json` overrides the shipped table, so a correction to the shipped rates would otherwise
+ * never reach an install that already had the file — which is how a superseded Flash table kept
+ * charging 1.5x for input after it was fixed. The stamp records the seeded bytes: while the file
+ * still hashes to them the tool owns it and follows the shipped table, and the first edit makes the
+ * file authoritative, so no rate the user chose is ever overwritten.
+ * @param directory - Configuration directory holding `prices.json`.
+ * @param shipped - Table this build ships, seeded on first use and followed while the file is untouched.
+ * @returns The validated table, and whether it came from a file the user maintains.
+ * @throws when the file exists but is not a valid table.
+ */
+export async function loadPrices(directory, shipped = DEFAULT_PRICES) {
+    const path = join(directory, 'prices.json');
+    const stampPath = join(directory, 'prices.seed.json');
+    const seeded = `${JSON.stringify(shipped, null, 2)}\n`;
+    const raw = await readText(path);
+    if (raw === undefined) {
+        await createPrivateFile(path, seeded);
+        await writePrivateFile(stampPath, stamp(seeded));
+        return { prices: shipped, custom: false };
+    }
+    const prices = pricesFrom(JSON.parse(raw));
+    const recorded = await readStamp(stampPath);
+    // A file without a stamp predates the record; only the superseded shipped seed is recognized there,
+    // because anything else may be a table the user wrote by hand.
+    const owned = recorded === undefined ? isUncorrectedSeed(prices) : recorded === hash(raw);
+    if (!owned)
+        return { prices, custom: true };
+    // Write only what a corrected table actually changed, so an unchanged file needs no write at all
+    // and a read-only configuration directory still starts.
+    if (raw !== seeded)
+        await writePrivateFile(path, seeded);
+    if (recorded !== hash(seeded))
+        await writePrivateFile(stampPath, stamp(seeded));
+    return { prices: shipped, custom: false };
+}
+/** Sha256 of one file's contents.
+ * @param contents - Exact file text.
+ * @returns Lowercase hex digest.
+ */
+function hash(contents) { return createHash('sha256').update(contents).digest('hex'); }
+/** Serialize the stamp written beside a seeded table.
+ * @param contents - Exact seeded text.
+ * @returns Stamp file contents.
+ */
+function stamp(contents) { return `${JSON.stringify({ revision: PRICES_REVISION, hash: hash(contents) }, null, 2)}\n`; }
+/** Read the seed stamp, tolerating a stamp written by another revision.
+ * @param path - Stamp file path.
+ * @returns The digest recorded for the seeded file, or undefined when no stamp applies.
+ */
+async function readStamp(path) {
+    const raw = await readText(path);
+    if (raw === undefined)
+        return;
+    try {
+        const parsed = JSON.parse(raw);
+        return typeof parsed.hash === 'string' ? parsed.hash : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/cost/controller.d.ts

@@ -0,0 +1,41 @@
+/** Periodic billing scans; the ledger outlives any single connection generation. */
+import type { Client } from '../transport/client.ts';
+import type { CostLedger } from './ledger.ts';
+/** Host access a scan needs; supplied by the controller facade. */
+export interface CostHost {
+    /** Connected client, or undefined while offline. */
+    client(): Client | undefined;
+    /** Whether the current connection generation is online. */
+    online(): boolean;
+    /** Client lifetime signal, aborted when the process closes the connection. */
+    signal(): AbortSignal;
+    /** Re-publish controller state after the ledger changes. */
+    publish(): void;
+}
+/** Owns the background scan: startup, the minute timer, turn-completion refresh, and `/cost`. */
+export declare class CostController {
+    readonly ledger: CostLedger;
+    private readonly host;
+    private task;
+    private abort;
+    private timer;
+    private updates;
+    constructor(ledger: CostLedger, host: CostHost);
+    /** Scan immediately, then once a minute while online.
+     *
+     * Every generation starts with no skip bookkeeping, because the host keeps running while this
+     * client is not connected: an update time this client already recorded cannot prove that nothing
+     * happened during the gap, so the first scan of the generation reads every session's history
+     * again. Within that generation the recorded times keep the minute timer from re-reading idle
+     * sessions.
+     */
+    start(): void;
+    /** Stop the timer and wait for an in-flight scan; the ledger keeps its folded totals. */
+    stop(): Promise<void>;
+    /** Refresh after the host reports a turn complete. */
+    onTurnIdle(): void;
+    /** Refresh all HTTP-visible sessions without changing the selected conversation.
+     * @param signal - Optional cancellation for an explicit `/cost` refresh.
+     */
+    refresh(signal?: AbortSignal): Promise<void>;
+}

package/dist/cost/controller.js

@@ -0,0 +1,115 @@
+import { array, errorText, object, string } from "../transport/wire.js";
+import { sessionCostHistory } from "./scanner.js";
+/** Refresh interval for the background cost scan. */
+const REFRESH_INTERVAL_MS = 60_000;
+/** Owns the background scan: startup, the minute timer, turn-completion refresh, and `/cost`. */
+export class CostController {
+    ledger;
+    host;
+    task;
+    abort;
+    timer;
+    updates = new Map();
+    constructor(ledger, host) {
+        this.ledger = ledger;
+        this.host = host;
+    }
+    /** Scan immediately, then once a minute while online.
+     *
+     * Every generation starts with no skip bookkeeping, because the host keeps running while this
+     * client is not connected: an update time this client already recorded cannot prove that nothing
+     * happened during the gap, so the first scan of the generation reads every session's history
+     * again. Within that generation the recorded times keep the minute timer from re-reading idle
+     * sessions.
+     */
+    start() {
+        if (this.timer)
+            return;
+        this.updates.clear();
+        void this.refresh().catch(() => undefined);
+        this.timer = setInterval(() => { if (this.host.online())
+            void this.refresh().catch(() => undefined); }, REFRESH_INTERVAL_MS);
+    }
+    /** Stop the timer and wait for an in-flight scan; the ledger keeps its folded totals. */
+    async stop() {
+        clearInterval(this.timer);
+        this.timer = undefined;
+        await this.task;
+    }
+    /** Refresh after the host reports a turn complete. */
+    onTurnIdle() {
+        if (this.host.online())
+            void this.refresh().catch(() => undefined);
+    }
+    /** Refresh all HTTP-visible sessions without changing the selected conversation.
+     * @param signal - Optional cancellation for an explicit `/cost` refresh.
+     */
+    async refresh(signal = this.host.signal()) {
+        if (this.task) {
+            const cancel = () => this.abort?.abort();
+            signal.addEventListener('abort', cancel, { once: true });
+            try {
+                await this.task;
+            }
+            finally {
+                signal.removeEventListener('abort', cancel);
+            }
+            return;
+        }
+        const client = this.host.client();
+        if (!client)
+            throw new Error('Not connected');
+        this.abort = new AbortController();
+        const combined = AbortSignal.any([signal, this.host.signal(), this.abort.signal]);
+        const ledger = this.ledger;
+        ledger.scanning = true;
+        ledger.error = '';
+        this.host.publish();
+        const task = (async () => {
+            try {
+                const sessions = array(object(await client.call('session/list', { _request: {} }, combined)).items).map(object);
+                combined.throwIfAborted();
+                const failures = [];
+                let scanned = 0, pages = 0, events = 0;
+                for (const session of sessions) {
+                    combined.throwIfAborted();
+                    const sessionId = string(session.sessionId);
+                    if (!session.running && typeof session.updatedAt === 'number' && this.updates.get(sessionId) === session.updatedAt)
+                        continue;
+                    try {
+                        const history = await sessionCostHistory(client, session, combined, () => { pages++; });
+                        scanned++;
+                        events += history.events.length;
+                        await ledger.replace(sessionId, history.cursor, history.events);
+                        if (!session.running && typeof session.updatedAt === 'number')
+                            this.updates.set(sessionId, session.updatedAt);
+                        this.host.publish();
+                    }
+                    catch (error) {
+                        // One unreachable or rejected session must not freeze every other session's rates.
+                        combined.throwIfAborted();
+                        failures.push(`${sessionId}: ${errorText(error)}`);
+                    }
+                }
+                ledger.error = failures.length === 0 ? '' : `${failures.length} of ${sessions.length} sessions failed: ${failures[0]}`;
+                ledger.lastScan = { sessions: scanned, pages, events };
+                ledger.scannedAt = Date.now();
+            }
+            catch (error) {
+                ledger.error = errorText(error);
+            }
+            finally {
+                ledger.scanning = false;
+                this.host.publish();
+            }
+        })();
+        this.task = task;
+        try {
+            await task;
+        }
+        finally {
+            this.task = undefined;
+            this.abort = undefined;
+        }
+    }
+}

package/dist/cost/index.d.ts

@@ -0,0 +1,10 @@
+/** Cost domain: price tables, record folding, the folded ledger, the scanner and its controller. */
+export { CostController } from './controller.ts';
+export type { CostHost } from './controller.ts';
+export { CostLedger, costText } from './ledger.ts';
+export { loadPrices } from './config.ts';
+export { candidates, canonicalModel, chargeFor, costDay, DEFAULT_PRICES, isUncorrectedSeed, priceAt, PRICES_REVISION, PRICING_ENGINE_VERSION, pricesDigest, pricesFrom } from './pricing.ts';
+export { costRecords, foldSamples } from './records.ts';
+export { costAddresses, sessionCostHistory } from './scanner.ts';
+export { MISSING_TIME, MISSING_USAGE, UNSUPPORTED_USAGE } from './types.ts';
+export type { ChargeSample, CostTotal, Coverage, DayTotal, PriceDecision, PriceVersion, Rates, SavedCost, Usage } from './types.ts';

package/dist/cost/index.js

@@ -0,0 +1,8 @@
+/** Cost domain: price tables, record folding, the folded ledger, the scanner and its controller. */
+export { CostController } from "./controller.js";
+export { CostLedger, costText } from "./ledger.js";
+export { loadPrices } from "./config.js";
+export { candidates, canonicalModel, chargeFor, costDay, DEFAULT_PRICES, isUncorrectedSeed, priceAt, PRICES_REVISION, PRICING_ENGINE_VERSION, pricesDigest, pricesFrom } from "./pricing.js";
+export { costRecords, foldSamples } from "./records.js";
+export { costAddresses, sessionCostHistory } from "./scanner.js";
+export { MISSING_TIME, MISSING_USAGE, UNSUPPORTED_USAGE } from "./types.js";

package/dist/cost/ledger-files.d.ts

@@ -0,0 +1,16 @@
+import type { SavedCost } from './types.ts';
+/** Load every session's stored totals; a file this build cannot read is left for the next scan.
+ * @param directory - Origin-scoped ledger directory, or undefined when persistence is disabled.
+ * @returns The newest saved slice per session identity.
+ */
+export declare function loadLedgers(directory: string | undefined): Promise<Map<string, SavedCost>>;
+/** Write one session's totals unless the directory already holds a newer scan.
+ *
+ * The file is the system of record across processes, so a scan that opened an older snapshot must
+ * not replace a cut another scan already persisted, and a process holding older decision rules must
+ * not seal its totals over newer ones.
+ * @param directory - Origin-scoped ledger directory.
+ * @param saved - Complete slice to persist.
+ * @returns Whether the directory now holds this slice.
+ */
+export declare function saveLedger(directory: string, saved: SavedCost): Promise<boolean>;

package/dist/cost/ledger-files.js

@@ -0,0 +1,103 @@
+/** Atomic per-session persistence for folded cost totals. */
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+import { ensureDirectory, listEntries, readText, writePrivateFile } from "../storage/index.js";
+/** Current on-disk ledger generation. A file of another generation is ignored: the next scan rebuilds it. */
+const LEDGER_VERSION = 3;
+/** The one file that holds a session's totals: the fixed per-session name. */
+function ledgerName(sessionId) {
+    return `${createHash('sha256').update(sessionId).digest('hex')}.json`;
+}
+/** Load every session's stored totals; a file this build cannot read is left for the next scan.
+ * @param directory - Origin-scoped ledger directory, or undefined when persistence is disabled.
+ * @returns The newest saved slice per session identity.
+ */
+export async function loadLedgers(directory) {
+    const sessions = new Map();
+    if (!directory)
+        return sessions;
+    await ensureDirectory(directory);
+    for (const name of await listEntries(directory)) {
+        if (!/^[0-9a-f]{64}\.json$/.test(name))
+            continue;
+        const path = join(directory, name);
+        const raw = await readText(path);
+        // A file removed between listing and reading is simply absent.
+        if (raw === undefined)
+            continue;
+        const saved = parseLedger(raw);
+        // A slice is a projection of the host log: one this build cannot use costs a rescan, not data.
+        if (saved === undefined)
+            continue;
+        if ((sessions.get(saved.sessionId)?.cut ?? -2) <= saved.cut)
+            sessions.set(saved.sessionId, saved);
+    }
+    return sessions;
+}
+/** Write one session's totals unless the directory already holds a newer scan.
+ *
+ * The file is the system of record across processes, so a scan that opened an older snapshot must
+ * not replace a cut another scan already persisted, and a process holding older decision rules must
+ * not seal its totals over newer ones.
+ * @param directory - Origin-scoped ledger directory.
+ * @param saved - Complete slice to persist.
+ * @returns Whether the directory now holds this slice.
+ */
+export async function saveLedger(directory, saved) {
+    const path = join(directory, ledgerName(saved.sessionId));
+    const existing = await readText(path);
+    if (existing !== undefined) {
+        const previous = parseLedger(existing);
+        if (previous !== undefined && (previous.cut > saved.cut || previous.engine > saved.engine))
+            return false;
+    }
+    await writePrivateFile(path, JSON.stringify(saved) + '\n');
+    return true;
+}
+/** Validate one persisted slice; another generation or an unreadable shape is absent. */
+function parseLedger(raw) {
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return undefined;
+    const record = value;
+    if (record.version !== LEDGER_VERSION)
+        return undefined;
+    if (typeof record.sessionId !== 'string' || !Number.isSafeInteger(record.cut))
+        throw new Error('Invalid cost ledger');
+    if (!Number.isSafeInteger(record.engine) || typeof record.catalog !== 'string')
+        throw new Error('Invalid cost ledger');
+    const total = validTotal(record.total);
+    const day = validDay(record.day);
+    if (total === undefined || day === undefined)
+        throw new Error('Invalid cost ledger');
+    if (!Array.isArray(record.unpriced) || record.unpriced.some(reason => typeof reason !== 'string'))
+        throw new Error('Invalid cost ledger');
+    return { version: LEDGER_VERSION, sessionId: record.sessionId, cut: record.cut, engine: record.engine,
+        catalog: record.catalog, total, day, unpriced: record.unpriced };
+}
+/** Accept one stored subtotal only when the amount is finite and the counts are whole.
+ * Costs are fractional, so only the counts are required to be integers. */
+function validTotal(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return undefined;
+    const total = value;
+    const amount = total.amount;
+    if (typeof amount !== 'number' || !Number.isFinite(amount) || amount < 0)
+        return undefined;
+    const counts = [total.unknown, total.records];
+    if (!counts.every(count => typeof count === 'number' && Number.isSafeInteger(count) && count >= 0))
+        return undefined;
+    return { amount, unknown: total.unknown, records: total.records };
+}
+/** Accept one stored day bucket only when it also names the Beijing day it covers. */
+function validDay(value) {
+    const total = validTotal(value);
+    const day = value?.day;
+    return total === undefined || typeof day !== 'string' || day === '' ? undefined : { day, ...total };
+}

package/dist/cost/ledger.d.ts

@@ -0,0 +1,78 @@
+/** CNY estimates folded from host history: per-session totals, re-decided by every scan. */
+import type { ObjectValue } from '../transport/wire.ts';
+import { type CostTotal, type Coverage, type PriceVersion } from './types.ts';
+/** Per-origin cache of folded session totals; every scan replaces a session at its cut. */
+export declare class CostLedger {
+    readonly prices: PriceVersion[];
+    readonly directory?: string | undefined;
+    /** Whether the table came from a file the user maintains, rather than the shipped one. */
+    readonly customPrices: boolean;
+    private sessions;
+    private totals;
+    private readonly catalog;
+    scannedAt?: number;
+    scanning: boolean;
+    error: string;
+    /** Work the last completed scan performed, so a memory sample can attribute its allocation. */
+    lastScan?: {
+        sessions: number;
+        pages: number;
+        events: number;
+    };
+    constructor(prices?: PriceVersion[], directory?: string | undefined, 
+    /** Whether the table came from a file the user maintains, rather than the shipped one. */
+    customPrices?: boolean);
+    /** Cached totals count as complete; only a failed scan or an empty ledger is partial.
+     * @returns Coverage of the current totals, so callers can mark them without re-deriving the rule.
+     */
+    get coverage(): Coverage;
+    /** Load the newest cut per session; a stored total is read as it was decided. */
+    load(): Promise<void>;
+    /** Replace one session using all billing events through the opening snapshot cut.
+     *
+     * The fold is the projection: every sample is decided again with the table loaded now, so a
+     * corrected table reaches history on the next scan and a request no table covered yet is priced
+     * as soon as one does. Only the totals are kept, and the cut and engine keep an older scan from
+     * replacing a newer one.
+     * @param sessionId - Host session identity.
+     * @param cut - Opening cursor, preventing a stale scan from overwriting a newer scan.
+     * @param events - Minimal events returned by `costRecords`, across all history pages.
+     * @param now - Clock that names the calendar day the day bucket covers.
+     */
+    replace(sessionId: string, cut: number, events: ObjectValue[], now?: number): Promise<void>;
+    /** Count the retained ledger so a memory sample can separate it from the transcript window.
+     * @returns Sessions, requests and unpriced requests currently held.
+     */
+    summary(): {
+        sessions: number;
+        records: number;
+        unpriced: number;
+    };
+    /** Whether this session has a complete cached scan.
+     * @param sessionId - Selected session identity, which may be unset before one is picked.
+     * @returns True when a complete scan is available, narrowing the identity to a string.
+     */
+    hasSession(sessionId: string | undefined): sessionId is string;
+    /** Describe unpriced model/usage combinations without exposing conversation content.
+     * @returns Unique reasons across cached sessions.
+     */
+    missing(): string[];
+    /** One session's stored totals.
+     * @param sessionId - Session identity to report.
+     * @returns The total a scan folded for it, or zeros when no scan has covered it.
+     */
+    total(sessionId: string): CostTotal;
+    /** Every session's requests on one Beijing calendar day.
+     *
+     * A slice keeps only the day its last scan ran on, so another day reads as nothing spent today
+     * rather than as the last day that was scanned.
+     * @param now - Clock that names the day to report.
+     * @returns The day's total across cached sessions.
+     */
+    today(now?: number): CostTotal;
+}
+/** Compact estimates retain an asterisk whenever a subtotal is not exact.
+ * @param total - Summary from the ledger.
+ * @returns Yuan amount and incompleteness marker.
+ */
+export declare function costText(total: CostTotal): string;