@goodandready/dsh-usage-guard 0.1.7 → 0.1.9

package/lib/usage.js

@@ -1,36 +1,22 @@
-// Как устроена порция расхода в событиях сессии.
-//
-// Харнесс слушает шину событий сессии и собирает статистику по двум типам
-// записей:
-//
-//   1. Потоковые порции ответа ассистента:
-//      `assistant/chunk` -> `event.data.chunk.usage`
-//
-//   2. Финальное сообщение ассистента:
-//      `assistant/message` -> `event.data.usage`
-//
-// В обоих случаях ядро ждёт четыре поля:
-//
-//     uncachedInputTokens: usage.inputTokens,
-//     outputTokens:        usage.outputTokens,
-//     cacheReadTokens:     usage.cacheReadTokens ?? 0,
-//     cacheWriteTokens:    usage.cacheWriteTokens ?? 0,
-//
-// Если первые два поля пропущены, не являются числом или содержат нечисловую строку,
-// их сложение с нулём даёт NaN. Из-за этого одна битая порция валит не просто
-// счётчик, а всю историю сессии.
-export const FIELDS = ['inputTokens', 'outputTokens', 'cacheReadTokens', 'cacheWriteTokens']
+// lib/usage.js — Pure functions for token-usage sanitization.
+// Zero imports, zero side-effects, testable without runtime context.
+
+export const FIELDS = [
+  'inputTokens',
+  'outputTokens',
+  'cacheReadTokens',
+  'cacheWriteTokens',
+]
 
 /**
- * Как то же самое число называют другие.
+ * Словарь привычных чужих имён для счётчиков токенов.
  *
- * Единого имени у расхода нет: одни присылают `inputTokens`, другие
- * `input_tokens`, третьи просто `input`. Харнесс знает одно написание, поэтому
+ * Каждый LLM-провайдер называет расход на свой лад. Харнесс ждёт camelCase, а
  * остальные для него — пустое место, хотя число лежит рядом. Прежде чем
  * подставлять ноль, стоит поискать его здесь: ноль — это признание поражения, а
  * не первый ход.
  */
-const ALIASES = {
+export const ALIASES = {
   inputTokens: [
     'input_tokens',
     'input',
@@ -66,7 +52,7 @@ const ALIASES = {
  * Значения меньше нуля (-1 и т.д.), нечисловые, а также дробные числа (floats)
  * не признаются годными, так как схема ядра DSH требует z.number().int().nonnegative().
  */
-function sound(value) {
+export function sound(value) {
   return typeof value === 'number' && Number.isFinite(value) && value >= 0 && Number.isInteger(value)
 }
 
@@ -75,7 +61,7 @@ function sound(value) {
  * Округляет дробные числа и парсит числовые строки (в т.ч. с десятичной точкой).
  * Исключает NaN, Infinity, отрицательные величины и мусорные строки.
  */
-function coerceNumber(value) {
+export function coerceNumber(value) {
   if (typeof value === 'number') {
     return Number.isFinite(value) && value >= 0 ? Math.round(value) : undefined
   }
@@ -111,21 +97,29 @@ export function usageOf(event) {
 }
 
 /**
- * Какие счётчики порции испорчены.
+ * Какие счётчики порции испорчены или превышают допустимый порог maxStepTokens.
  *
  * Отсутствие кэш-полей нарушением не считается: их не присылает добрая половина
  * провайдеров, и харнесс сам подставляет там ноль. Ругаемся только на то, что
  * действительно ломает сложение, — на пропущенные, нечисловые, нецелые или
  * отрицательные значения.
  */
-export function damage(usage) {
+export function damage(usage, options = {}) {
   if (!usage || typeof usage !== 'object') return FIELDS.slice(0, 2)
   const bad = []
+  const maxStepTokens = typeof options === 'number' ? options : (Number(options?.maxStepTokens) > 0 ? Number(options.maxStepTokens) : 0)
+
   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)
+    if (!sound(value)) {
+      bad.push(field)
+    } else if (maxStepTokens > 0 && value > maxStepTokens) {
+      bad.push(field)
+      bad.clamped = bad.clamped || {}
+      bad.clamped[field] = { from: value, to: maxStepTokens }
+    }
   }
   return bad
 }
@@ -165,17 +159,27 @@ export function borrowed(usage, field) {
 }
 
 /**
- * Порция с обезвреженными счётчиками.
+ * Порция с обезвреженными счётчиками и опциональным ограничением maxStepTokens.
  *
  * Сначала ищем число под чужим именем или нормализуем само поле (округление float/string),
  * и только если его нет — ставим ноль.
  * Чиним арифметику, а не переписываем остальной ответ провайдера.
  */
-export function repaired(usage, bad) {
+export function repaired(usage, bad, options = {}) {
   const fixed = usage && typeof usage === 'object' ? { ...usage } : {}
+  const maxStepTokens = typeof options === 'number' ? options : (Number(options?.maxStepTokens) > 0 ? Number(options.maxStepTokens) : 0)
+
   for (const field of bad) {
-    const found = usage && typeof usage === 'object' ? borrowed(usage, field) : undefined
-    fixed[field] = found === undefined ? 0 : found
+    const rawVal = usage && typeof usage === 'object' ? usage[field] : undefined
+    let found = usage && typeof usage === 'object' ? borrowed(usage, field) : undefined
+    let candidate = found === undefined ? 0 : found
+
+    if (maxStepTokens > 0 && candidate > maxStepTokens) {
+      candidate = maxStepTokens
+    } else if (maxStepTokens > 0 && typeof rawVal === 'number' && rawVal > maxStepTokens && candidate === 0) {
+      candidate = maxStepTokens
+    }
+    fixed[field] = candidate
   }
   return fixed
 }
@@ -188,10 +192,10 @@ export function repaired(usage, bad) {
  * достаётся исправное событие, а всё остальное в нём — та же ссылка, что и
  * была.
  */
-export function healed(event, bad) {
+export function healed(event, bad, options = {}) {
   const found = usageOf(event)
   if (!found || bad.length === 0) return event
-  const usage = repaired(found.usage, bad)
+  const usage = repaired(found.usage, bad, options)
 
   if (found.at === 'chunk') {
     return {
@@ -216,10 +220,23 @@ function safeStringify(value) {
 }
 
 /** Короткая строка для журнала: по ней видно, кого звать к ответу. */
-export function complaint(found, bad) {
-  const where = `turn ${String(found.turn)}, step ${String(found.step)}`
-  const taken = bad
-    .map((field) => (found.usage && borrowed(found.usage, field) !== undefined ? `${field} recovered via alias` : `${field} zeroed`))
-    .join('; ')
-  return `malformed usage sample — ${where}; received: ${safeStringify(found.usage)}; ${taken}`
+export function complaint(found, bad, options = {}) {
+  const where = `turn ${String(found?.turn ?? '-')}, step ${String(found?.step ?? '-')}`
+  const usage = found?.usage ?? found
+  const maxStepTokens = typeof options === 'number' ? options : (Number(options?.maxStepTokens) > 0 ? Number(options.maxStepTokens) : 0)
+  const taken = Array.isArray(bad)
+    ? bad
+        .map((field) => {
+          if (bad?.clamped?.[field]) {
+            return `${field} clamped abnormally large (${bad.clamped[field].from} -> ${bad.clamped[field].to})`
+          }
+          const val = usage?.[field]
+          if (maxStepTokens > 0 && typeof val === 'number' && val > maxStepTokens) {
+            return `${field} clamped to ${maxStepTokens}`
+          }
+          return usage && borrowed(usage, field) !== undefined ? `${field} recovered via alias` : `${field} zeroed`
+        })
+        .join('; ')
+    : ''
+  return `malformed usage sample — ${where}; received: ${safeStringify(usage)}; ${taken}`
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-usage-guard",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "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",