dsh-budget 0.3.0 → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +19 -0
- package/README.es.md +177 -172
- package/README.hi.md +177 -172
- package/README.md +180 -173
- package/README.pt.md +177 -172
- package/README.zh.md +179 -172
- package/lib/client.js +19 -3
- package/lib/client.js.map +1 -1
- package/lib/index.js +56 -3
- package/lib/{rolldown-runtime-D7D4PA-g.js → rolldown-runtime-8H4AJuhK.js} +1 -0
- package/lib/typert.host.js +1 -1
- package/lib/types/client/index.d.ts +2 -2
- package/lib/types/client/index.d.ts.map +1 -1
- package/lib/types/client/remote.d.ts +11 -1
- package/lib/types/client/remote.d.ts.map +1 -1
- package/lib/types/events.d.ts +16 -2
- package/lib/types/events.d.ts.map +1 -1
- package/lib/types/index.d.ts +3 -2
- package/lib/types/index.d.ts.map +1 -1
- package/lib/types/typert.host.d.ts +11 -1
- package/lib/types/typert.host.d.ts.map +1 -1
- package/lib/types/wire.d.ts +28 -3
- package/lib/types/wire.d.ts.map +1 -1
- package/lib/{wire-zYaXk7IG.js → wire-DE0ooHk0.js} +18 -3
- package/package.json +21 -5
package/README.md
CHANGED
|
@@ -1,178 +1,185 @@
|
|
|
1
|
-
<div align="center">
|
|
2
|
-
|
|
3
|
-
# 💰 dsh-budget
|
|
4
|
-
[
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
[ install ranking).
|
|
5
|
+
[](https://gitee.com/perrylink/dsh-budget)
|
|
6
|
+
|
|
7
|
+
**Cost governance for DeepSeek Harness: budgets, carbon, and latency in one panel.**
|
|
8
|
+
|
|
9
|
+
*Know what every session costs — before it costs you.*
|
|
10
|
+
|
|
11
|
+
> **Official repository.** This is the only official repository of dsh-budget, maintained by PerryLink. Same-name repositories under other accounts are not affiliated.
|
|
12
|
+
|
|
13
|
+
[](LICENSE)
|
|
14
|
+
[](https://github.com/topics/dsh-plugin)
|
|
15
|
+
[](#)
|
|
16
|
+
[](https://github.com/PerryLink/dsh-budget/actions)
|
|
17
|
+
[](https://github.com/PerryLink/dsh-budget/releases)
|
|
18
|
+
[](https://www.npmjs.com/package/dsh-budget)
|
|
19
|
+
[](https://www.npmjs.com/package/dsh-budget)
|
|
20
|
+
|
|
21
|
+
[English](README.md) · [简体中文](README.zh.md) · [Español](README.es.md) · [Português](README.pt.md) · [हिन्दी](README.hi.md)
|
|
22
|
+
|
|
23
|
+
</div>
|
|
24
|
+
|
|
25
|
+
---
|
|
26
|
+
|
|
27
|
+
## Compatibility
|
|
28
|
+
|
|
29
|
+
| Surface | Status |
|
|
30
|
+
|---|---|
|
|
31
|
+
| Harness | DeepSeek Harness `0.1.1-rc.2` |
|
|
32
|
+
|
|
33
|
+
| Audit events | Written on harnesses before `0.1.2-alpha.1`; suppressed with a logged degradation reason on `0.1.2-alpha.1` and later (fail-closed session event vocabulary, no external registration surface) || Node | `^22.19.0 \|\| >=24.0.0` |
|
|
34
|
+
| Surfaces | Host + Web client (Settings budget tab); `/budget` command |
|
|
35
|
+
|
|
36
|
+
## What you get
|
|
37
|
+
|
|
38
|
+
`dsh-budget` turns the session event stream into a four-in-one cost governance loop:
|
|
39
|
+
|
|
40
|
+
- **Aggregated metering** — tokens (uncached input / output / cache read / cache write), estimated USD cost, and carbon footprint per model, session, and day, priced through a built-in USD-per-1M table merged with your `config.prices`.
|
|
41
|
+
- **Budget governance** — session/daily/monthly caps; a warn-ratio threshold alert (webhook POST + desktop-notification flag) and three over-limit policies: `alert` (notify only), `block` (short-circuit new model requests until the user lifts the block), `degrade` (block with corrective guidance naming the cheaper model from your `degradation` map).
|
|
42
|
+
- **Carbon & latency** — token→carbon bridge (tokens × kWh/token × PUE × regional grid intensity, ported from AI-Carbon-Footprint-Calculator) and per-model latency percentiles.
|
|
43
|
+
- **Surfaces** — the Settings budget tab (usage bars, per-day usage curve, model breakdown, alerts, cap editors, unblock buttons) and the `/budget` command (`/budget`, `/budget models`, `/budget unblock <scope>`).
|
|
44
|
+
|
|
45
|
+
## Quick start
|
|
46
|
+
|
|
47
|
+
```sh
|
|
48
|
+
# 1. install the bundle into your profile
|
|
49
|
+
dsh plugin --profile web add "github:PerryLink/dsh-budget#main"
|
|
50
|
+
|
|
51
|
+
# or from npm (published releases)
|
|
52
|
+
dsh plugin --profile web add dsh-budget
|
|
53
|
+
|
|
54
|
+
# 2. restart and verify the row
|
|
55
|
+
dsh --profile web --dump-config | grep -A2 'id: budget'
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
Then ask the agent: `/budget` — and watch the Settings tab fill in.
|
|
59
|
+
|
|
60
|
+
## Install & uninstall
|
|
61
|
+
|
|
62
|
+
- **git channel** (latest `main`): `dsh plugin --profile web add "github:PerryLink/dsh-budget#main"` — the `prepare` script builds with production dependencies only.
|
|
63
|
+
- **npm channel** (published releases): `dsh plugin --profile web add dsh-budget`.
|
|
64
|
+
- **tarball channel**: `pnpm pack` in this repo, then `dsh plugin --profile web add ./dsh-budget-<version>.tgz`.
|
|
65
|
+
- **uninstall**: `dsh plugin --profile web remove dsh-budget`.
|
|
66
|
+
|
|
67
|
+
> If pnpm reports `ERR_PNPM_IGNORED_BUILDS` for this package (esbuild's harmless platform-binary validation), add `allowBuilds: { esbuild: true }` to your `pnpm-workspace.yaml` — the `dsh` CLI prints the exact snippet.
|
|
68
|
+
|
|
69
|
+
## Configuration
|
|
70
|
+
|
|
71
|
+
All tunables are Schemastery `Config` fields (changeable from cordis.yml). `cordis.patch.yml` documents each key inline.
|
|
72
|
+
|
|
73
|
+
| Key | Default | Meaning |
|
|
74
|
+
|---|---|---|
|
|
75
|
+
| `prices` | `{}` | Per-model USD prices per 1M tokens, merged over the built-in table |
|
|
76
|
+
| `defaultPrice` | `{input: 1.0, output: 3.0}` | Fallback for models absent from both tables |
|
|
77
|
+
| `budgets.session` / `daily` / `monthly` | `10` / `50` / `500` | Budget caps in USD per scope; omit for unlimited |
|
|
78
|
+
| `warnRatio` | `0.8` | Alert once usage reaches this fraction of a cap (0..1) |
|
|
79
|
+
| `overLimit` | `alert` | `alert` / `block` / `degrade` after a cap is crossed |
|
|
80
|
+
| `degradation` | `{}` | Model id → cheaper model id of the same provider |
|
|
81
|
+
| `webhookUrl` | *(none)* | Optional webhook URL for threshold alerts (POST JSON) |
|
|
82
|
+
| `webhookTimeoutMs` | `5000` | Webhook request timeout |
|
|
83
|
+
| `alertsEnabled` | `true` | Master switch for threshold alerts |
|
|
84
|
+
| `alertCooldownMs` | `3600000` | Minimum ms between two alerts of the same scope |
|
|
85
|
+
| `desktopNotifications` | `false` | Browser desktop notifications while the tab is open |
|
|
86
|
+
| `refreshIntervalMs` | `5000` | Settings tab polling interval |
|
|
87
|
+
| `carbon.enabled` / `region` / `pue` / `energyKwhPerToken` | `true` / `global` / `1.58` / `0.000007` | Carbon bridge (regions: global, us, eu, china, india, uk, france, iceland) |
|
|
88
|
+
| `latency.enabled` / `windowSize` | `true` / `200` | Per-model latency percentiles and their window |
|
|
89
|
+
| `currency` | `{code: USD, rate: 1.0, decimals: 2}` | Display currency (costs are computed in USD) |
|
|
90
|
+
| `outputLanguage` | `en` | `/budget` output language: `en` / `zh` |
|
|
91
|
+
| `historyDays` | `30` | Per-day usage history kept in the panel snapshot |
|
|
92
|
+
| `persistence.enabled` / `intervalMs` | `true` / `10000` | Durable day/month persistence across restarts (storage domain); degrades to in-memory when the domain is absent |
|
|
93
|
+
|
|
94
|
+
## Tools & surfaces
|
|
95
|
+
|
|
96
|
+
| Surface | Kind | Notes |
|
|
97
|
+
|---|---|---|
|
|
98
|
+
| `/budget` | Command | Per-scope overview (usage, ratio, carbon, blocked state) |
|
|
99
|
+
| `/budget models` | Command | Per-model breakdown with latency percentiles |
|
|
100
|
+
| `/budget unblock <scope>` | Command | Lift a blocked scope (`session` / `daily` / `monthly`) |
|
|
101
|
+
| Settings → Plugins → Budget | Settings tab | Usage bars, per-day usage curve, model breakdown, alerts, cap editors, unblock buttons |
|
|
102
|
+
| `budget/status`, `budget/setSettings`, `budget/unblock` | Typert Remote | The client channel (the tab consumes these) |
|
|
103
|
+
|
|
104
|
+
## Permissions & data
|
|
105
|
+
|
|
106
|
+
- **Permissions**: `network:outbound` (the optional alert webhook only), `session:append` (audit events), `native-code:none`.
|
|
107
|
+
- **Data**: everything displayed comes from the session event stream; the only host-side network call is the configured webhook, whose URL is validated at load and credential-stripped before any log. No prompts or payloads ever leave the host.
|
|
108
|
+
- **Session log**: `budget/alert` and `budget/block` are log-only audit events carrying scope names and USD amounts (microtask-deferred past the session-append reentrancy guard). On harnesses `0.1.2-alpha.1` and later they are not written — the fail-closed event vocabulary rejects logs with unregistered event types and offers no external registration surface — so the audit trail degrades to the budget logger and webhook only.
|
|
109
|
+
|
|
110
|
+
## Security boundaries
|
|
111
|
+
|
|
112
|
+
- **No fabrication**: a budget block yields a corrective error finish on the `llm/stream` waterfall — the plugin never invents model output.
|
|
113
|
+
- **No request rewriting**: loop-built requests are frozen; `degrade` therefore names the target model in the corrective message instead of swapping the request.
|
|
114
|
+
- **Fail loud**: invalid prices, URLs, ratios, regions, and bounds fail the mount.
|
|
115
|
+
- **Honest scope**: runtime edits from the panel are session-scoped; a reload restores the cordis.yml values.
|
|
116
|
+
|
|
117
|
+
## Known limitations
|
|
118
|
+
|
|
119
|
+
- Aggregation is process-local: usage resets when the harness restarts (per-day/per-month buckets rebuild from the current session log view).
|
|
120
|
+
- `block`/`degrade` rely on the `llm/stream` waterfall; harness builds without that seam cannot block requests (alerts still work).
|
|
121
|
+
- Built-in prices drift; override entries via `config.prices`.
|
|
122
|
+
|
|
123
|
+
## Development
|
|
124
|
+
|
|
125
|
+
```sh
|
|
126
|
+
pnpm install # node ^22.19 || >=24
|
|
127
|
+
pnpm run typecheck # tsc: src + tests against the local harness checkout
|
|
128
|
+
pnpm run typecheck:ci # tsc against the published 0.1.1-rc.2 types (no paths)
|
|
129
|
+
pnpm test # vitest
|
|
130
|
+
pnpm run build # tsc declarations + tsdown bundles (lib/)
|
|
131
|
+
pnpm run verify:self-contained # dependency specs resolve from the registry
|
|
132
|
+
pnpm run verify:artifacts # built ESM face + typert manifest + client bundle
|
|
133
|
+
pnpm pack # the published tarball
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
## Topics
|
|
137
|
+
|
|
138
|
+
`dsh`, `dsh-plugin`, `deepseek-harness`, `deepseek`, `cordis`, `budget`, `cost-tracking`, `carbon-footprint`, `latency-benchmark`, `token-usage`
|
|
139
|
+
|
|
140
|
+
## Contributors
|
|
141
|
+
|
|
142
|
+
- [@PerryLink](https://github.com/PerryLink) — creator and maintainer: aggregation, budget governance, carbon and latency ports, the Settings tab, and the five-language docs.
|
|
143
|
+
|
|
140
144
|
## PerryLink DSH Plugin Family
|
|
141
145
|
|
|
142
|
-
This project is one of the [
|
|
146
|
+
This project is one of the [33 DeepSeek Harness plugins](https://github.com/PerryLink) maintained by [PerryLink](https://github.com/PerryLink). If this one helps you, the others likely will too:
|
|
143
147
|
|
|
144
148
|
| Plugin | One-liner |
|
|
145
149
|
|---|---|
|
|
146
|
-
| [dsh-auto-review](https://github.com/PerryLink/dsh-auto-review) | Second-model auto-review on the approval chain, fail-closed by default |
|
|
147
|
-
| [dsh-background-agents](https://github.com/PerryLink/dsh-background-agents) | Durable background child agents with a Web UI sidebar, messaging and interrupt |
|
|
148
|
-
| **[dsh-
|
|
149
|
-
| [dsh-
|
|
150
|
-
| [dsh-
|
|
151
|
-
| [dsh-
|
|
152
|
-
| [dsh-
|
|
153
|
-
| [dsh-defend](https://github.com/PerryLink/dsh-defend) | Prompt-injection, jailbreak, and secret-leak defense for DeepSeek Harness. |
|
|
154
|
-
| [dsh-doublecheck](https://github.com/PerryLink/dsh-doublecheck) | Engineering-discipline guard: requirements grill, test gates, adversary review |
|
|
155
|
-
| [dsh-draw](https://github.com/PerryLink/dsh-draw) | Unified static-image generation routing for DeepSeek Harness. |
|
|
156
|
-
| [dsh-fast](https://github.com/PerryLink/dsh-fast) | Read-only performance diagnostics for DeepSeek Harness. |
|
|
157
|
-
| [dsh-
|
|
158
|
-
| [dsh-
|
|
159
|
-
| [dsh-
|
|
160
|
-
| [dsh-
|
|
161
|
-
| [dsh-
|
|
162
|
-
| [dsh-
|
|
163
|
-
| [dsh-
|
|
164
|
-
| [dsh-
|
|
165
|
-
| [dsh-
|
|
166
|
-
| [dsh-
|
|
167
|
-
| [dsh-
|
|
168
|
-
| [dsh-
|
|
169
|
-
| [dsh-
|
|
170
|
-
| [dsh-
|
|
171
|
-
| [dsh-
|
|
172
|
-
| [dsh-
|
|
173
|
-
| [dsh-
|
|
174
|
-
| [dsh-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
150
|
+
| **[dsh-dsh-auto-review](https://github.com/PerryLink/dsh-dsh-auto-review)** | Second-model auto-review on the approval chain, fail-closed by default | |
|
|
151
|
+
| **[dsh-dsh-background-agents](https://github.com/PerryLink/dsh-dsh-background-agents)** | Durable background child agents with a Web UI sidebar, messaging and interrupt | |
|
|
152
|
+
| **[dsh-dsh-checkpoint-rewind](https://github.com/PerryLink/dsh-dsh-checkpoint-rewind)** | Claude Code /rewind-equivalent: snapshots, session forks, one-shot restore | |
|
|
153
|
+
| **[dsh-dsh-claude-move](https://github.com/PerryLink/dsh-dsh-claude-move)** | Migrate Claude Code sessions, memory, skills and CLAUDE.md into DSH | |
|
|
154
|
+
| **[dsh-dsh-click](https://github.com/PerryLink/dsh-dsh-click)** | Cross-platform native desktop control for DeepSeek Harness — Windows first. | |
|
|
155
|
+
| **[dsh-dsh-composer-history](https://github.com/PerryLink/dsh-dsh-composer-history)** | Terminal-style input history for the web composer: arrows, Ctrl+R search | |
|
|
156
|
+
| **[dsh-dsh-data-quality](https://github.com/PerryLink/dsh-dsh-data-quality)** | Dataset quality checks and citation cross-checks (the optional numeric bridge consumed here) | |
|
|
157
|
+
| **[dsh-dsh-defend](https://github.com/PerryLink/dsh-dsh-defend)** | Prompt-injection, jailbreak, and secret-leak defense for DeepSeek Harness. | |
|
|
158
|
+
| **[dsh-dsh-doublecheck](https://github.com/PerryLink/dsh-dsh-doublecheck)** | Engineering-discipline guard: requirements grill, test gates, adversary review | |
|
|
159
|
+
| **[dsh-dsh-draw](https://github.com/PerryLink/dsh-dsh-draw)** | Unified static-image generation routing for DeepSeek Harness. | |
|
|
160
|
+
| **[dsh-dsh-fast](https://github.com/PerryLink/dsh-dsh-fast)** | Read-only performance diagnostics for DeepSeek Harness. | |
|
|
161
|
+
| **[dsh-dsh-fund-research](https://github.com/PerryLink/dsh-dsh-fund-research)** | Deterministic research reports for Chinese public mutual funds | |
|
|
162
|
+
| **[dsh-dsh-github](https://github.com/PerryLink/dsh-dsh-github)** | GitHub PR/issues integration for DSH, every write gated by approval | |
|
|
163
|
+
| **[dsh-dsh-industry-research](https://github.com/PerryLink/dsh-dsh-industry-research)** | Industry research orchestration that seals its deliverables through this plugin's `ctx.researchReport.assemble` | |
|
|
164
|
+
| **[dsh-dsh-library](https://github.com/PerryLink/dsh-dsh-library)** | Local document knowledge base for DeepSeek Harness. | |
|
|
165
|
+
| **[dsh-dsh-local-ai](https://github.com/PerryLink/dsh-dsh-local-ai)** | Local-model (Ollama) integration for DeepSeek Harness. | |
|
|
166
|
+
| **[dsh-dsh-lsp-actions](https://github.com/PerryLink/dsh-dsh-lsp-actions)** | LSP diagnostics, formatting, completion, code actions and rename over language servers | |
|
|
167
|
+
| **[dsh-dsh-mask](https://github.com/PerryLink/dsh-dsh-mask)** | PII masking middleware: anonymize at the model boundary, restore at the display layer | |
|
|
168
|
+
| **[dsh-dsh-mcp-panel](https://github.com/PerryLink/dsh-dsh-mcp-panel)** | Read-only MCP runtime panel: /mcp command + Settings tab with status, tools and errors | |
|
|
169
|
+
| **[dsh-dsh-memento](https://github.com/PerryLink/dsh-dsh-memento)** | Approval-gated cross-session memory: ctx.memory seam + SQLite + memory tool | |
|
|
170
|
+
| **[dsh-dsh-observe](https://github.com/PerryLink/dsh-dsh-observe)** | OpenTelemetry and Langfuse observability exporter for DeepSeek Harness. | |
|
|
171
|
+
| **[dsh-dsh-output-styles](https://github.com/PerryLink/dsh-dsh-output-styles)** | Claude Code outputStyles-equivalent runtime style switching | |
|
|
172
|
+
| **[dsh-dsh-permission-rules](https://github.com/PerryLink/dsh-dsh-permission-rules)** | Claude Code-style declarative allow/deny/ask permission rules with audit | |
|
|
173
|
+
| **[dsh-dsh-plugin-guide](https://github.com/PerryLink/dsh-dsh-plugin-guide)** | Plugin-development knowledge base as an on-demand agent skill | |
|
|
174
|
+
| **[dsh-dsh-research-report](https://github.com/PerryLink/dsh-dsh-research-report)** | Verifiable research-report engine: content-addressed evidence ledger and sealed versions | |
|
|
175
|
+
| **[dsh-dsh-score](https://github.com/PerryLink/dsh-dsh-score)** | Multi-dimensional quality scoring for DeepSeek Harness plugins. | |
|
|
176
|
+
| **[dsh-dsh-session-pin](https://github.com/PerryLink/dsh-dsh-session-pin)** | Pin sessions in the Web sidebar with durable ordering | |
|
|
177
|
+
| **[dsh-dsh-session-sync](https://github.com/PerryLink/dsh-dsh-session-sync)** | Cross-device session sync for DeepSeek Harness — a dedicated git mirror of your session store. | |
|
|
178
|
+
| **[dsh-dsh-skill-pack-security](https://github.com/PerryLink/dsh-dsh-skill-pack-security)** | Security-audit skill pack: secret scan, dependency and supply-chain review | |
|
|
179
|
+
| **[dsh-dsh-talk](https://github.com/PerryLink/dsh-dsh-talk)** | Voice-first session loop for DeepSeek Harness: talk to it, hear it answer. | |
|
|
180
|
+
| **[dsh-dsh-test-drive](https://github.com/PerryLink/dsh-dsh-test-drive)** | Isolated install-and-smoke test drives for DeepSeek Harness plugins. | |
|
|
181
|
+
| **[dsh-dsh-translate](https://github.com/PerryLink/dsh-dsh-translate)** | Vendor parameter translation and deterministic JSON repair for DeepSeek Harness. | |
|
|
182
|
+
|
|
183
|
+
## License
|
|
184
|
+
|
|
185
|
+
[Apache License 2.0](LICENSE) © 2026 dsh-budget contributors
|