dsh-plugin-usage 0.1.4 → 0.2.2

package/lib/host/aggregate.js

@@ -0,0 +1,98 @@
+/**
+ * Incremental aggregation index over state.records.
+ *
+ * P1-5 LOCKED CONTRACT — query.js consumes exactly these members and fold.js
+ * feeds them; do not change the signatures:
+ *   add(record)              — fold calls for every record inserted
+ *   remove(record)           — fold calls when a dedup replacement drops a record
+ *   recordsInRange(from, to) — iterable of records with from <= time <= to
+ *
+ * Implementation: a Map<dayOrdinal, records[]> slice index maintained
+ * incrementally by add()/remove(). Records are folded chronologically, so each
+ * day array preserves insertion order and iterating day ordinals in ascending
+ * order reproduces the baseline scan's order while skipping out-of-range days.
+ * recordsInRange() additionally sweeps state.records for entries missing from
+ * the map (bookkeeping gaps, e.g. records pushed before the index existed) so
+ * query results stay identical to the baseline O(N) scan even on partial
+ * indexes — each such record is guarded by a per-call Set against duplicates.
+ */
+import { DAY_MS, alignFloor } from './time.js';
+const dayOrdinal = (t) => Math.floor(alignFloor(t, 'day') / DAY_MS);
+export function createUsageIndex(state) {
+    const days = new Map();
+    return {
+        add(record) {
+            const o = dayOrdinal(record.time);
+            let day = days.get(o);
+            if (day === undefined) {
+                day = [];
+                days.set(o, day);
+            }
+            day.push(record);
+        },
+        remove(record) {
+            const day = days.get(dayOrdinal(record.time));
+            if (day === undefined)
+                return; // missing record: tolerate silently
+            const i = day.indexOf(record);
+            if (i === -1)
+                return; // not indexed: tolerate silently
+            day.splice(i, 1);
+            if (day.length === 0)
+                days.delete(dayOrdinal(record.time));
+        },
+        *recordsInRange(from, to) {
+            const startOrd = Number.isFinite(from) ? dayOrdinal(from) : null;
+            const endOrd = Number.isFinite(to) ? dayOrdinal(to) : null;
+            // Finite bounds cover ordinal ranges directly; unbounded sides fall back
+            // to scanning the known day keys (never an infinite loop on ±Infinity).
+            const ords = [];
+            if (startOrd !== null && endOrd !== null) {
+                for (let o = startOrd; o <= endOrd; o++)
+                    ords.push(o);
+            }
+            else {
+                for (const o of days.keys()) {
+                    if (startOrd === null || o >= startOrd) {
+                        if (endOrd === null || o <= endOrd)
+                            ords.push(o);
+                    }
+                }
+                ords.sort((a, b) => a - b);
+            }
+            const seen = new Set();
+            for (const o of ords) {
+                const day = days.get(o);
+                if (day === undefined)
+                    continue;
+                for (const r of day) {
+                    if (r.time >= from && r.time <= to) {
+                        seen.add(r);
+                        yield r;
+                    }
+                }
+            }
+            // Defensive sweep: surface any record the slice index missed (bookkeeping
+            // gaps) without yielding anything twice.
+            for (const r of state.records) {
+                if (r.time >= from && r.time <= to && !seen.has(r))
+                    yield r;
+            }
+        },
+        /** Total indexed records (day slices only). */
+        size() {
+            let n = 0;
+            for (const day of days.values())
+                n += day.length;
+            return n;
+        },
+        /** Drop whole day slices strictly before ts (keeps the day containing ts). */
+        pruneBefore(ts) {
+            const cut = dayOrdinal(ts);
+            for (const o of days.keys()) {
+                if (o < cut)
+                    days.delete(o);
+            }
+        },
+    };
+}

package/lib/host/client-source.js

@@ -0,0 +1,34 @@
+/**
+ * Client source loader.
+ *
+ * The full dashboard UI lives in src/client/index.js (single source of
+ * truth). A dynamic plugin cannot import files, so the host reads the file
+ * and serves it to the browser half, which evaluates it with new Function.
+ *
+ * P1-4: candidates are derived from import.meta.url so the dynamic-plugin
+ * dev flow works from any checkout location.
+ */
+import { fileURLToPath } from 'node:url';
+const CLIENT_SOURCE_CANDIDATES = [
+    // src/host -> src/client in dev; lib/host -> lib/client when built.
+    fileURLToPath(new URL('../client/index.js', import.meta.url)),
+    // Repo source fallback when the built lib runs inside a checkout.
+    fileURLToPath(new URL('../../src/client/index.js', import.meta.url)),
+];
+export async function getClientSource(ctx) {
+    const fs = ctx.get('fs');
+    if (fs === undefined)
+        return { ok: false, error: 'fs service unavailable' };
+    for (const p of CLIENT_SOURCE_CANDIDATES) {
+        try {
+            const target = await fs.resolve(p);
+            const body = await fs.readText(target);
+            if (typeof body === 'string' && body.length > 0)
+                return { ok: true, body };
+        }
+        catch (error) {
+            // try the next candidate
+        }
+    }
+    return { ok: false, error: 'client source not found (tried: ' + CLIENT_SOURCE_CANDIDATES.join(', ') + ')' };
+}

package/lib/host/fold.js

@@ -0,0 +1,173 @@
+/**
+ * Fold durable session events into usage records.
+ *
+ * This mirrors the official `tokenUsage` session projection
+ * (@deepseek-ai/dsh-token-meter) so a third-party dashboard and the built-in
+ * stats agree on what one session consumed:
+ *
+ *  - A **billed settlement** is `assistant/message` or `assistant/attempt`.
+ *    `assistant/message` carries `data.usage`; a retried/failed attempt has no
+ *    usage field but can still have reported usage on its exact stream, so the
+ *    last raw `usage` chunk of `data.stream` is used when the field is absent.
+ *  - `llm/retry-started` closes the replacement slot for that (turn, step):
+ *    the retried attempt is a NEW billable attempt and must add, not replace.
+ *  - Otherwise a later sample for the same (turn, step) replaces the previous
+ *    one in place (index remove + add), because a settlement re-reports the
+ *    cumulative usage of its step.
+ *  - `request/context` and `request/header` provide the route (provider/model)
+ *    for settlements that carry no `message.source`.
+ *
+ * Records without turn/step (legacy logs) are never deduped — they always
+ * append.
+ */
+/**
+ * Last raw `usage` chunk of one durable assistant stream.
+ *
+ * @param {unknown} stream - `AssistantStreamRecord[]` (packed records included).
+ * @returns {object | undefined} the reported usage, when the stream has one.
+ */
+export function streamUsage(stream) {
+    if (!Array.isArray(stream))
+        return undefined;
+    for (let index = stream.length - 1; index >= 0; index -= 1) {
+        const record = stream[index];
+        if (record && record.type === 'chunk' && record.chunk && record.chunk.type === 'usage') {
+            return record.chunk.usage;
+        }
+    }
+    return undefined;
+}
+/**
+ * Usage reported by one durable assistant settlement.
+ *
+ * @param {{ type?: string, data?: any }} event - session event.
+ * @returns {object | undefined} reported usage, when the settlement billed one.
+ */
+export function usageOf(event) {
+    const data = event && event.data;
+    if (event.type === 'assistant/message' && data && data.usage !== undefined)
+        return data.usage;
+    if (event.type !== 'assistant/message' && event.type !== 'assistant/attempt')
+        return undefined;
+    return streamUsage(data && data.stream);
+}
+/** Route carried by a request event, when present. */
+function routeOf(event) {
+    const data = event.data || {};
+    if (event.type === 'request/context') {
+        if (typeof data.provider === 'string' && typeof data.model === 'string') {
+            return { provider: data.provider, model: data.model };
+        }
+        return undefined;
+    }
+    if (event.type === 'request/header') {
+        const config = data.header && data.header.config;
+        if (config && typeof config.provider === 'string' && typeof config.model === 'string') {
+            return { provider: config.provider, model: config.model };
+        }
+    }
+    return undefined;
+}
+/**
+ * Fold one durable event into the usage records.
+ *
+ * @param {object} state - runtime state capsule (see state.js).
+ * @param {string} sessionId - owning session.
+ * @param {{ type?: string, seq?: number, time?: number, data?: any }} e - session event.
+ * @returns {object | null} the affected record, or null when the event billed nothing.
+ */
+export function foldEvent(state, sessionId, e) {
+    if (!e || typeof e !== 'object')
+        return null;
+    // Route tracking: every settlement of a turn is priced/attributed under the
+    // route its request ran on.
+    const route = routeOf(e);
+    if (route !== undefined) {
+        state.route.set(sessionId, route);
+        return null;
+    }
+    // Retry boundary: the retried attempt is a new billable attempt.
+    if (e.type === 'llm/retry-started') {
+        const data = e.data || {};
+        const last = state.lastSample.get(sessionId);
+        if (last && last.turn === data.turn && last.step === data.step) {
+            state.lastSample.delete(sessionId);
+        }
+        return null;
+    }
+    if (e.type !== 'assistant/message' && e.type !== 'assistant/attempt')
+        return null;
+    const usage = usageOf(e);
+    if (usage === undefined || usage === null || typeof usage !== 'object')
+        return null;
+    const data = e.data || {};
+    const source = (data.message && data.message.source) || state.route.get(sessionId) || {};
+    const u = usage;
+    const inputTokens = u.inputTokens || 0;
+    const outputTokens = u.outputTokens || 0;
+    const cacheReadTokens = u.cacheReadTokens || 0;
+    const cacheWriteTokens = u.cacheWriteTokens || 0;
+    const rec = {
+        time: e.time,
+        session: sessionId,
+        provider: source.provider || '',
+        model: source.model || '',
+        turn: data.turn,
+        step: data.step,
+        attempt: e.type === 'assistant/attempt',
+        inputTokens,
+        outputTokens,
+        cacheReadTokens,
+        cacheWriteTokens,
+        reasoningTokens: u.reasoningTokens || 0,
+        // Prefer the provider's authoritative full-call total when reported.
+        totalTokens: typeof u.totalTokens === 'number'
+            ? u.totalTokens
+            : inputTokens + outputTokens + cacheReadTokens + cacheWriteTokens,
+    };
+    const previous = state.lastSample.get(sessionId);
+    if (previous !== undefined
+        && data.turn !== undefined && data.step !== undefined
+        && previous.turn === data.turn && previous.step === data.step) {
+        const prev = previous.record;
+        if (state.index)
+            state.index.remove(prev);
+        Object.assign(prev, rec);
+        if (state.index)
+            state.index.add(prev);
+        state.lastSample.set(sessionId, { turn: data.turn, step: data.step, record: prev });
+        return prev;
+    }
+    state.records.push(rec);
+    if (state.index)
+        state.index.add(rec);
+    if (data.turn !== undefined && data.step !== undefined) {
+        state.lastSample.set(sessionId, { turn: data.turn, step: data.step, record: rec });
+    }
+    else {
+        state.lastSample.delete(sessionId);
+    }
+    return rec;
+}
+/**
+ * Fold events with seq > watermark for one session; returns the new watermark.
+ *
+ * @param {object} state - runtime state capsule.
+ * @param {string} sessionId - owning session.
+ * @param {ReadonlyArray<object>} events - events in log order.
+ * @param {number} wm - current watermark (last folded seq).
+ * @returns {number} the new watermark.
+ */
+export function foldNew(state, sessionId, events, wm) {
+    let max = wm;
+    if (!Array.isArray(events))
+        return max;
+    for (const e of events) {
+        if (e && typeof e.seq === 'number' && e.seq > wm) {
+            foldEvent(state, sessionId, e);
+            if (e.seq > max)
+                max = e.seq;
+        }
+    }
+    return max;
+}