dsh-plugin-usage 0.1.4 → 0.2.0

package/lib/host/query.js

@@ -0,0 +1,157 @@
+/**
+ * Aggregation/query logic — pure over the runtime state.
+ *
+ * P1-7 (unpriced detection) and P1-8 (provider/model composite keys in the
+ * by-model table and model candidate list) are owned here.
+ */
+import { dayKey, DAY_MS, bucketKeyFor, stepMs, alignFloor, stepDayKey, MAX_BUCKETS, } from './time.js';
+function emptyBucket(key) {
+    return {
+        key,
+        calls: 0,
+        inputTokens: 0,
+        outputTokens: 0,
+        cacheReadTokens: 0,
+        cacheWriteTokens: 0,
+        totalTokens: 0,
+        cost: 0,
+    };
+}
+function addToBucket(b, r, cost) {
+    b.calls += 1;
+    b.inputTokens += r.inputTokens;
+    b.outputTokens += r.outputTokens;
+    b.cacheReadTokens += r.cacheReadTokens;
+    b.cacheWriteTokens += r.cacheWriteTokens;
+    b.totalTokens += r.inputTokens + r.outputTokens + r.cacheReadTokens + r.cacheWriteTokens;
+    b.cost += cost;
+    return b;
+}
+/** Composite model key: `provider/model`, or the bare model when provider is empty. */
+function compositeModelKey(r) {
+    return r.provider ? r.provider + '/' + r.model : r.model;
+}
+export function query(state, args) {
+    const from = typeof args.from === 'number' ? args.from : -Infinity;
+    const to = typeof args.to === 'number' ? args.to : Infinity;
+    const granularity = args.granularity === 'minute' || args.granularity === 'hour' ? args.granularity : 'day';
+    const stepDays = granularity === 'day' && Number.isInteger(args.stepDays) && args.stepDays > 0 ? args.stepDays : 1;
+    // Zero-filled step series require a finite range.
+    const fill = Boolean(args.fill) && Number.isFinite(from) && Number.isFinite(to);
+    const modelSet = Array.isArray(args.models) && args.models.length > 0
+        ? new Set(args.models)
+        : null;
+    /** Match either a bare model id or a `provider/model` composite key. */
+    const modelMatches = (r) => {
+        if (!modelSet)
+            return true;
+        if (modelSet.has(r.model))
+            return true;
+        return Boolean(r.provider) && modelSet.has(r.provider + '/' + r.model);
+    };
+    const dailyMap = new Map();
+    const modelMap = new Map();
+    const total = emptyBucket('total');
+    const seenModels = new Map(); // composite key -> {provider, model} (first composite wins)
+    let unpricedCalls = 0;
+    // Range-anchored day-step grid: blocks start at the range's first day.
+    const dayAnchor = Number.isFinite(from) ? alignFloor(from, 'day') : null;
+    const useStepGrid = granularity === 'day' && stepDays > 1 && dayAnchor !== null;
+    for (const r of state.index ? state.index.recordsInRange(from, to) : state.records) {
+        if (r.time < from || r.time > to)
+            continue;
+        if (!modelMatches(r))
+            continue;
+        const cost = state.prices.costOf(r);
+        if (r.totalTokens > 0 && !state.prices.hasPrice(r))
+            unpricedCalls += 1;
+        const modelKey = compositeModelKey(r);
+        if (!seenModels.has(modelKey))
+            seenModels.set(modelKey, { provider: r.provider, model: r.model });
+        const dk = useStepGrid ? stepDayKey(r, dayAnchor, stepDays) : bucketKeyFor(r.time, granularity, stepDays);
+        let db = dailyMap.get(dk);
+        if (db === undefined) {
+            db = emptyBucket(dk);
+            dailyMap.set(dk, db);
+        }
+        addToBucket(db, r, cost);
+        let mb = modelMap.get(modelKey);
+        if (mb === undefined) {
+            mb = emptyBucket(modelKey);
+            modelMap.set(modelKey, mb);
+        }
+        addToBucket(mb, r, cost);
+        addToBucket(total, r, cost);
+    }
+    let daily;
+    if (fill) {
+        let start;
+        let step;
+        let end;
+        if (granularity === 'day') {
+            step = stepDays * DAY_MS;
+            start = dayAnchor !== null ? dayAnchor : alignFloor(from, 'day');
+            end = alignFloor(to, 'day') + step;
+        }
+        else {
+            step = stepMs(granularity);
+            start = alignFloor(from, granularity);
+            end = alignFloor(to, granularity) + step;
+        }
+        const count = Math.round((end - start) / step);
+        if (count <= MAX_BUCKETS) {
+            daily = [];
+            for (let i = 0; i < count; i++) {
+                const t = start + i * step;
+                const k = useStepGrid ? dayKey(t) : bucketKeyFor(t, granularity, stepDays);
+                daily.push(dailyMap.get(k) || emptyBucket(k));
+            }
+        }
+        else {
+            // Degenerate: too many steps; fall back to present-only buckets.
+            daily = [...dailyMap.values()].sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+        }
+    }
+    else {
+        daily = [...dailyMap.values()].sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+    }
+    const byModel = [...modelMap.values()].sort((a, b) => b.totalTokens - a.totalTokens);
+    const models = [...seenModels.values()];
+    // GitHub-style yearly heatmap: every calendar day of the current year up to
+    // today, zero-filled.
+    let heatmap = null;
+    if (args.heatmap) {
+        const now = Date.now();
+        const year = new Date(now).getFullYear();
+        const hmMap = new Map();
+        const yearStart = new Date(year, 0, 1).getTime();
+        for (const r of state.index ? state.index.recordsInRange(yearStart, now) : state.records) {
+            if (r.time < yearStart || r.time > now)
+                continue;
+            if (!modelMatches(r))
+                continue;
+            const dk = dayKey(r.time);
+            let b = hmMap.get(dk);
+            if (b === undefined) {
+                b = emptyBucket(dk);
+                hmMap.set(dk, b);
+            }
+            addToBucket(b, r, state.prices.costOf(r));
+        }
+        heatmap = [];
+        const todayStart = alignFloor(now, 'day');
+        for (let d = new Date(year, 0, 1); d.getTime() <= todayStart; d.setDate(d.getDate() + 1)) {
+            const k = dayKey(d.getTime());
+            heatmap.push(hmMap.get(k) || emptyBucket(k));
+        }
+    }
+    return {
+        daily,
+        byModel,
+        total,
+        models,
+        unpricedCalls,
+        ...heatmap === null ? {} : { heatmap },
+        backfill: { status: state.backfill.status, total: state.backfill.total, done: state.backfill.done },
+    };
+}

package/lib/host/rpc.js

@@ -0,0 +1,69 @@
+/**
+ * RPC registration.
+ *
+ * Dynamic-plugin runs expose `harness` directly; static (bundle) installs
+ * expose the generic Connection RPC bridge (the browser half calls
+ * connection.rpc.call('/usage', endpoint, args)). Support both from one file.
+ *
+ * P0-3: the official Typert gateway path (@deepseek-ai/dsh-api-gateway host
+ * service, ctx key `typertGateway`) is wired here when the detected gateway
+ * exposes a registration surface, keeping these paths as fallbacks.
+ */
+export function registerRPC(ctx, handlers) {
+    const dynamicHarness = (typeof harness !== 'undefined' && harness && typeof harness.handle === 'function') ? harness : null;
+    if (dynamicHarness !== null) {
+        for (const [endpoint, fn] of handlers) {
+            dynamicHarness.handle('usage/' + endpoint, fn);
+        }
+        return;
+    }
+    // P0-3 official Typert gateway path.
+    //
+    // Target API: @deepseek-ai/dsh-api-gateway host service, exposed on the host
+    // Read the gateway only via `ctx.get('typertGateway')` — cordis ctx is a
+    // property). The installed v0.1.0-rc.7 `TypertGateway` interface exposes
+    // only invoke() (see the package's lib/types/types.d.ts); the documented
+    // contribution path (@Remote/@RemoteScope + TypertRemoteService or
+    // bindTypertRemote from @deepseek-ai/dsh-typert-protocol) needs a runtime
+    // dependency this plugin must not add, so we only claim endpoints through a
+    // registration surface that already exists on the detected object:
+    // `typert.register(channel, endpoints)`, a forward-compatible contribution
+    // hook for host compositions that expose the gateway with registration.
+    //
+    // Precondition for this path to activate: the resolved typert gateway is
+    // non-null AND `typert.register` is a function. Endpoint functions receive
+    // (args) and return the raw value; the gateway/connection side owns the
+    // RPC envelope. Otherwise we fall back silently to the connection bridge
+    // below. All guards are typeof-based: nothing is imported, zero deps.
+    // cordis ctx is a strict proxy: direct property access to an un-injected
+    // service throws — always use ctx.get (returns undefined when absent).
+    const typert = typeof ctx.get === 'function' ? ctx.get('typertGateway') : undefined;
+    if (typert && typeof typert.register === 'function') {
+        const endpoints = {};
+        for (const [endpoint, fn] of handlers) {
+            endpoints[endpoint] = fn;
+        }
+        typert.register('usage', endpoints);
+        return;
+    }
+    // Static (bundle) installs: the `connection` service is provided
+    // asynchronously by the client-connection plugin, so wait for it before
+    // registering the /usage channel (the official api-gateway pattern).
+    ctx.inject(['connection'], (connectionCtx) => {
+        const connection = connectionCtx.connection;
+        if (connection === undefined || connection.rpc === undefined)
+            return;
+        connection.rpc.handle('/usage', async (endpoint, args) => {
+            const fn = handlers.get(endpoint);
+            if (fn === undefined) {
+                return { ok: false, error: { code: 'bad-request', message: `unknown endpoint: ${endpoint}`, details: { issues: [] } } };
+            }
+            try {
+                return { ok: true, value: await fn(args) };
+            }
+            catch (error) {
+                return { ok: false, error: { code: 'internal', message: String((error && error.message) || error), details: {} } };
+            }
+        }, { authority: 'loopback' });
+    });
+}

package/lib/host/scan.js

@@ -0,0 +1,140 @@
+/**
+ * Live/persisted session scanning + startup backfill.
+ *
+ * P1-6: optimization lives here — bounded-concurrency backfill, per-session
+ * failure backoff, progress notifications, and an optional onProgress/
+ * onDone callback so the host can push a usage/updated event to clients.
+ */
+import { foldNew } from './fold.js';
+/** How many persisted headers are read concurrently per batch. */
+const BATCH_SIZE = 8;
+/**
+ * Per-session backoff bookkeeping, kept at module (closure) scope so it spans
+ * multiple passes. Value is { failures, skipLeft }: consecutive failure count
+ * plus the number of upcoming passes the session is skipped for
+ * (2 ** failures, capped at 5; decays by one each pass).
+ */
+const backoffBySession = new Map();
+/** True while a scanPersisted pass is in flight; overlapping passes are dropped. */
+let persistedInFlight = false;
+/** Scan live in-memory sessions (cheap, every tick). */
+export function scanLive(ctx, state) {
+    const sessions = ctx.get('sessions');
+    if (sessions === undefined)
+        return;
+    for (const s of sessions.list()) {
+        if (!s || !s.id)
+            continue;
+        const wm = state.watermarks.get(s.id) ?? -1;
+        const next = foldNew(state, s.id, s.events || [], wm);
+        if (next > wm)
+            state.watermarks.set(s.id, next);
+    }
+}
+/**
+ * Incremental scan of persisted sessions (slow cadence). Headers are read in
+ * small concurrent batches; a failing session is backed off for an
+ * exponentially growing number of passes instead of aborting the pass.
+ */
+export async function scanPersisted(ctx, state, options) {
+    const sp = ctx.get('sessionPersistence');
+    if (sp === undefined)
+        return;
+    if (persistedInFlight)
+        return; // previous pass still running: skip this tick
+    persistedInFlight = true;
+    try {
+        const headers = await sp.list();
+        if (!Array.isArray(headers))
+            return;
+        state.backfill.total = headers.length;
+        for (let i = 0; i < headers.length; i += BATCH_SIZE) {
+            const batch = headers.slice(i, i + BATCH_SIZE);
+            await Promise.all(batch.map((h) => processHeader(sp, state, h, options)));
+        }
+    }
+    finally {
+        persistedInFlight = false;
+        if (options && typeof options.onDone === 'function') {
+            options.onDone({
+                status: state.backfill.status,
+                total: state.backfill.total,
+                done: state.backfill.done,
+            });
+        }
+    }
+}
+/** Read + fold one persisted session header; bounded by the batch caller. */
+async function processHeader(sp, state, h, options) {
+    if (!h || !h.id)
+        return;
+    const id = h.id;
+    const backoff = backoffBySession.get(id);
+    if (backoff && backoff.skipLeft > 0) {
+        backoff.skipLeft -= 1; // decay the skip count one pass at a time
+        return;
+    }
+    const wm = state.watermarks.get(id) ?? -1;
+    try {
+        const page = await sp.readFrom(id, wm + 1);
+        const events = (page && page.events) || [];
+        const next = foldNew(state, id, events, wm);
+        if (next > wm)
+            state.watermarks.set(id, next);
+        backoffBySession.delete(id); // success resets the consecutive-failure chain
+    }
+    catch (error) {
+        // A session may be gone or mid-rewrite: back off before trying again.
+        const b = backoffBySession.get(id) || { failures: 0, skipLeft: 0 };
+        b.failures += 1;
+        b.skipLeft = Math.min(5, 2 ** b.failures);
+        backoffBySession.set(id, b);
+        return;
+    }
+    finally {
+        if (state.backfill.status === 'running') {
+            state.backfill.done += 1;
+            if (options && typeof options.onProgress === 'function') {
+                options.onProgress({
+                    status: state.backfill.status,
+                    total: state.backfill.total,
+                    done: state.backfill.done,
+                });
+            }
+        }
+    }
+}
+/** Full history scan, once at startup. */
+export async function runBackfill(ctx, state, options) {
+    const sp = ctx.get('sessionPersistence');
+    if (sp === undefined) {
+        state.backfill.status = 'done';
+        fireBackfillDone(options, state);
+        return;
+    }
+    state.backfill.status = 'running';
+    state.backfill.done = 0;
+    // Delegate progress while the pass runs; onDone is fired right here exactly
+    // once so the pass callback does not double-report backfill completion.
+    const scanOptions = options && typeof options.onProgress === 'function'
+        ? { onProgress: options.onProgress }
+        : undefined;
+    try {
+        await scanPersisted(ctx, state, scanOptions);
+        state.backfill.status = 'done';
+        fireBackfillDone(options, state);
+    }
+    catch (error) {
+        state.backfill.status = 'done';
+        fireBackfillDone(options, state);
+    }
+}
+function fireBackfillDone(options, state) {
+    if (options && typeof options.onDone === 'function') {
+        options.onDone({
+            status: state.backfill.status,
+            total: state.backfill.total,
+            done: state.backfill.done,
+        });
+    }
+}

package/lib/host/settings.js

@@ -0,0 +1,162 @@
+/**
+ * Price table + cost computation.
+ *
+ * P0-1: createPriceStore() keeps the process-memory table. The optimization
+ * adds a durable settings-namespace backend via `ctx.settings` (official
+ * dsh-settings) with the in-memory store as fallback — implemented by the
+ * settings workstream inside this file only.
+ */
+export const DEFAULT_CURRENCY = '¥';
+export const DEFAULT_PRICES = {
+    'deepseek-chat': { inputPerM: 0.27, outputPerM: 1.1, cacheReadPerM: 0.07, cacheWritePerM: 0.27 },
+    'deepseek-v3': { inputPerM: 0.27, outputPerM: 1.1, cacheReadPerM: 0.07, cacheWritePerM: 0.27 },
+    'deepseek-v3.1': { inputPerM: 0.27, outputPerM: 1.1, cacheReadPerM: 0.07, cacheWritePerM: 0.27 },
+    'deepseek-v4': { inputPerM: 0.27, outputPerM: 1.1, cacheReadPerM: 0.07, cacheWritePerM: 0.27 },
+    'deepseek-v4-flash': { inputPerM: 0.14, outputPerM: 0.56, cacheReadPerM: 0.04, cacheWritePerM: 0.14 },
+    'deepseek-reasoner': { inputPerM: 0.55, outputPerM: 2.19, cacheReadPerM: 0.14, cacheWritePerM: 0.55 },
+    'deepseek-r1': { inputPerM: 0.55, outputPerM: 2.19, cacheReadPerM: 0.14, cacheWritePerM: 0.55 },
+};
+export function createPriceStore(defaultPrices, defaultCurrency) {
+    const prices = Object.assign({}, defaultPrices);
+    let currency = defaultCurrency || DEFAULT_CURRENCY;
+    const store = {
+        prices,
+        get currency() { return currency; },
+        /** Write-through slot wired by initSettings(); null without a settings service. */
+        persist: null,
+        /** Merge incoming per-model prices (each field coerced to a number). */
+        setPrices(incoming) {
+            if (!incoming || typeof incoming !== 'object')
+                return;
+            for (const [model, p] of Object.entries(incoming)) {
+                if (p && typeof p === 'object') {
+                    prices[model] = {
+                        inputPerM: Number(p.inputPerM) || 0,
+                        outputPerM: Number(p.outputPerM) || 0,
+                        cacheReadPerM: Number(p.cacheReadPerM) || 0,
+                        cacheWritePerM: Number(p.cacheWritePerM) || 0,
+                    };
+                }
+            }
+            if (typeof store.persist === 'function')
+                store.persist({ prices: Object.assign({}, prices) });
+        },
+        setCurrency(v) {
+            if (typeof v === 'string' && v.length > 0) {
+                currency = v;
+                if (typeof store.persist === 'function')
+                    store.persist({ currency });
+            }
+        },
+        /** Look up a price by `provider/model` composite first, then bare model. */
+        priceOf(r) {
+            const composite = r.provider ? r.provider + '/' + r.model : '';
+            return prices[composite] || prices[r.model];
+        },
+        /** Whether an explicit price entry exists (composite first, then bare model). */
+        hasPrice(r) {
+            const composite = r.provider ? r.provider + '/' + r.model : '';
+            return composite in prices || r.model in prices;
+        },
+        costOf(r) {
+            const p = store.priceOf(r);
+            if (!p)
+                return 0;
+            return (r.inputTokens * p.inputPerM +
+                r.outputTokens * p.outputPerM +
+                r.cacheReadTokens * (p.cacheReadPerM || 0) +
+                r.cacheWriteTokens * (p.cacheWritePerM || 0)) / 1e6;
+        },
+        snapshot() {
+            return { prices: Object.assign({}, prices), currency };
+        },
+    };
+    return store;
+}
+const USAGE_PRICES_NS = 'usage.prices';
+/** JSON-schema-shaped descriptor for the usage.prices settings section. */
+const PRICE_SECTION_DESCRIPTOR = {
+    type: 'object',
+    properties: {
+        prices: {
+            type: 'object',
+            description: 'Per-model prices (cost per 1M tokens, in `currency`).',
+            additionalProperties: {
+                type: 'object',
+                properties: {
+                    inputPerM: { type: 'number' },
+                    outputPerM: { type: 'number' },
+                    cacheReadPerM: { type: 'number' },
+                    cacheWritePerM: { type: 'number' },
+                },
+                required: ['inputPerM', 'outputPerM', 'cacheReadPerM', 'cacheWritePerM'],
+            },
+        },
+        currency: { type: 'string' },
+    },
+    required: ['prices', 'currency'],
+};
+/** Apply a resolved settings section onto the in-memory price store. */
+function applySection(store, section) {
+    if (!section || typeof section !== 'object')
+        return;
+    if (typeof store.setPrices === 'function' && section.prices && typeof section.prices === 'object' && !Array.isArray(section.prices)) {
+        store.setPrices(section.prices);
+    }
+    if (typeof store.setCurrency === 'function' && typeof section.currency === 'string')
+        store.setCurrency(section.currency);
+}
+/**
+ * P0-1: wire the price store to the official `ctx.settings` namespace
+ * (durable, shown in the official Plugins config tab) when available.
+ * Registers `usage.prices`, seeds the store from the resolved section, and
+ * writes every setPrices/setCurrency mutation through. Falls back to the
+ * in-memory store whenever the settings service is missing or unavailable.
+ */
+export function initSettings(ctx, store) {
+    if (!ctx || typeof ctx.get !== 'function' || !store || typeof store !== 'object')
+        return;
+    let settings;
+    try {
+        settings = ctx.get('settings');
+    }
+    catch {
+        return;
+    }
+    if (!settings || typeof settings.register !== 'function')
+        return;
+    let scope;
+    try {
+        scope = settings.register(USAGE_PRICES_NS, PRICE_SECTION_DESCRIPTOR, { base: { prices: DEFAULT_PRICES, currency: DEFAULT_CURRENCY }, applies: 'live' });
+    }
+    catch {
+        return; // registration failed — keep the current in-memory behavior
+    }
+    store.persist = (patch) => {
+        try {
+            if (scope && typeof scope.update === 'function')
+                return scope.update(USAGE_PRICES_NS, patch);
+            if (settings && typeof settings.update === 'function')
+                return settings.update(USAGE_PRICES_NS, patch);
+        }
+        catch {
+            // Never throw when the settings scope is unavailable.
+        }
+    };
+    let section;
+    try {
+        if (scope && typeof scope.get === 'function')
+            section = scope.get();
+        else if (settings && typeof settings.get === 'function')
+            section = settings.get(USAGE_PRICES_NS);
+    }
+    catch {
+        section = undefined;
+    }
+    if (section && typeof section.then === 'function') {
+        section.then((resolved) => applySection(store, resolved)).catch(() => { });
+    }
+    else {
+        applySection(store, section);
+    }
+}

package/lib/host/state.js

@@ -0,0 +1,21 @@
+/**
+ * Mutable runtime state capsule for the usage host half.
+ *
+ * - records: folded usage records, one per assistant/message with usage.
+ * - watermarks: sessionId -> last folded event seq.
+ * - backfill: progress counters surfaced through query results.
+ * - prices: the price store from settings.js.
+ * - dedup: (sessionId, turn, step) -> index in records; owned by fold.js.
+ * - index: incremental aggregation index (aggregate.js), kept in sync by
+ *   fold.js and consumed by query.js.
+ */
+export function createState(priceStore) {
+    return {
+        records: [],
+        watermarks: new Map(),
+        backfill: { status: 'idle', total: 0, done: 0 },
+        prices: priceStore,
+        dedup: new Map(),
+        index: null, // wired by apply() after createUsageIndex(state)
+    };
+}

package/lib/host/time.js

@@ -0,0 +1,82 @@
+/**
+ * Time helpers for usage bucketing — pure, dependency-free.
+ * Granularity keys: 'day' | 'hour' | 'minute'.
+ *
+ * User-facing buckets (dayKey / alignFloor / bucketKeyFor non-day cases) use
+ * LOCAL calendar time. dayIndex is a local-midnight-based ordinal used to
+ * align step-day blocks. DST-consistent handling is owned by this module.
+ */
+export const DAY_MS = 86400000;
+export function dayKey(t) {
+    const d = new Date(t);
+    const pad = (n) => String(n).padStart(2, '0');
+    return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+}
+/** Ordinal day number (local-midnight based), for step alignment. */
+export function dayIndex(t) {
+    return Math.floor(alignFloor(t, 'day') / DAY_MS);
+}
+/** Local-midnight epoch of the day whose dayIndex ordinal is `block`. */
+function localMidnightForOrdinal(block) {
+    let epoch = alignFloor(block * DAY_MS, 'day');
+    let idx = Math.floor(epoch / DAY_MS);
+    while (idx < block) {
+        epoch = alignFloor(epoch + DAY_MS, 'day');
+        idx = Math.floor(epoch / DAY_MS);
+    }
+    while (idx > block) {
+        epoch = alignFloor(epoch - DAY_MS, 'day');
+        idx = Math.floor(epoch / DAY_MS);
+    }
+    return epoch;
+}
+/** Bucket key for one instant under a granularity (day buckets may span stepDays). */
+export function bucketKeyFor(t, g, stepDays) {
+    const pad = (n) => String(n).padStart(2, '0');
+    if (g === 'day') {
+        // Single-day buckets are the local calendar day itself (DST-safe by construction).
+        if (stepDays === 1)
+            return dayKey(t);
+        const block = Math.floor(dayIndex(t) / stepDays) * stepDays;
+        return dayKey(localMidnightForOrdinal(block));
+    }
+    const d = new Date(t);
+    const date = `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+    const hm = pad(d.getHours()) + ':' + (g === 'hour' ? '00' : pad(d.getMinutes()));
+    return date + ' ' + hm;
+}
+export function stepMs(g) {
+    return g === 'day' ? DAY_MS : g === 'hour' ? 3600000 : 60000;
+}
+/** Floor an instant to its granularity boundary. */
+export function alignFloor(t, g) {
+    const d = new Date(t);
+    if (g === 'day') {
+        d.setHours(0, 0, 0, 0);
+        return d.getTime();
+    }
+    if (g === 'hour') {
+        d.setMinutes(0, 0, 0);
+        return d.getTime();
+    }
+    d.setSeconds(0, 0);
+    return d.getTime();
+}
+/** Floor an instant to its stepDays block start (local midnight of the block's anchor day). */
+export function alignBlock(t, stepDays) {
+    if (stepDays === 1)
+        return alignFloor(t, 'day');
+    const block = Math.floor(dayIndex(t) / stepDays) * stepDays;
+    return localMidnightForOrdinal(block);
+}
+/**
+ * Bucket key under a day granularity with a range-anchored step grid:
+ * blocks start at the range's first day, so a custom range reads naturally
+ * (e.g. 90 days -> 18 x 5-day buckets starting on the range's first day).
+ */
+export function stepDayKey(r, dayStart, stepDays) {
+    const k = Math.floor((alignFloor(r.time, 'day') - dayStart) / (stepDays * DAY_MS));
+    return dayKey(dayStart + k * stepDays * DAY_MS);
+}
+/** Cap on zero-filled output buckets; beyond it we emit present-only buckets. */
+export const MAX_BUCKETS = 2000;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-plugin-usage",
   "description": "Token usage statistics for DeepSeek Harness — daily/custom-range views, model filters, call counts and cost, inspired by CC Switch statistics.",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -39,8 +39,8 @@
     "client": {
       "inject": [
         "@deepseek-ai/dsh-client-runtime",
-        "@deepseek-ai/dsh-client-ui-sidebar",
-        "@deepseek-ai/dsh-client-ui-settings"
+        "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-client-locale"
       ],
       "platform": "web"
     }
@@ -57,7 +57,8 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json && node scripts/build-client.js",
+    "test": "node --test tests/*.test.js",
     "watch": "tsc -p tsconfig.json --watch",
     "prepublishOnly": "npm run build"
   }
-}
+}