@goodandready/dsh-usage-guard 0.1.7 → 0.1.9

package/lib/index.js

@@ -8,26 +8,13 @@
 //     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 { telemetry } from './telemetry.js'
+import { registerPluginUpdater } from './updater.js'
 import { complaint, damage, healed, usageOf } from './usage.js'
 
 export const name = 'dsh-usage-guard'
@@ -45,6 +32,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,7 +43,7 @@ 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) => {
@@ -68,17 +59,36 @@ export function apply(ctx, config) {
     } catch (_) {}
   })
 
-  // О каждом сочетании сессии, хода, шага и набора полей жалуемся один раз:
-  // выжимка считается проигрыванием журнала заново, и без этого одна и та же
-  // порция въезжала бы в журнал при каждом открытии истории.
-  // Честное FIFO-вытеснение с ограничением в 1000 записей предотвращает утечку
-  // памяти при длительной работе без сброса всей накопленной дедупликации.
+  // 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 (_) {}
+  })
+
   const told = new Set()
   const MAX_TOLD = 1000
-
-  // Кэш санитизированных событий: каждое событие проходит через 10-15 проекций DSH.
-  // WeakMap позволяет обработать событие один раз, отдавая остальным проекциям
-  // готовый результат за O(1) без повторного парсинга и без утечек памяти.
   const eventCache = new WeakMap()
 
   const guard = (event) => {
@@ -91,31 +101,54 @@ 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)
+    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) {
         try {
           // eslint-disable-next-line no-console
-          console.warn(`[dsh-usage-guard] ${complaint(found, bad)}`)
-        } catch {
-          // Ошибка вывода не должна ломать обработку событий
-        }
+          console.warn(`[dsh-usage-guard] ${complaint(found, bad, { maxStepTokens: live?.maxStepTokens })}`)
+        } catch {}
       }
     }
 
-    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
   }
@@ -127,3 +160,4 @@ export function apply(ctx, config) {
     )
   })
 }
+export { telemetry }

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));
+    },
+  });
+}

package/lib/updater.js

@@ -0,0 +1,266 @@
+// lib/updater.js — Host-side one-click updater for @goodandready/dsh-usage-guard
+// Implements canonical DSH plugin-updater specification.
+
+import { spawn } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { basename, dirname, isAbsolute, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const UPDATE_HEADER = 'x-dsh-plugin-update';
+const UPDATE_TIMEOUT_MS = 10 * 60_000;
+const VERSION_CACHE_MS = 5 * 60_000;
+let latestCache;
+
+function header(request, name) {
+  const value = request?.headers?.[name];
+  return Array.isArray(value) ? value[0] : value;
+}
+
+function isLoopback(value) {
+  const address = value?.toLowerCase().replace(/^\[|\]$/g, '');
+  return address === 'localhost' || address === 'localhost.' || address === '::1'
+    || address?.startsWith('127.') === true
+    || address?.startsWith('::ffff:127.') === true;
+}
+
+export function isTrustedUpdateRequest(request) {
+  if (header(request, UPDATE_HEADER) !== '1') return false;
+  if (!isLoopback(request.socket?.remoteAddress)) return false;
+  const site = header(request, 'sec-fetch-site');
+  if (site !== undefined && site !== 'same-origin') return false;
+  const origin = header(request, 'origin');
+  const host = header(request, 'host');
+  if (origin === undefined || host === undefined) return false;
+  try {
+    const url = new URL(origin);
+    return (url.protocol === 'http:' || url.protocol === 'https:')
+      && isLoopback(url.hostname) && url.host === host;
+  } catch {
+    return false;
+  }
+}
+
+function validProfileName(value) {
+  return typeof value === 'string' && value !== '' && value !== '.' && value !== '..'
+    && !value.includes('/') && !value.includes('\\') && !/[\0-\x1f\x7f]/.test(value);
+}
+
+function profileNameFromArgv(argv) {
+  for (let index = 2; index < argv.length; index += 1) {
+    if (argv[index] === '--profile') return argv[index + 1];
+    if (argv[index]?.startsWith('--profile=')) return argv[index].slice('--profile='.length);
+  }
+  return argv[2] === 'web' ? 'web' : undefined;
+}
+
+function findDshCliEntry() {
+  const value = process.argv[1];
+  if (value === undefined || value === '') return undefined;
+  const entry = value.startsWith('file:') ? fileURLToPath(value) : resolve(process.cwd(), value);
+  if (!existsSync(entry)) return undefined;
+  for (let directory = dirname(entry); ; directory = dirname(directory)) {
+    const manifestPath = resolve(directory, 'package.json');
+    if (existsSync(manifestPath)) {
+      try {
+        const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+        const bin = typeof manifest.bin === 'string'
+          ? manifest.bin
+          : typeof manifest.bin === 'object' && manifest.bin !== null
+            ? manifest.bin.dsh
+            : undefined;
+        if (manifest.name === '@deepseek-ai/dsh' && typeof bin === 'string'
+          && !isAbsolute(bin) && resolve(directory, bin) === resolve(entry)) return entry;
+      } catch {
+        // Continue searching parent package directories.
+      }
+    }
+    const parent = dirname(directory);
+    if (parent === directory) return undefined;
+  }
+}
+
+function runtime() {
+  const profileDir = resolve(process.env.DSH_PROFILE_DIR
+    ?? resolve(homedir(), '.dsh', 'profiles', 'web'));
+  const selected = profileNameFromArgv(process.argv);
+  const profileName = validProfileName(selected)
+    ? selected
+    : validProfileName(basename(profileDir)) ? basename(profileDir) : 'web';
+  const cliEntry = findDshCliEntry();
+  return cliEntry === undefined ? { profileName, profileDir } : { profileName, profileDir, cliEntry };
+}
+
+function parseSemver(value) {
+  const match = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(value);
+  if (match === null) return undefined;
+  return {
+    core: [Number(match[1]), Number(match[2]), Number(match[3])],
+    prerelease: match[4]?.split('.') ?? [],
+  };
+}
+
+function comparePrerelease(left, right) {
+  if (left.length === 0 || right.length === 0) return left.length === right.length ? 0 : left.length === 0 ? 1 : -1;
+  const length = Math.max(left.length, right.length);
+  for (let index = 0; index < length; index += 1) {
+    const a = left[index];
+    const b = right[index];
+    if (a === undefined || b === undefined) return a === b ? 0 : a === undefined ? -1 : 1;
+    if (a === b) continue;
+    const aNumeric = /^\d+$/.test(a);
+    const bNumeric = /^\d+$/.test(b);
+    if (aNumeric && bNumeric) {
+      const aNumber = BigInt(a);
+      const bNumber = BigInt(b);
+      if (aNumber !== bNumber) return aNumber > bNumber ? 1 : -1;
+      continue;
+    }
+    if (aNumeric !== bNumeric) return aNumeric ? -1 : 1;
+    return a > b ? 1 : -1;
+  }
+  return 0;
+}
+
+export function isNewerVersion(currentValue, candidateValue) {
+  const current = parseSemver(currentValue);
+  const candidate = parseSemver(candidateValue);
+  if (current === undefined || candidate === undefined) return false;
+  for (let index = 0; index < 3; index += 1) {
+    if (candidate.core[index] !== current.core[index]) return candidate.core[index] > current.core[index];
+  }
+  return comparePrerelease(candidate.prerelease, current.prerelease) > 0;
+}
+
+async function latestVersion(packageName, registry) {
+  if (latestCache?.packageName === packageName && latestCache.registry === registry && Date.now() < latestCache.expiresAt) return latestCache.version;
+  try {
+    const response = await fetch(`${registry.replace(/\/$/, '')}/${encodeURIComponent(packageName)}/latest`, {
+      signal: AbortSignal.timeout(8_000),
+    });
+    if (!response.ok) return undefined;
+    const value = await response.json();
+    if (typeof value.version !== 'string' || value.version === '') return undefined;
+    latestCache = { packageName, registry, version: value.version, expiresAt: Date.now() + VERSION_CACHE_MS };
+    return value.version;
+  } catch {
+    return undefined;
+  }
+}
+
+async function currentVersion(manifestUrl) {
+  const value = JSON.parse(await readFile(manifestUrl, 'utf8'));
+  if (typeof value.version !== 'string' || value.version === '') throw new Error('Cannot read current plugin version.');
+  return value.version;
+}
+
+export async function getUpdateStatus(options, target = runtime()) {
+  const current = await currentVersion(options.manifestUrl);
+  const latest = await latestVersion(options.packageName, options.registry ?? 'https://registry.npmjs.org');
+  return {
+    packageName: options.packageName,
+    currentVersion: current,
+    ...(latest === undefined ? {} : { latestVersion: latest }),
+    latestCheckFailed: latest === undefined,
+    updateAvailable: latest !== undefined && isNewerVersion(current, latest),
+    profileName: target.profileName,
+    canAutoUpdate: target.cliEntry !== undefined,
+  };
+}
+
+async function installExact(target, packageSpec, options) {
+  if (target.cliEntry === undefined) throw new Error('Automatic update is unavailable in this runtime.');
+  await new Promise((resolvePromise, reject) => {
+    const child = spawn(process.execPath, [
+      target.cliEntry, 'plugin', '--profile', target.profileName, 'add',
+      '--config.minimumReleaseAge=0', packageSpec,
+      `--registry=${options.registry ?? 'https://registry.npmjs.org/'}`,
+    ], {
+      cwd: target.profileDir,
+      windowsHide: true,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: { ...process.env, NO_COLOR: '1' },
+    });
+    let detail = '';
+    child.stdout?.on('data', chunk => { detail = (detail + String(chunk)).slice(-4_000); });
+    child.stderr?.on('data', chunk => { detail = (detail + String(chunk)).slice(-4_000); });
+    const timer = setTimeout(() => {
+      child.kill();
+      reject(new Error('Update timed out; use the normal DSH update flow.'));
+    }, UPDATE_TIMEOUT_MS);
+    child.once('error', error => { clearTimeout(timer); reject(error); });
+    child.once('exit', code => {
+      clearTimeout(timer);
+      if (code === 0) resolvePromise();
+      else reject(new Error(detail.trim() || `Update exited with code ${String(code)}.`));
+    });
+  });
+}
+
+function json(response, statusCode, value) {
+  response.writeHead(statusCode, {
+    'content-type': 'application/json; charset=utf-8',
+    'cache-control': 'no-store',
+  });
+  response.end(JSON.stringify(value));
+}
+
+export function registerPluginUpdater(ctx, options) {
+  const host = ctx;
+  let installing = false;
+  return host.webServer.register({
+    kind: 'exact',
+    path: options.endpoint,
+    handler: async (request, response) => {
+      try {
+        const target = runtime();
+        if (request.method === 'GET' || request.method === 'HEAD') {
+          const payload = await getUpdateStatus(options, target);
+          response.writeHead(200, {
+            'content-type': 'application/json; charset=utf-8',
+            'cache-control': 'no-store',
+          });
+          response.end(request.method === 'HEAD' ? undefined : JSON.stringify(payload));
+          return;
+        }
+        if (request.method !== 'POST') {
+          response.writeHead(405, { allow: 'GET, HEAD, POST' });
+          response.end();
+          return;
+        }
+        if (!isTrustedUpdateRequest(request)) {
+          json(response, 403, { error: 'Rejected non-local or cross-origin update request.' });
+          return;
+        }
+        if (installing) {
+          json(response, 409, { error: 'This plugin is already updating.' });
+          return;
+        }
+        installing = true;
+        try {
+          const before = await getUpdateStatus(options, target);
+          if (before.latestVersion === undefined) {
+            json(response, 503, { error: 'The latest version is temporarily unavailable.' });
+            return;
+          }
+          if (!before.updateAvailable) {
+            json(response, 200, before);
+            return;
+          }
+          await installExact(target, `${options.packageName}@${before.latestVersion}`, options);
+          json(response, 200, {
+            ...before,
+            updatedVersion: before.latestVersion,
+            restartRequired: true,
+          });
+        } finally {
+          installing = false;
+        }
+      } catch (error) {
+        ctx.logger?.warn?.(`plugin updater failed: ${String(error)}`);
+        json(response, 503, { error: 'Plugin update failed; see server logs.' });
+      }
+    },
+  });
+}