@goodandready/dsh-usage-guard 0.1.7 → 0.1.10

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

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',
+]
 
 /**
- * Как то же самое число называют другие.
+ * Dictionary of common external provider naming variants for token counters.
  *
- * Единого имени у расхода нет: одни присылают `inputTokens`, другие
- * `input_tokens`, третьи просто `input`. Харнесс знает одно написание, поэтому
- * остальные для него — пустое место, хотя число лежит рядом. Прежде чем
- * подставлять ноль, стоит поискать его здесь: ноль — это признание поражения, а
- * не первый ход.
+ * Each LLM provider formats token usage differently. DSH core expects camelCase,
+ * and ignores other conventions even if the token count is present under a different key.
+ * Instead of immediately falling back to zero, we check known provider aliases first.
+ * Setting zero is a last resort to preserve arithmetic, not the primary choice.
  */
-const ALIASES = {
+export const ALIASES = {
   inputTokens: [
     'input_tokens',
     'input',
@@ -62,20 +48,20 @@ const ALIASES = {
 }
 
 /**
- * Годное значение счётчика: конечное неотрицательное ЦЕЛОЕ число.
- * Значения меньше нуля (-1 и т.д.), нечисловые, а также дробные числа (floats)
- * не признаются годными, так как схема ядра DSH требует z.number().int().nonnegative().
+ * Valid counter value: a finite, non-negative integer.
+ * Negative values, non-numeric values, and floating point numbers are considered invalid
+ * as the DSH core schema expects integer counters.
  */
-function sound(value) {
+export function sound(value) {
   return typeof value === 'number' && Number.isFinite(value) && value >= 0 && Number.isInteger(value)
 }
 
 /**
- * Безопасное приведение значения к корректному неотрицательному целому числу.
- * Округляет дробные числа и парсит числовые строки (в т.ч. с десятичной точкой).
- * Исключает NaN, Infinity, отрицательные величины и мусорные строки.
+ * Safely coerces a value to a valid non-negative integer.
+ * Rounds floating point numbers and parses numeric strings (including decimals).
+ * Filters out NaN, Infinity, negative numbers, and non-numeric strings.
  */
-function coerceNumber(value) {
+export function coerceNumber(value) {
   if (typeof value === 'number') {
     return Number.isFinite(value) && value >= 0 ? Math.round(value) : undefined
   }
@@ -90,11 +76,10 @@ function coerceNumber(value) {
 }
 
 /**
- * Достать порцию расхода из события сессии — по тем же двум местам, где её ищет
- * харнесс.
+ * Extracts the usage sample from a session event by checking both standard DSH locations.
  *
- * @returns `{ usage, turn, step, at }`, где `at` — путь до порции внутри
- *          события, или `null`, если расхода в событии нет.
+ * @returns `{ usage, turn, step, at }` where `at` indicates the path within the event ('chunk' or 'message'),
+ *          or `null` if the event carries no usage data.
  */
 export function usageOf(event) {
   if (!event || typeof event !== 'object') return null
@@ -111,53 +96,60 @@ export function usageOf(event) {
 }
 
 /**
- * Какие счётчики порции испорчены.
+ * Detects which usage counters are malformed or exceed the maxStepTokens ceiling.
  *
- * Отсутствие кэш-полей нарушением не считается: их не присылает добрая половина
- * провайдеров, и харнесс сам подставляет там ноль. Ругаемся только на то, что
- * действительно ломает сложение, — на пропущенные, нечисловые, нецелые или
- * отрицательные значения.
+ * Omitted cache fields are not considered defects: many providers do not report them,
+ * and the harness automatically defaults them to zero. We only flag values that actually
+ * break arithmetic operations — missing required counters, non-numbers, non-integers, or negatives.
  */
-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
 }
 
 /**
- * Число под одним из привычных чужих имён, вложенных структур или числовых строк/дробей.
- * Возвращает валидное целое неотрицательное число или `undefined`, если его там нет.
+ * Attempts to borrow a valid counter number from known aliases, nested structures, or numeric strings.
+ * Returns a valid non-negative integer or `undefined` if none is found.
  */
 export function borrowed(usage, field) {
   if (!usage || typeof usage !== 'object') return undefined
 
-  // 1. Поиск по известным синонимам
+  // 1. Search known alias names
   for (const alias of ALIASES[field] ?? []) {
     const num = coerceNumber(usage[alias])
     if (num !== undefined) return num
   }
 
-  // 2. Поиск во вложенных деталях кэша (OpenAI-style: prompt_tokens_details.cached_tokens / cachedTokens)
+  // 2. Search nested cache details (OpenAI-style: prompt_tokens_details.cached_tokens / cachedTokens)
   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 ?? details.cache_read_tokens)
     if (num !== undefined) return num
   }
 
-  // 3. Поиск во вложенных деталях создания кэша (cache_creation_input_tokens)
+  // 3. Search nested cache creation details (cache_creation_input_tokens)
   if (field === 'cacheWriteTokens' && usage.prompt_tokens_details && typeof usage.prompt_tokens_details === 'object') {
     const details = usage.prompt_tokens_details
     const num = coerceNumber(details.cache_creation_tokens ?? details.cacheCreationTokens)
     if (num !== undefined) return num
   }
 
-  // 4. Само поле, если оно было передано валидной строкой или нецелым числом (напр. "123" или 15.4)
+  // 4. Check the field itself if passed as a string or float (e.g. "123" or 15.4)
   const selfNum = coerceNumber(usage[field])
   if (selfNum !== undefined) return selfNum
 
@@ -165,33 +157,41 @@ export function borrowed(usage, field) {
 }
 
 /**
- * Порция с обезвреженными счётчиками.
+ * Returns a usage object with sanitized counters and optional maxStepTokens clamping.
  *
- * Сначала ищем число под чужим именем или нормализуем само поле (округление float/string),
- * и только если его нет — ставим ноль.
- * Чиним арифметику, а не переписываем остальной ответ провайдера.
+ * We search for a value under known aliases or normalize the existing field first,
+ * and only substitute zero if no numeric value can be recovered.
+ * This restores arithmetic consistency without mutating unrelated provider response fields.
  */
-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
 }
 
 /**
- * Событие с обезвреженной порцией — или то же самое событие, если чинить
- * нечего.
+ * Returns an event with sanitized usage, or the exact same event if no repair was needed.
  *
- * Копия поверхностная и ровно по тому пути, где лежит расход: складыванию
- * достаётся исправное событие, а всё остальное в нём — та же ссылка, что и
- * была.
+ * Performs a shallow copy only along the exact path holding usage data:
+ * state reduction receives the repaired counters while all other event references remain untouched.
  */
-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 {
@@ -202,7 +202,7 @@ export function healed(event, bad) {
   return { ...event, data: { ...event.data, usage } }
 }
 
-/** Безопасная сериализация для журнала: предотвращает сбои на циклических объектах и BigInt. */
+/** Safe JSON stringification for logging: guards against circular references and BigInt values. */
 function safeStringify(value) {
   try {
     return JSON.stringify(value)
@@ -215,11 +215,24 @@ 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}`
+/** Formats a descriptive log line identifying the turn, step, raw payload, and applied repairs. */
+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.10",
   "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",