@goodandready/dsh-usage-guard 0.1.0 → 0.1.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 dsh-voice contributors
+Copyright (c) 2026 GooDAnDReaDY
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,133 +1,159 @@
-# dsh-usage-guard
+# 📦 @goodandready/dsh-usage-guard
 
-A one-purpose patch for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (dsh):
-**one malformed token-usage sample should not take a whole session history down with it.**
+<div align="center">
 
-## The failure
+<h3>Session Token-Usage Sanitizer, History Crash Guard & Arithmetic Protection for DeepSeek Harness</h3>
 
-Open a session and get this instead of your conversation:
+<p align="center">
+  <a href="https://www.npmjs.com/package/@goodandready/dsh-usage-guard"><img src="https://img.shields.io/npm/v/@goodandready/dsh-usage-guard.svg?style=for-the-badge&color=6366f1&labelColor=1e1b4b" alt="npm version"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-10b981.svg?style=for-the-badge&color=10b981&labelColor=064e3b" alt="license"></a>
+  <a href="https://github.com/topics/dsh-plugin"><img src="https://img.shields.io/badge/DSH-Plugin-8b5cf6.svg?style=for-the-badge&labelColor=2e1065" alt="DSH Plugin"></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node-20%2B-f59e0b.svg?style=for-the-badge&labelColor=451a03" alt="Node version"></a>
+</p>
 
-```
-history unavailable for session "session-…":
-  { "expected": "number", "code": "invalid_type", "received": "NaN",
-    "path": [ "uncachedInputTokens" ],
-    "message": "Invalid input: expected number, received NaN" }
-```
+<p align="center">
+  <a href="https://goodandready.app/"><img src="https://img.shields.io/badge/All_Author_Projects-goodandready.app-ff4500.svg?style=for-the-badge&logo=rocket&logoColor=white&labelColor=1a1a2e" alt="All Author Projects"></a>
+</p>
+
+<p align="center">
+  <a href="README.md"><b>🇬🇧 English</b></a> •
+  <a href="README.ru.md"><b>🇷🇺 Русский</b></a> •
+  <a href="README.zh.md"><b>🇨🇳 中文说明</b></a>
+</p>
 
-Not a wrong number in a counter — no history at all. And it stays that way,
-because the session summary is recomputed by replaying the log every time.
+</div>
 
-## The cause
+---
 
-The harness folds provider-reported usage into four buckets, and guards two of
-the four:
+## ⚡ The Root Problem: How Upstream Providers Poison Session History
 
-```js
-const bucketsFrom = (usage) => ({
-  uncachedInputTokens: usage.inputTokens,          // unguarded
-  outputTokens:        usage.outputTokens,         // unguarded
-  cacheReadTokens:     usage.cacheReadTokens ?? 0, // guarded
-  cacheWriteTokens:    usage.cacheWriteTokens ?? 0,// guarded
-})
+In **DeepSeek Harness**, session projections aggregate cumulative token usage across four core buckets:
+
+```javascript
+uncachedInputTokens: usage.inputTokens,        // No safety fallback in DSH core!
+outputTokens:        usage.outputTokens,       // No safety fallback in DSH core!
+cacheReadTokens:     usage.cacheReadTokens ?? 0,
+cacheWriteTokens:    usage.cacheWriteTokens ?? 0,
 ```
 
-Cache fields are optional because plenty of providers never send them. The two
-that are not guarded are just as optional in practice: providers disagree about
-the shape of a usage report, and some send only part of it. One sample without
-`inputTokens` turns the running total into `NaN`, the schema refuses it, and the
-whole history goes with it.
+While DSH core guards `cacheReadTokens` and `cacheWriteTokens` with `?? 0`, it takes `inputTokens` and `outputTokens` **as raw numbers without safety checks**.
 
-## What this plugin does
+When third-party providers, local inference servers, custom proxy gateways, or community routers return non-standard payloads, missing fields, or `NaN`, standard JavaScript arithmetic (`total += NaN`) instantly converts the session's cumulative token sum into `NaN`.
 
-It steps in front of the fold. A counter that is missing, `null`, `NaN` or not a
-number at all is repaired before the harness adds it up.
+Subsequently, DSH schema validation fatally rejects the entire session digest:
+```
+history unavailable for session "<session-id>": expected number, received NaN
+```
 
-Zero is the last resort, not the first move. Providers disagree about what to
-call the same number — `inputTokens`, `input_tokens`, `input`, `promptTokens` —
-and the harness knows one spelling, so the rest read as absent even though the
-figure is sitting right there. The plugin looks under the usual other names
-first and only falls back to zero when there is genuinely nothing to take.
+Because session history in DSH is computed dynamically by **replaying the event log**, a single malformed token packet permanently bricks the entire conversation history from being opened ever again.
+
+```mermaid
+graph LR
+    subgraph Malformed [Upstream Provider Stream]
+        API[LLM Output Stream] -->|Returns prompt_tokens / NaN / null| Event[Session Event Chunk]
+    end
+
+    subgraph Unprotected [Without dsh-usage-guard]
+        Event --> DSHMath[DSH Cumulative Arithmetic]
+        DSHMath -->|total += NaN| Poison[🚨 Cumulative Total becomes NaN]
+        Poison --> SchemaFail[Schema Validation Rejection]
+        SchemaFail --> DeadHistory[💥 Session History Permanently Unreadable]
+    end
+
+    subgraph Guarded [With dsh-usage-guard Active]
+        Event --> Patch[sessionProjections Interceptor]
+        Patch --> AliasCheck{Alias Borrowing Layer}
+        AliasCheck -->|Maps prompt_tokens -> inputTokens| Restored[Restored Number]
+        AliasCheck -->|If missing / NaN| ZeroFallback[Safe 0 Fallback]
+        Restored --> SafeMath[Clean Arithmetic Execution]
+        ZeroFallback --> SafeMath
+        SafeMath --> ValidHistory[✅ 100% Intact & Recovered Session History]
+    end
+
+    style Malformed fill:#1e1e2e,stroke:#89b4fa,stroke-width:2px,color:#cdd6f4
+    style Unprotected fill:#311b1b,stroke:#f38ba8,stroke-width:2px,color:#cdd6f4
+    style Guarded fill:#181825,stroke:#a6e3a1,stroke-width:2px,color:#cdd6f4
+```
 
-Because the fold is also where replay goes, **sessions that are already broken
-open again by themselves** — no session file is rewritten, nothing on disk is
-touched, and removing the plugin puts everything back exactly as it was.
+---
 
-Zero in place of a missing counter is a known lie. But the choice is not between
-an exact total and an approximate one — it is between an approximate total and a
-conversation you cannot read.
+## ✨ Key Features & Architectural Defense
 
-It also names the culprit. Each damaged sample is reported once, with the turn,
-the step and the raw object as it arrived:
+### 1. Instant Replay Recovery for Existing Corrupted Sessions
+The plugin does **not** alter or rewrite log files on disk. Instead, it hooks the projection fold at runtime. Because session replay passes through this exact interception point, **all previously broken or locked sessions are instantly restored and readable immediately upon installing the plugin**.
 
-```
-[dsh-usage-guard] usage sample out of shape — turn 1, step 1;
-    arrived as: {"outputTokens":14,"cacheReadTokens":1024}; inputTokens zeroed
-[dsh-usage-guard] usage sample out of shape — turn 3, step 1;
-    arrived as: {"input":22533,"output":20}; inputTokens taken from an alias; outputTokens taken from an alias
-```
+### 2. Comprehensive Alias Borrowing Lexicon (`borrowed`)
+Before substituting zero, `dsh-usage-guard` scans an extensive dictionary of industry-standard field aliases:
 
-That line is the point of the reporting half: providers that send incomplete
-usage are worth knowing about, and a bare `NaN` never told you which one it was.
+| Target DSH Field | Recognized Vendor Aliases |
+|---|---|
+| `inputTokens` | `input_tokens`, `input`, `promptTokens`, `prompt_tokens`, `promptTokenCount`, `prompt_eval_count` |
+| `outputTokens` | `output_tokens`, `output`, `completionTokens`, `completion_tokens`, `candidatesTokenCount`, `eval_count` |
+| `cacheReadTokens` | `cache_read_tokens`, `cachedTokens`, `cached_tokens`, `cache_read_input_tokens`, `cachedContentTokenCount`, `prompt_tokens_details.cached_tokens` |
+| `cacheWriteTokens` | `cache_write_tokens`, `cacheCreationTokens`, `cache_creation_input_tokens` |
 
-## Install
+### 3. Finite Non-Negative Soundness Validation (`sound`)
+Strictly validates `typeof value === 'number' && Number.isFinite(value) && value >= 0` to filter out `NaN`, `Infinity`, `null`, `undefined`, negative error codes (e.g. `-1`), and malformed strings before they reach arithmetic operations.
 
-```bash
-dsh plugin --profile web add @goodandready/dsh-usage-guard
-```
+### 4. Safe Zero Fallback (`repaired`)
+If a counter cannot be resolved from aliases, it is safely initialized to `0`. The choice is not between exact and approximate numbers, but between approximate token counts and an unreadable dead session.
 
-Restart the harness afterwards. There is no UI and nothing to configure to get
-the fix — it works from the moment it loads.
+### 5. In-Memory Registry Monkey-Patching (`lib/patch.js`)
+* **Pre-existing Projections**: Wraps all `.apply` methods currently registered in `sessionProjections.registrations` while preserving full `this` context.
+* **Late-Binding Projections**: Traps future projection registrations via `map.set` wrapping, guaranteeing 100% coverage regardless of plugin loading order.
+* **Universal Projection Protection**: Protects not only token counters, but also context pressure calculators and busy-state analyzers.
+* **Zero Performance Overhead**: Uses shallow event cloning only along the usage path; all other event data references remain untouched.
 
-## Settings
+### 6. Deduplicated Diagnostic Reporting (`told`)
+Logs informative diagnostic warnings naming the exact session, turn, step, raw payload, and recovery action (e.g. `inputTokens borrowed from alias` vs `inputTokens zeroed`). Incidents are deduplicated in memory so logs are not flooded during replays, and the cache is capped at 1,000 items to prevent memory leaks.
 
-In `$DSH_HOME/settings.yaml` under `dsh-usage-guard:`, or in the profile:
+---
 
-| Field | Default | Description |
-|---|---|---|
-| `repair` | `true` | Replace a missing or non-numeric counter with zero before the fold. Off means reporting only — the fold sees the sample as it came, and a broken one keeps the history unreadable. |
-| `report` | `true` | Log the turn, the step and the raw sample when a damaged one arrives. Reported once per turn, step and field set, not once per replay. |
+## 🚀 Changed in v0.1.1
 
-Turning `repair` off is for one situation: you want to see the failure happen
-rather than have it papered over.
+* **Negative Number Protection (`nonnegative`)**:
+  In v0.1.0, negative counters like `-1` (sometimes returned by proxy gateways during rate limits or faults) passed finite-number checks and crashed DSH schema validation (`z.number().int().nonnegative()`). In v0.1.1, `sound()` strictly requires `value >= 0`. Any negative number is treated as corrupted and safely zeroed out.
+* **Safe Coercion of Stringified Numbers**:
+  If an upstream provider delivers valid token counts formatted as strings (e.g. `inputTokens: "1540"`), v0.1.1 coerces them into true numbers rather than resetting them to zero.
+* **Expanded Ecosystem Aliases**:
+  - **Google Gemini API**: added `promptTokenCount`, `candidatesTokenCount`, and `cachedContentTokenCount`.
+  - **Ollama native API**: added `prompt_eval_count` and `eval_count`.
+  - **OpenAI prompt caching**: added nested resolution of `prompt_tokens_details.cached_tokens`.
+* **Preservation of `this` Context in Projections**:
+  In `lib/patch.js`, `wrapApply` now dispatches via `original.call(this, state, guard(event))`, ensuring complete compatibility with class-based projection handlers.
+* **Crash-Proof Diagnostic Logging**:
+  In `complaint()`, object serialization is now safely protected with `try...catch` against circular structures and `BigInt` values.
+* **Session-Aware Deduplication & Memory Bound**:
+  Warning deduplication now incorporates `sessionId` to avoid cross-session warning suppression. `told` cache size is bounded to 1,000 entries to prevent memory growth in long-running processes.
 
-## How it attaches
+---
 
-Session projections live in an ordinary registry service, keyed by name, and
-each entry holds the `apply` the harness actually calls. The plugin wraps those.
+## 📦 Quick Installation
 
-It wraps **all** of them, not one. Usage is read in three separate places —
-`tokenUsage` folds the four buckets, `contextPressure` computes its own sum for
-the prompt size, `contextBreakdown` its own for occupancy — and every one of
-them trips over the same missing counter. Keeping a list of keys in step with
-someone else's code is a standing debt; the guard is an identity for an event
-that carries no damaged usage, so a projection that never looks at usage pays
-one comparison and gets the very same event object it would have got anyway.
+```bash
+dsh plugin --profile web add @goodandready/dsh-usage-guard
+```
 
-Load order does not matter: whatever is already registered is wrapped
-immediately, and whatever registers later is caught as it lands in the registry.
+> [!IMPORTANT]
+> Restart DSH Web UI after installation (`systemctl --user restart dsh-web`) to activate protection and instantly revive any previously locked sessions.
 
-Nothing is patched by editing files, so a harness upgrade replaces the code this
-plugin wraps rather than fighting with it. If a later version guards those two
-fields itself, this plugin becomes a no-op that only reports — and can be
-removed.
+---
 
-## Structure
+## ⚙️ Configuration Reference (`settings.yaml`)
 
+```yaml
+dsh-usage-guard:
+  repair: true
+  report: true
 ```
-dsh-usage-guard/
-├── package.json         # dsh bundle metadata + peerDependencies
-├── cordis.patch.yml     # bundle layer: inserts the plugin row
-├── lib/index.js         # the plugin: settings, reporting, attachment
-├── lib/usage.js         # what counts as damaged and what it becomes — pure
-├── lib/patch.js         # how the guard gets in front of the fold — pure
-├── test/                # unit tests, no harness required
-├── README.md
-└── LICENSE              # MIT
-```
 
-Host half only — no browser code. No npm runtime dependencies, no build step,
-plain ESM.
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `repair` | `boolean` | `true` | Replace missing or non-numeric token counters with zero before arithmetic accumulation |
+| `report` | `boolean` | `true` | Log diagnostic warning lines naming turn, step, and raw sample when damaged metrics arrive |
+
+---
 
-## License
+## 📄 License
 
-MIT
+MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)

package/README.ru.md

@@ -0,0 +1,156 @@
+# 📦 @goodandready/dsh-usage-guard
+
+<div align="center">
+
+<h3>Санитайзер расхода токенов, защита от сбоев истории и сохранение сессий для DeepSeek Harness</h3>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@goodandready/dsh-usage-guard"><img src="https://img.shields.io/npm/v/@goodandready/dsh-usage-guard.svg?style=for-the-badge&color=6366f1&labelColor=1e1b4b" alt="npm version"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-10b981.svg?style=for-the-badge&color=10b981&labelColor=064e3b" alt="license"></a>
+  <a href="https://github.com/topics/dsh-plugin"><img src="https://img.shields.io/badge/DSH-Plugin-8b5cf6.svg?style=for-the-badge&labelColor=2e1065" alt="DSH Plugin"></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node-20%2B-f59e0b.svg?style=for-the-badge&labelColor=451a03" alt="Node version"></a>
+</p>
+
+<p align="center">
+  <a href="https://goodandready.app/"><img src="https://img.shields.io/badge/Все_проекты_автора-goodandready.app-ff4500.svg?style=for-the-badge&logo=rocket&logoColor=white&labelColor=1a1a2e" alt="Все проекты автора"></a>
+</p>
+
+<p align="center">
+  <a href="README.md"><b>🇬🇧 English</b></a> •
+  <a href="README.ru.md"><b>🇷🇺 Русский</b></a> •
+  <a href="README.zh.md"><b>🇨🇳 中文说明</b></a>
+</p>
+
+</div>
+
+---
+
+## ⚡ В чём суть проблемы: как провайдеры ломают историю сессий
+
+В ядре **DeepSeek Harness** подсчёт суммарного расхода токенов складывается из четырёх счётчиков:
+
+```javascript
+uncachedInputTokens: usage.inputTokens,        // Без подстраховки в ядре DSH!
+outputTokens:        usage.outputTokens,       // Без подстраховки в ядре DSH!
+cacheReadTokens:     usage.cacheReadTokens ?? 0,
+cacheWriteTokens:    usage.cacheWriteTokens ?? 0,
+```
+
+Поля кэша ядро подстраховывает через `?? 0`, а первые два берёт **как есть, без проверки на число**.
+
+Когда сторонний провайдер, локальный движок инференса, шлюз или роутер присылает нестандартные названия полей, пустые значения или `NaN`, стандартное сложение (`total += usage.inputTokens`) превращает сумму расхода сессии в `NaN`.
+
+После этого валидация схемы в ядре отвергает выжимку сессии:
+```
+history unavailable for session "<session-id>": expected number, received NaN
+```
+
+Поскольку история сессий в DSH рассчитывается на лету **путём повторного проигрывания журнала событий**, одна-единственная битая порция токенов навсегда блокирует открытие диалога в веб-интерфейсе.
+
+```mermaid
+graph LR
+    subgraph Malformed [Поток данных провайдера]
+        API[Ответ модели] -->|Присылает prompt_tokens / NaN / null| Event[Событие сессии]
+    end
+
+    subgraph Unprotected [Без dsh-usage-guard]
+        Event --> DSHMath[Сложение расхода в ядре DSH]
+        DSHMath -->|total += NaN| Poison[🚨 Сумма расхода становится NaN]
+        Poison --> SchemaFail[Отказ проверки схемы]
+        SchemaFail --> DeadHistory[💥 История сессии заблокирована навсегда]
+    end
+
+    subgraph Guarded [С активным dsh-usage-guard]
+        Event --> Patch[Перехватчик sessionProjections]
+        Patch --> AliasCheck{Поиск по синонимам}
+        AliasCheck -->|prompt_tokens -> inputTokens| Restored[Восстановленное число]
+        AliasCheck -->|Если число отсутствует| ZeroFallback[Безопасный 0]
+        Restored --> SafeMath[Корректное сложение]
+        ZeroFallback --> SafeMath
+        SafeMath --> ValidHistory[✅ 100% Восстановленная и сохранная история]
+    end
+
+    style Malformed fill:#1e1e2e,stroke:#89b4fa,stroke-width:2px,color:#cdd6f4
+    style Unprotected fill:#311b1b,stroke:#f38ba8,stroke-width:2px,color:#cdd6f4
+    style Guarded fill:#181825,stroke:#a6e3a1,stroke-width:2px,color:#cdd6f4
+```
+
+---
+
+## ✨ Ключевые возможности и механизмы защиты
+
+### 1. Мгновенное восстановление ранее сломанных сессий
+Плагин **не модифицирует** файлы журналов на диске. Он встаёт перед операцией сложения в памяти. Так как проигрывание сессий идёт через эту же точку, **все ранее повреждённые сессии начинают открываться снова сразу после установки плагина**.
+
+### 2. Полный словарь синонимов полей (`borrowed`)
+Прежде чем подставлять ноль, плагин ищет значения в общепринятых полях других API:
+
+| Целевое поле DSH | Распознаваемые синонимы |
+|---|---|
+| `inputTokens` | `input_tokens`, `input`, `promptTokens`, `prompt_tokens`, `promptTokenCount`, `prompt_eval_count` |
+| `outputTokens` | `output_tokens`, `output`, `completionTokens`, `completion_tokens`, `candidatesTokenCount`, `eval_count` |
+| `cacheReadTokens` | `cache_read_tokens`, `cachedTokens`, `cached_tokens`, `cache_read_input_tokens`, `cachedContentTokenCount`, `prompt_tokens_details.cached_tokens` |
+| `cacheWriteTokens` | `cache_write_tokens`, `cacheCreationTokens`, `cache_creation_input_tokens` |
+
+### 3. Проверка на конечное неотрицательное число (`sound`)
+Проверка `typeof value === 'number' && Number.isFinite(value) && value >= 0` гарантирует отсечение `NaN`, `Infinity`, `null`, `undefined`, отрицательных чисел (напр. `-1` при ошибках прокси) и строк.
+
+### 4. Безопасная подстановка нуля (`repaired`)
+Если число найти не удалось, подставляется `0`. Выбор делается в пользу приблизительного счёта вместо полностью заблокированной истории.
+
+### 5. Безопасный перехват в памяти (`lib/patch.js`)
+* **Существующие проекции**: оборачивает все методы `.apply` в `sessionProjections.registrations` с полным сохранением контекста `this`.
+* **Поздние проекции**: перехватывает будущие регистрации через хук `map.set`.
+* **Комплексная защита**: защищает не только токены, но и формулы давления на контекст и разбор занятости.
+* **Нулевой оверхед**: поверхностное клонирование применяется только к объекту расхода.
+
+### 6. Дедуплицированное журналирование (`told`)
+Выводит предупреждение с идентификатором сессии, номером хода, шагом и способом починки (взят по синониму или обнулён). Одинаковые инциденты не спамят в лог при повторных проигрываниях, а размер кэша ограничен 1000 записей для предотвращения утечек памяти.
+
+---
+
+## 🚀 Изменения в версии v0.1.1 (Changed in v0.1.1)
+
+* **Защита от отрицательных чисел (`nonnegative`)**:
+  В v0.1.0 значение `-1` (возвращаемое некоторыми шлюзами при ошибках) проходило проверку конечности числа и ломало схему DSH (`z.number().int().nonnegative()`). Начиная с v0.1.1 функция `sound()` строго требует `value >= 0`. Отрицательные значения теперь признаются повреждёнными и безопасно обнуляются.
+* **Безопасная коэрция числовых строк (Stringified Numbers)**:
+  Если провайдер возвращает валидное количество токенов строкой (например, `inputTokens: "1540"`), плагин в v0.1.1 больше не сбрасывает его в ноль, а безопасно приводит к настоящему числу (`1540`).
+* **Расширенная совместимость с экосистемами моделей**:
+  - **Google Gemini API**: добавлены `promptTokenCount`, `candidatesTokenCount`, `cachedContentTokenCount`.
+  - **Ollama native API**: добавлены `prompt_eval_count`, `eval_count`.
+  - **OpenAI prompt caching**: добавлена поддержка вложенного объекта `prompt_tokens_details.cached_tokens`.
+* **Сохранение контекста вызова `this` в проекциях**:
+  В `lib/patch.js` метод `wrapApply` переписан с сохранением `this` (`original.call(this, state, guard(event))`), обеспечивая полную совместимость с объектно-ориентированными проекциями.
+* **Отказоустойчивое логирование без риска краша**:
+  В функции `complaint()` сериализация данных экранирована `try...catch`, предотвращая падение рантайма при наличии циклических структур или `BigInt`.
+* **Изолированная межсессионная дедупликация**:
+  Ключ дедупликации предупреждений дополнен контекстом сессии (`sessionId`), что предотвращает ложное подавление сообщений об ошибках в последующих диалогах. Множество `told` ограничено 1000 элементами для защиты от утечек памяти.
+
+---
+
+## 📦 Быстрая установка
+
+```bash
+dsh plugin --profile web add @goodandready/dsh-usage-guard
+```
+
+---
+
+## ⚙️ Параметры конфигурации (`settings.yaml`)
+
+```yaml
+dsh-usage-guard:
+  repair: true
+  report: true
+```
+
+| Параметр | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `repair` | `boolean` | `true` | Заменять пропущенные и нечисловые значения на ноль до сложения |
+| `report` | `boolean` | `true` | Логировать информацию о поврежденных порциях в консоль |
+
+---
+
+## 📄 Лицензия
+
+MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)

package/README.zh.md

@@ -0,0 +1,114 @@
+# 📦 @goodandready/dsh-usage-guard
+
+<div align="center">
+
+<h3>DeepSeek Harness 会话用量数据清洗、历史记录防崩与 Token 算术保护插件</h3>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@goodandready/dsh-usage-guard"><img src="https://img.shields.io/npm/v/@goodandready/dsh-usage-guard.svg?style=for-the-badge&color=6366f1&labelColor=1e1b4b" alt="npm version"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-10b981.svg?style=for-the-badge&color=10b981&labelColor=064e3b" alt="license"></a>
+  <a href="https://github.com/topics/dsh-plugin"><img src="https://img.shields.io/badge/DSH-Plugin-8b5cf6.svg?style=for-the-badge&labelColor=2e1065" alt="DSH Plugin"></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node-20%2B-f59e0b.svg?style=for-the-badge&labelColor=451a03" alt="Node version"></a>
+</p>
+
+<p align="center">
+  <a href="https://goodandready.app/"><img src="https://img.shields.io/badge/作者全部项目-goodandready.app-ff4500.svg?style=for-the-badge&logo=rocket&logoColor=white&labelColor=1a1a2e" alt="作者全部项目"></a>
+</p>
+
+<p align="center">
+  <a href="README.md"><b>🇬🇧 English</b></a> •
+  <a href="README.ru.md"><b>🇷🇺 Русский</b></a> •
+  <a href="README.zh.md"><b>🇨🇳 中文说明</b></a>
+</p>
+
+</div>
+
+---
+
+## ⚡ 核心痛点深度剖析：上游格式异常如何导致会话历史永久损坏
+
+在 **DeepSeek Harness** 核心架构中，会话投影累加 4 类 Token 计数：
+
+```javascript
+uncachedInputTokens: usage.inputTokens,        // 核心源码无默认兜底保护！
+outputTokens:        usage.outputTokens,       // 核心源码无默认兜底保护！
+cacheReadTokens:     usage.cacheReadTokens ?? 0,
+cacheWriteTokens:    usage.cacheWriteTokens ?? 0,
+```
+
+当第三方服务商、本地引擎或网关返回非标字段、空值或 `NaN` 时，累加逻辑 (`total += usage.inputTokens`) 会将累计用量污染为 `NaN`，导致架构模式校验致命拒绝：
+```
+history unavailable for session "<session-id>": expected number, received NaN
+```
+
+由于 DSH 历史记录是通过重放事件流动态计算生成的，**单个损坏的数据块会导致整个历史对话永久白屏且无法重新打开**。
+
+```mermaid
+graph LR
+    subgraph Malformed [上游返回异常格式]
+        API[模型输出流] -->|返回 prompt_tokens / NaN / null| Event[会话事件]
+    end
+
+    subgraph Unprotected [未开启防护]
+        Event --> DSHMath[DSH 原生累加运算]
+        DSHMath -->|total += NaN| Poison[🚨 累计用量全变为 NaN]
+        Poison --> SchemaFail[模式校验致命失败]
+        SchemaFail --> DeadHistory[💥 历史记录永久锁定损坏]
+    end
+
+    subgraph Guarded [开启 dsh-usage-guard]
+        Event --> Patch[sessionProjections 拦截器]
+        Patch --> AliasCheck{同义名字典检索}
+        AliasCheck -->|prompt_tokens -> inputTokens| Restored[恢复有效数字]
+        AliasCheck -->|缺失字段| ZeroFallback[安全 0 值兜底]
+        Restored --> SafeMath[安全累加计算]
+        ZeroFallback --> SafeMath
+        SafeMath --> ValidHistory[✅ 100% 修复并完好读取会话历史]
+    end
+
+    style Malformed fill:#1e1e2e,stroke:#89b4fa,stroke-width:2px,color:#cdd6f4
+    style Unprotected fill:#311b1b,stroke:#f38ba8,stroke-width:2px,color:#cdd6f4
+    style Guarded fill:#181825,stroke:#a6e3a1,stroke-width:2px,color:#cdd6f4
+```
+
+---
+
+## ✨ 核心亮点与保护机制
+
+1. **已损坏历史记录免修文件即刻复活**：不修改磁盘日志，在内存重放链路拦截修复；
+2. **主流别名字典智能提取 (`borrowed`)**：覆盖 `prompt_tokens`、`completion_tokens`、`cached_tokens`、`promptTokenCount`、`prompt_eval_count` 等；
+3. **非负有限数字安全性校验 (`sound`)**：剔除 `NaN`、`Infinity`、负数错误码（如 `-1`）与非法格式；
+4. **安全 0 值兜底 (`repaired`)**：彻底阻断算术污染；
+5. **内存投影注册表动态切入 (`lib/patch.js`)**：无缝覆盖前置与后置投影，完整保留 `this` 上下文；
+6. **防刷屏告警与内存保护 (`told`)**：集成会话识别与容量上限（1,000 项），杜绝内存泄漏与误抑制。
+
+---
+
+## 🚀 v0.1.1 版本更新说明 (Changed in v0.1.1)
+
+* **负数穿透防护 (`nonnegative`)**：
+  在 v0.1.0 中，部分代理网关返回的 `-1` 能通过有限数检测，进而导致 DSH 模式校验报错。v0.1.1 严格要求 `value >= 0`，负数将被识别为损坏并安全置 0。
+* **数字字符串安全转换 (Stringified Numbers)**：
+  部分上游返回的字符串数字（如 `inputTokens: "1540"`）在 v0.1.1 中将安全转换为真正数值，不再误重置为 0。
+* **主流模型生态别名扩充**：
+  - **Google Gemini API**：新增 `promptTokenCount`、`candidatesTokenCount`、`cachedContentTokenCount`。
+  - **Ollama native API**：新增 `prompt_eval_count`、`eval_count`。
+  - **OpenAI 缓存详情**：新增嵌套对象 `prompt_tokens_details.cached_tokens` 支持。
+* **投影函数 `this` 上下文维持**：
+  修复 `wrapApply` 调用时缺失 `this` 的问题，确保与对象方法式投影兼容。
+* **日志防崩防护与跨会话隔离**：
+  日志格式化引入 `try...catch` 兜底，防止循环引用导致服务崩溃；告警去重引入会话维度标记，杜绝跨会话误抑制。
+
+---
+
+## 📦 安装指南
+
+```bash
+dsh plugin --profile web add @goodandready/dsh-usage-guard
+```
+
+---
+
+## 📄 开源协议
+
+MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)

package/lib/index.js

@@ -56,10 +56,12 @@ export function apply(ctx, config) {
     sctx.effect(() => scope.watch((next) => { live = next ?? live }))
   })
 
-  // О каждом сочетании хода, шага и набора полей жалуемся один раз: выжимка
-  // считается проигрыванием журнала заново, и без этого одна и та же порция
-  // въезжала бы в журнал при каждом открытии истории.
+  // О каждом сочетании сессии, хода, шага и набора полей жалуемся один раз:
+  // выжимка считается проигрыванием журнала заново, и без этого одна и та же
+  // порция въезжала бы в журнал при каждом открытии истории.
+  // Ограничиваем размер (до 1000 записей), чтобы исключить утечку памяти.
   const told = new Set()
+  const MAX_TOLD = 1000
 
   const guard = (event) => {
     const found = usageOf(event)
@@ -68,11 +70,19 @@ export function apply(ctx, config) {
     if (bad.length === 0) return event
 
     if (live.report !== false) {
-      const seen = `${String(found.turn)}/${String(found.step)}/${bad.join(',')}`
+      const sessionTag = event?.sessionId ?? event?.data?.sessionId ?? event?.data?.turn ?? 'global'
+      const seen = `${String(sessionTag)}/${String(found.turn)}/${String(found.step)}/${bad.join(',')}`
       if (!told.has(seen)) {
+        if (told.size >= MAX_TOLD) {
+          told.clear()
+        }
         told.add(seen)
-        // eslint-disable-next-line no-console
-        console.warn(`[dsh-usage-guard] ${complaint(found, bad)}`)
+        try {
+          // eslint-disable-next-line no-console
+          console.warn(`[dsh-usage-guard] ${complaint(found, bad)}`)
+        } catch {
+          // Ошибка вывода не должна ломать обработку событий
+        }
       }
     }
 
@@ -85,4 +95,4 @@ export function apply(ctx, config) {
       'dsh-usage-guard: обезвреживание порций расхода',
     )
   })
-}
+}

package/lib/patch.js

@@ -22,14 +22,16 @@
 export const PATCHED = Symbol.for('dsh-usage-guard.patched')
 
 /**
- * Обернуть складывание одной записи реестра.
+ * Обернуть складывание одной записи реестра с сохранением контекста this.
  *
  * @returns функция возврата к исходному состоянию.
  */
 export function wrapApply(def, guard) {
   if (!def || typeof def.apply !== 'function' || def.apply[PATCHED]) return () => {}
   const original = def.apply
-  const patched = (state, event) => original(state, guard(event))
+  const patched = function (state, event) {
+    return original.call(this, state, guard(event))
+  }
   patched[PATCHED] = true
   def.apply = patched
   return () => {
@@ -73,4 +75,4 @@ export function patchRegistry(registry, guard) {
     for (const step of undo.reverse()) step()
     undo.length = 0
   }
-}
+}

package/lib/usage.js

@@ -20,15 +20,58 @@ export const FIELDS = ['inputTokens', 'outputTokens', 'cacheReadTokens', 'cacheW
  * не первый ход.
  */
 const ALIASES = {
-  inputTokens: ['input_tokens', 'input', 'promptTokens', 'prompt_tokens'],
-  outputTokens: ['output_tokens', 'output', 'completionTokens', 'completion_tokens'],
-  cacheReadTokens: ['cache_read_tokens', 'cachedTokens', 'cached_tokens', 'cache_read_input_tokens'],
-  cacheWriteTokens: ['cache_write_tokens', 'cacheCreationTokens', 'cache_creation_input_tokens'],
+  inputTokens: [
+    'input_tokens',
+    'input',
+    'promptTokens',
+    'prompt_tokens',
+    'promptTokenCount',
+    'prompt_eval_count',
+  ],
+  outputTokens: [
+    'output_tokens',
+    'output',
+    'completionTokens',
+    'completion_tokens',
+    'candidatesTokenCount',
+    'eval_count',
+  ],
+  cacheReadTokens: [
+    'cache_read_tokens',
+    'cachedTokens',
+    'cached_tokens',
+    'cache_read_input_tokens',
+    'cachedContentTokenCount',
+  ],
+  cacheWriteTokens: [
+    'cache_write_tokens',
+    'cacheCreationTokens',
+    'cache_creation_input_tokens',
+  ],
 }
 
-/** Годное значение счётчика: конечное число, а не `undefined`, `null` или `NaN`. */
+/**
+ * Годное значение счётчика: конечное неотрицательное число.
+ * Значения меньше нуля (-1 и т.д.) или нечисловые не признаются годными,
+ * так как схема DSH требует nonnegative integer.
+ */
 function sound(value) {
-  return typeof value === 'number' && Number.isFinite(value)
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0
+}
+
+/**
+ * Приведение значения к корректному неотрицательному числу.
+ * Поддерживает числа и строковые представления целых неотрицательных чисел (напр. "1540").
+ */
+function coerceNumber(value) {
+  if (typeof value === 'number') {
+    return Number.isFinite(value) && value >= 0 ? value : undefined
+  }
+  if (typeof value === 'string' && /^\d+$/.test(value.trim())) {
+    const num = Number(value.trim())
+    return Number.isFinite(num) && num >= 0 ? num : undefined
+  }
+  return undefined
 }
 
 /**
@@ -57,8 +100,8 @@ export function usageOf(event) {
  *
  * Отсутствие кэш-полей нарушением не считается: их не присылает добрая половина
  * провайдеров, и харнесс сам подставляет там ноль. Ругаемся только на то, что
- * действительно ломает сложение, — на пропущенные или нечисловые значения тех
- * полей, которые харнесс берёт без оглядки.
+ * действительно ломает сложение, — на пропущенные, нечисловые или отрицательные
+ * значения тех полей, которые харнесс берёт без оглядки, либо на невалидные кэш-поля.
  */
 export function damage(usage) {
   if (!usage || typeof usage !== 'object') return FIELDS.slice(0, 2)
@@ -72,11 +115,30 @@ export function damage(usage) {
   return bad
 }
 
-/** Число под одним из привычных чужих имён — или `undefined`, если его там нет. */
+/**
+ * Число под одним из привычных чужих имён, вложенных структур или строковых чисел.
+ * Возвращает валидное неотрицательное число или `undefined`, если его там нет.
+ */
 export function borrowed(usage, field) {
+  if (!usage || typeof usage !== 'object') return undefined
+
+  // 1. Поиск по известным синонимам
   for (const alias of ALIASES[field] ?? []) {
-    if (sound(usage[alias])) return usage[alias]
+    const num = coerceNumber(usage[alias])
+    if (num !== undefined) return num
+  }
+
+  // 2. Поиск во вложенных деталях кэша (OpenAI-style: prompt_tokens_details.cached_tokens)
+  if (field === 'cacheReadTokens' && usage.prompt_tokens_details && typeof usage.prompt_tokens_details === 'object') {
+    const details = usage.prompt_tokens_details
+    const num = coerceNumber(details.cached_tokens ?? details.cachedTokens)
+    if (num !== undefined) return num
   }
+
+  // 3. Само поле, если оно было передано валидной строкой (напр. "123")
+  const selfNum = coerceNumber(usage[field])
+  if (selfNum !== undefined) return selfNum
+
   return undefined
 }
 
@@ -120,11 +182,24 @@ export function healed(event, bad) {
   return { ...event, data: { ...event.data, usage } }
 }
 
+/** Безопасная сериализация для журнала: предотвращает сбои на циклических объектах и BigInt. */
+function safeStringify(value) {
+  try {
+    return JSON.stringify(value)
+  } catch {
+    try {
+      return String(value)
+    } catch {
+      return '[не сериализуется]'
+    }
+  }
+}
+
 /** Короткая строка для журнала: по ней видно, кого звать к ответу. */
 export function complaint(found, bad) {
   const where = `ход ${String(found.turn)}, шаг ${String(found.step)}`
   const taken = bad
     .map((field) => (found.usage && borrowed(found.usage, field) !== undefined ? `${field} взят по синониму` : `${field} обнулён`))
     .join('; ')
-  return `порция расхода не по форме — ${where}; пришло: ${JSON.stringify(found.usage)}; ${taken}`
-}
+  return `порция расхода не по форме — ${where}; пришло: ${safeStringify(found.usage)}; ${taken}`
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-usage-guard",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Keeps a malformed token-usage sample from taking a whole session history down with it: a missing or non-numeric counter becomes zero before the harness adds it up, so the fold never yields NaN and already-broken sessions open again.",
   "keywords": [
     "deepseek-harness",
@@ -29,6 +29,8 @@
     "lib/",
     "cordis.patch.yml",
     "README.md",
+    "README.ru.md",
+    "README.zh.md",
     "LICENSE"
   ],
   "license": "MIT",
@@ -47,4 +49,4 @@
   "scripts": {
     "test": "node --test test/*.test.mjs"
   }
-}
+}