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

package/lib/shared/pricing.js

@@ -0,0 +1,192 @@
+/**
+ * Optional cost estimation. Prices are supplied by the user and stored only in
+ * the browser's localStorage; the plugin ships no price table and never infers
+ * a rate. All amounts are labelled "Estimated Cost".
+ */
+import { builtinPriceFor } from './builtin-prices.js';
+/** Suggested currencies; the editor accepts any short code as well. */
+export const SUGGESTED_CURRENCIES = ['CNY', 'USD', 'EUR', 'JPY'];
+/** Resolve user overrides over online prices over built-in list prices. */
+export function defaultsForModels(models, online) {
+    const table = {};
+    for (const model of models) {
+        const price = online[model.model.trim().toLowerCase()] ?? builtinPriceFor(model.model);
+        if (price !== undefined)
+            table[model.key] = price;
+    }
+    return table;
+}
+/** User overrides win per model; the defaults stay for untouched models. */
+export function mergePricing(defaults, overrides) {
+    return { ...defaults, ...overrides };
+}
+/** True when two price rows carry identical currency and rates. */
+export function samePrice(left, right) {
+    if (left === undefined || right === undefined)
+        return left === right;
+    return left.currency === right.currency
+        && left.input === right.input
+        && left.output === right.output
+        && left.cacheRead === right.cacheRead
+        && left.cacheWrite === right.cacheWrite;
+}
+/** Parse the persisted online table defensively. */
+export function parseOnlinePricing(raw) {
+    if (typeof raw !== 'string' || raw.trim() === '')
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+        return null;
+    const record = parsed;
+    const source = typeof record.source === 'string' ? record.source.trim().slice(0, 80) : '';
+    const fetchedAt = typeof record.fetchedAt === 'number' && Number.isFinite(record.fetchedAt)
+        ? record.fetchedAt
+        : 0;
+    const prices = {};
+    if (record.prices !== null && typeof record.prices === 'object' && !Array.isArray(record.prices)) {
+        for (const [name, value] of Object.entries(record.prices)) {
+            const price = normalizePrice(value);
+            if (price !== null)
+                prices[name.trim().toLowerCase()] = price;
+        }
+    }
+    return { prices, source, fetchedAt };
+}
+/** Serialize the online table and its provenance. */
+export function serializeOnlinePricing(state) {
+    return JSON.stringify(state);
+}
+/** True only when every rate and the currency are present and valid. */
+export function isPriceConfigured(price) {
+    if (price === undefined)
+        return false;
+    if (typeof price.currency !== 'string' || price.currency.trim() === '')
+        return false;
+    return [price.input, price.output, price.cacheRead, price.cacheWrite].every(validRate);
+}
+/** Estimated cost for one model, or null when no usable price exists. */
+export function costOf(usage, price) {
+    if (!isPriceConfigured(price))
+        return null;
+    const amount = (usage.uncachedInputTokens * price.input
+        + usage.cacheReadTokens * price.cacheRead
+        + usage.cacheWriteTokens * price.cacheWrite
+        + usage.outputTokens * price.output) / 1_000_000;
+    return Number.isFinite(amount) ? amount : null;
+}
+/** Build the per-model estimate and currency totals for the current range. */
+export function estimateCost(models, table) {
+    const rows = [];
+    const totals = new Map();
+    let pricedModels = 0;
+    let unpricedModels = 0;
+    for (const model of models) {
+        const price = table[model.key];
+        const configured = isPriceConfigured(price);
+        const amount = configured ? costOf(model, price) : null;
+        if (configured && amount !== null) {
+            pricedModels += 1;
+            totals.set(price.currency, (totals.get(price.currency) ?? 0) + amount);
+        }
+        else {
+            unpricedModels += 1;
+        }
+        rows.push({
+            key: model.key,
+            provider: model.provider,
+            model: model.model,
+            tokens: {
+                uncachedInputTokens: model.uncachedInputTokens,
+                cacheReadTokens: model.cacheReadTokens,
+                cacheWriteTokens: model.cacheWriteTokens,
+                outputTokens: model.outputTokens,
+            },
+            requests: model.requests,
+            priced: configured && amount !== null,
+            currency: configured ? price.currency : null,
+            amount,
+            missing: !configured,
+        });
+    }
+    return {
+        rows,
+        totals: [...totals.entries()].map(([currency, amount]) => ({ currency, amount })),
+        pricedModels,
+        unpricedModels,
+    };
+}
+/** Parse a persisted pricing table defensively; unknown or invalid rows are dropped. */
+export function parsePricing(raw) {
+    if (typeof raw !== 'string' || raw.trim() === '')
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+        return {};
+    const table = {};
+    for (const [key, value] of Object.entries(parsed)) {
+        const price = normalizePrice(value);
+        if (price !== null)
+            table[key] = price;
+    }
+    return table;
+}
+/** Serialize a table for localStorage. */
+export function serializePricing(table) {
+    return JSON.stringify(table);
+}
+/** Normalize one untrusted pricing value. */
+export function normalizePrice(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const record = value;
+    const currency = typeof record.currency === 'string' ? record.currency.trim().toUpperCase() : '';
+    if (currency === '' || currency.length > 8)
+        return null;
+    const input = numberOrNull(record.input);
+    const output = numberOrNull(record.output);
+    const cacheRead = numberOrNull(record.cacheRead);
+    const cacheWrite = numberOrNull(record.cacheWrite);
+    if (input === null || output === null || cacheRead === null || cacheWrite === null)
+        return null;
+    return { currency, input, output, cacheRead, cacheWrite };
+}
+/** Format an amount using its currency, with more precision for tiny values. */
+export function formatAmount(amount, currency) {
+    const digits = amount !== 0 && Math.abs(amount) < 0.01 ? 6 : 2;
+    try {
+        return new Intl.NumberFormat(undefined, {
+            style: 'currency',
+            currency,
+            minimumFractionDigits: digits,
+            maximumFractionDigits: digits,
+        }).format(amount);
+    }
+    catch {
+        return `${currency} ${amount.toFixed(digits)}`;
+    }
+}
+function numberOrNull(value) {
+    if (typeof value === 'number' && Number.isFinite(value) && value >= 0)
+        return value;
+    if (typeof value === 'string' && value.trim() !== '') {
+        const parsed = Number(value);
+        if (Number.isFinite(parsed) && parsed >= 0)
+            return parsed;
+    }
+    return null;
+}
+function validRate(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0;
+}

package/lib/shared/range.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Time-range selection for the dashboard. Range filtering happens on the
+ * compact per-day / per-hour buckets the Host already aggregated, so changing
+ * the range never triggers a log read.
+ */
+import type { ModelUsage, StatsPayload, TokenBuckets, UsageBucket } from './types.js';
+export type RangeId = 'today' | '7d' | '30d' | '90d' | 'all' | 'custom';
+export interface RangeSelection {
+    id: RangeId;
+    /** Custom range start (`YYYY-MM-DD`); ignored by the preset ranges. */
+    from: string;
+    /** Custom range end (`YYYY-MM-DD`); ignored by the preset ranges. */
+    to: string;
+}
+export interface RangeResult {
+    granularity: 'hour' | 'day';
+    from: string;
+    to: string;
+    buckets: UsageBucket[];
+    totals: TokenBuckets;
+    requests: number;
+    models: ModelUsage[];
+    cacheHitRate: number;
+    totalTokens: number;
+}
+export type RangeSource = Pick<StatsPayload, 'days' | 'hours' | 'today'>;
+/** Preset range lengths in days; 0 means all time and -1 means custom. */
+export declare const RANGE_DAYS: Record<Exclude<RangeId, 'custom' | 'all'>, number>;
+/** Build the chart bucket list and range totals for one selection. */
+export declare function selectRange(source: RangeSource, selection: RangeSelection): RangeResult;
+/** Sum buckets and merge their model rows. */
+export declare function summarize(buckets: UsageBucket[], granularity: 'hour' | 'day', from: string, to: string): RangeResult;
+/** Share of the range total, 0 when the range is empty. */
+export declare function shareOf(value: number, total: number): number;

package/lib/shared/range.js

@@ -0,0 +1,93 @@
+/**
+ * Time-range selection for the dashboard. Range filtering happens on the
+ * compact per-day / per-hour buckets the Host already aggregated, so changing
+ * the range never triggers a log read.
+ */
+import { addDays, dayHours, enumerateDays, isDayKey, lastDays, spanDays } from './dates.js';
+import { addBuckets, cacheHitRate as hitRateOf, emptyBuckets, sortModels, totalTokens, } from './model.js';
+/** Preset range lengths in days; 0 means all time and -1 means custom. */
+export const RANGE_DAYS = {
+    today: 1,
+    '7d': 7,
+    '30d': 30,
+    '90d': 90,
+};
+/** Build the chart bucket list and range totals for one selection. */
+export function selectRange(source, selection) {
+    const dayIndex = new Map(source.days.map(bucket => [bucket.bucket, bucket]));
+    const hourIndex = new Map(source.hours.map(bucket => [bucket.bucket, bucket]));
+    if (selection.id === 'today') {
+        const keys = dayHours(source.today);
+        const buckets = keys.map(key => hourIndex.get(key) ?? emptyBucket(key));
+        return summarize(buckets, 'hour', source.today, source.today);
+    }
+    let keys;
+    let from;
+    let to;
+    if (selection.id === 'all') {
+        const sorted = source.days.map(bucket => bucket.bucket).sort();
+        const first = sorted[0];
+        const last = sorted[sorted.length - 1];
+        if (first === undefined || last === undefined) {
+            return summarize([], 'day', source.today, source.today);
+        }
+        from = first;
+        to = last;
+        keys = spanDays(from, to) <= 400 ? enumerateDays(from, to) : sorted;
+    }
+    else if (selection.id === 'custom') {
+        const end = isDayKey(selection.to) ? selection.to : source.today;
+        const start = isDayKey(selection.from) ? selection.from : addDays(end, -29);
+        const [low, high] = start <= end ? [start, end] : [end, start];
+        to = high;
+        from = spanDays(low, high) > 400 ? addDays(high, -399) : low;
+        keys = enumerateDays(from, to, 400);
+    }
+    else {
+        const length = RANGE_DAYS[selection.id];
+        keys = lastDays(source.today, length);
+        from = keys[0] ?? source.today;
+        to = keys[keys.length - 1] ?? source.today;
+    }
+    const buckets = keys.map(key => dayIndex.get(key) ?? emptyBucket(key));
+    return summarize(buckets, 'day', from, to);
+}
+/** Sum buckets and merge their model rows. */
+export function summarize(buckets, granularity, from, to) {
+    const totals = emptyBuckets();
+    const models = new Map();
+    let requests = 0;
+    for (const bucket of buckets) {
+        addBuckets(totals, bucket);
+        requests += bucket.requests;
+        for (const usage of bucket.models) {
+            const existing = models.get(usage.key);
+            if (existing === undefined) {
+                // A detached row: bucket model rows are never mutated by range logic.
+                models.set(usage.key, { ...usage });
+            }
+            else {
+                addBuckets(existing, usage);
+                existing.requests += usage.requests;
+            }
+        }
+    }
+    return {
+        granularity,
+        from,
+        to,
+        buckets,
+        totals,
+        requests,
+        models: sortModels([...models.values()]),
+        cacheHitRate: hitRateOf(totals),
+        totalTokens: totalTokens(totals),
+    };
+}
+/** Share of the range total, 0 when the range is empty. */
+export function shareOf(value, total) {
+    return total <= 0 ? 0 : value / total;
+}
+function emptyBucket(bucket) {
+    return { bucket, requests: 0, models: [], ...emptyBuckets() };
+}

package/lib/shared/types.d.ts

@@ -0,0 +1,168 @@
+/**
+ * Wire contract shared by the Host aggregator and the browser dashboard.
+ *
+ * These values describe token accounting only. They never include prompt text,
+ * assistant text, tool arguments, file contents, credentials, or raw events.
+ */
+/** The only wire contract this plugin currently serves. */
+export declare const API_VERSION = 1;
+/** Same-origin route prefix registered on the Harness web server. */
+export declare const API_PREFIX = "/dsh-token-dashboard";
+/** The four disjoint buckets reported by providers and folded by token-meter. */
+export interface TokenBuckets {
+    /** Provider `inputTokens`: prompt tokens that were neither read from nor written to cache. */
+    uncachedInputTokens: number;
+    /** Provider `cacheReadTokens`: prompt tokens served from the provider cache. */
+    cacheReadTokens: number;
+    /** Provider `cacheWriteTokens`: prompt tokens written to the provider cache. */
+    cacheWriteTokens: number;
+    /** Provider `outputTokens`: generated tokens, reasoning included as the provider reports it. */
+    outputTokens: number;
+}
+/** One model (provider + model identity) over some window. */
+export interface ModelUsage extends TokenBuckets {
+    /** Stable key derived from provider and model id; `unknown` when unidentifiable. */
+    key: string;
+    provider: string;
+    model: string;
+    /** Number of billed attempts attributed to this model. */
+    requests: number;
+}
+/** One time bucket (a local calendar day or a local hour). */
+export interface UsageBucket extends TokenBuckets {
+    /** `YYYY-MM-DD` for days, `YYYY-MM-DDTHH` for hours. */
+    bucket: string;
+    requests: number;
+    models: ModelUsage[];
+}
+/** One session row in the dashboard table. */
+export interface SessionSummary {
+    id: string;
+    /** Latest log-backed `session/title`, or null when the log has none. */
+    title: string | null;
+    /** Human-readable project label: the workspace title when known, else the cwd basename. */
+    project: string;
+    /** Absolute working directory, or null when the session has none. */
+    cwd: string | null;
+    /** Model keys that contributed usage in this session. */
+    modelKeys: string[];
+    createdAt: number;
+    lastActivity: number;
+    live: boolean;
+    origin: 'root' | 'subagent';
+    /** True when this session's log inherited a prefix from another session. */
+    seeded: boolean;
+    parentSession: string | null;
+    agentPreset: string | null;
+    totals: TokenBuckets;
+    requests: number;
+    cacheHitRate: number;
+    models: ModelUsage[];
+    eventCount: number;
+    inheritedEventCount: number;
+    /** A newer log revision could not be read; the row shows the last good fold. */
+    stale: boolean;
+}
+/** One billed request row for the request log. */
+export interface RequestRecord {
+    /** Stable row key for React and paging. */
+    id: string;
+    sessionId: string;
+    sessionTitle: string | null;
+    project: string;
+    /** Agent preset label, or a generic harness label when absent. */
+    app: string;
+    time: number;
+    provider: string;
+    model: string;
+    /** Pricing key (`provider::model`). */
+    modelKey: string;
+    inputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    outputTokens: number;
+    speed: number | null;
+    firstToken: number | null;
+}
+/** One page of the request log. */
+export interface RequestLogPage {
+    revision: number;
+    total: number;
+    offset: number;
+    limit: number;
+    generatedAt: number;
+    rows: RequestRecord[];
+}
+/** One failed session read. Only an id and a stable reason code are exposed. */
+export interface SessionReadError {
+    sessionId: string;
+    reason: string;
+}
+/** What the last aggregation pass did. */
+export interface ScanReport {
+    /** Sessions currently visible (live + persisted). */
+    sessionsDiscovered: number;
+    /** Sessions whose log was actually read during the pass. */
+    sessionsRead: number;
+    /** Sessions served from the in-memory revision cache. */
+    sessionsReused: number;
+    sessionsFailed: number;
+    durationMs: number;
+    /** Epoch ms when the pass started. */
+    startedAt: number;
+    /** Epoch ms when the payload was produced. */
+    generatedAt: number;
+    /** True when at least one session could not be read. */
+    partial: boolean;
+}
+/** The complete dashboard payload. */
+export interface StatsPayload {
+    apiVersion: number;
+    revision: number;
+    generatedAt: number;
+    /** IANA time zone used for day/hour bucketing. */
+    timezone: string;
+    /** Today's local calendar date, `YYYY-MM-DD`. */
+    today: string;
+    totals: TokenBuckets;
+    /** Total billed attempts across all sessions. */
+    requests: number;
+    cacheHitRate: number;
+    sessions: {
+        total: number;
+        withUsage: number;
+        live: number;
+        subagents: number;
+        seeded: number;
+    };
+    models: ModelUsage[];
+    days: UsageBucket[];
+    /** Only the trailing 48 hours, so "today" can render an hourly chart. */
+    hours: UsageBucket[];
+    sessionRows: SessionSummary[];
+    scan: ScanReport;
+    errors: SessionReadError[];
+}
+/** Cross-check of this plugin's fold against token-meter's `tokenUsage` projection. */
+export interface VerifyReport {
+    apiVersion: number;
+    checked: number;
+    matched: number;
+    mismatched: number;
+    unsupported: number;
+    /** Fold result that matched the official projection, per checked session group. */
+    matchedBasis: {
+        own: number;
+        allLog: number;
+        none: number;
+    };
+    details: Array<{
+        sessionId: string;
+        official: TokenBuckets;
+        own: TokenBuckets;
+        allLog: TokenBuckets;
+        inheritedEventCount: number;
+        match: 'own' | 'allLog' | 'none';
+    }>;
+    generatedAt: number;
+}

package/lib/shared/types.js

@@ -0,0 +1,10 @@
+/**
+ * Wire contract shared by the Host aggregator and the browser dashboard.
+ *
+ * These values describe token accounting only. They never include prompt text,
+ * assistant text, tool arguments, file contents, credentials, or raw events.
+ */
+/** The only wire contract this plugin currently serves. */
+export const API_VERSION = 1;
+/** Same-origin route prefix registered on the Harness web server. */
+export const API_PREFIX = '/dsh-token-dashboard';

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Token usage",
+    "description": "Global Token usage for every local session: totals, daily trends, model breakdown, session ranking, and optional cost estimates."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Token 用量",
+    "description": "本机全部会话的 Token 用量看板：总量、每日趋势、模型分布、会话排行，以及可选费用估算。"
+  }
+}

package/package.json

@@ -1,6 +1,95 @@
 {
   "name": "@shi-yangyang/dsh-token-dashboard",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Global Token usage analytics for every DeepSeek Harness session: totals, trends, models, sessions, and optional cost estimates.",
+  "keywords": [
+    "deepseek",
+    "harness",
+    "dsh",
+    "dsh-plugin",
+    "token",
+    "usage",
+    "dashboard",
+    "analytics"
+  ],
+  "type": "module",
+  "main": "./lib/host/index.js",
+  "types": "./lib/host/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/host/index.d.ts",
+      "default": "./lib/host/index.js"
+    },
+    "./client": "./client/client.js",
+    "./locale/*.json": "./locale/*.json",
+    "./icon": "./icon.svg",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "client",
+    "locale",
+    "icon.svg",
+    "cordis.patch.yml",
+    "README.md",
+    "THIRD_PARTY_NOTICES.md",
+    "LICENSE"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "immediately": true,
+      "inject": [
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-theme"
+      ]
+    }
+  },
+  "scripts": {
+    "build": "npm run build:host && npm run build:client",
+    "build:prices": "node scripts/build-builtin-prices.mjs",
+    "build:host": "tsc -p tsconfig.host.json",
+    "build:css": "tailwindcss -i src/client/beui.css -o src/client/beui.generated.css --minify",
+    "build:client": "node scripts/build-client.mjs",
+    "pretest": "node scripts/build-client.mjs",
+    "typecheck": "tsc -p tsconfig.host.json --noEmit && tsc -p tsconfig.client.json --noEmit && tsc -p tsconfig.test.json --noEmit",
+    "test": "node scripts/test.mjs",
+    "prepare": "npm run build",
+    "prepack": "npm run build",
+    "verify:real": "node scripts/verify-real-sessions.mjs"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shi-YangYang/dsh-token-dashboard.git"
+  },
+  "homepage": "https://github.com/shi-YangYang/dsh-token-dashboard#readme",
+  "engines": {
+    "node": ">=22.18"
+  },
+  "devDependencies": {
+    "@tailwindcss/cli": "^4.3.5",
+    "@types/jsdom": "^21.1.7",
+    "@types/node": "^24.10.0",
+    "@types/react": "^18.3.12",
+    "@types/react-dom": "18.3.7",
+    "esbuild": "^0.25.0",
+    "jsdom": "^26.1.0",
+    "react": "18.3.1",
+    "react-dom": "18.3.1",
+    "tailwindcss": "^4.3.5",
+    "typescript": "^5.9.0"
+  },
+  "dependencies": {
+    "clsx": "^2.1.1",
+    "lucide-react": "^1.70.0",
+    "motion": "^14.10.1",
+    "tailwind-merge": "^3.7.0"
+  }
+}