@itookit/dsht 0.3.0 → 0.3.2

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;

package/dist/cost/pricing.js

@@ -0,0 +1,141 @@
+/** Versioned CNY price tables and the price decision taken for one request sample. */
+import { object } from "../transport/wire.js";
+import { MISSING_USAGE } from "./types.js";
+const clocks = new Map();
+/** Published rates verified on 2026-09-10; preceding dates require historical configuration.
+ * Flash and Pro are priced independently, and a separate cache write uses the cache-miss input rate.
+ */
+const OFFICIAL_PRICING = 'https://api-docs.deepseek.com/zh-cn/quick_start/pricing/';
+const PEAK_SCHEDULE = { weekdays: [1, 2, 3, 4, 5], windows: [[540, 720], [840, 1080]] };
+const FLASH_RATES = { peak: { input: 2, cacheRead: 0.04, cacheWrite: 2, output: 8 },
+    offPeak: { input: 1, cacheRead: 0.02, cacheWrite: 1, output: 4 } };
+const PRO_RATES = { peak: { input: 9, cacheRead: 0.3, cacheWrite: 9, output: 27 },
+    offPeak: { input: 4.5, cacheRead: 0.15, cacheWrite: 4.5, output: 13.5 } };
+export const DEFAULT_PRICES = [
+    { id: 'deepseek-2026-09-10-flash', provider: 'deepseek-official', model: 'deepseek-flash',
+        from: '2026-09-10T00:00:00+08:00', currency: 'CNY', source: OFFICIAL_PRICING, timezone: 'Asia/Shanghai',
+        ...PEAK_SCHEDULE, ...FLASH_RATES },
+    { id: 'deepseek-2026-09-10-pro', provider: 'deepseek-official', model: 'deepseek-v4-pro',
+        from: '2026-09-10T00:00:00+08:00', until: '2026-09-14T12:00:00+08:00', currency: 'CNY',
+        source: OFFICIAL_PRICING, timezone: 'Asia/Shanghai', ...PEAK_SCHEDULE, ...PRO_RATES },
+    // The provider bills `deepseek-v4-pro` requests at Flash rates once V4 Pro is retired.
+    { id: 'deepseek-2026-09-14-pro-served-by-flash', provider: 'deepseek-official', model: 'deepseek-v4-pro',
+        from: '2026-09-14T12:00:00+08:00', currency: 'CNY', source: OFFICIAL_PRICING, timezone: 'Asia/Shanghai',
+        ...PEAK_SCHEDULE, ...FLASH_RATES },
+];
+/** Validate user-maintained price versions, rejecting ambiguous overlapping intervals.
+ * @param value - Parsed prices.json array.
+ * @returns Price versions with validated rates and schedules.
+ */
+export function pricesFrom(value) {
+    if (!Array.isArray(value))
+        throw new Error('prices.json must contain an array');
+    const ids = new Set();
+    for (const raw of value) {
+        const p = object(raw);
+        for (const key of ['id', 'provider', 'model', 'source', 'timezone', 'from'])
+            if (typeof p[key] !== 'string' || !p[key])
+                throw new Error(`Invalid price ${key}`);
+        if (ids.has(String(p.id)))
+            throw new Error('Duplicate price id');
+        ids.add(String(p.id));
+        const from = Date.parse(String(p.from));
+        const until = p.until === undefined ? Infinity : Date.parse(String(p.until));
+        if (!Number.isFinite(from) || !(until > from) || p.currency !== 'CNY')
+            throw new Error('Invalid price interval or currency');
+        new Intl.DateTimeFormat('en', { timeZone: String(p.timezone) }).format();
+        for (const key of ['peak', 'offPeak'])
+            for (const bucket of ['input', 'cacheRead', 'cacheWrite', 'output']) {
+                const rate = object(p[key])[bucket];
+                if (typeof rate !== 'number' || !Number.isFinite(rate) || rate < 0)
+                    throw new Error('Invalid token rate');
+            }
+        if (!Array.isArray(p.weekdays) || p.weekdays.some(d => typeof d !== 'number' || !Number.isInteger(d) || d < 0 || d > 6)
+            || !Array.isArray(p.windows) || p.windows.some(w => !Array.isArray(w) || w.length !== 2 || w.some(n => typeof n !== 'number' || !Number.isInteger(n)) || Number(w[0]) < 0 || Number(w[1]) > 1440 || Number(w[0]) >= Number(w[1])))
+            throw new Error('Invalid peak schedule');
+    }
+    const prices = value;
+    for (const [index, p] of prices.entries())
+        for (const q of prices.slice(index + 1)) {
+            if (p.provider === q.provider && p.model === q.model && Date.parse(p.from) < (q.until ? Date.parse(q.until) : Infinity)
+                && Date.parse(q.from) < (p.until ? Date.parse(p.until) : Infinity))
+                throw new Error('Overlapping price intervals');
+        }
+    return prices;
+}
+/** 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 function costDay(time) { return new Date(time + 8 * 3600_000).toISOString().slice(0, 10); }
+/** Price family used when a recorded model name has no exact entry. */
+function priceFamily(model) { return model.toLowerCase().includes('pro') ? 'deepseek-v4-pro' : 'deepseek-flash'; }
+/** Candidate versions for one request: its exact model first, then the official model family. */
+function candidates(prices, provider, model) {
+    const exact = prices.filter(p => p.provider === provider && p.model === model);
+    if (exact.length)
+        return exact;
+    return provider === 'deepseek-official' ? prices.filter(p => p.model === priceFamily(model)) : [];
+}
+/** 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 function priceAt(prices, provider, model, time) {
+    const price = candidates(prices, provider, model).find(p => Date.parse(p.from) <= time && (p.until === undefined || time < Date.parse(p.until)));
+    if (!price)
+        return;
+    let clock = clocks.get(price.timezone);
+    if (!clock) {
+        clock = new Intl.DateTimeFormat('en-US', { timeZone: price.timezone, weekday: 'short', hour: '2-digit', minute: '2-digit', hourCycle: 'h23' });
+        clocks.set(price.timezone, clock);
+    }
+    const parts = clock.formatToParts(time);
+    const part = (name) => parts.find(p => p.type === name).value;
+    const day = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'].indexOf(part('weekday'));
+    const minute = Number(part('hour')) * 60 + Number(part('minute'));
+    return { price, rates: price.weekdays.includes(day) && price.windows.some(([a, b]) => minute >= a && minute < b) ? price.peak : price.offPeak };
+}
+/** 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 function lowestPrice(prices, provider, model) {
+    let best;
+    for (const price of candidates(prices, provider, model)) {
+        if (best === undefined || price.offPeak.input < best.rates.input)
+            best = { price, rates: price.offPeak };
+    }
+    return best;
+}
+/** 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 function chargeFor(prices, provider, model, time, usage) {
+    if (!usage)
+        return { reason: MISSING_USAGE };
+    const selected = time === undefined ? lowestPrice(prices, provider, model) : priceAt(prices, provider, model, time);
+    if (!selected)
+        return { reason: 'no price version' };
+    const amount = (usage.input * selected.rates.input + usage.output * selected.rates.output
+        + usage.cacheRead * selected.rates.cacheRead + usage.cacheWrite * selected.rates.cacheWrite) / 1e6;
+    if (!Number.isFinite(amount))
+        return { reason: 'invalid estimate' };
+    return { priceId: selected.price.id, amount, ...(time === undefined ? { estimated: true } : {}) };
+}

package/dist/cost/records.d.ts

@@ -0,0 +1,17 @@
+/** Fold host history records into per-request samples; conversation text never enters the ledger. */
+import { type ObjectValue } from '../transport/wire.ts';
+import type { ChargeSample } from './types.ts';
+/** Keep only billing-relevant fields; prompts, tool bodies, cookies and keys never enter the ledger.
+ * @param records - One HTTP history page's records.
+ * @returns Minimal durable events for a deterministic usage fold.
+ */
+export declare function costRecords(records: unknown): ObjectValue[];
+/** Fold minimal billing events into one sample per model attempt.
+ *
+ * A replacement sample in the same turn and step updates its attempt's sample, a retry starts a
+ * new one, and fork-inherited records are excluded. The sample carries no amount: deciding one
+ * belongs to the ledger, which records the decision once.
+ * @param events - Minimal events returned by `costRecords`, across all history pages.
+ * @returns Ordered samples with the last valid usage observed for each attempt.
+ */
+export declare function foldSamples(events: readonly ObjectValue[]): ChargeSample[];

package/dist/cost/records.js

@@ -0,0 +1,66 @@
+/** Fold host history records into per-request samples; conversation text never enters the ledger. */
+import { array, object } from "../transport/wire.js";
+/** Host event types that carry billing-relevant usage or route context. */
+const BILLING_EVENTS = new Set(['request/context', 'assistant/message', 'assistant/attempt', 'llm/retry-started', 'session/end-seed']);
+/** Keep only billing-relevant fields; prompts, tool bodies, cookies and keys never enter the ledger.
+ * @param records - One HTTP history page's records.
+ * @returns Minimal durable events for a deterministic usage fold.
+ */
+export function costRecords(records) {
+    return array(records).map(raw => object(object(raw).event)).filter(e => BILLING_EVENTS.has(String(e.type))).map(e => {
+        const d = object(e.data);
+        const m = object(d.message ?? {});
+        const stream = array(d.stream ?? []).map(r => object(object(r).chunk ?? {})).filter(c => c.type === 'usage');
+        return { seq: e.seq ?? null, time: e.time ?? null, type: e.type, data: {
+                inherited: d.inherited ?? false, turn: d.turn ?? null, step: d.step ?? null, provider: d.provider ?? null, model: d.model ?? null,
+                source: m.source ?? null, usage: d.usage ?? stream.at(-1)?.usage ?? null,
+            } };
+    });
+}
+/** Fold minimal billing events into one sample per model attempt.
+ *
+ * A replacement sample in the same turn and step updates its attempt's sample, a retry starts a
+ * new one, and fork-inherited records are excluded. The sample carries no amount: deciding one
+ * belongs to the ledger, which records the decision once.
+ * @param events - Minimal events returned by `costRecords`, across all history pages.
+ * @returns Ordered samples with the last valid usage observed for each attempt.
+ */
+export function foldSamples(events) {
+    const inheritedCut = Math.max(-1, ...events.filter(e => e.type === 'session/end-seed' && object(e.data).inherited === true).map(e => Number(e.seq)));
+    const samples = [];
+    let route = {};
+    let last;
+    for (const e of [...new Map(events.map(e => [Number(e.seq), e])).values()].sort((a, b) => Number(a.seq) - Number(b.seq))) {
+        const d = object(e.data);
+        if (e.type === 'request/context') {
+            route = d;
+            continue;
+        }
+        if (Number(e.seq) <= inheritedCut || e.type === 'session/end-seed')
+            continue;
+        if (e.type === 'llm/retry-started') {
+            if (last?.turn === d.turn && last?.step === d.step)
+                last = undefined;
+            continue;
+        }
+        const source = object(d.source ?? {});
+        const provider = String(source.provider ?? route.provider ?? '');
+        const model = String(source.model ?? route.model ?? '');
+        const time = typeof e.time === 'number' && Number.isFinite(e.time) && e.time >= 0 && e.time <= 8.64e15 ? e.time : undefined;
+        const usage = validUsage(d.usage);
+        const index = last && d.turn !== null && d.step !== null && last.turn === d.turn && last.step === d.step ? last.index : samples.length;
+        if (!usage && samples[index]?.usage)
+            continue;
+        samples[index] = { key: samples[index]?.key ?? String(e.seq), ...(time === undefined ? {} : { time }), provider, model, ...(usage ? { usage } : {}) };
+        last = { turn: d.turn, step: d.step, index };
+    }
+    return samples;
+}
+/** Accept a token report only when every bucket is a non-negative integer and totals agree. */
+function validUsage(value) {
+    const u = object(value ?? {});
+    const buckets = [u.inputTokens, u.outputTokens, u.cacheReadTokens ?? 0, u.cacheWriteTokens ?? 0];
+    const valid = buckets.every(n => typeof n === 'number' && Number.isSafeInteger(n) && n >= 0)
+        && (u.totalTokens === undefined || typeof u.totalTokens === 'number' && Number.isSafeInteger(u.totalTokens) && u.totalTokens === buckets.reduce((sum, n) => sum + Number(n), 0));
+    return valid ? { input: Number(buckets[0]), output: Number(buckets[1]), cacheRead: Number(buckets[2]), cacheWrite: Number(buckets[3]) } : undefined;
+}

package/dist/cost/scanner.d.ts

@@ -0,0 +1,22 @@
+/** Address and page one session's complete billing history over the host connection. */
+import { type Client } from '../transport/client.ts';
+import { type ObjectValue } from '../transport/wire.ts';
+/** Wire addresses for one `session/list` row, in the order the cost scan should try them.
+ *
+ * A subagent child is reachable only under its durable parent, and the list row omits the delivery
+ * mode, so both modes are offered with the continuable form first.
+ * @param session - One row from the host session list.
+ * @returns One plain-session address, or both subagent forms when the row is a child.
+ */
+export declare function costAddresses(session: ObjectValue): ObjectValue[];
+/** Read one session's complete cost history, retrying a subagent child with its other delivery mode.
+ * @param client - Authenticated host transport.
+ * @param session - One row from the host session list.
+ * @param signal - Cancels paging without cancelling any agent work.
+ * @param onPage - Counts each history request, so a scan can report how much it re-read.
+ * @returns Opening cursor and the minimal billing events behind it.
+ */
+export declare function sessionCostHistory(client: Client, session: ObjectValue, signal: AbortSignal, onPage?: () => void): Promise<{
+    cursor: number;
+    events: ObjectValue[];
+}>;