dsh-usage-atlas

DSH Usage Atlas

English | 中文

Repository · Architecture · MIT License

Usage Atlas turns the durable session projections already available to DSH into a visual answer to three questions: how much did the workspace use, which model carried it, and when did it happen. It is shipped as one removable bundle with a host projection and a browser settings section, so the upstream repository keeps its original usage surface after extraction.

_{Real browser capture from the included local demo fixture; production data stays local to the DSH session list.}

Install

The package is designed for the Web profile and is installable because package.json declares a dsh.bundle patch.

dsh plugin --profile web add dsh-usage-atlas
dsh plugin --profile web add github:merenguesL/dsh-usage-atlas
dsh plugin --profile web add ./plugins/dsh-usage-atlas

Restart dsh web after installing so the bundle composition is rebuilt. Pin a published version or commit when using the plugin in a repeatable deployment.

What it adds

Surface	What you get
Hero band	Total tokens, exact value, week-over-week movement, and a fourteen-day sparkline.
KPI atlas	Today, seven-day total, cache-hit gauge, four billing buckets, calls, sessions, active days, and subagent share.
Model / day	UTC-day columns stacked by provider-reported model, ranked legend, focus/hover composition, and coverage note.
Trend studio	Daily, weekly, or monthly token bars, output mode, cache-rate mode, moving average, range filters, and peak marker.
Activity map	Daily detail, heuristic context composition, local-hour heatmap, and known-call hints.
Drill-down	Workspace and session tabs with filtering, sorting, badges, context occupancy, copy report, and RFC 4180 CSV export.

The section is read-only. It refreshes on mount, on demand, after a connection reset, and optionally every 30 seconds.

How it works

request/header + assistant usage events
                    │
                    ▼
       dsh-usage-atlas / modelUsage projection
                    │  totals by model + 90 UTC days
                    ▼
          session.list durable projection rows
                    │
                    ▼
             Usage Atlas browser report

The host half registers modelUsage through the existing sessionProjections seam. The client half aggregates visible session.list rows and contributes a settings.section slot. The original tokenUsage projection remains owned by dsh-token-meter; Usage Atlas adds a separate projection so existing consumers do not need a wire-contract migration.

Model days are UTC calendar days for replay stability. The existing local-day trend and heatmap remain separate because they describe session activity rather than provider event time.

Model Experience

None. The plugin renders a browser configuration UI and does not add prompt fields, tools, model instructions, RPC methods, or provider request fields.

KV Cache effect

None. It reads provider-reported usage from durable session projections and sends no model request of its own.

Privacy and security

Usage Atlas reads the DSH session-list response already available to the Web profile, performs aggregation in the browser, and writes only a user-triggered CSV download. It has no analytics endpoint, no third-party telemetry, no credential access, and no background network destination beyond the host connection.

Known Limitations and Deferred Work

• Measured rows only — a session without a usable tokenUsage projection contributes zero and is shown in coverage messaging instead of triggering a full-history read.
• Model coverage is optional — the model chart appears only when the host composition includes the modelUsage projection; totals still work without the model dimension.
• Visible list scope — deleted sessions and sessions omitted by session.list cannot appear in a later report.
• Activity time is indicative — the current list contract provides cumulative totals and an updatedAt marker, not per-request timestamps.
• Known calls are a lower bound — a nonzero session counts as one known call because exact request counts are not part of the existing projection.
• Context data is heuristic — occupancy and context composition are projection values, not a live provider billing statement.
• No pricing layer yet — the dashboard reports tokens and cache health, not currency or provider invoice totals.

Development

The plugin is intentionally outside the upstream workspace so it can become its own repository without adding a workspace dependency or a web-app roster entry.

cd plugins/dsh-usage-atlas
pnpm install
pnpm run typecheck
pnpm test
pnpm run build
pnpm run demo

lib/ is committed on purpose: GitHub installs can consume the prebuilt host and browser entries without executing a repository build. The demo serves a deterministic fixture used to refresh the README screenshot; it does not ship as part of the published package.

Maintainer release steps live in docs/releasing.md.

Repository layout

dsh-usage-atlas/
├── .github/workflows/ci.yml      # Node 22/24 install, test, build, and pack gate
├── .github/workflows/publish.yml # semver tag -> npm -> GitHub Release
├── assets/                 # hero artwork and browser-captured dashboard
├── docs/                   # architecture and maintainer release reference
├── lib/                    # committed installable host/client artifacts
├── scripts/                # independent build and screenshot demo entry
├── src/                    # host projection and browser settings section
├── tests/                  # projection, report, UI, and lifecycle coverage
├── pnpm-workspace.yaml     # explicit esbuild build-script approval
├── cordis.patch.yml        # one-row dsh.bundle composition patch
└── package.json            # dsh.bundle and dsh.client declarations

Compatibility

The current package targets the DSH 0.1.2-alpha.1 plugin interfaces and Node.js ^22.19.0 || >=24.0.0. The package follows the host's pre-release compatibility policy; publish a new plugin version when the DSH projection or browser slot interfaces change.

License

MIT. The extracted DSH code retains its © 2026 DeepSeek attribution; plugin-specific additions are © 2026 merenguesL.