@goodandready/dsh-usage-guard 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-voice contributors
+
+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,133 @@
+# 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.**
+
+## The failure
+
+Open a session and get this instead of your conversation:
+
+```
+history unavailable for session "session-…":
+  { "expected": "number", "code": "invalid_type", "received": "NaN",
+    "path": [ "uncachedInputTokens" ],
+    "message": "Invalid input: expected number, received NaN" }
+```
+
+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.
+
+## The cause
+
+The harness folds provider-reported usage into four buckets, and guards two of
+the four:
+
+```js
+const bucketsFrom = (usage) => ({
+  uncachedInputTokens: usage.inputTokens,          // unguarded
+  outputTokens:        usage.outputTokens,         // unguarded
+  cacheReadTokens:     usage.cacheReadTokens ?? 0, // guarded
+  cacheWriteTokens:    usage.cacheWriteTokens ?? 0,// guarded
+})
+```
+
+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.
+
+## What this plugin does
+
+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.
+
+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 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.
+
+It also names the culprit. Each damaged sample is reported once, with the turn,
+the step and the raw object as it arrived:
+
+```
+[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
+```
+
+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.
+
+## Install
+
+```bash
+dsh plugin --profile web add @goodandready/dsh-usage-guard
+```
+
+Restart the harness afterwards. There is no UI and nothing to configure to get
+the fix — it works from the moment it loads.
+
+## Settings
+
+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. |
+
+Turning `repair` off is for one situation: you want to see the failure happen
+rather than have it papered over.
+
+## 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.
+
+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.
+
+Load order does not matter: whatever is already registered is wrapped
+immediately, and whatever registers later is caught as it lands in the registry.
+
+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
+
+```
+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.
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,7 @@
+# dsh-usage-guard bundle layer: applied automatically when the package is
+# installed as a profile bundle (package.json declares dsh.bundle.patch).
+# Override any field in the profile's own cordis.patch.yml or in
+# $DSH_HOME/settings.yaml under `dsh-usage-guard:`.
+- insert:
+    - id: dsh-usage-guard
+      name: '@goodandready/dsh-usage-guard'

package/lib/index.js

@@ -0,0 +1,88 @@
+// dsh-usage-guard — заплатка на счёт токенов.
+//
+// Харнесс складывает расход в четыре ведра, и два из них берёт без оглядки:
+//
+//     uncachedInputTokens: usage.inputTokens,        // без подстраховки
+//     outputTokens:        usage.outputTokens,       // без подстраховки
+//     cacheReadTokens:     usage.cacheReadTokens ?? 0,
+//     cacheWriteTokens:    usage.cacheWriteTokens ?? 0,
+//
+// Стоит провайдеру прислать порцию без первых двух, и сложение даёт NaN.
+// Дальше проверка схемы отвергает всю выжимку сессии, а наружу это выходит
+// так:
+//
+//     history unavailable for session "...": expected number, received NaN
+//
+// Не «счётчик соврал», а «история не открывается вовсе» — и остаётся такой
+// навсегда, потому что выжимка считается проигрыванием журнала заново.
+//
+// Отсюда и лечение. Плагин не переписывает журналы на диске: он встаёт перед
+// сложением и подставляет ноль вместо пропажи. Проигрывание идёт через ту же
+// точку, поэтому уже испорченные сессии открываются снова — сами, без починки
+// файлов.
+//
+// Ноль вместо пропущенного счётчика — заведомо неправда. Но выбор не между
+// точным счётом и приблизительным, а между приблизительным и нечитаемой
+// историей.
+
+import z from '@deepseek-ai/schemastery'
+
+import { patchRegistry } from './patch.js'
+import { complaint, damage, healed, usageOf } from './usage.js'
+
+export const name = 'dsh-usage-guard'
+export const inject = ['sessionProjections']
+
+export const Config = z.object({
+  repair: z
+    .boolean()
+    .default(true)
+    .description('Replace a missing or non-numeric token counter with zero before the harness adds it up. '
+      + 'Off means reporting only: the counters reach the fold as they came, and a broken sample keeps the '
+      + 'session history unreadable.'),
+  report: z
+    .boolean()
+    .default(true)
+    .description('Log a line naming the turn, the step and the raw sample whenever a damaged one arrives. '
+      + 'Each turn, step and field set is reported once, not once per replay.'),
+})
+
+export function apply(ctx, config) {
+  let live = Config(structuredClone(config ?? {})) ?? config
+
+  ctx.inject(['settings'], (sctx) => {
+    const scope = sctx.settings.register(name, Config, { base: config })
+    live = scope.get() ?? live
+    sctx.effect(() => scope.watch((next) => { live = next ?? live }))
+  })
+
+  // О каждом сочетании хода, шага и набора полей жалуемся один раз: выжимка
+  // считается проигрыванием журнала заново, и без этого одна и та же порция
+  // въезжала бы в журнал при каждом открытии истории.
+  const told = new Set()
+
+  const guard = (event) => {
+    const found = usageOf(event)
+    if (!found) return event
+    const bad = damage(found.usage)
+    if (bad.length === 0) return event
+
+    if (live.report !== false) {
+      const seen = `${String(found.turn)}/${String(found.step)}/${bad.join(',')}`
+      if (!told.has(seen)) {
+        told.add(seen)
+        // eslint-disable-next-line no-console
+        console.warn(`[dsh-usage-guard] ${complaint(found, bad)}`)
+      }
+    }
+
+    return live.repair === false ? event : healed(event, bad)
+  }
+
+  ctx.inject(['sessionProjections'], (pctx) => {
+    pctx.effect(
+      () => patchRegistry(pctx.sessionProjections, guard),
+      'dsh-usage-guard: обезвреживание порций расхода',
+    )
+  })
+}

package/lib/patch.js

@@ -0,0 +1,76 @@
+// Как заплатка встаёт перед сложением.
+//
+// Реестр проекций сессии — служба с открытой картой записей. Каждая запись
+// держит обезличенную копию того, что зарегистрировал владелец, и зовёт `apply`
+// именно у копии. Значит, подменять надо её, а не то, что владелец отдал при
+// регистрации.
+//
+// Порядок загрузки не гарантирован, и на деле проекция ядра заводится позже
+// нас. Подменять при этом метод `register` у службы бесполезно: до неё
+// добираются через посредника, и замена, поставленная на посредника, до
+// настоящего вызова не доезжает. Поэтому цепляемся за саму карту записей —
+// обычный Map, один и тот же для всех, кто до него дотянулся.
+//
+// Оборачиваются все проекции, а не одна «нужная». Порцию расхода читает не
+// только счёт токенов: давление на контекст считает её своей формулой, разбор
+// занятости — своей, и каждая спотыкается об один и тот же пропущенный
+// счётчик. Список ключей пришлось бы держать в согласии с чужим кодом, а
+// обезвреживатель для здорового события возвращает ровно то же событие — тем,
+// кто расхода не касается, он обходится в одно сравнение.
+
+/** Метка на подменённой функции: второй раз оборачивать нечего. */
+export const PATCHED = Symbol.for('dsh-usage-guard.patched')
+
+/**
+ * Обернуть складывание одной записи реестра.
+ *
+ * @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))
+  patched[PATCHED] = true
+  def.apply = patched
+  return () => {
+    if (def.apply === patched) def.apply = original
+  }
+}
+
+/**
+ * Поставить заплатку на реестр проекций.
+ *
+ * @param registry - служба `sessionProjections`.
+ * @param guard - обезвреживатель события; получает событие, возвращает его же
+ *                или исправленное.
+ * @returns функция, снимающая всё поставленное, в обратном порядке.
+ */
+export function patchRegistry(registry, guard) {
+  const undo = []
+  const map = registry && typeof registry === 'object' ? registry.registrations : undefined
+  if (!map || typeof map.set !== 'function' || typeof map.values !== 'function') return () => {}
+
+  // Успели завестись раньше нас — оборачиваем прямо сейчас.
+  for (const entry of map.values()) {
+    if (entry && entry.def) undo.push(wrapApply(entry.def, guard))
+  }
+
+  // Заведутся позже — поймаем на укладке в карту.
+  const set = map.set
+  if (!set[PATCHED]) {
+    const patched = function (key, value) {
+      if (value && value.def) undo.push(wrapApply(value.def, guard))
+      return set.call(this, key, value)
+    }
+    patched[PATCHED] = true
+    map.set = patched
+    undo.push(() => {
+      if (map.set === patched) delete map.set
+    })
+  }
+
+  return () => {
+    for (const step of undo.reverse()) step()
+    undo.length = 0
+  }
+}

package/lib/usage.js

@@ -0,0 +1,130 @@
+// Чистая часть заплатки: что считать испорченной порцией расхода и во что её
+// превращать. Ни контекста, ни сети — поэтому проверяется тестами целиком.
+
+/**
+ * Поля, из которых харнесс собирает свои четыре ведра.
+ *
+ * Два первых он берёт как есть, два вторых подстраховывает нулём. Отсюда и весь
+ * сыр-бор: провайдер, приславший порцию без `inputTokens`, роняет не свой
+ * счётчик, а всю историю сессии.
+ */
+export const FIELDS = ['inputTokens', 'outputTokens', 'cacheReadTokens', 'cacheWriteTokens']
+
+/**
+ * Как то же самое число называют другие.
+ *
+ * Единого имени у расхода нет: одни присылают `inputTokens`, другие
+ * `input_tokens`, третьи просто `input`. Харнесс знает одно написание, поэтому
+ * остальные для него — пустое место, хотя число лежит рядом. Прежде чем
+ * подставлять ноль, стоит поискать его здесь: ноль — это признание поражения, а
+ * не первый ход.
+ */
+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'],
+}
+
+/** Годное значение счётчика: конечное число, а не `undefined`, `null` или `NaN`. */
+function sound(value) {
+  return typeof value === 'number' && Number.isFinite(value)
+}
+
+/**
+ * Достать порцию расхода из события сессии — по тем же двум местам, где её ищет
+ * харнесс.
+ *
+ * @returns `{ usage, turn, step, at }`, где `at` — путь до порции внутри
+ *          события, или `null`, если расхода в событии нет.
+ */
+export function usageOf(event) {
+  if (!event || typeof event !== 'object') return null
+  const data = event.data
+  if (!data || typeof data !== 'object') return null
+
+  if (event.type === 'assistant/chunk' && data.chunk && data.chunk.type === 'usage') {
+    return { usage: data.chunk.usage, turn: data.turn, step: data.step, at: 'chunk' }
+  }
+  if (event.type === 'assistant/message' && data.usage !== undefined) {
+    return { usage: data.usage, turn: data.turn, step: data.step, at: 'message' }
+  }
+  return null
+}
+
+/**
+ * Какие счётчики порции испорчены.
+ *
+ * Отсутствие кэш-полей нарушением не считается: их не присылает добрая половина
+ * провайдеров, и харнесс сам подставляет там ноль. Ругаемся только на то, что
+ * действительно ломает сложение, — на пропущенные или нечисловые значения тех
+ * полей, которые харнесс берёт без оглядки.
+ */
+export function damage(usage) {
+  if (!usage || typeof usage !== 'object') return FIELDS.slice(0, 2)
+  const bad = []
+  for (const field of FIELDS) {
+    const value = usage[field]
+    const optional = field !== 'inputTokens' && field !== 'outputTokens'
+    if (value === undefined && optional) continue
+    if (!sound(value)) bad.push(field)
+  }
+  return bad
+}
+
+/** Число под одним из привычных чужих имён — или `undefined`, если его там нет. */
+export function borrowed(usage, field) {
+  for (const alias of ALIASES[field] ?? []) {
+    if (sound(usage[alias])) return usage[alias]
+  }
+  return undefined
+}
+
+/**
+ * Порция с обезвреженными счётчиками.
+ *
+ * Сначала ищем число под чужим именем, и только если его нет — ставим ноль.
+ * Ноль здесь заведомо неправда, но выбор не между точным счётом и
+ * приблизительным, а между приблизительным и нечитаемой историей. Остальные
+ * поля порции остаются как были: чиним арифметику, а не переписываем ответ
+ * провайдера.
+ */
+export function repaired(usage, bad) {
+  const fixed = usage && typeof usage === 'object' ? { ...usage } : {}
+  for (const field of bad) {
+    const found = usage && typeof usage === 'object' ? borrowed(usage, field) : undefined
+    fixed[field] = found === undefined ? 0 : found
+  }
+  return fixed
+}
+
+/**
+ * Событие с обезвреженной порцией — или то же самое событие, если чинить
+ * нечего.
+ *
+ * Копия поверхностная и ровно по тому пути, где лежит расход: складыванию
+ * достаётся исправное событие, а всё остальное в нём — та же ссылка, что и
+ * была.
+ */
+export function healed(event, bad) {
+  const found = usageOf(event)
+  if (!found || bad.length === 0) return event
+  const usage = repaired(found.usage, bad)
+
+  if (found.at === 'chunk') {
+    return {
+      ...event,
+      data: { ...event.data, chunk: { ...event.data.chunk, usage } },
+    }
+  }
+  return { ...event, data: { ...event.data, usage } }
+}
+
+/** Короткая строка для журнала: по ней видно, кого звать к ответу. */
+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}`
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@goodandready/dsh-usage-guard",
+  "version": "0.1.0",
+  "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",
+    "dsh",
+    "dsh-plugin",
+    "token-usage",
+    "session-history",
+    "patch"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/GooDAnDReaDY/dsh-usage-guard.git"
+  },
+  "homepage": "https://github.com/GooDAnDReaDY/dsh-usage-guard",
+  "bugs": {
+    "url": "https://github.com/GooDAnDReaDY/dsh-usage-guard/issues"
+  },
+  "type": "module",
+  "main": "./lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./package.json": "./package.json",
+    "./cordis.patch.yml": "./cordis.patch.yml"
+  },
+  "files": [
+    "lib/",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  }
+}