@itookit/dsht 0.3.0 → 0.3.3

package/dist/cost/ledger.js

@@ -0,0 +1,146 @@
+import { chargeFor, costDay, DEFAULT_PRICES, pricesDigest, PRICING_ENGINE_VERSION } from "./pricing.js";
+import { foldSamples } from "./records.js";
+import { loadLedgers, saveLedger } from "./ledger-files.js";
+/** Reasons one slice keeps at most, so a broken table cannot grow the ledger without bound. */
+const UNPRICED_LIMIT = 8;
+/** Per-origin cache of folded session totals; every scan replaces a session at its cut. */
+export class CostLedger {
+    prices;
+    directory;
+    customPrices;
+    sessions = new Map();
+    totals = new Map();
+    catalog;
+    scannedAt;
+    scanning = false;
+    error = '';
+    /** Work the last completed scan performed, so a memory sample can attribute its allocation. */
+    lastScan;
+    constructor(prices = DEFAULT_PRICES, directory, 
+    /** Whether the table came from a file the user maintains, rather than the shipped one. */
+    customPrices = false) {
+        this.prices = prices;
+        this.directory = directory;
+        this.customPrices = customPrices;
+        this.catalog = pricesDigest(prices);
+    }
+    /** 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() {
+        if (this.scanning)
+            return 'scanning';
+        if (this.error)
+            return 'partial';
+        return this.scannedAt !== undefined || this.sessions.size > 0 ? 'complete' : 'partial';
+    }
+    /** Load the newest cut per session; a stored total is read as it was decided. */
+    async load() {
+        this.totals.clear();
+        this.sessions = await loadLedgers(this.directory);
+    }
+    /** 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.
+     */
+    async replace(sessionId, cut, events, now = Date.now()) {
+        const current = this.sessions.get(sessionId);
+        if ((current?.cut ?? -2) > cut)
+            return;
+        const day = costDay(now);
+        const total = { amount: 0, unknown: 0, records: 0 };
+        const today = { day, amount: 0, unknown: 0, records: 0 };
+        const unpriced = new Set();
+        for (const sample of foldSamples(events)) {
+            const decision = chargeFor(this.prices, sample.provider, sample.model, sample.time, sample.usage);
+            // A request belongs to the day it settled on, so the day bucket only counts the requests of
+            // the calendar day this scan is running on; another day reads as nothing spent today. A request
+            // with no settlement time belongs to no day, so it is counted as unknown wherever it is read.
+            const buckets = sample.time === undefined || costDay(sample.time) === day ? [total, today] : [total];
+            for (const bucket of buckets) {
+                bucket.records++;
+                if (decision.amount === undefined)
+                    bucket.unknown++;
+                else
+                    bucket.amount += decision.amount;
+            }
+            if (decision.amount === undefined && unpriced.size < UNPRICED_LIMIT)
+                unpriced.add(`${sample.provider}/${sample.model}: ${decision.reason}`);
+        }
+        const saved = { version: 3, sessionId, cut, engine: PRICING_ENGINE_VERSION, catalog: this.catalog,
+            total, day: today, unpriced: [...unpriced] };
+        // 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, requests and unpriced requests currently held.
+     */
+    summary() {
+        let records = 0, unpriced = 0;
+        for (const session of this.sessions.values()) {
+            records += session.total.records;
+            unpriced += session.total.unknown;
+        }
+        return { sessions: this.sessions.size, records, unpriced };
+    }
+    /** 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) { 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.unpriced))]; }
+    /** 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) {
+        const cached = this.totals.get(`s:${sessionId}`);
+        if (cached)
+            return cached;
+        const session = this.sessions.get(sessionId);
+        const result = session === undefined ? { amount: 0, unknown: 0, records: 0 } : { ...session.total };
+        this.totals.set(`s:${sessionId}`, result);
+        return result;
+    }
+    /** 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 = Date.now()) {
+        const day = costDay(now);
+        const cached = this.totals.get(`d:${day}`);
+        if (cached)
+            return cached;
+        const result = { amount: 0, unknown: 0, records: 0 };
+        for (const session of this.sessions.values()) {
+            if (session.day.day !== day)
+                continue;
+            result.amount += session.day.amount;
+            result.unknown += session.day.unknown;
+            result.records += session.day.records;
+        }
+        this.totals.set(`d:${day}`, 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 ? '*' : ''}`; }

package/dist/cost/pricing.d.ts

@@ -0,0 +1,86 @@
+import { type PriceDecision, type PriceVersion, type Rates, type Usage } from './types.ts';
+export declare const DEFAULT_PRICES: PriceVersion[];
+/** Revision of the pricing decision rules, recorded with the totals they decided.
+ *
+ * Bump it whenever the rules change what an amount would be — the matching of a model name, the
+ * token buckets an amount covers, or the timestamp it is priced at — so a stored total can be traced
+ * to the rules that produced it. Version 1 matched a model by the substring `pro` and priced a
+ * request with no settlement time at the cheapest off-peak rate.
+ */
+export declare const PRICING_ENGINE_VERSION = 2;
+/** Revision of the shipped table, recorded beside a seeded file so a correction can replace it. */
+export declare const PRICES_REVISION = "2026-09-12";
+/** Whether a table is the seed an earlier revision wrote, which a corrected ship must replace.
+ *
+ * `prices.json` overrides the shipped table, so an install seeded before the Flash rates were
+ * corrected keeps charging 1.5x for input and 2.5x for cache reads for as long as that file lives.
+ * Only an exact match to the superseded revision qualifies, so a rate the user chose is never rewritten.
+ * @param prices - Table loaded from the configuration file.
+ * @returns True when every entry carries the superseded revision's rates.
+ */
+export declare function isUncorrectedSeed(prices: readonly PriceVersion[]): boolean;
+/** 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 Beijing calendar date a request is attributed to.
+ * @param time - Epoch milliseconds.
+ * @returns Beijing calendar date, YYYY-MM-DD.
+ */
+export declare function costDay(time: number): string;
+/** Canonical form of a model name before matching.
+ *
+ * The host reports names that differ from the published table by width, case, surrounding space, or
+ * the CJK full stop a display path can substitute for a period. Normalizing here keeps the table
+ * readable and keeps a name variant from silently missing its entry. NFKC does not fold the CJK
+ * stops, so they are mapped explicitly.
+ * @param model - Model name exactly as the recorded request reported it.
+ * @returns The name in the form the table is matched against.
+ */
+export declare function canonicalModel(model: string): string;
+/** Candidate versions for one request, in the order the table is searched: the exact model, then
+ * the aliases a version declares. A name the table does not cover stays unpriced rather than
+ * falling back to a family guess, because guessing a rate is indistinguishable from a wrong one.
+ * @param prices - Validated versions.
+ * @param provider - Provider identity from the recorded request.
+ * @param model - Recorded model name.
+ * @returns Matching versions, each with the rule that matched it.
+ */
+export declare function candidates(prices: PriceVersion[], provider: string, model: string): {
+    price: PriceVersion;
+    matchedBy: 'exact' | 'alias';
+}[];
+/** Stable identity of a loaded price table.
+ *
+ * The identity a price version carries can be edited in place while keeping its `id` — which is how
+ * a corrected table once kept charging superseded rates under one id — so a stored total records a
+ * digest of the whole table it was decided from, not only the version names.
+ * @param prices - Price versions loaded for this process.
+ * @returns Short digest of the table.
+ */
+export declare function pricesDigest(prices: readonly PriceVersion[]): 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.
+ * @param time - Recorded settlement timestamp used as the billing instant.
+ * @returns Matching price version, the rule that matched it, and its per-million-token rates.
+ */
+export declare function priceAt(prices: PriceVersion[], provider: string, model: string, time: number): {
+    price: PriceVersion;
+    rates: Rates;
+    matchedBy: 'exact' | 'alias';
+} | undefined;
+/** Decide the amount for one request sample using the table loaded at decision time.
+ *
+ * A decision is a number or a reason; nothing about the rates that produced it is kept, because the
+ * ledger stores totals rather than requests and the next scan decides the sample again.
+ * @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 amount, or the reason 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,223 @@
+/** Versioned CNY price tables and the price decision taken for one request sample. */
+import { createHash } from 'node:crypto';
+import { object } from "../transport/wire.js";
+import { MISSING_TIME, MISSING_USAGE, UNSUPPORTED_USAGE } from "./types.js";
+const clocks = new Map();
+/** Published rates verified on 2026-09-12; 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 = [
+    // The published table states that superseded Flash names stay callable and are served by
+    // V4.1-Flash at Flash rates, so every name the host can report is listed instead of guessed at.
+    { id: 'deepseek-2026-09-10-flash', provider: 'deepseek-official', model: 'deepseek-flash',
+        aliases: ['deepseek-v4-flash', 'deepseek-v4-flash-vision-exp', 'deepseek-v4-flash*', 'deepseek-v4.1-flash*', 'deepseek-v4.1-flash'],
+        from: '2026-09-10T00:00:00+08:00', currency: 'CNY', source: OFFICIAL_PRICING, timezone: 'Asia/Shanghai',
+        ...PEAK_SCHEDULE, ...FLASH_RATES },
+    // The published table keeps V4 Pro available after 2026-09-14 at these rates, so the interval
+    // stays open until a later page names an end.
+    { id: 'deepseek-2026-09-10-pro', provider: 'deepseek-official', model: 'deepseek-v4-pro',
+        // No `deepseek-pro*`: a prefix that broad would also claim `deepseek-proxy-*` or `deepseek-prompt-*`.
+        aliases: ['deepseek-v4-pro', 'deepseek-v4-pro*', 'deepseek-v4.1-pro*'],
+        from: '2026-09-10T00:00:00+08:00', currency: 'CNY', source: OFFICIAL_PRICING, timezone: 'Asia/Shanghai',
+        ...PEAK_SCHEDULE, ...PRO_RATES },
+];
+/** Revision of the pricing decision rules, recorded with the totals they decided.
+ *
+ * Bump it whenever the rules change what an amount would be — the matching of a model name, the
+ * token buckets an amount covers, or the timestamp it is priced at — so a stored total can be traced
+ * to the rules that produced it. Version 1 matched a model by the substring `pro` and priced a
+ * request with no settlement time at the cheapest off-peak rate.
+ */
+export const PRICING_ENGINE_VERSION = 2;
+/** Revision of the shipped table, recorded beside a seeded file so a correction can replace it. */
+export const PRICES_REVISION = '2026-09-12';
+/** Rates the first published revision charged, rebuilt with the same arithmetic so the values compare equal.
+ * It only recognizes that seed; it never prices a request.
+ */
+const UNCORRECTED_SEED_RATES = Object.fromEntries(['deepseek-v4-flash', 'deepseek-v4-pro', 'deepseek-v4-flash-vision-exp'].map(model => {
+    const scale = model === 'deepseek-v4-pro' ? 3 : 1;
+    return [`deepseek-2026-09-10-${model}`, {
+            peak: { input: 3 * scale, cacheRead: 0.1 * scale, cacheWrite: 3 * scale, output: 9 * scale },
+            offPeak: { input: 1.5 * scale, cacheRead: 0.05 * scale, cacheWrite: 1.5 * scale, output: 4.5 * scale },
+        }];
+}));
+/** Whether a table is the seed an earlier revision wrote, which a corrected ship must replace.
+ *
+ * `prices.json` overrides the shipped table, so an install seeded before the Flash rates were
+ * corrected keeps charging 1.5x for input and 2.5x for cache reads for as long as that file lives.
+ * Only an exact match to the superseded revision qualifies, so a rate the user chose is never rewritten.
+ * @param prices - Table loaded from the configuration file.
+ * @returns True when every entry carries the superseded revision's rates.
+ */
+export function isUncorrectedSeed(prices) {
+    const superseded = Object.keys(UNCORRECTED_SEED_RATES);
+    return prices.length === superseded.length && prices.every(price => {
+        const legacy = UNCORRECTED_SEED_RATES[price.id];
+        return legacy !== undefined && sameRates(price.peak, legacy.peak) && sameRates(price.offPeak, legacy.offPeak);
+    });
+}
+/** Compare two rate sets, allowing the representation error a JSON round trip can introduce.
+ * @param a - One rate set.
+ * @param b - The other rate set.
+ * @returns True when every rate agrees.
+ */
+function sameRates(a, b) {
+    return ['input', 'cacheRead', 'cacheWrite', 'output'].every(bucket => Math.abs(a[bucket] - b[bucket]) < 1e-9);
+}
+/** 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));
+        if (p.aliases !== undefined && (!Array.isArray(p.aliases) || p.aliases.some(alias => typeof alias !== 'string' || alias === '')))
+            throw new Error('Invalid price aliases');
+        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 Beijing calendar date a request is attributed to.
+ * @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); }
+/** Canonical form of a model name before matching.
+ *
+ * The host reports names that differ from the published table by width, case, surrounding space, or
+ * the CJK full stop a display path can substitute for a period. Normalizing here keeps the table
+ * readable and keeps a name variant from silently missing its entry. NFKC does not fold the CJK
+ * stops, so they are mapped explicitly.
+ * @param model - Model name exactly as the recorded request reported it.
+ * @returns The name in the form the table is matched against.
+ */
+export function canonicalModel(model) {
+    return model.normalize('NFKC').replace(/[\u3002\uff0e\uff61]/g, '.').trim().toLowerCase();
+}
+/** Whether an alias matches a canonical model name, treating a trailing `*` as a prefix.
+ * @param alias - Alias declared by a price version.
+ * @param model - Canonical model name.
+ * @returns True when the alias covers the name.
+ */
+function aliasMatches(alias, model) {
+    const canonical = canonicalModel(alias);
+    return canonical.endsWith('*') ? model.startsWith(canonical.slice(0, -1)) : model === canonical;
+}
+/** Candidate versions for one request, in the order the table is searched: the exact model, then
+ * the aliases a version declares. A name the table does not cover stays unpriced rather than
+ * falling back to a family guess, because guessing a rate is indistinguishable from a wrong one.
+ * @param prices - Validated versions.
+ * @param provider - Provider identity from the recorded request.
+ * @param model - Recorded model name.
+ * @returns Matching versions, each with the rule that matched it.
+ */
+export function candidates(prices, provider, model) {
+    const canonical = canonicalModel(model);
+    const exact = prices.filter(p => p.provider === provider && canonicalModel(p.model) === canonical);
+    if (exact.length)
+        return exact.map(price => ({ price, matchedBy: 'exact' }));
+    return prices.filter(p => p.provider === provider && (p.aliases ?? []).some(alias => aliasMatches(alias, canonical)))
+        .map(price => ({ price, matchedBy: 'alias' }));
+}
+/** Stable identity of a loaded price table.
+ *
+ * The identity a price version carries can be edited in place while keeping its `id` — which is how
+ * a corrected table once kept charging superseded rates under one id — so a stored total records a
+ * digest of the whole table it was decided from, not only the version names.
+ * @param prices - Price versions loaded for this process.
+ * @returns Short digest of the table.
+ */
+export function pricesDigest(prices) {
+    return createHash('sha256').update(JSON.stringify(prices)).digest('hex').slice(0, 12);
+}
+/** 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.
+ * @param time - Recorded settlement timestamp used as the billing instant.
+ * @returns Matching price version, the rule that matched it, and its per-million-token rates.
+ */
+export function priceAt(prices, provider, model, time) {
+    const candidate = candidates(prices, provider, model)
+        .find(({ price }) => Date.parse(price.from) <= time && (price.until === undefined || time < Date.parse(price.until)));
+    if (candidate === undefined)
+        return;
+    const { price, matchedBy } = candidate;
+    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, matchedBy, rates: price.weekdays.includes(day) && price.windows.some(([a, b]) => minute >= a && minute < b) ? price.peak : price.offPeak };
+}
+/** Decide the amount for one request sample using the table loaded at decision time.
+ *
+ * A decision is a number or a reason; nothing about the rates that produced it is kept, because the
+ * ledger stores totals rather than requests and the next scan decides the sample again.
+ * @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 amount, or the reason no amount exists.
+ */
+export function chargeFor(prices, provider, model, time, usage) {
+    if (!usage)
+        return { reason: MISSING_USAGE };
+    // The published DeepSeek table prices cache hits, cache misses and output; a fourth bucket means
+    // the usage mapping is wrong, and inventing a rate for it would hide that.
+    if (provider === 'deepseek-official' && usage.cacheWrite !== 0)
+        return { reason: UNSUPPORTED_USAGE };
+    // No settlement time means the host did not say when the request was billed, and the two peak
+    // bands differ by a factor of two: a floor amount would enter the total while belonging to no day,
+    // so the request is reported unresolved instead of guessed.
+    if (time === undefined)
+        return { reason: MISSING_TIME };
+    const selected = 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 { amount };
+}

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,79 @@
+/** 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.
+ *
+ * `compaction/summary` is a provider request like any other — it reads the whole context to write the
+ * summary — and it records its own provider, model and usage instead of appearing as an assistant
+ * message, so a fold without it under-reports the most expensive requests in a session.
+ */
+const BILLING_EVENTS = new Set(['request/context', 'assistant/message', 'assistant/attempt', 'llm/retry-started', 'session/end-seed', 'compaction/summary']);
+/** 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)))
+        // A summary written without a model call — an unmarked template or remote summarizer — has no
+        // usage and no cost, so it is not a billable sample at all.
+        .filter(e => e.type !== 'compaction/summary' || object(e.data).usage !== undefined).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');
+        // A summary names its own provider and model, and carries no turn or step to fold against, so
+        // its route travels as the source a message would carry rather than as folded context.
+        const source = e.type === 'compaction/summary' ? { provider: d.provider ?? null, model: d.model ?? null } : m.source ?? null;
+        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, 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;
+        }
+        // A message or summary carries its own route; only the remaining events inherit the folded one.
+        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[];
+}>;