@syncended/dsh-usage 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 syncended
+
+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/README.md

@@ -0,0 +1,103 @@
+# DeepSeek Harness Usage
+
+A local-first DeepSeek Harness plugin for token usage, estimated model cost, trends, and a GitHub-style activity heatmap.
+
+> **Status:** MVP for `@deepseek-ai/dsh` `0.1.1-rc.2`. The plugin is read-only: the durable Harness session log remains the single source of truth and no parallel telemetry database is created.
+
+## What works
+
+- Full **Usage** workspace opened from the main sidebar.
+- 30-day, 90-day, one-year, and all-time ranges.
+- Summary cards for estimated spend, total tokens, model calls, sessions, and active days.
+- Interactive trend chart for tokens, estimated cost, or calls.
+- Input/output/cache token mix.
+- GitHub-style 365-day activity heatmap.
+- Per-provider/model usage, session count, call count, token volume, and estimated cost.
+- Browser timezone-aware day grouping.
+- Revision-aware in-memory scan cache: unchanged durable sessions are not reparsed on every refresh.
+- Responsive light/dark UI built on the supported DSH sidebar and center-workspace slots.
+
+## Install
+
+Requirements: Node.js 22+ and a working `dsh web` profile.
+
+From npm:
+
+```bash
+dsh plugin --profile web add @syncended/dsh-usage
+```
+
+Or from this checkout:
+
+```bash
+pnpm install
+pnpm check
+
+dsh plugin --profile web add .
+```
+
+The package declares a DSH bundle, so `dsh plugin` appends it to the Web profile automatically. Restart the running Web Harness after the initial install, refresh the page, and open **Usage** from the sidebar.
+
+To remove it:
+
+```bash
+dsh plugin --profile web remove @syncended/dsh-usage
+```
+
+## Pricing
+
+Cost is an estimate derived from provider-reported token buckets and USD-per-million-token rules. The plugin ships starter public-list-price rules for common OpenAI GPT-5, Anthropic Claude 4, and DeepSeek routes. Pricing changes over time and negotiated or subscription plans may not map to token billing, so override the rules for your environment.
+
+Rules are matched in order against `provider/model`. `*` is the only wildcard. A route without a matching rule remains visible as **UNPRICED** and is excluded from estimated spend; the dashboard reports pricing coverage.
+
+Override the bundle row in `$DSH_HOME/profiles/web/cordis.patch.yml`:
+
+```yaml
+- id: usage
+  config:
+    scanConcurrency: 4
+    pricing:
+      - route: openai-codex/gpt-5*
+        input: 1.25
+        output: 10
+        cacheRead: 0.125
+        cacheWrite: 1.25
+      - route: my-provider/private-model
+        input: 0.8
+        output: 3.2
+        cacheRead: 0.08
+        cacheWrite: 0.8
+```
+
+All amounts are USD per one million tokens. Reasoning tokens are already included in the provider's output bucket and are not counted again.
+
+## Data semantics
+
+1. The host lists materialized sessions through `ctx.sessionPersistence.listSnapshots()`.
+2. Changed sessions are read from the durable persistence prefix and accepted only when a second revision snapshot still matches, which avoids caching buffered live events under a durable revision. The capability transparently handles JSONL, compressed JSONL, SQLite, or another backend.
+3. Usage chunks and final assistant-message usage are folded with one last-wins sample per `(turn, step)`, matching Harness token-meter semantics.
+4. The exact provider/model route comes from request headers, request context, or the final model message source.
+5. The browser requests an aggregate from the package-owned read-only `GET /api/usage` endpoint. Prompts, tool arguments, and message content are never returned.
+
+The first dashboard load may scan historical sessions. Subsequent loads reuse cached results while each persistence revision is unchanged.
+
+## Privacy and security
+
+- No analytics leave the Harness host.
+- No external telemetry or pricing requests are made.
+- The HTTP API is same-origin and read-only.
+- API output contains dates, route names, token counts, call/session counts, estimated costs, and aggregate read-error count. It does not include prompts, responses, paths, or session IDs.
+
+## Development
+
+```bash
+pnpm install
+pnpm check
+npm pack --dry-run
+```
+
+The host plugin is strict TypeScript compiled to `dist/`. The external Web Client Plugin is a ready lazy-CJS module in `lib/client.js`, so it does not depend on unpublished DSH monorepo frontend tooling.
+
+## License
+
+MIT

package/RELEASING.md

@@ -0,0 +1,40 @@
+# Releasing
+
+Releases use the same tag-driven npm publication flow as the other `@syncended/dsh-*` plugins. The base branch is `trunk`; there are no Changesets or release-it steps.
+
+## One-time setup
+
+1. Add an npm granular access token with package read/write access and 2FA bypass to the GitHub Actions secret `NPM_REGISTRY_TOKEN`.
+2. Keep GitHub Actions allowed to create provenance attestations and GitHub Releases.
+
+## Every release
+
+Start from a clean `trunk` with all checks passing:
+
+```bash
+pnpm install --frozen-lockfile
+pnpm check
+npm pack --dry-run
+```
+
+Then bump, commit, tag, and push:
+
+```bash
+npm version patch   # or minor, major, or an explicit version
+pnpm install --lockfile-only
+git add pnpm-lock.yaml
+git commit --amend --no-edit
+git tag -f "v$(node -p 'require("./package.json").version')"
+git push --follow-tags
+```
+
+If the lockfile did not change, the `git add`/amend/tag refresh steps are unnecessary and the usual two commands are enough:
+
+```bash
+npm version patch
+git push --follow-tags
+```
+
+`.github/workflows/release.yml` verifies that the tag equals `v<package version>`, installs with pnpm 11, runs all checks, verifies package contents, publishes to npm with provenance, and creates an idempotent GitHub Release with generated notes.
+
+Package page: https://www.npmjs.com/package/@syncended/dsh-usage

package/cordis.patch.yml

@@ -0,0 +1,5 @@
+# @syncended/dsh-usage bundle patch.
+# Reads the existing durable session log; no parallel telemetry store is created.
+- insert:
+    - id: usage
+      name: "@syncended/dsh-usage"

package/dist/aggregate.d.ts

@@ -0,0 +1,12 @@
+import type { SessionEvent, SessionHeader } from '@deepseek-ai/dsh-session';
+import type { ModelPrice, SessionUsage, UsageRange, UsageSnapshot } from './types.js';
+/**
+ * Built-in public-list-price estimates (USD / 1M tokens).
+ * Route rules are deliberately overridable through plugin config.
+ */
+export declare const DEFAULT_PRICING: ModelPrice[];
+/** Fold one durable session into billable provider usage samples. */
+export declare function extractSessionUsage(meta: SessionHeader, events: readonly SessionEvent[]): SessionUsage;
+export declare function dateKey(timestamp: number, timeZone: string): string;
+export declare function priceFor(route: string, pricing: readonly ModelPrice[]): ModelPrice | undefined;
+export declare function aggregateUsage(sessions: readonly SessionUsage[], pricing: readonly ModelPrice[], range: UsageRange, timeZone: string, now?: number, errors?: number): UsageSnapshot;

package/dist/aggregate.js

@@ -0,0 +1,293 @@
+/**
+ * Built-in public-list-price estimates (USD / 1M tokens).
+ * Route rules are deliberately overridable through plugin config.
+ */
+export const DEFAULT_PRICING = [
+    { route: 'openai-codex/gpt-5', input: 1.25, output: 10, cacheRead: 0.125, cacheWrite: 1.25 },
+    { route: 'openai/gpt-5', input: 1.25, output: 10, cacheRead: 0.125, cacheWrite: 1.25 },
+    { route: 'anthropic/claude-sonnet-4-20250514', input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+    { route: 'anthropic/claude-opus-4-20250514', input: 15, output: 75, cacheRead: 1.5, cacheWrite: 18.75 },
+    { route: 'deepseek/deepseek-chat', input: 0.28, output: 0.42, cacheRead: 0.028, cacheWrite: 0.28 },
+    { route: 'deepseek/deepseek-reasoner', input: 0.55, output: 2.19, cacheRead: 0.14, cacheWrite: 0.55 },
+];
+const DAY_MS = 86_400_000;
+const dateFormatterCache = new Map();
+function finiteToken(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : 0;
+}
+function buckets(usage) {
+    return {
+        input: finiteToken(usage.inputTokens),
+        output: finiteToken(usage.outputTokens),
+        cacheRead: finiteToken(usage.cacheReadTokens),
+        cacheWrite: finiteToken(usage.cacheWriteTokens),
+    };
+}
+function routeFrom(value) {
+    if (typeof value !== 'object' || value === null)
+        return null;
+    const route = value;
+    if (typeof route.provider !== 'string' || route.provider === '')
+        return null;
+    if (typeof route.model !== 'string' || route.model === '')
+        return null;
+    return { provider: route.provider, model: route.model };
+}
+function assistantRoute(event) {
+    if (event.type !== 'assistant/message')
+        return null;
+    const message = event.data.message;
+    return routeFrom(message.source);
+}
+/** Fold one durable session into billable provider usage samples. */
+export function extractSessionUsage(meta, events) {
+    let currentRoute = null;
+    const samples = new Map();
+    const seedLength = meta.seedLength ?? 0;
+    for (let index = 0; index < events.length; index += 1) {
+        const event = events[index];
+        if (event === undefined)
+            continue;
+        if (event.type === 'request/header') {
+            currentRoute = routeFrom(event.data.header.config);
+            continue;
+        }
+        if (event.type === 'request/context') {
+            currentRoute = routeFrom(event.data);
+            continue;
+        }
+        if (index < seedLength)
+            continue;
+        if (event.type === 'compaction/summary' && event.data.usage !== undefined) {
+            const amount = buckets(event.data.usage);
+            samples.set(`compaction:${event.seq}`, {
+                sessionId: String(meta.id),
+                timestamp: event.time,
+                provider: event.data.provider,
+                model: event.data.model,
+                ...amount,
+            });
+            continue;
+        }
+        let usage;
+        let turn;
+        let step;
+        if (event.type === 'assistant/chunk' && event.data.chunk.type === 'usage') {
+            usage = event.data.chunk.usage;
+            turn = event.data.turn;
+            step = event.data.step;
+        }
+        else if (event.type === 'assistant/message' && event.data.usage !== undefined) {
+            usage = event.data.usage;
+            turn = event.data.turn;
+            step = event.data.step;
+            currentRoute = assistantRoute(event) ?? currentRoute;
+        }
+        if (usage === undefined || turn === undefined || step === undefined)
+            continue;
+        const amount = buckets(usage);
+        const route = assistantRoute(event) ?? currentRoute ?? { provider: 'unknown', model: 'unknown' };
+        samples.set(`${turn}:${step}`, {
+            sessionId: String(meta.id),
+            timestamp: event.time,
+            provider: route.provider,
+            model: route.model,
+            ...amount,
+        });
+    }
+    return {
+        sessionId: String(meta.id),
+        createdAt: meta.createdAt,
+        ...(meta.cwd === undefined ? {} : { cwd: meta.cwd }),
+        records: [...samples.values()].sort((left, right) => left.timestamp - right.timestamp),
+    };
+}
+export function dateKey(timestamp, timeZone) {
+    let formatter = dateFormatterCache.get(timeZone);
+    if (formatter === undefined) {
+        formatter = new Intl.DateTimeFormat('en-CA', {
+            timeZone,
+            year: 'numeric',
+            month: '2-digit',
+            day: '2-digit',
+        });
+        dateFormatterCache.set(timeZone, formatter);
+    }
+    const parts = formatter.formatToParts(new Date(timestamp));
+    const year = parts.find((part) => part.type === 'year')?.value;
+    const month = parts.find((part) => part.type === 'month')?.value;
+    const day = parts.find((part) => part.type === 'day')?.value;
+    if (year === undefined || month === undefined || day === undefined)
+        throw new Error('could not format usage date');
+    return `${year}-${month}-${day}`;
+}
+function shiftDate(date, amount) {
+    const shifted = new Date(`${date}T00:00:00.000Z`);
+    shifted.setUTCDate(shifted.getUTCDate() + amount);
+    return shifted.toISOString().slice(0, 10);
+}
+function datesBetween(start, end) {
+    const days = Math.max(0, Math.round((Date.parse(`${end}T00:00:00Z`) - Date.parse(`${start}T00:00:00Z`)) / DAY_MS));
+    return Array.from({ length: days + 1 }, (_, index) => shiftDate(start, index));
+}
+function wildcardMatches(pattern, value) {
+    const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*');
+    return new RegExp(`^${escaped}$`, 'i').test(value);
+}
+export function priceFor(route, pricing) {
+    return pricing.find((price) => wildcardMatches(price.route, route));
+}
+function tokensOf(value) {
+    return value.input + value.output + value.cacheRead + value.cacheWrite;
+}
+function costOf(value, price) {
+    if (price === undefined)
+        return 0;
+    return (value.input * price.input +
+        value.output * price.output +
+        value.cacheRead * price.cacheRead +
+        value.cacheWrite * price.cacheWrite) / 1_000_000;
+}
+function emptyDay(date) {
+    return {
+        date,
+        input: 0,
+        output: 0,
+        cacheRead: 0,
+        cacheWrite: 0,
+        calls: 0,
+        sessions: 0,
+        cost: 0,
+        pricedTokens: 0,
+        totalTokens: 0,
+    };
+}
+function rangeDays(range) {
+    if (range === '30d')
+        return 30;
+    if (range === '90d')
+        return 90;
+    if (range === '365d')
+        return 365;
+    return null;
+}
+export function aggregateUsage(sessions, pricing, range, timeZone, now = Date.now(), errors = 0) {
+    const endDate = dateKey(now, timeZone);
+    const days = rangeDays(range);
+    let earliest = null;
+    if (days === null) {
+        for (const session of sessions) {
+            for (const record of session.records) {
+                const date = dateKey(record.timestamp, timeZone);
+                if (earliest === null || date < earliest)
+                    earliest = date;
+            }
+        }
+    }
+    const startDate = days === null ? earliest ?? endDate : shiftDate(endDate, -(days - 1));
+    const heatmapStart = shiftDate(endDate, -364);
+    const allStart = startDate < heatmapStart ? startDate : heatmapStart;
+    const daily = new Map(datesBetween(allStart, endDate).map((date) => [date, emptyDay(date)]));
+    const dailySessions = new Map();
+    const rangeSessionIds = new Set();
+    const modelRows = new Map();
+    const priceCache = new Map();
+    for (const session of sessions) {
+        for (const record of session.records) {
+            const date = dateKey(record.timestamp, timeZone);
+            if (date < allStart || date > endDate)
+                continue;
+            const route = `${record.provider}/${record.model}`;
+            let price = priceCache.get(route);
+            if (!priceCache.has(route)) {
+                price = priceFor(route, pricing);
+                priceCache.set(route, price);
+            }
+            const totalTokens = tokensOf(record);
+            const pricedTokens = price === undefined ? 0 : totalTokens;
+            const cost = costOf(record, price);
+            const day = daily.get(date);
+            if (day !== undefined) {
+                day.input += record.input;
+                day.output += record.output;
+                day.cacheRead += record.cacheRead;
+                day.cacheWrite += record.cacheWrite;
+                day.calls += 1;
+                day.cost += cost;
+                day.pricedTokens += pricedTokens;
+                day.totalTokens += totalTokens;
+                const sessionIds = dailySessions.get(date) ?? new Set();
+                sessionIds.add(record.sessionId);
+                dailySessions.set(date, sessionIds);
+            }
+            if (date < startDate)
+                continue;
+            rangeSessionIds.add(record.sessionId);
+            let model = modelRows.get(route);
+            if (model === undefined) {
+                model = {
+                    route,
+                    provider: record.provider,
+                    model: record.model,
+                    input: 0,
+                    output: 0,
+                    cacheRead: 0,
+                    cacheWrite: 0,
+                    calls: 0,
+                    sessions: 0,
+                    cost: 0,
+                    pricedTokens: 0,
+                    totalTokens: 0,
+                    sessionIds: new Set(),
+                };
+                modelRows.set(route, model);
+            }
+            model.input += record.input;
+            model.output += record.output;
+            model.cacheRead += record.cacheRead;
+            model.cacheWrite += record.cacheWrite;
+            model.calls += 1;
+            model.cost += cost;
+            model.pricedTokens += pricedTokens;
+            model.totalTokens += totalTokens;
+            model.sessionIds.add(record.sessionId);
+        }
+    }
+    for (const [date, sessionIds] of dailySessions) {
+        const day = daily.get(date);
+        if (day !== undefined)
+            day.sessions = sessionIds.size;
+    }
+    const trend = [...daily.values()].filter((day) => day.date >= startDate);
+    const heatmap = [...daily.values()].filter((day) => day.date >= heatmapStart);
+    const models = [...modelRows.values()]
+        .map(({ sessionIds, ...model }) => ({ ...model, sessions: sessionIds.size }))
+        .sort((left, right) => right.cost - left.cost || right.totalTokens - left.totalTokens);
+    const summary = trend.reduce((total, day) => ({
+        input: total.input + day.input,
+        output: total.output + day.output,
+        cacheRead: total.cacheRead + day.cacheRead,
+        cacheWrite: total.cacheWrite + day.cacheWrite,
+        totalTokens: total.totalTokens + day.totalTokens,
+        calls: total.calls + day.calls,
+        cost: total.cost + day.cost,
+        pricedTokens: total.pricedTokens + day.pricedTokens,
+        activeDays: total.activeDays + (day.calls > 0 ? 1 : 0),
+    }), { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, calls: 0, cost: 0, pricedTokens: 0, activeDays: 0 });
+    return {
+        generatedAt: new Date(now).toISOString(),
+        range,
+        timeZone,
+        startDate,
+        endDate,
+        summary: {
+            ...summary,
+            sessions: rangeSessionIds.size,
+            pricingCoverage: summary.totalTokens === 0 ? 1 : summary.pricedTokens / summary.totalTokens,
+        },
+        trend,
+        heatmap,
+        models,
+        errors,
+    };
+}

package/dist/http.d.ts

@@ -0,0 +1,10 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { UsageRange, UsageSnapshot } from './types.js';
+interface UsageSnapshotProvider {
+    snapshot(range: UsageRange, timeZone: string): Promise<UsageSnapshot>;
+}
+interface HttpLogger {
+    warn(message: string, ...args: unknown[]): void;
+}
+export declare function createUsageHttpHandler(service: UsageSnapshotProvider, prefix: string, logger: HttpLogger): (request: IncomingMessage, response: ServerResponse) => Promise<void>;
+export {};

package/dist/http.js

@@ -0,0 +1,59 @@
+function sendJson(response, status, value) {
+    const body = `${JSON.stringify(value)}\n`;
+    response.writeHead(status, {
+        'content-type': 'application/json; charset=utf-8',
+        'content-length': Buffer.byteLength(body),
+        'cache-control': 'no-store',
+        'x-content-type-options': 'nosniff',
+    });
+    response.end(body);
+}
+function validRange(value) {
+    if (value === null)
+        return '30d';
+    if (value === '30d' || value === '90d' || value === '365d' || value === 'all')
+        return value;
+    throw Object.assign(new Error('range must be one of 30d, 90d, 365d, or all'), { status: 400 });
+}
+function validTimeZone(value) {
+    const timeZone = value?.trim() || 'UTC';
+    if (timeZone.length > 100)
+        throw Object.assign(new Error('timeZone is too long'), { status: 400 });
+    try {
+        new Intl.DateTimeFormat('en-US', { timeZone }).format();
+    }
+    catch {
+        throw Object.assign(new Error('timeZone is not recognized'), { status: 400 });
+    }
+    return timeZone;
+}
+export function createUsageHttpHandler(service, prefix, logger) {
+    return async (request, response) => {
+        try {
+            const url = new URL(request.url ?? '/', 'http://dsh.local');
+            const relative = url.pathname.slice(prefix.length).replace(/^\/+|\/+$/g, '');
+            if (relative !== '')
+                return sendJson(response, 404, { error: { code: 'NOT_FOUND', message: 'Usage API route not found.' } });
+            if ((request.method ?? 'GET') !== 'GET') {
+                response.setHeader('allow', 'GET');
+                return sendJson(response, 405, { error: { code: 'METHOD_NOT_ALLOWED', message: 'Allowed method: GET' } });
+            }
+            const range = validRange(url.searchParams.get('range'));
+            const timeZone = validTimeZone(url.searchParams.get('timeZone'));
+            return sendJson(response, 200, await service.snapshot(range, timeZone));
+        }
+        catch (error) {
+            const maybeStatus = error.status;
+            const status = typeof maybeStatus === 'number' ? maybeStatus : 500;
+            const message = error instanceof Error ? error.message : String(error);
+            if (status >= 500)
+                logger.warn('usage: HTTP request failed: %s', message);
+            return sendJson(response, status, {
+                error: {
+                    code: status >= 500 ? 'INTERNAL_ERROR' : 'INVALID_REQUEST',
+                    message: status >= 500 ? 'Could not build usage analytics.' : message,
+                },
+            });
+        }
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+import { Context, Service } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { UsagePluginConfig, UsageRange, UsageSnapshot } from './types.js';
+export * from './aggregate.js';
+export * from './types.js';
+export declare const name = "usage";
+export declare const Config: z<UsagePluginConfig>;
+/** Read-only analytics over the canonical durable Harness session log. */
+export declare class UsageService extends Service {
+    static Config: z<UsagePluginConfig>;
+    static inject: string[];
+    private readonly pricing;
+    private readonly scanConcurrency;
+    private readonly cache;
+    private refreshPromise;
+    constructor(ctx: Context, config: UsagePluginConfig);
+    [Service.init](): AsyncGenerator<() => void, void, unknown>;
+    snapshot(range: UsageRange, timeZone: string): Promise<UsageSnapshot>;
+    private refresh;
+    private scan;
+}
+export default UsageService;

package/dist/index.js

@@ -0,0 +1,106 @@
+import { Context, Service } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import { aggregateUsage, DEFAULT_PRICING, extractSessionUsage } from './aggregate.js';
+import { createUsageHttpHandler } from './http.js';
+export * from './aggregate.js';
+export * from './types.js';
+export const name = 'usage';
+const API_PREFIX = '/api/usage';
+const PriceSchema = z.object({
+    route: z.string().required(),
+    input: z.number().min(0).default(0),
+    output: z.number().min(0).default(0),
+    cacheRead: z.number().min(0).default(0),
+    cacheWrite: z.number().min(0).default(0),
+});
+export const Config = z.object({
+    pricing: z.array(PriceSchema).default(DEFAULT_PRICING.map((price) => ({ ...price }))),
+    scanConcurrency: z.number().min(1).max(16).default(4),
+});
+/** Read-only analytics over the canonical durable Harness session log. */
+export class UsageService extends Service {
+    static Config = Config;
+    static inject = ['sessionPersistence', 'webServer'];
+    pricing;
+    scanConcurrency;
+    cache = new Map();
+    refreshPromise;
+    constructor(ctx, config) {
+        super(ctx, 'usage');
+        this.pricing = (config.pricing ?? DEFAULT_PRICING).map((price) => ({ ...price }));
+        this.scanConcurrency = config.scanConcurrency ?? 4;
+    }
+    async *[Service.init]() {
+        const unregister = this.ctx.webServer.register({
+            kind: 'prefix',
+            path: API_PREFIX,
+            handler: createUsageHttpHandler(this, API_PREFIX, this.ctx.logger),
+        });
+        yield () => unregister();
+    }
+    async snapshot(range, timeZone) {
+        const { sessions, errors } = await this.refresh();
+        return aggregateUsage(sessions, this.pricing, range, timeZone, Date.now(), errors);
+    }
+    refresh() {
+        if (this.refreshPromise !== undefined)
+            return this.refreshPromise;
+        const operation = this.scan();
+        this.refreshPromise = operation;
+        void operation.finally(() => {
+            if (this.refreshPromise === operation)
+                this.refreshPromise = undefined;
+        }).catch(() => undefined);
+        return operation;
+    }
+    async scan() {
+        const snapshots = await this.ctx.sessionPersistence.listSnapshots();
+        const liveIds = new Set(snapshots.map((snapshot) => String(snapshot.header.id)));
+        for (const sessionId of this.cache.keys()) {
+            if (!liveIds.has(sessionId))
+                this.cache.delete(sessionId);
+        }
+        let errors = 0;
+        let cursor = 0;
+        const pending = new Map();
+        const workers = Array.from({ length: Math.min(this.scanConcurrency, Math.max(1, snapshots.length)) }, async () => {
+            while (cursor < snapshots.length) {
+                const index = cursor;
+                cursor += 1;
+                const snapshot = snapshots[index];
+                if (snapshot === undefined)
+                    continue;
+                const sessionId = String(snapshot.header.id);
+                const revision = String(snapshot.revision);
+                const cached = this.cache.get(sessionId);
+                if (cached?.revision === revision)
+                    continue;
+                try {
+                    const stored = await this.ctx.sessionPersistence.readFrom(snapshot.header.id, 0);
+                    pending.set(sessionId, {
+                        revision,
+                        usage: extractSessionUsage(stored.meta, stored.events),
+                    });
+                }
+                catch (error) {
+                    errors += 1;
+                    this.ctx.logger.warn('usage: could not read durable session %s', sessionId);
+                    this.ctx.logger.warn(error instanceof Error ? error.stack ?? error.message : String(error));
+                }
+            }
+        });
+        await Promise.all(workers);
+        const confirmed = await this.ctx.sessionPersistence.listSnapshots();
+        const confirmedRevisions = new Map(confirmed.map((snapshot) => [String(snapshot.header.id), String(snapshot.revision)]));
+        for (const [sessionId, entry] of pending) {
+            if (confirmedRevisions.get(sessionId) === entry.revision)
+                this.cache.set(sessionId, entry);
+        }
+        for (const sessionId of this.cache.keys()) {
+            if (!confirmedRevisions.has(sessionId))
+                this.cache.delete(sessionId);
+        }
+        return { sessions: [...this.cache.values()].map((entry) => entry.usage), errors };
+    }
+}
+export default UsageService;

package/dist/types.d.ts

@@ -0,0 +1,74 @@
+export type UsageRange = '30d' | '90d' | '365d' | 'all';
+export interface ModelPrice {
+    /** Provider/model glob. Only `*` is special. */
+    route: string;
+    /** USD per one million uncached input tokens. */
+    input: number;
+    /** USD per one million output tokens. */
+    output: number;
+    /** USD per one million cache-read tokens. */
+    cacheRead: number;
+    /** USD per one million cache-write tokens. */
+    cacheWrite: number;
+}
+export interface UsagePluginConfig {
+    pricing?: ModelPrice[];
+    scanConcurrency?: number;
+}
+export interface UsageBuckets {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+}
+export interface UsageRecord extends UsageBuckets {
+    sessionId: string;
+    timestamp: number;
+    provider: string;
+    model: string;
+}
+export interface SessionUsage {
+    sessionId: string;
+    createdAt: number;
+    cwd?: string;
+    records: UsageRecord[];
+}
+export interface UsageDay extends UsageBuckets {
+    date: string;
+    calls: number;
+    sessions: number;
+    cost: number;
+    pricedTokens: number;
+    totalTokens: number;
+}
+export interface UsageModel extends UsageBuckets {
+    route: string;
+    provider: string;
+    model: string;
+    calls: number;
+    sessions: number;
+    cost: number;
+    pricedTokens: number;
+    totalTokens: number;
+}
+export interface UsageSummary extends UsageBuckets {
+    totalTokens: number;
+    calls: number;
+    sessions: number;
+    activeDays: number;
+    cost: number;
+    pricedTokens: number;
+    pricingCoverage: number;
+}
+export interface UsageSnapshot {
+    generatedAt: string;
+    range: UsageRange;
+    timeZone: string;
+    startDate: string;
+    endDate: string;
+    summary: UsageSummary;
+    trend: UsageDay[];
+    heatmap: UsageDay[];
+    models: UsageModel[];
+    errors: number;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/lib/client.js

@@ -0,0 +1,263 @@
+window.__ModuleLoader__.load({
+  id: "@syncended/dsh-usage",
+  factory: (require) => {
+    const module = { exports: {} };
+    const exports = module.exports;
+    Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+
+    const React = require("react");
+    const h = React.createElement;
+    const { useCallback, useEffect, useId, useMemo, useRef, useState, useSyncExternalStore } = React;
+    const inject = ["slots"];
+    const API_PREFIX = "/api/usage";
+    const RANGES = [
+      { id: "30d", label: "30D" },
+      { id: "90d", label: "90D" },
+      { id: "365d", label: "1Y" },
+      { id: "all", label: "All" },
+    ];
+    const METRICS = [
+      { id: "totalTokens", label: "Tokens" },
+      { id: "cost", label: "Cost" },
+      { id: "calls", label: "Calls" },
+    ];
+
+    const STYLE_CSS = String.raw`
+.dsh-usage-sidebar{box-sizing:border-box;width:100%;height:42px;display:flex;align-items:center;margin:4px 0 0}
+.dsh-usage-sidebar-button{box-sizing:border-box;appearance:none;width:calc(100% + 4px);height:42px;margin:0 -2px;padding:0 10px 0 8px;border:0;border-radius:12px;background:transparent;color:var(--dsw-alias-label-primary,#101318);display:flex;align-items:center;gap:8px;overflow:hidden;font:500 14px/22px inherit;cursor:pointer}
+.dsh-usage-sidebar-button:hover,.dsh-usage-sidebar-button[data-active="true"]{background:var(--dsw-alias-interactive-bg-hover,rgba(38,49,72,.06))}
+.dsh-usage-sidebar-button:focus-visible,.dsh-usage-button:focus-visible,.dsh-usage-segment button:focus-visible{outline:2px solid var(--dsh-usage-accent,#5d73e6);outline-offset:2px}
+.dsh-usage-sidebar-label{min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+.dsh-usage-sidebar-rail{width:36px;height:36px;margin:0}.dsh-usage-sidebar-rail .dsh-usage-sidebar-button{width:36px;height:36px;margin:0;padding:0;justify-content:center;border-radius:50%}
+.dsh-usage-workspace{--dsh-usage-accent:#5d73e6;--dsh-usage-accent-2:#8a6de9;--dsh-usage-green:#27a56b;--dsh-usage-amber:#d68a22;--dsh-usage-text:var(--dsw-alias-label-primary,#15171b);--dsh-usage-muted:var(--dsw-alias-label-tertiary,#747984);--dsh-usage-border:var(--dsw-alias-border-l2,rgba(15,17,21,.12));--dsh-usage-card:var(--dsw-alias-bg-layer-2,#fff);--dsh-usage-soft:var(--dsw-alias-bg-layer-1,#f7f8fa);box-sizing:border-box;width:100%;height:100%;min-width:0;min-height:0;display:flex;flex-direction:column;overflow:hidden;color:var(--dsh-usage-text);background:var(--dsw-alias-bg-base,#fff);font-family:Inter,ui-sans-serif,system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif}
+.dsh-usage-workspace *,.dsh-usage-workspace *::before,.dsh-usage-workspace *::after{box-sizing:border-box}
+.dsh-usage-toolbar{height:54px;flex:none;display:flex;align-items:center;gap:10px;padding:0 18px;border-bottom:1px solid var(--dsh-usage-border);background:color-mix(in srgb,var(--dsw-alias-bg-base,#fff) 90%,transparent);backdrop-filter:blur(14px)}
+.dsh-usage-brand{width:32px;height:32px;display:grid;place-items:center;border-radius:10px;color:#fff;background:linear-gradient(145deg,var(--dsh-usage-accent),var(--dsh-usage-accent-2));box-shadow:0 8px 20px color-mix(in srgb,var(--dsh-usage-accent) 24%,transparent)}
+.dsh-usage-title{min-width:0;flex:1}.dsh-usage-title strong{display:block;font-size:14px;line-height:19px}.dsh-usage-title span{display:block;color:var(--dsh-usage-muted);font-size:11px;line-height:15px}
+.dsh-usage-button{appearance:none;min-height:32px;display:inline-flex;align-items:center;justify-content:center;gap:6px;border:1px solid var(--dsh-usage-border);border-radius:9px;padding:0 10px;color:var(--dsh-usage-text);background:var(--dsh-usage-card);font:500 12px/18px inherit;cursor:pointer}.dsh-usage-button:hover{background:var(--dsh-usage-soft)}.dsh-usage-button:disabled{cursor:progress;opacity:.55}
+.dsh-usage-scroll{min-height:0;flex:1;overflow:auto;overscroll-behavior:contain;padding:28px clamp(18px,4vw,52px) 52px}
+.dsh-usage-dashboard{width:min(1180px,100%);margin:0 auto;display:flex;flex-direction:column;gap:18px}
+.dsh-usage-heading{display:flex;align-items:flex-end;justify-content:space-between;gap:16px;flex-wrap:wrap}.dsh-usage-heading h1{margin:0;font-size:26px;line-height:1.2;letter-spacing:-.035em}.dsh-usage-heading p{margin:5px 0 0;color:var(--dsh-usage-muted);font-size:13px}.dsh-usage-segment{display:inline-flex;gap:2px;padding:3px;border:1px solid var(--dsh-usage-border);border-radius:10px;background:var(--dsh-usage-soft)}.dsh-usage-segment button{appearance:none;height:28px;border:0;border-radius:7px;padding:0 10px;color:var(--dsh-usage-muted);background:transparent;font:600 11px/18px inherit;cursor:pointer}.dsh-usage-segment button[data-active="true"]{color:var(--dsh-usage-text);background:var(--dsh-usage-card);box-shadow:0 1px 3px rgba(15,17,21,.1)}
+.dsh-usage-cards{display:grid;grid-template-columns:repeat(4,minmax(0,1fr));gap:12px}.dsh-usage-card{position:relative;min-width:0;border:1px solid var(--dsh-usage-border);border-radius:16px;padding:16px;background:var(--dsh-usage-card);box-shadow:0 1px 2px color-mix(in srgb,var(--dsh-usage-text) 4%,transparent)}.dsh-usage-card::after{content:"";position:absolute;left:16px;right:16px;bottom:-1px;height:2px;border-radius:2px;background:var(--card-accent,var(--dsh-usage-accent));opacity:.85}.dsh-usage-card-label{display:flex;align-items:center;justify-content:space-between;gap:8px;color:var(--dsh-usage-muted);font-size:11px;font-weight:600;letter-spacing:.04em;text-transform:uppercase}.dsh-usage-card-value{margin-top:10px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;font-size:24px;font-weight:650;line-height:30px;letter-spacing:-.035em;font-variant-numeric:tabular-nums}.dsh-usage-card-detail{margin-top:3px;color:var(--dsh-usage-muted);font-size:11px;line-height:17px}
+.dsh-usage-grid{display:grid;grid-template-columns:minmax(0,1.65fr) minmax(260px,.85fr);gap:12px}.dsh-usage-panel{min-width:0;border:1px solid var(--dsh-usage-border);border-radius:16px;padding:17px;background:var(--dsh-usage-card)}.dsh-usage-panel-head{display:flex;align-items:flex-start;justify-content:space-between;gap:12px;margin-bottom:15px}.dsh-usage-panel-title{margin:0;font-size:14px;line-height:20px}.dsh-usage-panel-sub{margin:2px 0 0;color:var(--dsh-usage-muted);font-size:11px;line-height:16px}
+.dsh-usage-chart{width:100%;height:auto;display:block;overflow:visible}.dsh-usage-chart-grid{stroke:var(--dsh-usage-border);stroke-width:1}.dsh-usage-chart-line{fill:none;stroke:var(--dsh-usage-accent);stroke-width:2.4;stroke-linecap:round;stroke-linejoin:round}.dsh-usage-chart-dot{fill:var(--dsh-usage-card);stroke:var(--dsh-usage-accent);stroke-width:2}.dsh-usage-chart-label{fill:var(--dsh-usage-muted);font:10px Inter,system-ui,sans-serif}.dsh-usage-chart-empty{height:212px;display:grid;place-items:center;color:var(--dsh-usage-muted);font-size:12px}
+.dsh-usage-mix{display:flex;align-items:center;gap:18px;min-height:215px}.dsh-usage-donut{position:relative;width:132px;height:132px;flex:none;border-radius:50%;background:conic-gradient(var(--dsh-usage-accent) 0 var(--mix-input),var(--dsh-usage-accent-2) var(--mix-input) var(--mix-output),var(--dsh-usage-green) var(--mix-output) var(--mix-cache),var(--dsh-usage-border) var(--mix-cache) 100%)}.dsh-usage-donut::after{content:"";position:absolute;inset:19px;border-radius:50%;background:var(--dsh-usage-card)}.dsh-usage-donut-center{position:absolute;z-index:1;inset:0;display:grid;place-content:center;text-align:center}.dsh-usage-donut-center strong{font-size:18px;line-height:22px}.dsh-usage-donut-center span{color:var(--dsh-usage-muted);font-size:10px}.dsh-usage-legend{min-width:0;flex:1;display:flex;flex-direction:column;gap:10px}.dsh-usage-legend-row{display:grid;grid-template-columns:9px minmax(0,1fr) auto;align-items:center;gap:8px;font-size:11px}.dsh-usage-legend-dot{width:8px;height:8px;border-radius:3px}.dsh-usage-legend-value{font-variant-numeric:tabular-nums;font-weight:600}
+.dsh-usage-heat-wrap{overflow-x:auto;padding-bottom:4px}.dsh-usage-heat-layout{min-width:760px;display:flex;gap:9px}.dsh-usage-day-labels{width:24px;flex:none;display:grid;grid-template-rows:repeat(7,11px);gap:3px;padding-top:0;color:var(--dsh-usage-muted);font-size:8px;line-height:11px}.dsh-usage-heatmap{display:grid;grid-template-rows:repeat(7,11px);grid-auto-flow:column;grid-auto-columns:11px;gap:3px}.dsh-usage-heat-cell{width:11px;height:11px;border-radius:2.5px;background:var(--dsh-usage-heat-0)}.dsh-usage-heat-cell[data-level="1"]{background:color-mix(in srgb,var(--dsh-usage-accent) 28%,var(--dsh-usage-card))}.dsh-usage-heat-cell[data-level="2"]{background:color-mix(in srgb,var(--dsh-usage-accent) 50%,var(--dsh-usage-card))}.dsh-usage-heat-cell[data-level="3"]{background:color-mix(in srgb,var(--dsh-usage-accent) 72%,var(--dsh-usage-card))}.dsh-usage-heat-cell[data-level="4"]{background:var(--dsh-usage-accent)}.dsh-usage-workspace{--dsh-usage-heat-0:color-mix(in srgb,var(--dsh-usage-muted) 10%,transparent)}.dsh-usage-heat-footer{display:flex;justify-content:space-between;gap:12px;margin-top:11px;color:var(--dsh-usage-muted);font-size:10px}.dsh-usage-heat-key{display:flex;align-items:center;gap:4px}.dsh-usage-heat-key i{display:block;width:10px;height:10px;border-radius:2px}
+.dsh-usage-model-list{display:flex;flex-direction:column}.dsh-usage-model-head,.dsh-usage-model-row{display:grid;grid-template-columns:minmax(170px,1.4fr) minmax(170px,1fr) 100px 82px;gap:14px;align-items:center}.dsh-usage-model-head{padding:0 9px 9px;color:var(--dsh-usage-muted);font-size:10px;font-weight:600;text-transform:uppercase;letter-spacing:.04em}.dsh-usage-model-row{min-height:58px;padding:9px;border-top:1px solid var(--dsh-usage-border);font-size:11px}.dsh-usage-model-name{min-width:0}.dsh-usage-model-name strong{display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;font-size:12px}.dsh-usage-model-name span{display:block;margin-top:2px;color:var(--dsh-usage-muted);overflow:hidden;text-overflow:ellipsis;white-space:nowrap}.dsh-usage-model-meter{height:5px;margin-top:6px;border-radius:3px;background:var(--dsh-usage-soft);overflow:hidden}.dsh-usage-model-meter i{display:block;height:100%;border-radius:inherit;background:linear-gradient(90deg,var(--dsh-usage-accent),var(--dsh-usage-accent-2))}.dsh-usage-num{text-align:right;font-variant-numeric:tabular-nums}.dsh-usage-unpriced{color:var(--dsh-usage-amber);font-size:9px}
+.dsh-usage-notice{border:1px solid color-mix(in srgb,var(--dsh-usage-amber) 30%,var(--dsh-usage-border));border-radius:12px;padding:10px 12px;color:var(--dsh-usage-muted);background:color-mix(in srgb,var(--dsh-usage-amber) 7%,transparent);font-size:11px;line-height:17px}.dsh-usage-loading,.dsh-usage-error{min-height:360px;display:grid;place-content:center;justify-items:center;gap:12px;color:var(--dsh-usage-muted);text-align:center}.dsh-usage-spinner{width:24px;height:24px;border:2px solid var(--dsh-usage-border);border-top-color:var(--dsh-usage-accent);border-radius:50%;animation:dsh-usage-spin .8s linear infinite}@keyframes dsh-usage-spin{to{transform:rotate(360deg)}}
+@media(max-width:900px){.dsh-usage-cards{grid-template-columns:repeat(2,minmax(0,1fr))}.dsh-usage-grid{grid-template-columns:1fr}.dsh-usage-mix{min-height:170px}.dsh-usage-model-head,.dsh-usage-model-row{grid-template-columns:minmax(160px,1.3fr) minmax(150px,1fr) 90px}.dsh-usage-model-head>:last-child,.dsh-usage-model-row>:last-child{display:none}}
+@media(max-width:560px){.dsh-usage-toolbar{padding:0 10px}.dsh-usage-title span{display:none}.dsh-usage-button-label{display:none}.dsh-usage-scroll{padding:20px 12px 36px}.dsh-usage-heading{align-items:flex-start;flex-direction:column}.dsh-usage-heading h1{font-size:22px}.dsh-usage-cards{grid-template-columns:1fr 1fr;gap:8px}.dsh-usage-card{padding:13px}.dsh-usage-card-value{font-size:20px}.dsh-usage-panel{padding:14px}.dsh-usage-mix{align-items:flex-start;flex-direction:column}.dsh-usage-donut{align-self:center}.dsh-usage-model-head{display:none}.dsh-usage-model-row{grid-template-columns:minmax(0,1fr) auto;gap:10px}.dsh-usage-model-row>:nth-child(2){display:none}}
+`;
+
+    function UsageGlyph({ size = 18 }) {
+      return h("svg", { width: size, height: size, viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "1.8", strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": "true" },
+        h("path", { d: "M4 19V9m5 10V5m5 14v-7m5 7V3" }),
+        h("path", { d: "M2.5 19.5h18" }),
+      );
+    }
+
+    function RefreshGlyph() {
+      return h("svg", { width: 14, height: 14, viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": "true" }, h("path", { d: "M20 6v5h-5M4 18v-5h5" }), h("path", { d: "M18.5 9A7 7 0 0 0 6 6.5L4 9m2 6a7 7 0 0 0 12 2.5L20 15" }));
+    }
+
+    function createDisclosureStore() {
+      let open = false;
+      const listeners = new Set();
+      const notify = () => listeners.forEach((listener) => listener());
+      return {
+        getSnapshot: () => open,
+        subscribe(listener) { listeners.add(listener); return () => listeners.delete(listener); },
+        toggle() { open = !open; notify(); },
+        close() { if (open) { open = false; notify(); } },
+        dispose() { open = false; listeners.clear(); },
+      };
+    }
+
+    function formatCompact(value) {
+      if (!Number.isFinite(value)) return "—";
+      return new Intl.NumberFormat(undefined, { notation: "compact", maximumFractionDigits: value >= 1000000 ? 1 : 0 }).format(value);
+    }
+    function formatCost(value) {
+      if (!Number.isFinite(value)) return "—";
+      if (value === 0) return "$0.00";
+      if (value < .01) return "<$0.01";
+      return new Intl.NumberFormat(undefined, { style: "currency", currency: "USD", maximumFractionDigits: value < 100 ? 2 : 0 }).format(value);
+    }
+    function formatMetric(value, metric) {
+      if (metric === "cost") return formatCost(value);
+      return formatCompact(value);
+    }
+    function formatDate(date) {
+      try { return new Date(date + "T00:00:00Z").toLocaleDateString(undefined, { month: "short", day: "numeric", timeZone: "UTC" }); }
+      catch { return date; }
+    }
+    function rangeDescription(snapshot) {
+      if (!snapshot) return "Durable session analytics";
+      return formatDate(snapshot.startDate) + " – " + formatDate(snapshot.endDate) + " · " + snapshot.timeZone;
+    }
+
+    function Segment({ values, selected, onChange, label }) {
+      return h("div", { className: "dsh-usage-segment", role: "group", "aria-label": label }, values.map((value) => h("button", { key: value.id, type: "button", "data-active": value.id === selected ? "true" : undefined, "aria-pressed": value.id === selected, onClick: () => onChange(value.id) }, value.label)));
+    }
+
+    function StatCard({ label, value, detail, accent }) {
+      return h("article", { className: "dsh-usage-card", style: { "--card-accent": accent } },
+        h("div", { className: "dsh-usage-card-label" }, label),
+        h("div", { className: "dsh-usage-card-value", title: value }, value),
+        h("div", { className: "dsh-usage-card-detail" }, detail),
+      );
+    }
+
+    function TrendChart({ days, metric }) {
+      const width = 760, height = 220, left = 48, right = 10, top = 12, bottom = 28;
+      const values = days.map((day) => Number(day[metric]) || 0);
+      const max = Math.max(1, ...values);
+      if (!days.length) return h("div", { className: "dsh-usage-chart-empty" }, "No usage in this range");
+      const x = (index) => left + (days.length === 1 ? (width - left - right) / 2 : index * (width - left - right) / (days.length - 1));
+      const y = (value) => top + (height - top - bottom) * (1 - value / max);
+      const points = values.map((value, index) => [x(index), y(value)]);
+      const line = points.map((point, index) => (index === 0 ? "M" : "L") + point[0].toFixed(2) + " " + point[1].toFixed(2)).join(" ");
+      const area = line + " L " + x(days.length - 1) + " " + (height - bottom) + " L " + x(0) + " " + (height - bottom) + " Z";
+      const labels = [0, Math.floor((days.length - 1) / 2), days.length - 1].filter((value, index, all) => all.indexOf(value) === index);
+      return h("svg", { className: "dsh-usage-chart", viewBox: `0 0 ${width} ${height}`, role: "img", "aria-label": "Usage trend" },
+        h("defs", null, h("linearGradient", { id: "dsh-usage-area", x1: "0", y1: "0", x2: "0", y2: "1" }, h("stop", { offset: "0%", stopColor: "var(--dsh-usage-accent)", stopOpacity: ".28" }), h("stop", { offset: "100%", stopColor: "var(--dsh-usage-accent)", stopOpacity: "0" }))),
+        [0, .5, 1].map((ratio) => h("g", { key: ratio }, h("line", { className: "dsh-usage-chart-grid", x1: left, x2: width - right, y1: y(max * ratio), y2: y(max * ratio) }), h("text", { className: "dsh-usage-chart-label", x: left - 8, y: y(max * ratio) + 3, textAnchor: "end" }, formatMetric(max * ratio, metric)))),
+        h("path", { d: area, fill: "url(#dsh-usage-area)" }),
+        h("path", { d: line, className: "dsh-usage-chart-line" }),
+        points.length <= 45 ? points.map((point, index) => h("circle", { key: index, className: "dsh-usage-chart-dot", cx: point[0], cy: point[1], r: 2.7 }, h("title", null, days[index].date + ": " + formatMetric(values[index], metric)))) : null,
+        labels.map((index) => h("text", { key: index, className: "dsh-usage-chart-label", x: x(index), y: height - 6, textAnchor: index === 0 ? "start" : index === days.length - 1 ? "end" : "middle" }, formatDate(days[index].date))),
+      );
+    }
+
+    function TokenMix({ summary }) {
+      const input = summary.input || 0, output = summary.output || 0, cache = (summary.cacheRead || 0) + (summary.cacheWrite || 0);
+      const total = Math.max(1, input + output + cache);
+      const inputEnd = input / total * 100;
+      const outputEnd = (input + output) / total * 100;
+      const cacheEnd = (input + output + cache) / total * 100;
+      const rows = [
+        { label: "Input", value: input, color: "var(--dsh-usage-accent)" },
+        { label: "Output", value: output, color: "var(--dsh-usage-accent-2)" },
+        { label: "Cache", value: cache, color: "var(--dsh-usage-green)" },
+      ];
+      return h("div", { className: "dsh-usage-mix" },
+        h("div", { className: "dsh-usage-donut", style: { "--mix-input": inputEnd + "%", "--mix-output": outputEnd + "%", "--mix-cache": cacheEnd + "%" } }, h("div", { className: "dsh-usage-donut-center" }, h("strong", null, formatCompact(summary.totalTokens)), h("span", null, "tokens"))),
+        h("div", { className: "dsh-usage-legend" }, rows.map((row) => h("div", { key: row.label, className: "dsh-usage-legend-row" }, h("i", { className: "dsh-usage-legend-dot", style: { background: row.color } }), h("span", null, row.label), h("span", { className: "dsh-usage-legend-value" }, formatCompact(row.value))))),
+      );
+    }
+
+    function Heatmap({ days }) {
+      const max = Math.max(1, ...days.map((day) => day.totalTokens || 0));
+      const firstOffset = days.length ? new Date(days[0].date + "T00:00:00Z").getUTCDay() : 0;
+      const cells = Array.from({ length: firstOffset }, (_, index) => h("i", { key: "blank-" + index }));
+      for (const day of days) {
+        const ratio = Math.log1p(day.totalTokens || 0) / Math.log1p(max);
+        const level = day.totalTokens === 0 ? 0 : Math.max(1, Math.ceil(ratio * 4));
+        cells.push(h("i", { key: day.date, className: "dsh-usage-heat-cell", "data-level": level }, h("title", null, `${day.date}: ${formatCompact(day.totalTokens)} tokens · ${day.calls} calls · ${formatCost(day.cost)}`)));
+      }
+      return h(React.Fragment, null,
+        h("div", { className: "dsh-usage-heat-wrap" }, h("div", { className: "dsh-usage-heat-layout" }, h("div", { className: "dsh-usage-day-labels", "aria-hidden": "true" }, h("span"), h("span", null, "M"), h("span"), h("span", null, "W"), h("span"), h("span", null, "F"), h("span")), h("div", { className: "dsh-usage-heatmap", role: "img", "aria-label": "Usage activity over the last year" }, cells))),
+        h("div", { className: "dsh-usage-heat-footer" }, h("span", null, days.filter((day) => day.calls > 0).length + " active days in the last year"), h("span", { className: "dsh-usage-heat-key" }, "Less", [0,1,2,3,4].map((level) => h("i", { key: level, className: "dsh-usage-heat-cell", "data-level": level })), "More")),
+      );
+    }
+
+    function ModelTable({ models }) {
+      const max = Math.max(1, ...models.map((model) => model.totalTokens));
+      return h("div", { className: "dsh-usage-model-list" },
+        h("div", { className: "dsh-usage-model-head" }, h("span", null, "Model"), h("span", null, "Volume"), h("span", { className: "dsh-usage-num" }, "Calls"), h("span", { className: "dsh-usage-num" }, "Cost")),
+        models.length ? models.map((model) => h("div", { key: model.route, className: "dsh-usage-model-row" },
+          h("div", { className: "dsh-usage-model-name" }, h("strong", { title: model.model }, model.model), h("span", { title: model.provider }, model.provider + " · " + model.sessions + " sessions")),
+          h("div", null, h("div", null, formatCompact(model.totalTokens) + " tokens"), h("div", { className: "dsh-usage-model-meter" }, h("i", { style: { width: (model.totalTokens / max * 100).toFixed(1) + "%" } }))),
+          h("div", { className: "dsh-usage-num" }, formatCompact(model.calls)),
+          h("div", { className: "dsh-usage-num" }, model.pricedTokens ? formatCost(model.cost) : h("span", { className: "dsh-usage-unpriced", title: "Add a pricing rule for this route" }, "UNPRICED")),
+        )) : h("div", { className: "dsh-usage-chart-empty" }, "No model usage in this range"),
+      );
+    }
+
+    function Dashboard({ snapshot, range, setRange, metric, setMetric }) {
+      const summary = snapshot.summary;
+      const coverage = Math.round(summary.pricingCoverage * 100);
+      return h("div", { className: "dsh-usage-dashboard" },
+        h("div", { className: "dsh-usage-heading" }, h("div", null, h("h1", null, "Usage overview"), h("p", null, rangeDescription(snapshot))), h(Segment, { values: RANGES, selected: range, onChange: setRange, label: "Analytics range" })),
+        h("section", { className: "dsh-usage-cards", "aria-label": "Usage summary" },
+          h(StatCard, { label: "Estimated spend", value: formatCost(summary.cost), detail: coverage + "% of tokens priced", accent: "var(--dsh-usage-green)" }),
+          h(StatCard, { label: "Total tokens", value: formatCompact(summary.totalTokens), detail: formatCompact(summary.output) + " output · " + formatCompact(summary.cacheRead) + " cache read", accent: "var(--dsh-usage-accent)" }),
+          h(StatCard, { label: "Model calls", value: formatCompact(summary.calls), detail: summary.sessions + " sessions", accent: "var(--dsh-usage-accent-2)" }),
+          h(StatCard, { label: "Active days", value: String(summary.activeDays), detail: snapshot.trend.length + " calendar days", accent: "var(--dsh-usage-amber)" }),
+        ),
+        h("section", { className: "dsh-usage-grid" },
+          h("article", { className: "dsh-usage-panel" }, h("header", { className: "dsh-usage-panel-head" }, h("div", null, h("h2", { className: "dsh-usage-panel-title" }, "Usage trend"), h("p", { className: "dsh-usage-panel-sub" }, "Provider-reported durable usage")), h(Segment, { values: METRICS, selected: metric, onChange: setMetric, label: "Chart metric" })), h(TrendChart, { days: snapshot.trend, metric })),
+          h("article", { className: "dsh-usage-panel" }, h("header", { className: "dsh-usage-panel-head" }, h("div", null, h("h2", { className: "dsh-usage-panel-title" }, "Token mix"), h("p", { className: "dsh-usage-panel-sub" }, "Input, output, and cache"))), h(TokenMix, { summary })),
+        ),
+        h("article", { className: "dsh-usage-panel" }, h("header", { className: "dsh-usage-panel-head" }, h("div", null, h("h2", { className: "dsh-usage-panel-title" }, "Activity"), h("p", { className: "dsh-usage-panel-sub" }, "A year of Harness model activity"))), h(Heatmap, { days: snapshot.heatmap })),
+        h("article", { className: "dsh-usage-panel" }, h("header", { className: "dsh-usage-panel-head" }, h("div", null, h("h2", { className: "dsh-usage-panel-title" }, "Models"), h("p", { className: "dsh-usage-panel-sub" }, "Usage and estimated cost by provider route"))), h(ModelTable, { models: snapshot.models })),
+        coverage < 100 ? h("div", { className: "dsh-usage-notice" }, "Cost is an estimate. " + (100 - coverage) + "% of tokens use routes without a matching pricing rule. Override pricing in the usage row of cordis.patch.yml for exact internal or negotiated rates.") : null,
+        snapshot.errors ? h("div", { className: "dsh-usage-notice" }, snapshot.errors + " session logs could not be read. Their last cached values are shown when available.") : null,
+      );
+    }
+
+    function UsageWorkspace({ disclosure }) {
+      const titleId = useId();
+      const rootRef = useRef(null);
+      const [range, setRange] = useState("30d");
+      const [metric, setMetric] = useState("totalTokens");
+      const [snapshot, setSnapshot] = useState(null);
+      const [error, setError] = useState(null);
+      const [refreshKey, setRefreshKey] = useState(0);
+      const [loading, setLoading] = useState(true);
+      const timeZone = useMemo(() => { try { return Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC"; } catch { return "UTC"; } }, []);
+      const refresh = useCallback(() => setRefreshKey((value) => value + 1), []);
+
+      useEffect(() => {
+        const controller = new AbortController();
+        setLoading(true); setError(null); setSnapshot(null);
+        fetch(API_PREFIX + "?range=" + encodeURIComponent(range) + "&timeZone=" + encodeURIComponent(timeZone), { signal: controller.signal })
+          .then(async (response) => {
+            const body = await response.json().catch(() => null);
+            if (!response.ok) throw new Error(body?.error?.message || "Usage request failed (" + response.status + ")");
+            return body;
+          })
+          .then((body) => { setSnapshot(body); setLoading(false); })
+          .catch((cause) => { if (cause.name !== "AbortError") { setError(cause instanceof Error ? cause.message : String(cause)); setLoading(false); } });
+        return () => controller.abort();
+      }, [range, timeZone, refreshKey]);
+
+      useEffect(() => {
+        const frame = requestAnimationFrame(() => rootRef.current?.querySelector('[data-dsh-usage-exit="true"]')?.focus());
+        const keydown = (event) => { if (event.key === "Escape" && !event.defaultPrevented) { event.preventDefault(); disclosure.close(); } };
+        window.addEventListener("keydown", keydown);
+        return () => { cancelAnimationFrame(frame); window.removeEventListener("keydown", keydown); };
+      }, [disclosure]);
+
+      return h("section", { ref: rootRef, className: "dsh-usage-workspace", "aria-labelledby": titleId },
+        h("header", { className: "dsh-usage-toolbar" }, h("span", { className: "dsh-usage-brand" }, h(UsageGlyph, { size: 17 })), h("div", { className: "dsh-usage-title" }, h("strong", { id: titleId }, "Usage"), h("span", null, snapshot ? "Updated " + new Date(snapshot.generatedAt).toLocaleTimeString(undefined, { hour: "2-digit", minute: "2-digit" }) : "Reading durable sessions")), h("button", { type: "button", className: "dsh-usage-button", disabled: loading, onClick: refresh }, h(RefreshGlyph), h("span", { className: "dsh-usage-button-label" }, "Refresh")), h("button", { type: "button", className: "dsh-usage-button", "data-dsh-usage-exit": "true", onClick: disclosure.close }, "Close")),
+        h("div", { className: "dsh-usage-scroll" }, loading && !snapshot ? h("div", { className: "dsh-usage-loading" }, h("i", { className: "dsh-usage-spinner" }), h("span", null, "Scanning session usage…")) : error && !snapshot ? h("div", { className: "dsh-usage-error" }, h("strong", null, "Usage unavailable"), h("span", null, error), h("button", { type: "button", className: "dsh-usage-button", onClick: refresh }, "Try again")) : h(Dashboard, { snapshot, range, setRange, metric, setMetric })),
+      );
+    }
+
+    function SidebarAction({ wide, disclosure }) {
+      const open = useSyncExternalStore(disclosure.subscribe, disclosure.getSnapshot, disclosure.getSnapshot);
+      return h("div", { className: "dsh-usage-sidebar" + (wide ? "" : " dsh-usage-sidebar-rail") }, h("button", { type: "button", className: "dsh-usage-sidebar-button", title: wide ? undefined : "Usage", "aria-label": open ? "Close Usage" : "Open Usage", "aria-pressed": open, "data-active": open ? "true" : undefined, onClick: disclosure.toggle }, h(UsageGlyph, { size: wide ? 16 : 18 }), wide ? h("span", { className: "dsh-usage-sidebar-label" }, "Usage") : null));
+    }
+
+    function apply(ctx) {
+      const disclosure = createDisclosureStore();
+      let centerDeclared = false;
+      let disposeCenter = null;
+      const unmount = () => { if (disposeCenter) { const dispose = disposeCenter; disposeCenter = null; dispose(); } };
+      const mount = () => {
+        if (!centerDeclared || !disclosure.getSnapshot() || disposeCenter) return;
+        try { disposeCenter = ctx.slots.register({ name: "conversation", priority: -190, inject: () => ({ disclosure }) }, UsageWorkspace); }
+        catch (error) { console.error("dsh usage: could not mount center workspace", error); disclosure.close(); }
+      };
+      ctx.effect(() => { const tag = document.createElement("style"); tag.setAttribute("data-plugin", "@syncended/dsh-usage"); tag.textContent = STYLE_CSS; document.head.appendChild(tag); return () => tag.remove(); }, "@syncended/dsh-usage: client styles");
+      ctx.effect(() => ctx.slots.inject("conversation", () => { centerDeclared = true; mount(); return () => { centerDeclared = false; unmount(); }; }), "@syncended/dsh-usage: center workspace");
+      ctx.effect(() => { const unsubscribe = disclosure.subscribe(() => disclosure.getSnapshot() ? mount() : unmount()); return () => { unsubscribe(); unmount(); disclosure.dispose(); }; }, "@syncended/dsh-usage: workspace state");
+      ctx.slots.inject("sidebar.footer.action", () => ctx.slots.register({ name: "sidebar.footer.action", id: "usage", order: 45, label: "Usage", inject: () => ({ disclosure }) }, SidebarAction));
+    }
+
+    exports.inject = inject;
+    exports.apply = apply;
+    return module.exports;
+  },
+});

package/package.json

@@ -0,0 +1,108 @@
+{
+  "name": "@syncended/dsh-usage",
+  "version": "0.1.0",
+  "description": "Token usage, model cost analytics, trends, and activity heatmaps for DeepSeek Harness",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./client": "./lib/client.js",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "lib/client.js",
+    "cordis.patch.yml",
+    "README.md",
+    "RELEASING.md",
+    "LICENSE"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-ui-layout",
+        "@deepseek-ai/dsh-client-ui-conversation",
+        "@deepseek-ai/dsh-client-ui-sidebar",
+        "@deepseek-ai/dsh-client-ui-primitives"
+      ],
+      "platform": "web"
+    }
+  },
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "pnpm clean && tsc -p tsconfig.json && node --check lib/client.js",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "pnpm build && node --test test/*.test.mjs",
+    "check": "pnpm typecheck && pnpm test",
+    "prepare": "pnpm build"
+  },
+  "keywords": [
+    "deepseek",
+    "deepseek-harness",
+    "dsh",
+    "usage",
+    "tokens",
+    "cost",
+    "analytics",
+    "heatmap"
+  ],
+  "author": "syncended",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/syncended/deepseek-harness-usage.git"
+  },
+  "bugs": {
+    "url": "https://github.com/syncended/deepseek-harness-usage/issues"
+  },
+  "homepage": "https://github.com/syncended/deepseek-harness-usage#readme",
+  "engines": {
+    "node": ">=22"
+  },
+  "packageManager": "pnpm@11.22.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-compaction": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-runtime": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-conversation": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-layout": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-sidebar": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-session": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-session-persistence": "^0.1.1-rc.2",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "4.0.1",
+    "@deepseek-ai/dsh-compaction": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-runtime": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-conversation": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-layout": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-primitives": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-sidebar": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-host-webserver": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-session": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-session-persistence": "0.1.1-rc.2",
+    "@types/node": "^22.0.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "typescript": "^5.9.3"
+  }
+}