@itookit/dsht 0.2.4 → 0.3.2

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/controller.d.ts

@@ -0,0 +1,34 @@
+/** 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. */
+    start(): void;
+    /** Stop the timer and wait for an in-flight scan; the ledger keeps its cached charges. */
+    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,107 @@
+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. */
+    start() {
+        if (this.timer)
+            return;
+        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 cached charges. */
+    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,9 @@
+/** Cost domain: price tables, record folding, the immutable ledger, the scanner and its controller. */
+export { CostController } from './controller.ts';
+export type { CostHost } from './controller.ts';
+export { CostLedger, costText } from './ledger.ts';
+export { chargeFor, costDay, DEFAULT_PRICES, lowestPrice, priceAt, pricesFrom } from './pricing.ts';
+export { costRecords, foldSamples } from './records.ts';
+export { costAddresses, sessionCostHistory } from './scanner.ts';
+export { MISSING_USAGE } from './types.ts';
+export type { Charge, ChargeSample, CostTotal, Coverage, PriceDecision, PriceVersion, Rates, SavedCost, Usage } from './types.ts';

package/dist/cost/index.js

@@ -0,0 +1,7 @@
+/** Cost domain: price tables, record folding, the immutable ledger, the scanner and its controller. */
+export { CostController } from "./controller.js";
+export { CostLedger, costText } from "./ledger.js";
+export { chargeFor, costDay, DEFAULT_PRICES, lowestPrice, priceAt, pricesFrom } from "./pricing.js";
+export { costRecords, foldSamples } from "./records.js";
+export { costAddresses, sessionCostHistory } from "./scanner.js";
+export { MISSING_USAGE } from "./types.js";

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

@@ -0,0 +1,20 @@
+import type { SavedCost } from './types.ts';
+/** Load every session's newest cut, leaving one fixed file per session.
+ *
+ * A file of another generation, a file with an unreadable shape, and a cut file superseded by the
+ * newer name all describe work the next scan rebuilds, so loading removes them; the newest slice
+ * of a superseded name is rewritten under the fixed one first. Files this unit does not own are
+ * left where they are.
+ * @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 cut unless the directory already holds a newer one.
+ *
+ * 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.
+ * @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,128 @@
+/** Atomic per-session persistence for the immutable charge ledger. */
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+import { ensureDirectory, listEntries, readText, removeFile, writePrivateFile } from "../storage/index.js";
+/** Current on-disk ledger generation. Files of another generation are ignored, not migrated. */
+const LEDGER_VERSION = 2;
+/** Every file this unit owns: the fixed per-session name, or the `<session>-<cut>.json` it replaced. */
+const OWNED_FILE = /^[0-9a-f]{64}(?:-\d+)?\.json$/;
+/** The one file that holds a session's newest cut; the cut itself lives inside the file. */
+function ledgerName(sessionId) {
+    return `${createHash('sha256').update(sessionId).digest('hex')}.json`;
+}
+/** Load every session's newest cut, leaving one fixed file per session.
+ *
+ * A file of another generation, a file with an unreadable shape, and a cut file superseded by the
+ * newer name all describe work the next scan rebuilds, so loading removes them; the newest slice
+ * of a superseded name is rewritten under the fixed one first. Files this unit does not own are
+ * left where they are.
+ * @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);
+    const superseded = [];
+    for (const name of await listEntries(directory)) {
+        if (!OWNED_FILE.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);
+        if (saved === undefined) {
+            await removeFile(path);
+            continue;
+        }
+        if ((sessions.get(saved.sessionId)?.cut ?? -2) <= saved.cut)
+            sessions.set(saved.sessionId, saved);
+        if (name !== ledgerName(saved.sessionId))
+            superseded.push({ path, sessionId: saved.sessionId });
+    }
+    for (const { path, sessionId } of superseded) {
+        await writePrivateFile(join(directory, ledgerName(sessionId)), JSON.stringify(sessions.get(sessionId)) + '\n');
+        await removeFile(path);
+    }
+    return sessions;
+}
+/** Write one session cut unless the directory already holds a newer one.
+ *
+ * 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.
+ * @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 && persistedCut(existing) > saved.cut)
+        return false;
+    await writePrivateFile(path, JSON.stringify(saved) + '\n');
+    return true;
+}
+/** The cut already persisted in one file, or -1 when it holds no decision worth keeping.
+ * @param raw - File contents read from the ledger directory.
+ * @returns The persisted cut.
+ */
+function persistedCut(raw) {
+    try {
+        return parseLedger(raw)?.cut ?? -1;
+    }
+    // A file of another generation or an unreadable shape carries no decision, so the new cut replaces it.
+    catch {
+        return -1;
+    }
+}
+/** Validate one persisted ledger; 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) || !Array.isArray(record.charges)) {
+        throw new Error('Invalid cost ledger');
+    }
+    const charges = record.charges;
+    if (!charges.every(validCharge))
+        throw new Error('Invalid cost ledger');
+    return { version: LEDGER_VERSION, sessionId: record.sessionId, cut: record.cut, charges: charges };
+}
+/** One charge is valid when every recorded field is present with the type the fold writes. */
+function validCharge(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const c = value;
+    if (typeof c.key !== 'string' || typeof c.provider !== 'string' || typeof c.model !== 'string')
+        return false;
+    if (c.priceId !== undefined && typeof c.priceId !== 'string')
+        return false;
+    if (c.reason !== undefined && typeof c.reason !== 'string')
+        return false;
+    if (c.amount !== undefined && (typeof c.amount !== 'number' || !Number.isFinite(c.amount) || c.amount < 0))
+        return false;
+    if (c.estimated !== undefined && c.estimated !== true)
+        return false;
+    if (c.time !== undefined && (typeof c.time !== 'number' || !Number.isFinite(c.time) || c.time < 0 || c.time > 8.64e15))
+        return false;
+    if (c.usage !== undefined) {
+        if (typeof c.usage !== 'object' || c.usage === null || Array.isArray(c.usage))
+            return false;
+        const buckets = Object.values(c.usage);
+        if (buckets.length === 0 || buckets.some(n => typeof n !== 'number' || !Number.isSafeInteger(n) || n < 0))
+            return false;
+    }
+    return true;
+}

package/dist/cost/ledger.d.ts

@@ -0,0 +1,65 @@
+/** Immutable CNY ledger: a charge is priced once and never follows later price configuration. */
+import type { ObjectValue } from '../transport/wire.ts';
+import { type CostTotal, type Coverage, type PriceVersion } from './types.ts';
+/** Per-origin cache of decided request charges; each scan replaces a session at a fixed cut. */
+export declare class CostLedger {
+    readonly prices: PriceVersion[];
+    readonly directory?: string | undefined;
+    private sessions;
+    private totals;
+    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);
+    /** Cached charges 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 complete cut per session; recorded amounts load without re-pricing. */
+    load(): Promise<void>;
+    /** Replace one session using all billing events through the opening snapshot cut.
+     *
+     * Sampling is replayed, but a charge that an earlier scan already decided keeps its recorded
+     * `priceId` and `amount`, so editing `prices.json` only affects requests decided afterwards.
+     * @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.
+     */
+    replace(sessionId: string, cut: number, events: ObjectValue[]): Promise<void>;
+    /** Count the retained ledger so a memory sample can separate it from the transcript window.
+     * @returns Sessions and charges currently held, and how many charges carry no amount.
+     */
+    summary(): {
+        sessions: number;
+        charges: number;
+        unpriced: number;
+    };
+    /** Whether this session has a complete cached scan.
+     * @param sessionId - Selected session identity.
+     * @returns True when a complete scan is available.
+     */
+    hasSession(sessionId?: string): boolean;
+    /** Describe unpriced model/usage combinations without exposing conversation content.
+     * @returns Unique reasons across cached sessions.
+     */
+    missing(): string[];
+    /** Summarize recorded requests across one session or Beijing calendar days.
+     * @param sessionId - Optional session restriction.
+     * @param days - Today or today plus the preceding two calendar days.
+     * @param now - Clock used for date attribution.
+     * @returns Known subtotal, unpriceable count, and estimated count; an estimated record always
+     *   names an amount, but a dated range only adds the records it can place inside that range.
+     */
+    total(sessionId?: string, days?: 1 | 3, 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;

package/dist/cost/ledger.js

@@ -0,0 +1,136 @@
+import { chargeFor, costDay, DEFAULT_PRICES } from "./pricing.js";
+import { foldSamples } from "./records.js";
+import { loadLedgers, saveLedger } from "./ledger-files.js";
+import { MISSING_USAGE } from "./types.js";
+/** Whether a charge already carries a decision that a later scan must keep. */
+function sealed(charge) {
+    return charge.amount !== undefined || (charge.reason !== undefined && charge.reason !== MISSING_USAGE);
+}
+/** Attach the current table's decision, or reuse the decision an earlier scan recorded.
+ *
+ * A sample without usage has not finished reporting tokens, so it stays open for the next scan;
+ * every other decision — priced, unpriced, or estimated — is final.
+ */
+function decide(prices, sample, previous) {
+    if (previous !== undefined && (sealed(previous) || sample.usage === undefined))
+        return previous;
+    return { ...sample, ...chargeFor(prices, sample.provider, sample.model, sample.time, sample.usage) };
+}
+/** Per-origin cache of decided request charges; each scan replaces a session at a fixed cut. */
+export class CostLedger {
+    prices;
+    directory;
+    sessions = new Map();
+    totals = new Map();
+    scannedAt;
+    scanning = false;
+    error = '';
+    /** Work the last completed scan performed, so a memory sample can attribute its allocation. */
+    lastScan;
+    constructor(prices = DEFAULT_PRICES, directory) {
+        this.prices = prices;
+        this.directory = directory;
+    }
+    /** Cached charges 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() {
+        if (this.scanning)
+            return 'scanning';
+        if (this.error)
+            return 'partial';
+        return this.scannedAt !== undefined || this.sessions.size > 0 ? 'complete' : 'partial';
+    }
+    /** Load the newest complete cut per session; recorded amounts load without re-pricing. */
+    async load() {
+        this.totals.clear();
+        for (const [sessionId, saved] of await loadLedgers(this.directory)) {
+            if ((this.sessions.get(sessionId)?.cut ?? -2) <= saved.cut)
+                this.sessions.set(sessionId, saved);
+        }
+    }
+    /** Replace one session using all billing events through the opening snapshot cut.
+     *
+     * Sampling is replayed, but a charge that an earlier scan already decided keeps its recorded
+     * `priceId` and `amount`, so editing `prices.json` only affects requests decided afterwards.
+     * @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.
+     */
+    async replace(sessionId, cut, events) {
+        const current = this.sessions.get(sessionId);
+        if ((current?.cut ?? -2) > cut)
+            return;
+        const previous = new Map((current?.charges ?? []).map(charge => [charge.key, charge]));
+        const charges = foldSamples(events).map(sample => decide(this.prices, sample, previous.get(sample.key)));
+        const saved = { version: 2, sessionId, cut, charges };
+        // Another process may have persisted a newer cut of this session since it was last read.
+        if (this.directory && !await saveLedger(this.directory, saved))
+            return;
+        this.sessions.set(sessionId, saved);
+        this.totals.clear();
+    }
+    /** Count the retained ledger so a memory sample can separate it from the transcript window.
+     * @returns Sessions and charges currently held, and how many charges carry no amount.
+     */
+    summary() {
+        let charges = 0, unpriced = 0;
+        for (const session of this.sessions.values()) {
+            charges += session.charges.length;
+            unpriced += session.charges.filter(charge => charge.amount === undefined).length;
+        }
+        return { sessions: this.sessions.size, charges, unpriced };
+    }
+    /** Whether this session has a complete cached scan.
+     * @param sessionId - Selected session identity.
+     * @returns True when a complete scan is available.
+     */
+    hasSession(sessionId) { return sessionId !== undefined && this.sessions.has(sessionId); }
+    /** Describe unpriced model/usage combinations without exposing conversation content.
+     * @returns Unique reasons across cached sessions.
+     */
+    missing() {
+        return [...new Set([...this.sessions.values()].flatMap(s => s.charges.filter(c => c.amount === undefined).map(c => `${c.provider}/${c.model}: ${c.reason}`)))];
+    }
+    /** Summarize recorded requests across one session or Beijing calendar days.
+     * @param sessionId - Optional session restriction.
+     * @param days - Today or today plus the preceding two calendar days.
+     * @param now - Clock used for date attribution.
+     * @returns Known subtotal, unpriceable count, and estimated count; an estimated record always
+     *   names an amount, but a dated range only adds the records it can place inside that range.
+     */
+    total(sessionId, days, now = Date.now()) {
+        const cacheKey = JSON.stringify([sessionId, days, days ? costDay(now) : '']);
+        const cached = this.totals.get(cacheKey);
+        if (cached)
+            return cached;
+        const result = { amount: 0, unknown: 0, estimated: 0, records: 0 };
+        const end = costDay(now);
+        const start = costDay(now - ((days ?? 1) - 1) * 86400_000);
+        for (const session of this.sessions.values()) {
+            if (sessionId !== undefined && session.sessionId !== sessionId)
+                continue;
+            for (const charge of session.charges) {
+                if (days && charge.time !== undefined && (costDay(charge.time) < start || costDay(charge.time) > end))
+                    continue;
+                result.records++;
+                if (charge.amount === undefined) {
+                    result.unknown++;
+                    continue;
+                }
+                const dated = days === undefined || charge.time !== undefined;
+                if (charge.estimated === true || !dated)
+                    result.estimated++;
+                if (dated)
+                    result.amount += charge.amount;
+            }
+        }
+        this.totals.set(cacheKey, result);
+        return result;
+    }
+}
+/** Compact estimates retain an asterisk whenever a subtotal is not exact.
+ * @param total - Summary from the ledger.
+ * @returns Yuan amount and incompleteness marker.
+ */
+export function costText(total) { return `~¥${total.amount.toFixed(4)}${total.unknown || total.estimated ? '*' : ''}`; }

package/dist/cost/pricing.d.ts

@@ -0,0 +1,48 @@
+import { type PriceDecision, type PriceVersion, type Rates, type Usage } from './types.ts';
+export declare const DEFAULT_PRICES: PriceVersion[];
+/** Validate user-maintained price versions, rejecting ambiguous overlapping intervals.
+ * @param value - Parsed prices.json array.
+ * @returns Price versions with validated rates and schedules.
+ */
+export declare function pricesFrom(value: unknown): PriceVersion[];
+/** Return the calendar date used by both daily and three-calendar-day summaries.
+ * @param time - Epoch milliseconds.
+ * @returns Beijing calendar date, YYYY-MM-DD.
+ */
+export declare function costDay(time: number): string;
+/** Select a price by event time, applying half-open local peak windows.
+ * @param prices - Validated versions.
+ * @param provider - Provider identity from the recorded request.
+ * @param model - Recorded model name; official DeepSeek aliases fall back to Pro when containing pro, otherwise Flash.
+ * @param time - Recorded settlement timestamp used as a billing-time estimate.
+ * @returns Matching price version and per-million-token rates, if known.
+ */
+export declare function priceAt(prices: PriceVersion[], provider: string, model: string, time: number): {
+    price: PriceVersion;
+    rates: Rates;
+} | undefined;
+/** Select a rate without a settlement time, so an unattributable request still enters the total.
+ * The cheapest candidate off-peak rate is a floor: it never overstates, and the charge stays
+ * marked as estimated.
+ * @param prices - Validated versions.
+ * @param provider - Provider identity from the recorded request.
+ * @param model - Recorded model name.
+ * @returns The candidate version with the lowest off-peak input rate and its rates, if any.
+ */
+export declare function lowestPrice(prices: PriceVersion[], provider: string, model: string): {
+    price: PriceVersion;
+    rates: Rates;
+} | undefined;
+/** Decide the amount for one request sample using the table loaded at decision time.
+ *
+ * The returned decision is recorded once and never revisited: a later `prices.json` change must
+ * not move a historical amount. Only a sample with no usable usage (`missing usage`) is left
+ * undecided, because its request has not finished reporting tokens yet.
+ * @param prices - Validated versions currently loaded.
+ * @param provider - Provider identity from the recorded request.
+ * @param model - Recorded model name.
+ * @param time - Recorded settlement timestamp, when the host logged one.
+ * @param usage - Disjoint token buckets, when the host reported valid counts.
+ * @returns The selected price identity, the amount, and the reason when no amount exists.
+ */
+export declare function chargeFor(prices: PriceVersion[], provider: string, model: string, time: number | undefined, usage: Usage | undefined): PriceDecision;