@goodandready/dsh-usage-guard 0.1.7 → 0.1.10

package/lib/index.js

@@ -1,36 +1,24 @@
-// dsh-usage-guard — заплатка на счёт токенов.
+// dsh-usage-guard — Token usage counter sanitizer and session history protector.
 //
-// Харнесс складывает расход в четыре ведра, и два из них берёт без оглядки:
+// DSH core aggregates token usage into four buckets, two of which are accessed without fallbacks:
 //
-//     uncachedInputTokens: usage.inputTokens,        // без подстраховки
-//     outputTokens:        usage.outputTokens,       // без подстраховки
+//     uncachedInputTokens: usage.inputTokens,        // unguarded
+//     outputTokens:        usage.outputTokens,       // unguarded
 //     cacheReadTokens:     usage.cacheReadTokens ?? 0,
 //     cacheWriteTokens:    usage.cacheWriteTokens ?? 0,
 //
-// Стоит провайдеру прислать порцию без первых двух, и сложение даёт NaN.
-// Дальше проверка схемы отвергает всю выжимку сессии, а наружу это выходит
-// так:
-//
-//     history unavailable for session "...": expected number, received NaN
-//
-// Не «счётчик соврал», а «история не открывается вовсе» — и остаётся такой
-// навсегда, потому что выжимка считается проигрыванием журнала заново.
-//
-// Отсюда и лечение. Плагин не переписывает журналы на диске: он встаёт перед
-// сложением и подставляет ноль вместо пропажи. Проигрывание идёт через ту же
-// точку, поэтому уже испорченные сессии открываются снова — сами, без починки
-// файлов.
-//
-// Ноль вместо пропущенного счётчика — заведомо неправда. Но выбор не между
-// точным счётом и приблизительным, а между приблизительным и нечитаемой
-// историей.
+// If a provider returns a usage sample missing either of the first two, accumulation yields NaN.
+// Subsequent schema validation then rejects the entire session history projection.
 
 import z from '@deepseek-ai/schemastery'
 
 import { patchRegistry } from './patch.js'
+import { telemetry } from './telemetry.js'
+import { registerPluginUpdater } from './updater.js'
 import { complaint, damage, healed, usageOf } from './usage.js'
 
-export const name = 'dsh-usage-guard'
+export const name = '@goodandready/dsh-usage-guard'
+export const NS = 'dsh-usage-guard'
 export const inject = ['sessionProjections']
 
 export const Config = z.object({
@@ -45,6 +33,10 @@ export const Config = z.object({
     .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.'),
+  maxStepTokens: z
+    .natural()
+    .default(0)
+    .description('Maximum allowed token count for a single turn step. Spikes exceeding this ceiling are clamped to prevent integer overflow and runaway stats. Set to 0 to disable.'),
 })
 
 export function apply(ctx, config) {
@@ -52,33 +44,84 @@ export function apply(ctx, config) {
   try {
     live = Config(structuredClone(config ?? {})) ?? config
   } catch (_) {
-    live = Config({}) ?? { repair: true, report: true }
+    live = Config({}) ?? { repair: true, report: true, maxStepTokens: 0 }
   }
 
   ctx.inject(['settings'], (sctx) => {
     try {
-      const scope = sctx.settings.register(name, Config, { base: config })
-      try {
-        const fresh = scope.get()
-        if (fresh && typeof fresh === 'object') live = fresh
-      } catch (_) {}
-      sctx.effect(() => scope.watch((next) => {
-        if (next && typeof next === 'object') live = next
-      }))
-    } catch (_) {}
+      const scope = sctx.settings?.register?.(NS, Config, { base: config })
+      if (!scope) {
+        const msg = `[dsh-usage-guard] settings service register() unavailable; running with default config`
+        if (typeof sctx.logger?.warn === 'function') sctx.logger.warn(msg)
+        else if (typeof ctx.logger?.warn === 'function') ctx.logger.warn(msg)
+        return
+      }
+
+      if (typeof scope.get === 'function') {
+        try {
+          const fresh = scope.get()
+          if (fresh && typeof fresh === 'object') live = fresh
+        } catch (readErr) {
+          const msg = `[dsh-usage-guard] failed to read current settings: ${readErr?.message || readErr}; running with initial config`
+          if (typeof sctx.logger?.warn === 'function') sctx.logger.warn(msg)
+          else if (typeof ctx.logger?.warn === 'function') ctx.logger.warn(msg)
+        }
+      } else {
+        const msg = `[dsh-usage-guard] settings scope has no get() method; running with default config`
+        if (typeof sctx.logger?.warn === 'function') sctx.logger.warn(msg)
+        else if (typeof ctx.logger?.warn === 'function') ctx.logger.warn(msg)
+      }
+
+      if (typeof scope.watch === 'function') {
+        sctx.effect(() => scope.watch((next) => {
+          if (next && typeof next === 'object') live = next
+        }))
+      } else {
+        const msg = `[dsh-usage-guard] settings scope has no watch() method; running with default config without live update subscription`
+        if (typeof sctx.logger?.warn === 'function') sctx.logger.warn(msg)
+        else if (typeof ctx.logger?.warn === 'function') ctx.logger.warn(msg)
+      }
+    } catch (err) {
+      const msg = `[dsh-usage-guard] failed to register settings subscription: ${err?.message || err}; running with default config`
+      if (typeof sctx.logger?.warn === 'function') sctx.logger.warn(msg)
+      else if (typeof ctx.logger?.warn === 'function') ctx.logger.warn(msg)
+    }
+  })
+
+  // Register one-click updater and telemetry endpoints if webServer is available
+  ctx.inject(['webServer'], (wctx) => {
+    try {
+      wctx.effect(() => registerPluginUpdater(wctx, {
+        endpoint: '/api/dsh-usage-guard/update',
+        packageName: '@goodandready/dsh-usage-guard',
+        manifestUrl: new URL('../package.json', import.meta.url),
+      }), 'dsh-usage-guard: plugin updater route')
+
+      wctx.effect(() => wctx.webServer.register({
+        kind: 'exact',
+        path: '/api/dsh-usage-guard/telemetry',
+        handler: async (req, res) => {
+          if (req.method === 'GET' || req.method === 'HEAD') {
+            res.writeHead(200, {
+              'content-type': 'application/json; charset=utf-8',
+              'cache-control': 'no-store',
+            })
+            res.end(req.method === 'HEAD' ? undefined : JSON.stringify(telemetry.getSnapshot()))
+            return
+          }
+          res.writeHead(405, { allow: 'GET, HEAD' })
+          res.end()
+        },
+      }), 'dsh-usage-guard: telemetry route')
+    } catch (err) {
+      const msg = `[dsh-usage-guard] failed to register routes on webServer: ${err?.message || err}`
+      if (typeof wctx.logger?.warn === 'function') wctx.logger.warn(msg)
+      else if (typeof ctx.logger?.warn === 'function') ctx.logger.warn(msg)
+    }
   })
 
-  // О каждом сочетании сессии, хода, шага и набора полей жалуемся один раз:
-  // выжимка считается проигрыванием журнала заново, и без этого одна и та же
-  // порция въезжала бы в журнал при каждом открытии истории.
-  // Честное FIFO-вытеснение с ограничением в 1000 записей предотвращает утечку
-  // памяти при длительной работе без сброса всей накопленной дедупликации.
   const told = new Set()
   const MAX_TOLD = 1000
-
-  // Кэш санитизированных событий: каждое событие проходит через 10-15 проекций DSH.
-  // WeakMap позволяет обработать событие один раз, отдавая остальным проекциям
-  // готовый результат за O(1) без повторного парсинга и без утечек памяти.
   const eventCache = new WeakMap()
 
   const guard = (event) => {
@@ -91,31 +134,57 @@ export function apply(ctx, config) {
       eventCache.set(event, event)
       return event
     }
-    const bad = damage(found.usage)
+    const bad = damage(found.usage, { maxStepTokens: live?.maxStepTokens })
     if (bad.length === 0) {
       eventCache.set(event, event)
       return event
     }
 
-    if (live && live.report !== false) {
-      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) {
-          const oldest = told.values().next().value
-          told.delete(oldest)
-        }
-        told.add(seen)
-        try {
+    const sessionTag = event?.sessionId ?? event?.data?.sessionId ?? event?.data?.turn ?? 'global'
+    const seen = `${String(sessionTag)}/${String(found.turn)}/${String(found.step)}/${bad.join(',')}`
+
+    let clampedAny = false
+    let fixedTokensCount = 0
+    const maxLimit = Number(live?.maxStepTokens) > 0 ? Number(live?.maxStepTokens) : 0
+    for (const f of bad) {
+      const val = found.usage?.[f]
+      if (maxLimit > 0 && typeof val === 'number' && val > maxLimit) {
+        clampedAny = true
+        fixedTokensCount += (val - maxLimit)
+      } else {
+        fixedTokensCount += 1
+      }
+    }
+
+    if (!told.has(seen)) {
+      if (told.size >= MAX_TOLD) {
+        const oldest = told.values().next().value
+        told.delete(oldest)
+      }
+      told.add(seen)
+
+      telemetry.recordIncident({
+        turn: found.turn,
+        step: found.step,
+        badFields: bad,
+        fixedTokenCount: fixedTokensCount,
+        clamped: clampedAny,
+        provider: event?.provider ?? event?.data?.provider ?? 'unknown',
+        sample: found.usage,
+      })
+
+      if (live && live.report !== false) {
+        const msg = `[dsh-usage-guard] ${complaint(found, bad, { maxStepTokens: live?.maxStepTokens })}`
+        if (typeof ctx.logger?.warn === 'function') {
+          ctx.logger.warn(msg)
+        } else {
           // eslint-disable-next-line no-console
-          console.warn(`[dsh-usage-guard] ${complaint(found, bad)}`)
-        } catch {
-          // Ошибка вывода не должна ломать обработку событий
+          console.warn(msg)
         }
       }
     }
 
-    const result = live && live.repair === false ? event : healed(event, bad)
+    const result = live && live.repair === false ? event : healed(event, bad, { maxStepTokens: live?.maxStepTokens })
     eventCache.set(event, result)
     return result
   }
@@ -123,7 +192,8 @@ export function apply(ctx, config) {
   ctx.inject(['sessionProjections'], (pctx) => {
     pctx.effect(
       () => patchRegistry(pctx.sessionProjections, guard),
-      'dsh-usage-guard: обезвреживание порций расхода',
+      'dsh-usage-guard: sanitize usage counter samples',
     )
   })
 }
+export { telemetry }

package/lib/patch.js

@@ -1,30 +1,27 @@
-// Как заплатка встаёт перед сложением.
+// How the patch intercepts before state reduction.
 //
-// Реестр проекций сессии — служба с открытой картой записей. Каждая запись
-// держит обезличенную копию того, что зарегистрировал владелец, и зовёт `apply`
-// именно у копии. Значит, подменять надо её, а не то, что владелец отдал при
-// регистрации.
+// The session projection registry is a service with an exposed registrations map. Each entry
+// holds a sanitized copy of what the owner registered, and calls `apply` on that copy.
+// Therefore, we patch the definition's apply method, not the original object passed at registration.
 //
-// Порядок загрузки не гарантирован, и на деле проекция ядра заводится позже
-// нас. Подменять при этом метод `register` у службы бесполезно: до неё
-// добираются через посредника, и замена, поставленная на посредника, до
-// настоящего вызова не доезжает. Поэтому цепляемся за саму карту записей —
-// обычный Map, один и тот же для всех, кто до него дотянулся.
+// Load order is not guaranteed, and in practice core projections may register later than our plugin.
+// Patching the service's `register` method is ineffective because callers go through an intermediary.
+// Hence, we hook into the registrations map itself — a standard Map instance shared by all participants.
 //
-// Оборачиваются все проекции, а не одна «нужная». Порцию расхода читает не
-// только счёт токенов: давление на контекст считает её своей формулой, разбор
-// занятости — своей, и каждая спотыкается об один и тот же пропущенный
-// счётчик. Список ключей пришлось бы держать в согласии с чужим кодом, а
-// обезвреживатель для здорового события возвращает ровно то же событие — тем,
-// кто расхода не касается, он обходится в одно сравнение.
+// All projections are wrapped, not just a single one. Token usage is consumed by multiple systems:
+// context pressure calculations, session token sums, and analytics. Each would fail on a missing
+// counter. Wrapping all projections with a guard that returns the exact object reference for healthy
+// events costs only a single reference comparison for events without usage.
 
-/** Метка на подменённой функции: второй раз оборачивать нечего. */
+/** Marker on patched functions to prevent double wrapping. */
 export const PATCHED = Symbol.for('dsh-usage-guard.patched')
 
 /**
- * Обернуть складывание одной записи реестра с сохранением контекста this.
+ * Wrap the apply method of a registry definition, preserving `this` context.
  *
- * @returns функция возврата к исходному состоянию.
+ * @param def - Projection definition entry.
+ * @param guard - Event sanitizer function.
+ * @returns Cleanup function restoring the original method.
  */
 export function wrapApply(def, guard) {
   if (!def || typeof def.apply !== 'function' || def.apply[PATCHED]) return () => {}
@@ -40,27 +37,23 @@ export function wrapApply(def, guard) {
 }
 
 /**
- * Поставить заплатку на реестр проекций.
+ * Patch the session projections registry.
  *
- * @param registry - служба `sessionProjections`.
- * @param guard - обезвреживатель события; получает событие, возвращает его же
- *                или исправленное.
- * @returns функция, снимающая всё поставленное, в обратном порядке.
+ * @param registry - `sessionProjections` service instance.
+ * @param guard - Event sanitizer function; receives an event and returns either the same event or a repaired copy.
+ * @returns Teardown function that removes all installed hooks in reverse order.
  */
 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 () => {}
 
-  // Успели завестись раньше нас — оборачиваем прямо сейчас.
+  // Wrap entries already registered before this patch
   for (const entry of map.values()) {
     if (entry && entry.def) undo.push(wrapApply(entry.def, guard))
   }
 
-  // Заведутся позже — поймаем на укладке в карту.
-  // Save the current map.set (may be the prototype method or a previous patched version).
-  // We restore via explicit assignment — relying on `delete` to restore the prototype method
-  // is fragile when the environment mutates Map.prototype.
+  // Intercept entries registered in the future when inserted into the map
   const originalSet = map.set
   if (!originalSet[PATCHED]) {
     const patched = function (key, value) {
@@ -78,4 +71,4 @@ export function patchRegistry(registry, guard) {
     for (const step of undo.reverse()) step()
     undo.length = 0
   }
-}
+}

package/lib/telemetry.js

@@ -0,0 +1,111 @@
+// lib/telemetry.js — In-memory telemetry accumulator for dsh-usage-guard
+// Tracks rescued malformed usage samples, fixed NaN counters, and clamped token spikes.
+
+class UsageGuardTelemetry {
+  constructor() {
+    this.rescuedEvents = 0;
+    this.fixedTokens = 0;
+    this.clampedSpikes = 0;
+    this.lastIncident = null;
+    this.maxRecentIncidents = 20;
+    this.recentIncidents = [];
+  }
+
+  recordIncident({ turn = 0, step = 0, badFields = [], fixedTokenCount = 0, clamped = false, provider = 'unknown', sample = null, kind = 'malformed-usage', target = '' } = {}) {
+    this.rescuedEvents += 1;
+    this.fixedTokens += Number(fixedTokenCount) || 0;
+    if (clamped) {
+      this.clampedSpikes += 1;
+    }
+
+    const incident = {
+      timestamp: new Date().toISOString(),
+      kind: String(kind),
+      turn: turn ?? 0,
+      step: step ?? 0,
+      target: String(target || (Array.isArray(badFields) ? badFields.join(',') : '')),
+      fields: Array.isArray(badFields) ? badFields : [],
+      clamped: Boolean(clamped),
+      provider: typeof provider === 'string' ? provider : 'unknown',
+      sample: sample && typeof sample === 'object' ? JSON.stringify(sample).slice(0, 300) : null,
+    };
+
+    this.lastIncident = incident;
+    this.recentIncidents.unshift(incident);
+    if (this.recentIncidents.length > this.maxRecentIncidents) {
+      this.recentIncidents.pop();
+    }
+    return incident;
+  }
+
+  recordRescue(tokens = 0) {
+    this.rescuedEvents += 1;
+    this.fixedTokens += Number(tokens) || 0;
+  }
+
+  recordClamped(tokens = 0) {
+    this.clampedSpikes += 1;
+    this.fixedTokens += Number(tokens) || 0;
+  }
+
+  getSnapshot() {
+    return {
+      rescuedEvents: this.rescuedEvents,
+      fixedTokens: this.fixedTokens,
+      clampedSpikes: this.clampedSpikes,
+      lastIncident: this.lastIncident ? { ...this.lastIncident } : null,
+      recentIncidents: this.recentIncidents.map((i) => ({ ...i })),
+    };
+  }
+
+  reset() {
+    this.rescuedEvents = 0;
+    this.fixedTokens = 0;
+    this.clampedSpikes = 0;
+    this.lastIncident = null;
+    this.recentIncidents = [];
+  }
+}
+
+export const telemetry = new UsageGuardTelemetry();
+
+export function recordIncident(options) {
+  return telemetry.recordIncident(options);
+}
+
+export function recordRescue(tokens) {
+  return telemetry.recordRescue(tokens);
+}
+
+export function recordClamped(tokens) {
+  return telemetry.recordClamped(tokens);
+}
+
+export function getSnapshot() {
+  return telemetry.getSnapshot();
+}
+
+export function resetTelemetry() {
+  telemetry.reset();
+}
+
+export function registerTelemetryRoute(ctx, options = {}) {
+  const endpoint = options.endpoint || '/api/dsh-usage-guard/telemetry';
+  return ctx.webServer.register({
+    kind: 'exact',
+    path: endpoint,
+    handler: async (request, response) => {
+      if (request.method !== 'GET' && request.method !== 'HEAD') {
+        response.writeHead(405, { allow: 'GET, HEAD' });
+        response.end();
+        return;
+      }
+      const snapshot = telemetry.getSnapshot();
+      response.writeHead(200, {
+        'content-type': 'application/json; charset=utf-8',
+        'cache-control': 'no-store',
+      });
+      response.end(request.method === 'HEAD' ? undefined : JSON.stringify(snapshot));
+    },
+  });
+}