@itookit/dsht 0.2.4 → 0.3.2

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[];
+}>;

package/dist/cost/scanner.js

@@ -0,0 +1,95 @@
+/** Address and page one session's complete billing history over the host connection. */
+import { RemoteError } from "../transport/client.js";
+import { array, errorText, object, string } from "../transport/wire.js";
+import { costRecords } from "./records.js";
+/** 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 function costAddresses(session) {
+    const sessionId = string(session.sessionId);
+    const parentSessionId = typeof session.parentSessionId === 'string' ? session.parentSessionId : '';
+    if (session.origin !== 'subagent' || parentSessionId === '')
+        return [{ kind: 'session', sessionId }];
+    return [
+        { kind: 'subagent', parentSessionId, childSessionId: sessionId, mode: 'continuable' },
+        { kind: 'subagent', parentSessionId, childSessionId: sessionId, mode: 'one-shot' },
+    ];
+}
+/** 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 async function sessionCostHistory(client, session, signal, onPage) {
+    let lastError;
+    for (const address of costAddresses(session)) {
+        try {
+            return await readCostHistory(client, address, signal, onPage);
+        }
+        catch (error) {
+            lastError = error;
+            // Only a delivery-mode mismatch justifies the other form; every other failure is final here.
+            if (!(error instanceof RemoteError && error.code === 'subagent/unauthorized'))
+                throw error;
+        }
+    }
+    throw lastError;
+}
+/** Page one addressed session's history into the billing events the ledger folds. */
+async function readCostHistory(client, address, signal, onPage) {
+    onPage?.();
+    const snapshot = await new Promise((resolve, reject) => {
+        let sub;
+        const timeout = setTimeout(() => finish(new Error('Cost history snapshot timed out')), client.timeoutMs);
+        const onAbort = () => finish(new Error('Cost refresh cancelled'));
+        const finish = (error, frame) => {
+            clearTimeout(timeout);
+            signal.removeEventListener('abort', onAbort);
+            sub?.cancel();
+            if (error)
+                reject(error);
+            else
+                resolve(frame);
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+        try {
+            sub = client.subscribe('session/follow', { request: { address, maxMessages: 80, assistantStream: true } }, {
+                item: value => { const frame = object(value); if (frame.type === 'snapshot')
+                    finish(undefined, frame); },
+                end: error => finish(error ?? new Error('Cost history stream ended')),
+            });
+        }
+        catch (error) {
+            finish(error instanceof Error ? error : new Error(errorText(error)));
+        }
+    });
+    const cursor = snapshot.cursor;
+    if (typeof cursor !== 'number' || !Number.isSafeInteger(cursor))
+        throw new Error('Invalid cost history cursor');
+    let page = snapshot;
+    const events = [];
+    while (true) {
+        signal.throwIfAborted();
+        const records = array(page.records);
+        events.push(...costRecords(records));
+        if (!page.hasMore)
+            break;
+        const seqs = records.map(r => object(object(r).event).seq);
+        if (!seqs.length || seqs.some(n => typeof n !== 'number' || !Number.isSafeInteger(n)))
+            throw new Error('Invalid cost history page');
+        const beforeSeq = Math.min(...seqs);
+        onPage?.();
+        page = object(await client.call('session/page', { request: { address, throughSeq: cursor, beforeSeq, maxMessages: 80 } }, signal));
+        if (page.hasMore && array(page.records).every(r => Number(object(object(r).event).seq) >= beforeSeq))
+            throw new Error('Cost history page did not advance');
+    }
+    if (object(snapshot.header).isSeeded === true && !events.some(e => e.type === 'session/end-seed' && object(e.data).inherited === true))
+        throw new Error('Cannot attribute inherited session usage');
+    return { cursor, events };
+}

package/dist/cost/types.d.ts

@@ -0,0 +1,69 @@
+/** Cost-domain types shared by pricing, record folding, storage and the in-memory ledger. */
+/** Per-million-token rates for one peak or off-peak bucket. */
+export interface Rates {
+    input: number;
+    cacheRead: number;
+    cacheWrite: number;
+    output: number;
+}
+/** An explicit validity interval and weekday peak windows in the named time zone. */
+export interface PriceVersion {
+    id: string;
+    provider: string;
+    model: string;
+    from: string;
+    until?: string;
+    currency: 'CNY';
+    source: string;
+    timezone: string;
+    peak: Rates;
+    offPeak: Rates;
+    weekdays: number[];
+    windows: [number, number][];
+}
+/** Disjoint token buckets reported for one model request. */
+export interface Usage {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+}
+/** One folded request sample before a price decision is attached. */
+export interface ChargeSample {
+    key: string;
+    time?: number;
+    provider: string;
+    model: string;
+    usage?: Usage;
+}
+/** The price decision recorded the first time a request sample was evaluated. */
+export interface PriceDecision {
+    priceId?: string;
+    amount?: number;
+    estimated?: true;
+    reason?: string;
+}
+/** One ledger entry: a request sample plus the price decision that seals it. */
+export interface Charge extends ChargeSample, PriceDecision {
+}
+/** One session's persisted ledger slice. */
+export interface SavedCost {
+    version: 2;
+    sessionId: string;
+    cut: number;
+    charges: Charge[];
+}
+/** Summary retains the known subtotal, the records it could not price, and the coarse estimates.
+ * `unknown` counts records with no amount at all; `estimated` counts records that only have a
+ * floor amount, including dated requests whose timestamp cannot place them inside the range.
+ */
+export interface CostTotal {
+    amount: number;
+    unknown: number;
+    estimated: number;
+    records: number;
+}
+/** How much of the visible history the cached ledger currently covers. */
+export type Coverage = 'complete' | 'scanning' | 'partial';
+/** Reason recorded when a sample carries no usable token counts. */
+export declare const MISSING_USAGE = "missing usage";

package/dist/cost/types.js

@@ -0,0 +1,3 @@
+/** Cost-domain types shared by pricing, record folding, storage and the in-memory ledger. */
+/** Reason recorded when a sample carries no usable token counts. */
+export const MISSING_USAGE = 'missing usage';

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+/** Published library entry: the reusable host client and its error types. */
+export { Client, HttpError, RemoteError } from './transport/client.ts';
+export type { Subscription } from './transport/client.ts';

package/dist/index.js

@@ -0,0 +1,2 @@
+/** Published library entry: the reusable host client and its error types. */
+export { Client, HttpError, RemoteError } from "./transport/client.js";

package/dist/session/connection-view.d.ts

@@ -0,0 +1,18 @@
+/** What the session domain reads from the connection the controller owns. */
+import type { Telemetry } from './telemetry.ts';
+import type { ObjectValue } from '../transport/wire.ts';
+/** Read-only connection facts and actions the session controller needs. */
+export interface ConnectionView {
+    /** Projection store of the current generation. */
+    telemetryView(): Telemetry;
+    /** Cached host running flag for one session, or undefined when never reported. */
+    runningFor(sessionId: string): boolean | undefined;
+    /** When this client first observed the session, for the elapsed-time fallback. */
+    observedAt(sessionId: string): number | undefined;
+    /** Record an observation start for a session this client just opened. */
+    observe(sessionId: string): void;
+    /** Fail the current generation, so the controller reopens a snapshot. */
+    fail(error: Error): void;
+    /** Answer one retained host waterfall through the event-result endpoint. */
+    reply(frame: ObjectValue, outcome: ObjectValue): Promise<void>;
+}

package/dist/session/connection-view.js

@@ -0,0 +1 @@
+export {};