@shi-yangyang/dsh-token-dashboard 0.0.0-stage → 0.2.0

package/cordis.patch.yml

@@ -0,0 +1,7 @@
+# dsh-token-dashboard bundle patch.
+# Installs the plugin as one Loader entry. The plugin reads the durable session
+# logs through the official sessionPersistence service and serves its dashboard
+# data over an authenticated same-origin route.
+- insert:
+    - id: dsh-token-dashboard
+      name: '@shi-yangyang/dsh-token-dashboard'

package/icon.svg

@@ -0,0 +1,13 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-label="Token usage">
+  <defs>
+    <linearGradient id="tdb-bg" x1="8" y1="4" x2="56" y2="60" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#4f6ef7"/>
+      <stop offset="1" stop-color="#2b3fb8"/>
+    </linearGradient>
+  </defs>
+  <rect x="2" y="2" width="60" height="60" rx="16" fill="url(#tdb-bg)"/>
+  <rect x="14" y="34" width="8" height="16" rx="3" fill="#ffffff" fill-opacity="0.72"/>
+  <rect x="28" y="24" width="8" height="26" rx="3" fill="#ffffff" fill-opacity="0.9"/>
+  <rect x="42" y="14" width="8" height="36" rx="3" fill="#ffffff"/>
+  <circle cx="46" cy="48" r="4" fill="#7ee2b8"/>
+</svg>

package/lib/host/aggregate.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Incremental, revision-aware aggregation over every local session.
+ *
+ * The cache is in memory and derived exclusively from the official logs. It is
+ * rebuilt from scratch when the Host process restarts, and every entry is
+ * keyed by the persistence revision (or the live session's event count), so a
+ * dashboard open never rescans an unchanged log.
+ */
+import type { RequestLogPage, StatsPayload, TokenBuckets } from '../shared/types.js';
+import type { AggregatorSource } from './source.js';
+import type { RawSessionEvent } from './types.js';
+export interface AggregatorOptions {
+    now?: () => number;
+    concurrency?: number;
+    keepHoursMs?: number;
+}
+/** Revision-aware token aggregator. One instance per Host plugin activation. */
+export declare class TokenAggregator {
+    private readonly source;
+    private readonly now;
+    private readonly concurrency;
+    private readonly keepHoursMs;
+    private cache;
+    private failures;
+    private revision;
+    private initialized;
+    private refreshing;
+    private payload;
+    private payloadRevision;
+    private lastScan;
+    constructor(source: AggregatorSource, options?: AggregatorOptions);
+    /** Scan once; a repeated call is a no-op until the next refresh. */
+    ensure(): Promise<void>;
+    /** Reconcile the cache with the current persisted + live corpus. */
+    refresh(signal?: AbortSignal): Promise<void>;
+    /** Current ETag revision. Bumped only when derived data can have changed. */
+    getRevision(): number;
+    /**
+     * Read-only per-session fold totals for the diagnostic projection check.
+     * The returned buckets are detached copies.
+     */
+    sessionsForVerification(): Array<{
+        id: string;
+        own: TokenBuckets;
+        allLog: TokenBuckets;
+        inheritedEventCount: number;
+    }>;
+    get isInitialized(): boolean;
+    /**
+     * Fold one live event without listing or rescanning anything.
+     * @returns false when the event is out of sequence and a resync is needed.
+     */
+    applyLiveEvent(sessionId: string, event: RawSessionEvent): boolean;
+    /** Build (or reuse) the wire payload for the dashboard. */
+    stats(): StatsPayload;
+    /** Paginated request log, newest first. */
+    requestPage(offset: number, limit: number): RequestLogPage;
+    private doRefresh;
+    private planFor;
+    private markChanged;
+}

package/lib/host/aggregate.js

@@ -0,0 +1,472 @@
+/**
+ * Incremental, revision-aware aggregation over every local session.
+ *
+ * The cache is in memory and derived exclusively from the official logs. It is
+ * rebuilt from scratch when the Host process restarts, and every entry is
+ * keyed by the persistence revision (or the live session's event count), so a
+ * dashboard open never rescans an unchanged log.
+ */
+import { currentTimezone, hourKey, todayKey } from '../shared/dates.js';
+import { addBuckets, cacheHitRate, emptyBuckets, sortModels, totalTokens, } from '../shared/model.js';
+import { API_VERSION } from '../shared/types.js';
+import { createAggregate, foldInto } from './fold.js';
+/** Revision-aware token aggregator. One instance per Host plugin activation. */
+export class TokenAggregator {
+    source;
+    now;
+    concurrency;
+    keepHoursMs;
+    cache = new Map();
+    failures = [];
+    revision = 0;
+    initialized = false;
+    refreshing = null;
+    payload = null;
+    payloadRevision = -1;
+    lastScan = {
+        sessionsDiscovered: 0,
+        sessionsRead: 0,
+        sessionsReused: 0,
+        sessionsFailed: 0,
+        durationMs: 0,
+        startedAt: 0,
+    };
+    constructor(source, options = {}) {
+        this.source = source;
+        this.now = options.now ?? Date.now;
+        this.concurrency = Math.max(1, Math.trunc(options.concurrency ?? 3));
+        this.keepHoursMs = options.keepHoursMs ?? 48 * 60 * 60 * 1000;
+    }
+    /** Scan once; a repeated call is a no-op until the next refresh. */
+    async ensure() {
+        if (this.initialized)
+            return;
+        await this.refresh();
+    }
+    /** Reconcile the cache with the current persisted + live corpus. */
+    async refresh(signal) {
+        if (this.refreshing !== null) {
+            await this.refreshing;
+            return;
+        }
+        const run = this.doRefresh(signal);
+        this.refreshing = run.finally(() => {
+            this.refreshing = null;
+        });
+        await this.refreshing;
+    }
+    /** Current ETag revision. Bumped only when derived data can have changed. */
+    getRevision() {
+        return this.revision;
+    }
+    /**
+     * Read-only per-session fold totals for the diagnostic projection check.
+     * The returned buckets are detached copies.
+     */
+    sessionsForVerification() {
+        return [...this.cache.values()]
+            .map(entry => ({
+            id: entry.descriptor.id,
+            own: { ...entry.aggregate.totals },
+            allLog: { ...entry.aggregate.allTotals },
+            inheritedEventCount: entry.aggregate.inheritedEventCount,
+        }))
+            .sort((left, right) => left.id.localeCompare(right.id));
+    }
+    get isInitialized() {
+        return this.initialized;
+    }
+    /**
+     * Fold one live event without listing or rescanning anything.
+     * @returns false when the event is out of sequence and a resync is needed.
+     */
+    applyLiveEvent(sessionId, event) {
+        const entry = this.cache.get(sessionId);
+        if (entry === undefined || !entry.descriptor.live)
+            return false;
+        if (entry.failed !== null)
+            return false;
+        if (!isEvent(event))
+            return true;
+        if (event.seq <= entry.aggregate.carry.lastSeq)
+            return true;
+        if (event.seq !== entry.aggregate.carry.lastSeq + 1)
+            return false;
+        foldInto(entry.aggregate, [event], { now: this.now(), keepHoursMs: this.keepHoursMs });
+        entry.descriptor.seq = Math.max(entry.descriptor.seq, event.seq + 1);
+        entry.stamp = `live:${entry.descriptor.seq}`;
+        entry.failed = null;
+        this.markChanged();
+        return true;
+    }
+    /** Build (or reuse) the wire payload for the dashboard. */
+    stats() {
+        const now = this.now();
+        const today = todayKey(now);
+        if (this.payload !== null && this.payloadRevision === this.revision && this.payload.today === today) {
+            return this.payload;
+        }
+        const totals = emptyBuckets();
+        let requests = 0;
+        let liveCount = 0;
+        let subagentCount = 0;
+        let seededCount = 0;
+        let withUsage = 0;
+        const models = new Map();
+        const days = new Map();
+        const hours = new Map();
+        const rows = [];
+        const errors = [...this.failures];
+        for (const entry of this.cache.values()) {
+            const { descriptor, aggregate } = entry;
+            addBuckets(totals, aggregate.totals);
+            requests += aggregate.requests;
+            for (const model of Object.values(aggregate.models)) {
+                mergeModel(models, model);
+            }
+            for (const bucket of Object.values(aggregate.days))
+                mergeBucket(days, bucket);
+            for (const bucket of Object.values(aggregate.hours))
+                mergeBucket(hours, bucket);
+            const rowModels = sortModels(Object.values(aggregate.models).map(cloneModel));
+            const summary = {
+                id: descriptor.id,
+                title: aggregate.title,
+                project: this.source.projectLabel?.(descriptor.header.cwd) ?? '',
+                cwd: descriptor.header.cwd ?? null,
+                modelKeys: rowModels.map(model => model.key),
+                createdAt: aggregate.createdAt,
+                lastActivity: aggregate.lastActivity,
+                live: descriptor.live,
+                origin: descriptor.header.origin === 'subagent' ? 'subagent' : 'root',
+                seeded: descriptor.header.isSeeded === true,
+                parentSession: descriptor.header.parentSession ?? null,
+                agentPreset: descriptor.header.agentPreset ?? null,
+                totals: { ...aggregate.totals },
+                requests: aggregate.requests,
+                cacheHitRate: cacheHitRate(aggregate.totals),
+                models: rowModels,
+                eventCount: aggregate.processed,
+                inheritedEventCount: aggregate.inheritedEventCount,
+                stale: entry.failed !== null,
+            };
+            rows.push(summary);
+            if (descriptor.live)
+                liveCount += 1;
+            if (summary.origin === 'subagent')
+                subagentCount += 1;
+            if (summary.seeded)
+                seededCount += 1;
+            if (summary.requests > 0 || totalTokens(summary.totals) > 0)
+                withUsage += 1;
+            if (entry.failed !== null) {
+                errors.push({ sessionId: descriptor.id, reason: entry.failed });
+            }
+        }
+        rows.sort((left, right) => right.lastActivity - left.lastActivity);
+        const uniqueErrors = [...new Map(errors.map(error => [error.sessionId, error])).values()];
+        const payload = {
+            apiVersion: API_VERSION,
+            revision: this.revision,
+            generatedAt: now,
+            timezone: currentTimezone(),
+            today,
+            totals,
+            requests,
+            cacheHitRate: cacheHitRate(totals),
+            sessions: {
+                total: rows.length,
+                withUsage,
+                live: liveCount,
+                subagents: subagentCount,
+                seeded: seededCount,
+            },
+            models: sortModels([...models.values()].map(cloneModel)),
+            days: [...days.values()].sort((left, right) => left.bucket.localeCompare(right.bucket)),
+            hours: [...hours.values()]
+                .filter(bucket => bucket.bucket >= hourKey(now - this.keepHoursMs))
+                .sort((left, right) => left.bucket.localeCompare(right.bucket)),
+            sessionRows: rows,
+            scan: {
+                ...this.lastScan,
+                generatedAt: now,
+                partial: uniqueErrors.length > 0,
+            },
+            errors: uniqueErrors,
+        };
+        this.payload = payload;
+        this.payloadRevision = this.revision;
+        return payload;
+    }
+    /** Paginated request log, newest first. */
+    requestPage(offset, limit) {
+        const rows = [];
+        for (const entry of this.cache.values()) {
+            const { descriptor, aggregate } = entry;
+            if (aggregate.requestSamples.length === 0)
+                continue;
+            const project = this.source.projectLabel?.(descriptor.header.cwd) ?? '';
+            const app = descriptor.header.agentPreset ?? 'DSH';
+            for (const sample of aggregate.requestSamples) {
+                rows.push({
+                    id: `${descriptor.id}:${sample.key}`,
+                    sessionId: descriptor.id,
+                    sessionTitle: aggregate.title,
+                    project,
+                    app,
+                    time: sample.time,
+                    provider: sample.provider,
+                    model: sample.model,
+                    modelKey: sample.modelKey,
+                    inputTokens: sample.buckets.uncachedInputTokens,
+                    cacheReadTokens: sample.buckets.cacheReadTokens,
+                    cacheWriteTokens: sample.buckets.cacheWriteTokens,
+                    outputTokens: sample.buckets.outputTokens,
+                    speed: sample.speed,
+                    firstToken: sample.firstToken,
+                });
+            }
+        }
+        rows.sort((left, right) => right.time - left.time);
+        const safeOffset = Number.isFinite(offset) ? Math.max(0, Math.trunc(offset)) : 0;
+        const safeLimit = Number.isFinite(limit) ? Math.max(1, Math.min(100, Math.trunc(limit))) : 24;
+        return {
+            revision: this.revision,
+            total: rows.length,
+            offset: safeOffset,
+            limit: safeLimit,
+            generatedAt: this.now(),
+            rows: rows.slice(safeOffset, safeOffset + safeLimit),
+        };
+    }
+    async doRefresh(signal) {
+        const startedAt = this.now();
+        const started = performance.now();
+        let descriptors;
+        try {
+            descriptors = await this.source.list();
+        }
+        catch (error) {
+            this.lastScan = {
+                sessionsDiscovered: 0,
+                sessionsRead: 0,
+                sessionsReused: 0,
+                sessionsFailed: 0,
+                durationMs: Math.round(performance.now() - started),
+                startedAt,
+            };
+            throw error;
+        }
+        throwIfAborted(signal);
+        const plans = descriptors.map(descriptor => ({
+            descriptor,
+            plan: this.planFor(descriptor),
+        }));
+        let sessionsRead = 0;
+        let sessionsReused = 0;
+        let sessionsFailed = 0;
+        let changed = false;
+        const next = new Map();
+        const failures = [];
+        const queue = [...plans];
+        let cursor = 0;
+        const worker = async () => {
+            for (;;) {
+                const item = queue[cursor];
+                cursor += 1;
+                if (item === undefined)
+                    return;
+                throwIfAborted(signal);
+                const { descriptor } = item;
+                const previous = this.cache.get(descriptor.id);
+                let plan = item.plan;
+                if (plan.kind === 'reuse') {
+                    if (previous !== undefined) {
+                        sessionsReused += 1;
+                        next.set(descriptor.id, {
+                            descriptor,
+                            aggregate: previous.aggregate,
+                            stamp: stampOf(descriptor),
+                            failed: null,
+                        });
+                        continue;
+                    }
+                    plan = { kind: 'read', from: 0 };
+                }
+                try {
+                    const read = await this.source.read(descriptor, plan.from);
+                    const canAppend = plan.from > 0
+                        && previous !== undefined
+                        && read.inheritedEventCount === previous.aggregate.inheritedEventCount;
+                    const aggregate = canAppend
+                        ? foldTail(previous.aggregate, read, this.now(), this.keepHoursMs)
+                        : foldFull(read, this.now(), this.keepHoursMs);
+                    sessionsRead += 1;
+                    changed = true;
+                    next.set(descriptor.id, {
+                        descriptor: { ...descriptor, seq: Math.max(descriptor.seq, aggregate.processed) },
+                        aggregate,
+                        stamp: stampOf(descriptor),
+                        failed: null,
+                    });
+                }
+                catch {
+                    sessionsFailed += 1;
+                    failures.push({ sessionId: descriptor.id, reason: 'read-failed' });
+                    if (previous !== undefined) {
+                        next.set(descriptor.id, {
+                            descriptor,
+                            aggregate: previous.aggregate,
+                            stamp: stampOf(descriptor),
+                            failed: 'read-failed',
+                        });
+                    }
+                }
+            }
+        };
+        await Promise.all(Array.from({ length: Math.min(this.concurrency, Math.max(1, queue.length)) }, () => worker()));
+        throwIfAborted(signal);
+        if (next.size !== this.cache.size)
+            changed = true;
+        if (!changed) {
+            for (const [id, entry] of next) {
+                const before = this.cache.get(id);
+                if (before !== undefined && before.stamp !== entry.stamp) {
+                    changed = true;
+                    break;
+                }
+            }
+        }
+        this.cache = next;
+        this.failures = failures;
+        this.lastScan = {
+            sessionsDiscovered: descriptors.length,
+            sessionsRead,
+            sessionsReused,
+            sessionsFailed,
+            durationMs: Math.round(performance.now() - started),
+            startedAt,
+        };
+        this.initialized = true;
+        if (changed)
+            this.markChanged();
+        else {
+            this.payload = null;
+            this.payloadRevision = -1;
+        }
+    }
+    planFor(descriptor) {
+        const entry = this.cache.get(descriptor.id);
+        if (entry === undefined || entry.failed !== null)
+            return { kind: 'read', from: 0 };
+        if (!sameSessionIdentity(entry.descriptor.header, descriptor.header))
+            return { kind: 'read', from: 0 };
+        if (descriptor.live) {
+            if (entry.aggregate.processed === descriptor.seq)
+                return { kind: 'reuse' };
+            if (entry.aggregate.processed < descriptor.seq
+                && entry.aggregate.inheritedEventCount === descriptor.inheritedEventCount) {
+                return { kind: 'read', from: entry.aggregate.processed };
+            }
+            return { kind: 'read', from: 0 };
+        }
+        if (entry.descriptor.live) {
+            // Live → persisted transition: the live fold already covers the log.
+            if (descriptor.eventCount === undefined || entry.aggregate.processed >= descriptor.eventCount) {
+                return { kind: 'reuse' };
+            }
+            return { kind: 'read', from: entry.aggregate.processed };
+        }
+        if (entry.stamp === stampOf(descriptor))
+            return { kind: 'reuse' };
+        return { kind: 'read', from: 0 };
+    }
+    markChanged() {
+        this.revision += 1;
+        this.payload = null;
+        this.payloadRevision = -1;
+    }
+}
+function foldFull(read, now, keepHoursMs) {
+    const aggregate = createAggregate(read.header, read.inheritedEventCount);
+    foldInto(aggregate, read.events, { now, keepHoursMs });
+    return aggregate;
+}
+function foldTail(aggregate, read, now, keepHoursMs) {
+    foldInto(aggregate, read.events, { now, keepHoursMs });
+    return aggregate;
+}
+function stampOf(descriptor) {
+    return descriptor.live ? `live:${descriptor.seq}` : `persisted:${descriptor.revision ?? ''}`;
+}
+function sameSessionIdentity(left, right) {
+    return left.id === right.id
+        && left.createdAt === right.createdAt
+        && left.cwd === right.cwd
+        && left.parentSession === right.parentSession
+        && left.isSeeded === right.isSeeded;
+}
+function mergeBucket(target, bucket) {
+    const existing = target.get(bucket.bucket);
+    if (existing === undefined) {
+        target.set(bucket.bucket, {
+            bucket: bucket.bucket,
+            requests: bucket.requests,
+            models: bucket.models.map(cloneModel),
+            ...cloneBuckets(bucket),
+        });
+        return;
+    }
+    addBuckets(existing, bucket);
+    existing.requests += bucket.requests;
+    for (const model of bucket.models)
+        mergeModelInBucket(existing, model);
+}
+function mergeModel(target, model) {
+    const existing = target.get(model.key);
+    if (existing === undefined) {
+        target.set(model.key, cloneModel(model));
+        return;
+    }
+    addBuckets(existing, model);
+    existing.requests += model.requests;
+}
+function mergeModelInBucket(bucket, model) {
+    const existing = bucket.models.find(item => item.key === model.key);
+    if (existing === undefined) {
+        bucket.models.push(cloneModel(model));
+        return;
+    }
+    addBuckets(existing, model);
+    existing.requests += model.requests;
+}
+function cloneModel(model) {
+    return {
+        key: model.key,
+        provider: model.provider,
+        model: model.model,
+        requests: model.requests,
+        ...cloneBuckets(model),
+    };
+}
+function cloneBuckets(buckets) {
+    return {
+        uncachedInputTokens: buckets.uncachedInputTokens,
+        cacheReadTokens: buckets.cacheReadTokens,
+        cacheWriteTokens: buckets.cacheWriteTokens,
+        outputTokens: buckets.outputTokens,
+    };
+}
+function isEvent(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const record = value;
+    return typeof record.type === 'string' && typeof record.seq === 'number' && Number.isFinite(record.seq);
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted === true) {
+        const error = new Error('aborted');
+        error.name = 'AbortError';
+        throw error;
+    }
+}

package/lib/host/fold.d.ts

@@ -0,0 +1,103 @@
+/**
+ * The pure token fold.
+ *
+ * It mirrors the official `tokenUsage` projection from
+ * `@deepseek-ai/dsh-token-meter`: the four provider buckets
+ * (`inputTokens`, `cacheReadTokens`, `cacheWriteTokens`, `outputTokens`) are
+ * disjoint, a later sample for the same (turn, step) replaces the previous
+ * sample instead of adding to it, and `llm/retry-started` closes that
+ * replacement scope so the retried attempt is billed separately. It also
+ * attributes each sample to the provider/model route the log records, buckets
+ * usage by local day and hour, and derives the session title.
+ *
+ * Events inherited by a seeded (forked) session are folded into `allTotals`
+ * for diagnostics but excluded from the session's own totals and from every
+ * global aggregate, so a forked prefix is never counted twice.
+ */
+import type { ModelUsage, TokenBuckets, UsageBucket } from '../shared/types.js';
+import type { RawSessionEvent, SessionHeaderLike } from './types.js';
+/** The last usage sample not yet closed by a retry; replacement scope. */
+export interface UsageTiming {
+    /** Time from step start to the first streamed token, when derivable. */
+    firstTokenMs: number | null;
+    /** Time from first streamed token to the final stream record. */
+    generationMs: number | null;
+    /** Full measured request window (first token plus generation, or fallback). */
+    totalMs: number | null;
+}
+export interface RequestSample {
+    key: string;
+    time: number;
+    provider: string;
+    model: string;
+    modelKey: string;
+    buckets: TokenBuckets;
+    speed: number | null;
+    firstToken: number | null;
+}
+export interface UsageSlot {
+    turn: number;
+    step: number;
+    time: number;
+    buckets: TokenBuckets;
+    provider: string;
+    model: string;
+    modelKey: string;
+    timing: UsageTiming | null;
+    requestKey: string;
+}
+/** Mutable incremental state carried between folds of the same session. */
+export interface FoldCarry {
+    /** Highest event seq folded so far; -1 before the first event. */
+    lastSeq: number;
+    /** Replacement scope for this session's own (non-inherited) events. */
+    own: UsageSlot | null;
+    /** Replacement scope over the whole log, used only for verification. */
+    all: UsageSlot | null;
+    currentProvider: string;
+    currentModel: string;
+    stepStart: {
+        turn: number;
+        step: number;
+        time: number;
+    } | null;
+}
+/** One session's derived token state. Plain JSON, no raw event content. */
+export interface SessionAggregate {
+    totals: TokenBuckets;
+    allTotals: TokenBuckets;
+    requests: number;
+    allRequests: number;
+    models: Record<string, ModelUsage>;
+    days: Record<string, UsageBucket>;
+    hours: Record<string, UsageBucket>;
+    title: string | null;
+    lastActivity: number;
+    createdAt: number;
+    processed: number;
+    inheritedEventCount: number;
+    /** Billed requests retained for the request log (own events only). */
+    requestSamples: RequestSample[];
+    carry: FoldCarry;
+}
+export interface FoldOptions {
+    /** Wall clock used for hour-bucket retention. */
+    now?: number;
+    /** Hours retained for the hourly "today" chart. */
+    keepHoursMs?: number;
+}
+/** Create an empty aggregate for one session. */
+export declare function createAggregate(header: SessionHeaderLike, inheritedEventCount: number): SessionAggregate;
+/** Fold additional contiguous events into one aggregate in place. */
+export declare function foldInto(aggregate: SessionAggregate, events: readonly RawSessionEvent[], options?: FoldOptions): void;
+/** Fold one complete session log from scratch. */
+export declare function foldSession(header: SessionHeaderLike, events: readonly RawSessionEvent[], inheritedEventCount: number, options?: FoldOptions): SessionAggregate;
+/** Detached, wire-safe session counters for diagnostics and row rendering. */
+export declare function summarizeSession(aggregate: SessionAggregate): {
+    totals: TokenBuckets;
+    requests: number;
+    cacheHitRate: number;
+    models: ModelUsage[];
+    eventCount: number;
+    inheritedEventCount: number;
+};