@nexus-aethra/dshell-usage 0.1.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nexus Aethra
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/lib/client/heatmap.js

@@ -0,0 +1,96 @@
+/**
+ * The heatmap's layout: a fixed calendar rectangle of day cells.
+ *
+ * The grid is filled the way a page is read — top to bottom, then the next
+ * column — so the newest day always sits in the BOTTOM-RIGHT corner. That is
+ * the shape a reader expects from a "last 26 weeks" block, and it is why the
+ * cells are not weekday-aligned: aligning columns to weeks would leave the most
+ * recent day wherever its weekday happened to fall, which reads as a hole in the
+ * corner rather than as "this is now".
+ *
+ * Pure and separate from the page for the same reason the fold is separate from
+ * the store: the interesting part is date arithmetic (which day a cell holds,
+ * which cells the history actually covers, how a token count becomes a shade),
+ * and that is testable without a browser while a chart is not.
+ *
+ * Days are the host's own `YYYY-MM-DD` local days, and the anchor is the host's
+ * today — the index bucketed by LOCAL day when it scanned, so the grid reads
+ * them as local dates too, or a bucket would slide across a cell boundary near
+ * midnight.
+ */
+/** How many shades a non-empty day can take, above "nothing recorded". */
+export const HEAT_LEVELS = 4;
+/** The shape of the grid: columns of a week, however many weeks fit. */
+export const HEAT_ROWS = 7;
+/** The local date of a `YYYY-MM-DD` label, at local midnight. */
+function dateOf(day) {
+    return new Date(`${day}T00:00:00`);
+}
+/** The `YYYY-MM-DD` label of a local date, the way the index spells days. */
+function labelOf(date) {
+    const pad = (value) => String(value).padStart(2, '0');
+    return `${String(date.getFullYear())}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+}
+/**
+ * Lay the recorded days out in a full rectangle of `weeks` columns.
+ *
+ * The newest cell is the anchor: the last column's bottom cell holds the anchor
+ * day, and every earlier cell steps back one day, so the grid reads oldest at
+ * the top-left and newest at the bottom-right. The rectangle is always full —
+ * cells the history does not reach are present but empty — because a grid that
+ * grew and shrank with the data would move the corner as the history changed.
+ *
+ * @param days - one entry per recorded day, any order.
+ * @param weeks - how many columns to draw.
+ * @param anchor - the host's today, `YYYY-MM-DD`; the bottom-right cell.
+ * @returns the columns, left to right.
+ */
+export function heatmapColumns(days, weeks, anchor) {
+    const byDay = new Map(days.map(day => [day.day, day]));
+    const max = Math.max(1, ...days.map(day => day.total));
+    const end = dateOf(anchor);
+    const columns = [];
+    for (let column = 0; column < weeks; column += 1) {
+        const cells = [];
+        for (let row = 0; row < HEAT_ROWS; row += 1) {
+            // Counted back from the anchor, so the loop's last cell is the anchor
+            // itself however many columns the grid has.
+            const back = (weeks - 1 - column) * HEAT_ROWS + (HEAT_ROWS - 1 - row);
+            const date = new Date(end);
+            date.setDate(date.getDate() - back);
+            const label = labelOf(date);
+            if (date.getTime() > end.getTime()) {
+                cells.push(undefined);
+                continue;
+            }
+            const recorded = byDay.get(label);
+            cells.push(recorded === undefined
+                ? undefined
+                : {
+                    ...recorded,
+                    level: recorded.total === 0
+                        ? 0
+                        : Math.min(HEAT_LEVELS, 1 + Math.floor((recorded.total / max) * (HEAT_LEVELS - 1))),
+                });
+        }
+        columns.push(cells);
+    }
+    return columns;
+}
+/**
+ * Whether the history reaches further back than the grid draws.
+ *
+ * @param days - the same days handed to {@link heatmapColumns}.
+ * @param weeks - the same width.
+ * @param anchor - the same anchor.
+ * @returns whether any recorded day fell off the left edge.
+ */
+export function heatmapTruncated(days, weeks, anchor) {
+    if (days.length === 0)
+        return false;
+    const oldest = days.reduce((earliest, day) => (day.day < earliest ? day.day : earliest), days[0].day);
+    const start = dateOf(anchor);
+    start.setDate(start.getDate() - (weeks * HEAT_ROWS - 1));
+    return dateOf(oldest).getTime() < start.getTime();
+}
+//# sourceMappingURL=heatmap.js.map

package/lib/client/heatmap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"heatmap.js","sourceRoot":"","sources":["../../src/client/heatmap.ts"],"names":[],"mappings":"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"}

package/lib/client/index.js

@@ -0,0 +1,36 @@
+/**
+ * The usage page's client face: the locale dictionaries and the Settings
+ * navigation row that mounts the page.
+ *
+ * `settings.section` is the seat dsh's own Plugins page uses, so this page is a
+ * peer of it rather than a tab inside it — the charts want the full settings
+ * column, and a reader looking for "what did this cost" looks in the
+ * navigation, not under a plugin list.
+ */
+import { en, zh } from './locales.js';
+import { UsageSection } from './page.js';
+import { watchUsageNavIcon } from './nav-icon.js';
+/** The locale namespace, matching the key `locales.ts` declares. */
+const NS = 'dshellUsage';
+export const name = '@nexus-aethra/dshell-usage/client';
+export const inject = ['slots', 'locale'];
+export function apply(ctx) {
+    const t = ctx.locale.bind(NS);
+    // Registered through an effect so a composition that unloads this plugin
+    // takes its copy with it.
+    ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'dshell-usage: dictionaries');
+    // Ordered after the Plugins page (15) so the navigation reads
+    // sessions → plugins → usage, and named with its own id so it is added beside
+    // the shipped entries rather than replacing one.
+    ctx.slots.inject('settings.section', () => ctx.slots.register({
+        name: 'settings.section',
+        id: 'usage',
+        order: 40,
+        label: () => t('nav'),
+        locale: NS,
+    }, UsageSection));
+    // The row's own icon, because this seat carries none: dsh draws a generic
+    // gear for any section id it does not ship (see nav-icon.ts).
+    ctx.effect(() => watchUsageNavIcon(() => t('nav')), 'dshell-usage: navigation icon');
+}
+//# sourceMappingURL=index.js.map

package/lib/client/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAUH,OAAO,EAAE,EAAE,EAAE,EAAE,EAAE,MAAM,cAAc,CAAA;AACrC,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AACxC,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AAEjD,oEAAoE;AACpE,MAAM,EAAE,GAAG,aAAa,CAAA;AAExB,MAAM,CAAC,MAAM,IAAI,GAAG,mCAAmC,CAAA;AAEvD,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,OAAO,EAAE,QAAQ,CAAU,CAAA;AAElD,MAAM,UAAU,KAAK,CAAC,GAAY;IAChC,MAAM,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IAC7B,yEAAyE;IACzE,0BAA0B;IAC1B,GAAG,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,4BAA4B,CAAC,CAAA;IACnF,8DAA8D;IAC9D,8EAA8E;IAC9E,iDAAiD;IACjD,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,kBAAkB,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC;QAC5D,IAAI,EAAE,kBAAkB;QACxB,EAAE,EAAE,OAAO;QACX,KAAK,EAAE,EAAE;QACT,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;QACrB,MAAM,EAAE,EAAE;KACX,EAAE,YAAY,CAAC,CAAC,CAAA;IACjB,0EAA0E;IAC1E,8DAA8D;IAC9D,GAAG,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,iBAAiB,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,+BAA+B,CAAC,CAAA;AACtF,CAAC"}

package/lib/client/locales.js

@@ -0,0 +1,95 @@
+/**
+ * `dshellUsage` namespace dictionaries, and the namespace's declaration.
+ *
+ * The namespace merge lives with its key set so that any module naming
+ * `TranslateNS<'dshellUsage'>` or `PropsLocale<'dshellUsage'>` needs only this
+ * file. Keys are lowercase and dotted: `nav.*` (the settings navigation row),
+ * `range.*` (the window selector), `chart.*` (the two charts' captions),
+ * `table.*` (the route breakdown), and `state.*` (empty, busy, freshness, and
+ * the load failure).
+ */
+/** Simplified Chinese dictionary and key-set source of truth. */
+export const zh = {
+    // The Settings navigation row this page owns.
+    'nav': '用量',
+    'title': '模型 token 消耗',
+    'subtitle': '按模型汇总每个会话上报的用量。索引建在 dshell 自己的数据目录里，首次打开会扫一遍全部历史会话，之后只补新增的部分。',
+    // The window selector. `{days}` is the day count.
+    'range.7': '近 7 天',
+    'range.30': '近 30 天',
+    'range.all': '全部',
+    'range.label': '时间范围',
+    'rebuild': '重新聚合',
+    'rebuild.busy': '正在聚合…',
+    'chart.heatmap': '每日热力（近 26 周内）',
+    'chart.heatmapDay': '{day} · {total} tok · {turns} 次调用',
+    'chart.heatmapLess': '少',
+    'chart.heatmapMore': '多',
+    'chart.heatmapPeak': '最忙一天 {total} tok',
+    'chart.heatmapTruncated': '只画最近 26 周',
+    'chart.curve': '每日消耗（按模型）',
+    'chart.pie': '模型占比',
+    'summary.total': '合计',
+    'summary.uncached': '未缓存输入',
+    'summary.output': '输出',
+    'summary.cacheRead': '缓存读',
+    'summary.turns': '调用',
+    'summary.hitRate': '缓存命中率',
+    'table.title': '按模型明细',
+    'table.model': '模型',
+    'table.input': '输入',
+    'table.output': '输出',
+    'table.cacheRead': '缓存读',
+    'table.cacheWrite': '缓存写',
+    'table.turns': '调用',
+    'table.total': '合计',
+    'state.empty.title': '还没有可统计的用量',
+    'state.empty.body': '索引里没有任何一条带用量上报的模型调用。跑一次 agent 会话后再点「重新聚合」。',
+    'state.freshness': '索引更新于 {day}',
+    'state.skipped': '有 {count} 个会话的日志读不了，未计入（详情见悬停提示）。',
+    'state.scanned': '本次扫描列出 {sessions} 个会话，读取了 {read} 个，命中 {turns} 次调用。',
+    'state.error': '读取用量失败：{reason}',
+    'state.loading': '正在读取索引…',
+};
+/** English dictionary, keyed by the same set. */
+export const en = {
+    'nav': 'Usage',
+    'title': 'Model token usage',
+    'subtitle': 'Per-model totals folded from the usage every session reports. The index lives in dshell\'s own data directory: the first visit scans every session once, and later visits add only what is new.',
+    'range.7': 'Last 7 days',
+    'range.30': 'Last 30 days',
+    'range.all': 'All time',
+    'range.label': 'Range',
+    'rebuild': 'Rebuild',
+    'rebuild.busy': 'Rebuilding…',
+    'chart.heatmap': 'Daily heatmap (last 26 weeks)',
+    'chart.heatmapDay': '{day} · {total} tok · {turns} calls',
+    'chart.heatmapLess': 'Less',
+    'chart.heatmapMore': 'More',
+    'chart.heatmapPeak': 'Busiest day {total} tok',
+    'chart.heatmapTruncated': 'Showing the last 26 weeks',
+    'chart.curve': 'Daily usage by model',
+    'chart.pie': 'Share by model',
+    'summary.total': 'Total',
+    'summary.uncached': 'Uncached input',
+    'summary.output': 'Output',
+    'summary.cacheRead': 'Cache read',
+    'summary.turns': 'Calls',
+    'summary.hitRate': 'Cache hit rate',
+    'table.title': 'By model',
+    'table.model': 'Model',
+    'table.input': 'Input',
+    'table.output': 'Output',
+    'table.cacheRead': 'Cache read',
+    'table.cacheWrite': 'Cache write',
+    'table.turns': 'Calls',
+    'table.total': 'Total',
+    'state.empty.title': 'No usage to count yet',
+    'state.empty.body': 'The index holds no model call that reported usage. Run an agent session, then press Rebuild.',
+    'state.freshness': 'Index updated {day}',
+    'state.skipped': '{count} session logs could not be read and are not counted (hover for the reason).',
+    'state.scanned': 'This scan listed {sessions} sessions, read {read}, and counted {turns} calls.',
+    'state.error': 'Reading usage failed: {reason}',
+    'state.loading': 'Reading the index…',
+};
+//# sourceMappingURL=locales.js.map

package/lib/client/locales.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"locales.js","sourceRoot":"","sources":["../../src/client/locales.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAWH,iEAAiE;AACjE,MAAM,CAAC,MAAM,EAAE,GAAG;IAChB,8CAA8C;IAC9C,KAAK,EAAE,IAAI;IAEX,OAAO,EAAE,aAAa;IACtB,UAAU,EAAE,+DAA+D;IAE3E,kDAAkD;IAClD,SAAS,EAAE,OAAO;IAClB,UAAU,EAAE,QAAQ;IACpB,WAAW,EAAE,IAAI;IACjB,aAAa,EAAE,MAAM;IAErB,SAAS,EAAE,MAAM;IACjB,cAAc,EAAE,OAAO;IAEvB,eAAe,EAAE,eAAe;IAChC,kBAAkB,EAAE,mCAAmC;IACvD,mBAAmB,EAAE,GAAG;IACxB,mBAAmB,EAAE,GAAG;IACxB,mBAAmB,EAAE,kBAAkB;IACvC,wBAAwB,EAAE,WAAW;IACrC,aAAa,EAAE,WAAW;IAC1B,WAAW,EAAE,MAAM;IAEnB,eAAe,EAAE,IAAI;IACrB,kBAAkB,EAAE,OAAO;IAC3B,gBAAgB,EAAE,IAAI;IACtB,mBAAmB,EAAE,KAAK;IAC1B,eAAe,EAAE,IAAI;IACrB,iBAAiB,EAAE,OAAO;IAE1B,aAAa,EAAE,OAAO;IACtB,aAAa,EAAE,IAAI;IACnB,aAAa,EAAE,IAAI;IACnB,cAAc,EAAE,IAAI;IACpB,iBAAiB,EAAE,KAAK;IACxB,kBAAkB,EAAE,KAAK;IACzB,aAAa,EAAE,IAAI;IACnB,aAAa,EAAE,IAAI;IAEnB,mBAAmB,EAAE,WAAW;IAChC,kBAAkB,EAAE,4CAA4C;IAChE,iBAAiB,EAAE,aAAa;IAChC,eAAe,EAAE,mCAAmC;IACpD,eAAe,EAAE,oDAAoD;IACrE,aAAa,EAAE,iBAAiB;IAChC,eAAe,EAAE,SAAS;CAClB,CAAA;AAKV,iDAAiD;AACjD,MAAM,CAAC,MAAM,EAAE,GAAmC;IAChD,KAAK,EAAE,OAAO;IAEd,OAAO,EAAE,mBAAmB;IAC5B,UAAU,EAAE,iMAAiM;IAE7M,SAAS,EAAE,aAAa;IACxB,UAAU,EAAE,cAAc;IAC1B,WAAW,EAAE,UAAU;IACvB,aAAa,EAAE,OAAO;IAEtB,SAAS,EAAE,SAAS;IACpB,cAAc,EAAE,aAAa;IAE7B,eAAe,EAAE,+BAA+B;IAChD,kBAAkB,EAAE,qCAAqC;IACzD,mBAAmB,EAAE,MAAM;IAC3B,mBAAmB,EAAE,MAAM;IAC3B,mBAAmB,EAAE,yBAAyB;IAC9C,wBAAwB,EAAE,2BAA2B;IACrD,aAAa,EAAE,sBAAsB;IACrC,WAAW,EAAE,gBAAgB;IAE7B,eAAe,EAAE,OAAO;IACxB,kBAAkB,EAAE,gBAAgB;IACpC,gBAAgB,EAAE,QAAQ;IAC1B,mBAAmB,EAAE,YAAY;IACjC,eAAe,EAAE,OAAO;IACxB,iBAAiB,EAAE,gBAAgB;IAEnC,aAAa,EAAE,UAAU;IACzB,aAAa,EAAE,OAAO;IACtB,aAAa,EAAE,OAAO;IACtB,cAAc,EAAE,QAAQ;IACxB,iBAAiB,EAAE,YAAY;IAC/B,kBAAkB,EAAE,aAAa;IACjC,aAAa,EAAE,OAAO;IACtB,aAAa,EAAE,OAAO;IAEtB,mBAAmB,EAAE,uBAAuB;IAC5C,kBAAkB,EAAE,8FAA8F;IAClH,iBAAiB,EAAE,qBAAqB;IACxC,eAAe,EAAE,oFAAoF;IACrG,eAAe,EAAE,+EAA+E;IAChG,aAAa,EAAE,gCAAgC;IAC/C,eAAe,EAAE,oBAAoB;CACtC,CAAA"}

package/lib/client/nav-icon.js

@@ -0,0 +1,88 @@
+/**
+ * The usage entry's own icon in the settings navigation.
+ *
+ * dsh's settings shell picks a nav icon from a map of the section ids IT ships
+ * (`account`, `models`, `plugins`, …) and draws a generic gear for anything
+ * else, and rc.2's `settings.section` seat carries no icon of its own — so a
+ * contributed section cannot ask for one and ours read as "some settings".
+ *
+ * Hence the one DOM patch in this package: find our own row by the label we
+ * registered, and put a gauge where the gear was. It is the same technique
+ * dshell's sidebar section uses (and the artwork is copied verbatim from
+ * `@deepseek-ai/dsh-client-ui-primitives`, medium weight, 16 viewBox, 1.3px
+ * stroke) because a surface mounted into a node dsh owns cannot render React
+ * components into it.
+ *
+ * The row is re-created whenever the dialog opens, so a MutationObserver
+ * watches for it; the patch is idempotent (it re-checks the label and a marker
+ * attribute) and only touches the svg node React will not write to again.
+ * Delete this file the day `settings.section` accepts an icon.
+ */
+/**
+ * The gauge artwork, verbatim from the primitives package
+ * (`IconGaugeOutlineMedium`): the same three paths, in the same order.
+ */
+const GAUGE_PATHS = [
+    { d: 'M3.4041 13.096C2.49514 12.187 1.87614 11.0288 1.62537 9.76798C1.37459 8.50716 1.50331 7.20028 1.99525 6.01261C2.48719 4.82494 3.32025 3.80981 4.3891 3.09557C5.45795 2.38134 6.71458 2.00008 8.0001 2C9.28563 2.00008 10.5423 2.38134 11.6111 3.09557C12.68 3.80981 13.513 4.82494 14.005 6.01261C14.4969 7.20028 14.6256 8.50716 14.3748 9.76798C14.1241 11.0288 13.5051 12.187 12.5961 13.096', stroke: true },
+    { d: 'M8 8.49994L11.6114 4.88855', stroke: true },
+    { d: 'M8 9.75C8.69036 9.75 9.25 9.19036 9.25 8.5C9.25 7.80964 8.69036 7.25 8 7.25C7.30964 7.25 6.75 7.80964 6.75 8.5C6.75 9.19036 7.30964 9.75 8 9.75Z', stroke: false },
+];
+const SVG_NS = 'http://www.w3.org/2000/svg';
+/** The marker that says a row already carries our artwork. */
+const MARKER = 'data-dshell-usage-icon';
+/** One gauge, sized and coloured like the icons beside it. */
+function gauge(size, className) {
+    const svg = document.createElementNS(SVG_NS, 'svg');
+    svg.setAttribute('width', String(size));
+    svg.setAttribute('height', String(size));
+    svg.setAttribute('viewBox', '0 0 16 16');
+    svg.setAttribute('fill', 'none');
+    svg.setAttribute('stroke-width', '1.3');
+    svg.setAttribute('aria-hidden', 'true');
+    if (className !== null)
+        svg.setAttribute('class', className);
+    for (const spec of GAUGE_PATHS) {
+        const path = document.createElementNS(SVG_NS, 'path');
+        path.setAttribute('d', spec.d);
+        if (spec.stroke)
+            path.setAttribute('stroke', 'currentColor');
+        else
+            path.setAttribute('fill', 'currentColor');
+        svg.append(path);
+    }
+    return svg;
+}
+/**
+ * Keep the settings navigation's usage row drawn with the gauge.
+ *
+ * @param label - the section label as the shell renders it, in the live locale.
+ * @returns the disposer that stops watching.
+ */
+export function watchUsageNavIcon(label) {
+    if (typeof document === 'undefined')
+        return () => { };
+    const patch = () => {
+        for (const dialog of document.querySelectorAll('[role="dialog"]')) {
+            for (const row of dialog.querySelectorAll('nav button')) {
+                const text = row.textContent?.trim() ?? '';
+                if (text !== label())
+                    continue;
+                const svg = row.querySelector('svg');
+                if (svg === null || svg.getAttribute(MARKER) !== null)
+                    continue;
+                // React owns both children by position and neither is re-rendered while
+                // the dialog lives, so the replacement is what the reader sees; the
+                // pristine node would only come back with a full re-mount, which the
+                // observer catches.
+                const replacement = gauge(Number(svg.getAttribute('width') ?? 16) || 16, svg.getAttribute('class'));
+                replacement.setAttribute(MARKER, '');
+                svg.replaceWith(replacement);
+            }
+        }
+    };
+    patch();
+    const observer = new MutationObserver(() => { patch(); });
+    observer.observe(document.body, { childList: true, subtree: true });
+    return () => { observer.disconnect(); };
+}
+//# sourceMappingURL=nav-icon.js.map

package/lib/client/nav-icon.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nav-icon.js","sourceRoot":"","sources":["../../src/client/nav-icon.ts"],"names":[],"mappings":"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"}