dsh-budget 0.1.0

package/README.md

@@ -0,0 +1,140 @@
+<div align="center">
+
+# 💰 dsh-budget
+
+**Cost governance for DeepSeek Harness: budgets, carbon, and latency in one panel.**
+
+*Know what every session costs — before it costs you.*
+
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
+[![DSH plugin](https://img.shields.io/badge/dsh-plugin-✅-green)](https://github.com/topics/dsh-plugin)
+[![Node](https://img.shields.io/badge/node-%5E22.19%20%7C%7C%20%3E%3D24-brightgreen.svg)](#)
+[![CI](https://img.shields.io/github/actions/workflow/status/PerryLink/dsh-budget/ci.yml?branch=main&label=CI)](https://github.com/PerryLink/dsh-budget/actions)
+[![Version](https://img.shields.io/github/v/tag/PerryLink/dsh-budget?label=version)](https://github.com/PerryLink/dsh-budget/releases)
+[![npm version](https://img.shields.io/npm/v/dsh-budget)](https://www.npmjs.com/package/dsh-budget)
+[![npm downloads](https://img.shields.io/npm/dm/dsh-budget)](https://www.npmjs.com/package/dsh-budget)
+
+[English](README.md) · [简体中文](README.zh.md) · [Español](README.es.md) · [Português](README.pt.md) · [हिन्दी](README.hi.md)
+
+</div>
+
+---
+
+## Compatibility
+
+| Surface | Status |
+|---|---|
+| Harness | DeepSeek Harness `0.1.0-rc.6` |
+| Node | `^22.19.0 \|\| >=24.0.0` |
+| Surfaces | Host + Web client (Settings budget tab); `/budget` command |
+
+## What you get
+
+`dsh-budget` turns the session event stream into a four-in-one cost governance loop:
+
+- **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`.
+- **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).
+- **Carbon & latency** — token→carbon bridge (tokens × kWh/token × PUE × regional grid intensity, ported from AI-Carbon-Footprint-Calculator) and per-model latency percentiles.
+- **Surfaces** — the Settings budget tab (usage bars, model breakdown, alerts, cap editors, unblock buttons) and the `/budget` command (`/budget`, `/budget models`, `/budget unblock <scope>`).
+
+## Quick start
+
+```sh
+# 1. install the bundle into your profile
+dsh plugin --profile web add "github:PerryLink/dsh-budget#main"
+
+# or from npm (published releases)
+dsh plugin --profile web add dsh-budget
+
+# 2. restart and verify the row
+dsh --profile web --dump-config | grep -A2 'id: budget'
+```
+
+Then ask the agent: `/budget` — and watch the Settings tab fill in.
+
+## Install & uninstall
+
+- **git channel** (latest `main`): `dsh plugin --profile web add "github:PerryLink/dsh-budget#main"` — the `prepare` script builds with production dependencies only.
+- **npm channel** (published releases): `dsh plugin --profile web add dsh-budget`.
+- **tarball channel**: `pnpm pack` in this repo, then `dsh plugin --profile web add ./dsh-budget-<version>.tgz`.
+- **uninstall**: `dsh plugin --profile web remove dsh-budget`.
+
+> 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.
+
+## Configuration
+
+All tunables are Schemastery `Config` fields (changeable from cordis.yml). `cordis.patch.yml` documents each key inline.
+
+| Key | Default | Meaning |
+|---|---|---|
+| `prices` | `{}` | Per-model USD prices per 1M tokens, merged over the built-in table |
+| `defaultPrice` | `{input: 1.0, output: 3.0}` | Fallback for models absent from both tables |
+| `budgets.session` / `daily` / `monthly` | `10` / `50` / `500` | Budget caps in USD per scope; omit for unlimited |
+| `warnRatio` | `0.8` | Alert once usage reaches this fraction of a cap (0..1) |
+| `overLimit` | `alert` | `alert` / `block` / `degrade` after a cap is crossed |
+| `degradation` | `{}` | Model id → cheaper model id of the same provider |
+| `webhookUrl` | *(none)* | Optional webhook URL for threshold alerts (POST JSON) |
+| `webhookTimeoutMs` | `5000` | Webhook request timeout |
+| `alertsEnabled` | `true` | Master switch for threshold alerts |
+| `alertCooldownMs` | `3600000` | Minimum ms between two alerts of the same scope |
+| `desktopNotifications` | `false` | Browser desktop notifications while the tab is open |
+| `refreshIntervalMs` | `5000` | Settings tab polling interval |
+| `carbon.enabled` / `region` / `pue` / `energyKwhPerToken` | `true` / `global` / `1.58` / `0.000007` | Carbon bridge (regions: global, us, eu, china, india, uk, france, iceland) |
+| `latency.enabled` / `windowSize` | `true` / `200` | Per-model latency percentiles and their window |
+| `currency` | `{code: USD, rate: 1.0, decimals: 2}` | Display currency (costs are computed in USD) |
+| `outputLanguage` | `en` | `/budget` output language: `en` / `zh` |
+| `historyDays` | `30` | Per-day usage history kept in the panel snapshot |
+
+## Tools & surfaces
+
+| Surface | Kind | Notes |
+|---|---|---|
+| `/budget` | Command | Per-scope overview (usage, ratio, carbon, blocked state) |
+| `/budget models` | Command | Per-model breakdown with latency percentiles |
+| `/budget unblock <scope>` | Command | Lift a blocked scope (`session` / `daily` / `monthly`) |
+| Settings → Plugins → Budget | Settings tab | Usage bars, model breakdown, alerts, cap editors, unblock buttons |
+| `budget/status`, `budget/setSettings`, `budget/unblock` | Typert Remote | The client channel (the tab consumes these) |
+
+## Permissions & data
+
+- **Permissions**: `network:outbound` (the optional alert webhook only), `session:append` (audit events), `native-code:none`.
+- **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.
+- **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).
+
+## Security boundaries
+
+- **No fabrication**: a budget block yields a corrective error finish on the `llm/stream` waterfall — the plugin never invents model output.
+- **No request rewriting**: loop-built requests are frozen; `degrade` therefore names the target model in the corrective message instead of swapping the request.
+- **Fail loud**: invalid prices, URLs, ratios, regions, and bounds fail the mount.
+- **Honest scope**: runtime edits from the panel are session-scoped; a reload restores the cordis.yml values.
+
+## Known limitations
+
+- Aggregation is process-local: usage resets when the harness restarts (per-day/per-month buckets rebuild from the current session log view).
+- `block`/`degrade` rely on the `llm/stream` waterfall; harness builds without that seam cannot block requests (alerts still work).
+- Built-in prices drift; override entries via `config.prices`.
+
+## Development
+
+```sh
+pnpm install        # node ^22.19 || >=24
+pnpm run typecheck  # tsc: src + tests against the local harness checkout
+pnpm run typecheck:ci  # tsc against the published 0.1.0-rc.6 types (no paths)
+pnpm test           # vitest: 45 tests
+pnpm run build      # tsc declarations + tsdown bundles (lib/)
+pnpm run verify:self-contained  # dependency specs resolve from the registry
+pnpm run verify:artifacts       # built ESM face + typert manifest + client bundle
+pnpm pack           # the published tarball
+```
+
+## Topics
+
+`dsh`, `dsh-plugin`, `deepseek-harness`, `deepseek`, `cordis`, `budget`, `cost-tracking`, `carbon-footprint`, `latency-benchmark`, `token-usage`
+
+## Contributors
+
+- [@PerryLink](https://github.com/PerryLink) — creator and maintainer: aggregation, budget governance, carbon and latency ports, the Settings tab, and the five-language docs.
+
+## License
+
+[Apache License 2.0](LICENSE) © 2026 dsh-budget contributors

package/README.pt.md

@@ -0,0 +1,140 @@
+<div align="center">
+
+# 💰 dsh-budget
+
+**Governança de custos para o DeepSeek Harness: orçamentos, carbono e latência em um só painel.**
+
+*Saiba quanto cada sessão custa — antes que custe a você.*
+
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
+[![DSH plugin](https://img.shields.io/badge/dsh-plugin-✅-green)](https://github.com/topics/dsh-plugin)
+[![Node](https://img.shields.io/badge/node-%5E22.19%20%7C%7C%20%3E%3D24-brightgreen.svg)](#)
+[![CI](https://img.shields.io/github/actions/workflow/status/PerryLink/dsh-budget/ci.yml?branch=main&label=CI)](https://github.com/PerryLink/dsh-budget/actions)
+[![Version](https://img.shields.io/github/v/tag/PerryLink/dsh-budget?label=version)](https://github.com/PerryLink/dsh-budget/releases)
+[![npm version](https://img.shields.io/npm/v/dsh-budget)](https://www.npmjs.com/package/dsh-budget)
+[![npm downloads](https://img.shields.io/npm/dm/dsh-budget)](https://www.npmjs.com/package/dsh-budget)
+
+[English](README.md) · [简体中文](README.zh.md) · [Español](README.es.md) · [Português](README.pt.md) · [हिन्दी](README.hi.md)
+
+</div>
+
+---
+
+## Compatibilidade
+
+| Superfície | Status |
+|---|---|
+| Harness | DeepSeek Harness `0.1.0-rc.6` |
+| Node | `^22.19.0 \|\| >=24.0.0` |
+| Superfícies | Host + cliente Web (aba Budget em Settings); comando `/budget` |
+
+## O que você ganha
+
+O `dsh-budget` transforma o fluxo de eventos da sessão em um ciclo de governança de custos quatro em um:
+
+- **Medição agregada** — tokens (entrada sem cache / saída / leitura de cache / escrita de cache), custo USD estimado e pegada de carbono por modelo, sessão e dia, precificados por uma tabela integrada de USD por 1M de tokens mesclada com `config.prices`.
+- **Governança de orçamento** — tetos de sessão/diários/mensais; alerta de limiar `warnRatio` (webhook POST + indicador de notificação de desktop) e três políticas ao estourar: `alert` (apenas notificar), `block` (curto-circuitar novas requisições até o usuário liberar), `degrade` (bloqueio com orientação corretiva nomeando o modelo mais barato do seu mapa `degradation`).
+- **Carbono e latência** — ponte token→carbono (tokens × kWh/token × PUE × intensidade da rede regional, portado do AI-Carbon-Footprint-Calculator) e percentis de latência por modelo.
+- **Superfícies** — a aba Budget em Settings (barras de uso, detalhamento por modelo, alertas, editores de teto, botões de desbloqueio) e o comando `/budget` (`/budget`, `/budget models`, `/budget unblock <scope>`).
+
+## Início rápido
+
+```sh
+# 1. instale o bundle no seu perfil
+dsh plugin --profile web add "github:PerryLink/dsh-budget#main"
+
+# ou pelo npm (versões publicadas)
+dsh plugin --profile web add dsh-budget
+
+# 2. reinicie e verifique a linha
+dsh --profile web --dump-config | grep -A2 'id: budget'
+```
+
+Então peça ao agente: `/budget` — e veja a aba de Settings se preencher.
+
+## Instalação e desinstalação
+
+- **Canal git** (último `main`): `dsh plugin --profile web add "github:PerryLink/dsh-budget#main"` — o script `prepare` compila apenas com dependências de produção.
+- **Canal npm** (versões publicadas): `dsh plugin --profile web add dsh-budget`.
+- **Canal tarball**: `pnpm pack` neste repositório e então `dsh plugin --profile web add ./dsh-budget-<version>.tgz`.
+- **Desinstalar**: `dsh plugin --profile web remove dsh-budget`.
+
+> Se o pnpm reportar `ERR_PNPM_IGNORED_BUILDS` para este pacote (a validação inofensiva do binário de plataforma do esbuild), adicione `allowBuilds: { esbuild: true }` ao seu `pnpm-workspace.yaml` — o CLI `dsh` imprime o trecho exato.
+
+## Configuração
+
+Todos os ajustes são campos `Config` do Schemastery (alteráveis pelo cordis.yml). O `cordis.patch.yml` documenta cada chave em linha.
+
+| Chave | Padrão | Significado |
+|---|---|---|
+| `prices` | `{}` | Preços USD por 1M de tokens por modelo, mesclados sobre a tabela integrada |
+| `defaultPrice` | `{input: 1.0, output: 3.0}` | Reserva para modelos ausentes de ambas as tabelas |
+| `budgets.session` / `daily` / `monthly` | `10` / `50` / `500` | Tetos de orçamento USD por escopo; omitir para ilimitado |
+| `warnRatio` | `0.8` | Alertar quando o uso atingir esta fração do teto (0..1) |
+| `overLimit` | `alert` | `alert` / `block` / `degrade` após cruzar um teto |
+| `degradation` | `{}` | Id de modelo → id de modelo mais barato do mesmo provedor |
+| `webhookUrl` | *(nenhuma)* | URL opcional de webhook para alertas de limiar (POST JSON) |
+| `webhookTimeoutMs` | `5000` | Timeout da requisição webhook |
+| `alertsEnabled` | `true` | Interruptor mestre dos alertas de limiar |
+| `alertCooldownMs` | `3600000` | Mínimo em ms entre dois alertas do mesmo escopo |
+| `desktopNotifications` | `false` | Notificações de desktop do navegador com a aba aberta |
+| `refreshIntervalMs` | `5000` | Intervalo de sondagem da aba |
+| `carbon.enabled` / `region` / `pue` / `energyKwhPerToken` | `true` / `global` / `1.58` / `0.000007` | Ponte de carbono (regiões: global, us, eu, china, india, uk, france, iceland) |
+| `latency.enabled` / `windowSize` | `true` / `200` | Percentis de latência por modelo e sua janela |
+| `currency` | `{code: USD, rate: 1.0, decimals: 2}` | Moeda de exibição (custos calculados em USD) |
+| `outputLanguage` | `en` | Idioma de saída do `/budget`: `en` / `zh` |
+| `historyDays` | `30` | Dias de histórico de uso diário no snapshot |
+
+## Ferramentas e superfícies
+
+| Superfície | Tipo | Notas |
+|---|---|---|
+| `/budget` | Comando | Visão geral por escopo (uso, proporção, carbono, estado bloqueado) |
+| `/budget models` | Comando | Detalhamento por modelo com percentis de latência |
+| `/budget unblock <scope>` | Comando | Liberar um escopo bloqueado (`session` / `daily` / `monthly`) |
+| Settings → Plugins → Budget | Aba de Settings | Barras de uso, detalhamento, alertas, editores de teto, desbloqueio |
+| `budget/status`, `budget/setSettings`, `budget/unblock` | Typert Remote | Canal do cliente (consumido pela aba) |
+
+## Permissões e dados
+
+- **Permissões**: `network:outbound` (apenas o webhook de alerta opcional), `session:append` (eventos de auditoria), `native-code:none`.
+- **Dados**: tudo exibido vem do fluxo de eventos da sessão; a única chamada de rede é o webhook configurado, validado ao carregar e sem credenciais nos registros. Nenhum prompt ou payload sai do host.
+- **Registro de sessão**: `budget/alert` e `budget/block` são eventos de auditoria somente-registro com nomes de escopo e valores USD (adiados por microtarefa ante o guard de reentrância do append).
+
+## Limites de segurança
+
+- **Sem fabricação**: um bloqueio de orçamento produz um final de erro corretivo no waterfall `llm/stream` — o plugin nunca inventa saída de modelo.
+- **Sem reescrita de requisições**: requisições do loop são congeladas; `degrade` nomeia o modelo alvo na mensagem corretiva em vez de substituir a requisição.
+- **Falha ruidosa**: preços, URLs, proporções, regiões ou limites inválidos falham o mount.
+- **Escopo honesto**: edições em tempo de execução do painel valem por sessão; uma recarga restaura os valores do cordis.yml.
+
+## Limitações conhecidas
+
+- A agregação é local ao processo: o uso zera ao reiniciar o harness (os buckets diários/mensais se reconstroem da visão atual do log).
+- `block`/`degrade` dependem do waterfall `llm/stream`; builds sem esse seam não podem bloquear requisições (alertas continuam funcionando).
+- Os preços integrados ficam defasados; sobrescreva entradas via `config.prices`.
+
+## Desenvolvimento
+
+```sh
+pnpm install        # node ^22.19 || >=24
+pnpm run typecheck  # tsc: src + tests contra o checkout local do harness
+pnpm run typecheck:ci  # tsc contra os tipos publicados 0.1.0-rc.6 (sem paths)
+pnpm test           # vitest: 45 testes
+pnpm run build      # declarações tsc + bundles tsdown (lib/)
+pnpm run verify:self-contained  # especificações de dependências resolvem pelo registry
+pnpm run verify:artifacts       # face ESM + manifesto typert + bundle de cliente
+pnpm pack           # o tarball publicado
+```
+
+## Topics
+
+`dsh`, `dsh-plugin`, `deepseek-harness`, `deepseek`, `cordis`, `budget`, `cost-tracking`, `carbon-footprint`, `latency-benchmark`, `token-usage`
+
+## Contributors
+
+- [@PerryLink](https://github.com/PerryLink) — criador e mantenedor: agregação, governança de orçamento, portes de carbono e latência, a aba de Settings e a documentação em cinco idiomas.
+
+## License
+
+[Apache License 2.0](LICENSE) © 2026 dsh-budget contributors

package/README.zh.md

@@ -0,0 +1,140 @@
+<div align="center">
+
+# 💰 dsh-budget
+
+**DeepSeek Harness 的成本治理：预算、碳足迹与延迟，一个面板全览。**
+
+*让每次会话的成本在超支之前就被看清。*
+
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
+[![DSH plugin](https://img.shields.io/badge/dsh-plugin-✅-green)](https://github.com/topics/dsh-plugin)
+[![Node](https://img.shields.io/badge/node-%5E22.19%20%7C%7C%20%3E%3D24-brightgreen.svg)](#)
+[![CI](https://img.shields.io/github/actions/workflow/status/PerryLink/dsh-budget/ci.yml?branch=main&label=CI)](https://github.com/PerryLink/dsh-budget/actions)
+[![Version](https://img.shields.io/github/v/tag/PerryLink/dsh-budget?label=version)](https://github.com/PerryLink/dsh-budget/releases)
+[![npm version](https://img.shields.io/npm/v/dsh-budget)](https://www.npmjs.com/package/dsh-budget)
+[![npm downloads](https://img.shields.io/npm/dm/dsh-budget)](https://www.npmjs.com/package/dsh-budget)
+
+[English](README.md) · [简体中文](README.zh.md) · [Español](README.es.md) · [Português](README.pt.md) · [हिन्दी](README.hi.md)
+
+</div>
+
+---
+
+## 兼容性
+
+| 方面 | 状态 |
+|---|---|
+| Harness | DeepSeek Harness `0.1.0-rc.6` |
+| Node | `^22.19.0 \|\| >=24.0.0` |
+| 界面 | Host + Web 客户端（设置页预算页签）；`/budget` 命令 |
+
+## 你能得到什么
+
+`dsh-budget` 把会话事件流变成四合一成本治理闭环：
+
+- **聚合计量** —— token（未缓存输入 / 输出 / 缓存读 / 缓存写）、估算 USD 成本与碳足迹，按模型/会话/天聚合；内置 USD/百万 token 价目表与 `config.prices` 合并定价。
+- **预算治理** —— 会话/日/月三档封顶；warnRatio 阈值告警（webhook POST + 桌面通知开关）与三种超限策略：`alert`（仅告警）、`block`（在用户解除前短路新模型请求）、`degrade`（阻断并给出指向 `degradation` 映射中更便宜模型的修正提示）。
+- **碳足迹与延迟** —— token→碳桥接（tokens × kWh/token × PUE × 区域电网强度，移植自 AI-Carbon-Footprint-Calculator）与按模型延迟百分位。
+- **界面** —— 设置页预算页签（用量条、模型明细、告警、上限编辑、解除阻断按钮）与 `/budget` 命令（`/budget`、`/budget models`、`/budget unblock <scope>`）。
+
+## 快速开始
+
+```sh
+# 1. 把 bundle 装进你的 profile
+dsh plugin --profile web add "github:PerryLink/dsh-budget#main"
+
+# 或从 npm 安装（正式发布版）
+dsh plugin --profile web add dsh-budget
+
+# 2. 重启并核实行
+dsh --profile web --dump-config | grep -A2 'id: budget'
+```
+
+然后在会话里输入 `/budget`，并在设置页查看预算页签。
+
+## 安装与卸载
+
+- **git 通道**（最新 `main`）：`dsh plugin --profile web add "github:PerryLink/dsh-budget#main"` —— `prepare` 脚本仅用生产依赖构建。
+- **npm 通道**（正式发布版）：`dsh plugin --profile web add dsh-budget`。
+- **tarball 通道**：在本仓库执行 `pnpm pack`，然后 `dsh plugin --profile web add ./dsh-budget-<version>.tgz`。
+- **卸载**：`dsh plugin --profile web remove dsh-budget`。
+
+> 如果 pnpm 对本包报 `ERR_PNPM_IGNORED_BUILDS`（esbuild 的平台二进制无害校验），在你的 `pnpm-workspace.yaml` 中加入 `allowBuilds: { esbuild: true }` —— `dsh` CLI 会打印确切片段。
+
+## 配置
+
+所有可调项都是 Schemastery `Config` 字段（可在 cordis.yml 中修改）。`cordis.patch.yml` 内联说明每个键。
+
+| 键 | 默认值 | 含义 |
+|---|---|---|
+| `prices` | `{}` | 每模型 USD/百万 token 价格，合并覆盖内置价目表 |
+| `defaultPrice` | `{input: 1.0, output: 3.0}` | 两表均无该模型时的回退价格 |
+| `budgets.session` / `daily` / `monthly` | `10` / `50` / `500` | 各作用域 USD 预算上限；缺省表示不限 |
+| `warnRatio` | `0.8` | 用量达到上限该比例时告警（0..1） |
+| `overLimit` | `alert` | 超限后策略：`alert` / `block` / `degrade` |
+| `degradation` | `{}` | 模型 id → 同厂商更便宜模型 id 的映射 |
+| `webhookUrl` | *(无)* | 可选阈值告警 webhook URL（POST JSON） |
+| `webhookTimeoutMs` | `5000` | webhook 请求超时 |
+| `alertsEnabled` | `true` | 阈值告警总开关 |
+| `alertCooldownMs` | `3600000` | 同一作用域两次告警的最小间隔（ms） |
+| `desktopNotifications` | `false` | 页签打开时的浏览器桌面通知 |
+| `refreshIntervalMs` | `5000` | 设置页签轮询间隔 |
+| `carbon.enabled` / `region` / `pue` / `energyKwhPerToken` | `true` / `global` / `1.58` / `0.000007` | 碳桥接（区域：global, us, eu, china, india, uk, france, iceland） |
+| `latency.enabled` / `windowSize` | `true` / `200` | 按模型延迟百分位与其窗口 |
+| `currency` | `{code: USD, rate: 1.0, decimals: 2}` | 展示货币（成本以 USD 计算，仅展示换算） |
+| `outputLanguage` | `en` | `/budget` 输出语言：`en` / `zh` |
+| `historyDays` | `30` | 面板快照保留的按天用量历史天数 |
+
+## 工具与界面
+
+| 界面 | 类型 | 说明 |
+|---|---|---|
+| `/budget` | 命令 | 各作用域概览（用量、比例、碳足迹、阻断状态） |
+| `/budget models` | 命令 | 按模型明细 + 延迟百分位 |
+| `/budget unblock <scope>` | 命令 | 解除某作用域阻断（`session` / `daily` / `monthly`） |
+| 设置 → 插件 → 预算 | 设置页签 | 用量条、模型明细、告警、上限编辑、解除阻断按钮 |
+| `budget/status`、`budget/setSettings`、`budget/unblock` | Typert Remote | 客户端通道（页签消费这些方法） |
+
+## 权限与数据
+
+- **权限**：`network:outbound`（仅可选告警 webhook）、`session:append`（审计事件）、`native-code:none`。
+- **数据**：展示内容全部来自会话事件流；主机侧唯一网络调用是配置的 webhook，URL 在加载时校验、入日志前剥离凭据。任何 prompt/载荷都不会离开主机。
+- **会话日志**：`budget/alert` 与 `budget/block` 是仅日志审计事件，只携带作用域名与 USD 金额（微任务延后以绕过会话 append 重入保护）。
+
+## 安全边界
+
+- **不伪造数据**：预算阻断在 `llm/stream` 瀑布上产出修正性错误 finish —— 插件绝不编造模型输出。
+- **不改写请求**：loop 构建的请求被冻结；`degrade` 因此在修正消息中点名目标模型，而非替换请求。
+- **失败大声**：非法价格、URL、比例、区域与边界在挂载时即失败。
+- **如实作用域**：面板的运行时编辑仅会话级生效；重载后恢复 cordis.yml 配置。
+
+## 已知限制
+
+- 聚合为进程本地：harness 重启后用量清零（日/月桶从当前会话日志视图重建）。
+- `block`/`degrade` 依赖 `llm/stream` 瀑布；无此 seam 的构建无法阻断请求（告警仍有效）。
+- 内置价目会漂移；用 `config.prices` 覆盖条目。
+
+## 开发
+
+```sh
+pnpm install        # node ^22.19 || >=24
+pnpm run typecheck  # tsc：src + tests，对照本地 harness checkout
+pnpm run typecheck:ci  # tsc：对照已发布的 0.1.0-rc.6 类型（无 paths）
+pnpm test           # vitest：45 个测试
+pnpm run build      # tsc 声明 + tsdown bundles（lib/）
+pnpm run verify:self-contained  # 依赖声明全部来自 registry
+pnpm run verify:artifacts       # 构建产物 ESM 面 + typert manifest + 客户端 bundle
+pnpm pack           # 发布用 tarball
+```
+
+## Topics
+
+`dsh`, `dsh-plugin`, `deepseek-harness`, `deepseek`, `cordis`, `budget`, `cost-tracking`, `carbon-footprint`, `latency-benchmark`, `token-usage`
+
+## Contributors
+
+- [@PerryLink](https://github.com/PerryLink) —— 创建者与维护者：聚合、预算治理、碳足迹与延迟移植、设置页签与五语文档。
+
+## License
+
+[Apache License 2.0](LICENSE) © 2026 dsh-budget contributors

package/SECURITY.md

@@ -0,0 +1,37 @@
+# Security policy
+
+## Reporting a vulnerability
+
+Please **do not** open a public issue for security vulnerabilities.
+
+Report privately through GitHub's private vulnerability reporting:
+
+**https://github.com/PerryLink/dsh-budget/security/advisories/new**
+
+That flow keeps the report confidential while we triage, and it is the channel we watch first.
+
+## Before you report
+
+- **Redact sensitive data** from any logs, session excerpts, or config files you attach: tokens, API keys, secrets, webhook URLs with credentials, Authorization headers, personal paths, and account identifiers.
+- Include, when possible: the plugin version, the harness (`dsh`) version, Node and OS versions, and the minimal steps to reproduce.
+
+## What to expect
+
+- **Acknowledgment**: within 5 business days.
+- **Triage**: within 10 business days we confirm the issue and assess severity, or ask for more details.
+- **Fix**: security fixes are prepared in a private fork, released as a patch version, and announced in the release notes.
+
+## Disclosure and credit
+
+- We follow coordinated disclosure: a public advisory (and CVE request where appropriate) is published once a fix ships.
+- Reporters are credited in the advisory unless they ask to remain anonymous. There is no bug bounty program at this time.
+
+## Scope
+
+This plugin meters and budgets the harness's model usage. Its own guarantees:
+
+- The only network call the plugin can make is the configured threshold-alert webhook; the URL is validated at load, sanitized (credentials dropped) before any log line, and requests are timeout-bounded and fire-and-forget.
+- Everything shown to the model or written to the session log is sanitized; the audit events carry amounts and scope names only — never prompts, payloads, or credentials.
+- Budget blocks manifest as a corrective error finish on the `llm/stream` waterfall; the plugin never fabricates model output and never rewrites loop-built requests.
+
+Vulnerabilities in the harness itself should be reported to the official harness maintainers instead.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,23 @@
+# Third-party notices
+
+The following upstream projects (all by the plugin author, all Apache-2.0) were
+ported into `src/estimate/` for this plugin. No upstream source files are
+bundled verbatim; the ports keep the upstream data and formulas and are
+annotated per module with the source file and commit:
+
+| Upstream project | License | Ported into |
+|---|---|---|
+| [LLM-Cost-Estimator-CN](https://github.com/PerryLink/LLM-Cost-Estimator-CN) (commit `aa6cc2f`) | Apache-2.0 | `src/estimate/models.ts` (CNY price table, verbatim), `src/estimate/cost.ts` (cost formulas) |
+| [Mode-Latency-Benchmark](https://github.com/PerryLink/Mode-Latency-Benchmark) (commit `8123838`) | Apache-2.0 | `src/estimate/latency-stats.ts` (benchmark vocabulary + percentile statistics) |
+| [AI-Carbon-Footprint-Calculator](https://github.com/PerryLink/AI-Carbon-Footprint-Calculator) (commit `d8d52b5`) | Apache-2.0 | `src/estimate/carbon.ts` (GPU/region/PUE data, formulas, equivalence comparisons) |
+
+The read-only reference checkouts live under `upstream/` (gitignored, never
+shipped). The operational USD price table in `src/estimate/prices.ts` is
+maintained separately; entries converted from the upstream CNY table carry
+`source: 'upstream-cny'` with the fixed conversion rate captured at porting
+time.
+
+At runtime the plugin depends only on the official `@deepseek-ai/*` packages
+listed as peerDependencies, plus the build-time tools (`typescript`,
+`tsdown`) and `zod` declared as regular dependencies for the git-channel
+`prepare` build.

package/cordis.patch.yml

@@ -0,0 +1,73 @@
+# dsh-budget: cost governance for DeepSeek Harness.
+#
+# Aggregated token/cost metering (per model, session, day), session/daily/monthly
+# budget caps with threshold alerts (webhook + desktop notification) and
+# alert / block / degrade over-limit policies, carbon footprint estimation,
+# per-model latency statistics, a Settings budget tab, and the /budget command.
+#
+# Every key below is a Schemastery-validated config field; an invalid value
+# fails loudly at load time. Empty caps mean "unlimited" for that scope.
+- insert:
+    - id: budget
+      name: dsh-budget
+      inject: [sessions]
+      config:
+        # Per-model USD prices per 1M tokens, merged OVER the built-in table.
+        # Keys are model ids ("deepseek-chat", "gpt-4o", ...); each entry
+        # supports input/output and optional cacheRead/cacheWrite prices.
+        prices: {}
+        # Fallback price for models absent from both tables.
+        defaultPrice: { input: 1.0, output: 3.0 }
+        # Budget caps in USD per scope; omit a scope for unlimited.
+        budgets:
+          session: 10
+          daily: 50
+          monthly: 500
+        # Alert once usage reaches this fraction of a cap (0..1).
+        warnRatio: 0.8
+        # Behavior after a cap is crossed:
+        #   alert   - notify only (webhook/notification/session event)
+        #   block   - fail new model requests until unblocked by the user
+        #   degrade - rewrite the model to the configured cheaper tier
+        overLimit: alert
+        # Degradation map: model id -> cheaper model id of the SAME provider.
+        # Example: { "gpt-4o": "gpt-4o-mini" }
+        degradation: {}
+        # Optional webhook URL for threshold alerts (POST JSON). Credentials in
+        # the URL are never logged; use an https endpoint you control.
+        webhookUrl: ''
+        # Webhook request timeout in milliseconds.
+        webhookTimeoutMs: 5000
+        # Master switch for threshold alerts; the Settings tab can override
+        # this at runtime until the plugin reloads.
+        alertsEnabled: true
+        # Minimum milliseconds between two alerts of the same scope.
+        alertCooldownMs: 3600000
+        # Browser desktop notifications for new alerts while the Settings
+        # budget tab is open (requires browser permission).
+        desktopNotifications: false
+        # Settings budget tab polling interval in milliseconds.
+        refreshIntervalMs: 5000
+        # Carbon footprint estimation (token-based bridge over the upstream
+        # GPU-hours model).
+        carbon:
+          enabled: true
+          # Electricity region key: global us eu china india uk france iceland.
+          region: global
+          # Power usage effectiveness (datacenter overhead multiplier).
+          pue: 1.58
+          # IT energy per token in kWh; default derives from an A100 (400 W TDP)
+          # serving ~25 tokens/s: 400 W / 3600 s / 25 tok/s = 4.4e-6 kWh, rounded.
+          energyKwhPerToken: 0.000007
+        # Per-model latency statistics over the llm/stream wrapper.
+        latency:
+          enabled: true
+          # Samples kept per model for percentile computation.
+          windowSize: 200
+        # Display currency (code, units per USD, decimals). Costs are computed
+        # in USD; this only converts for display.
+        currency: { code: USD, rate: 1.0, decimals: 2 }
+        # /budget command output language: en | zh.
+        outputLanguage: en
+        # Days of per-day usage history kept in the panel snapshot.
+        historyDays: 30