@goodandready/dsh-usage-guard 0.1.7 → 0.1.9

package/lib/client.js

@@ -22,38 +22,86 @@ window.__ModuleLoader__.load({
       repairDesc: 'Replace missing, non-numeric, or malformed counters with 0 before summing to prevent NaN history lockups.',
       report: 'Log diagnostic warnings',
       reportDesc: 'Log a detailed warning naming the session turn, step, and raw sample whenever damaged usage arrives.',
+      maxStepTokens: 'Token Spike Clamping Limit',
+      maxStepTokensDesc: 'Clamp abnormally huge step usage counters (e.g., > 1,000,000) before projection calculation to prevent integer overflow and corrupted session summaries. Set 0 to disable.',
       stats_title: 'Protection Status',
       stats_mode: 'Current Mode',
       stats_mode_repair: 'Active Repair (Safe)',
       stats_mode_report: 'Audit Only (Unsafe)',
       stats_scope: 'Scope Target',
       stats_scope_val: 'sessionProjections',
+      telemetry_title: 'Live Telemetry',
+      telemetry_rescued: 'Rescued Events',
+      telemetry_tokens: 'Fixed Tokens',
+      telemetry_clamped: 'Clamped Spikes',
+      telemetry_last_incident: 'Last Incident',
+      telemetry_no_incidents: 'No incidents detected (System healthy)',
+      telemetry_refresh: 'Refresh Telemetry',
+      telemetry_refreshing: 'Refreshing…',
+      updater_title: 'Plugin Version & Updates',
+      updater_current: 'Current Version',
+      updater_latest: 'Latest Version',
+      updater_checking: 'Checking…',
+      updater_check: 'Check for Updates',
+      updater_updating: 'Updating…',
+      updater_update_now: 'Update to {version}',
+      updater_up_to_date: 'Plugin is up to date',
+      updater_failed: 'Update check failed',
+      updater_success: 'Update successful. Please reload page.',
     };
 
-    const ru = {
-      title: 'Usage Guard',
-      subtitle: 'Санитайзер расхода токенов и защита от сбоев сессий',
-      header_desc: 'Защищает проекции истории сессий от повреждённых или отсутствующих счётчиков токенов всех LLM-провайдеров.',
-      badge_active: 'Защита активна',
-      badge_report_only: 'Только аудит',
-      'settings.loading': 'Загрузка настроек Usage Guard…',
-      'settings.unavailable': 'Настройки недоступны (пространство хоста ещё не готово).',
-      'settings.retry': 'Повторить попытку',
-      saved: 'Настройки успешно сохранены',
-      save: 'Сохранить изменения',
-      saving: 'Сохранение…',
-      repair: 'Автоматическая починка счётчиков',
-      repairDesc: 'Подставлять 0 вместо пропущенных или нечисловых счётчиков до сложения ядра, предотвращая зависание истории с ошибкой NaN.',
-      report: 'Диагностические предупреждения',
-      reportDesc: 'Выводить в системный журнал подробную строку с указанием сессии, хода, шага и сырой порции при обнаружении повреждений.',
-      stats_title: 'Статус защиты',
-      stats_mode: 'Текущий режим',
-      stats_mode_repair: 'Активная починка (Безопасно)',
-      stats_mode_report: 'Только аудит (Небезопасно)',
-      stats_scope: 'Целевая служба',
+    const zh = {
+      title: 'Token 用量防护',
+      subtitle: 'Token 用量清洗与会话防崩溃保护',
+      header_desc: '保护会话历史投影免受所有 LLM 提供商损坏或缺失的 Token 计数器影响。',
+      badge_active: '保护生效中',
+      badge_report_only: '仅审计',
+      'settings.loading': '正在加载 Usage Guard 设置…',
+      'settings.unavailable': '设置不可用（宿主命名空间尚未就绪）。',
+      'settings.retry': '重试',
+      saved: '设置保存成功',
+      save: '保存更改',
+      saving: '正在保存…',
+      repair: '自动修复 Token 计数器',
+      repairDesc: '在求和前将缺失、非数值或格式错误的计数器替换为 0，防止 NaN 导致会话历史崩溃锁死。',
+      report: '记录诊断告警',
+      reportDesc: '每当收到损坏的用量数据时，记录详细警告并指出会话轮次、步骤和原始样本。',
+      maxStepTokens: '单步 Token 突增削峰阈值',
+      maxStepTokensDesc: '在进行投影计算前，对异常巨大的单步用量计数器（例如 > 1,000,000）进行削峰限制，防止整数溢出与会话汇总异常。设为 0 表示禁用。',
+      stats_title: '保护状态',
+      stats_mode: '当前模式',
+      stats_mode_repair: '主动修复（安全）',
+      stats_mode_report: '仅审计（不安全）',
+      stats_scope: '作用范围',
       stats_scope_val: 'sessionProjections',
+      telemetry_title: '实时拦截指标',
+      telemetry_rescued: '已挽救异常事件',
+      telemetry_tokens: '已修复 Token 数',
+      telemetry_clamped: '削峰拦截次数',
+      telemetry_last_incident: '最近一次拦截事件',
+      telemetry_no_incidents: '未检测到拦截事件（系统运行健康）',
+      telemetry_refresh: '刷新指标',
+      telemetry_refreshing: '正在刷新…',
+      updater_title: '插件版本与在线更新',
+      updater_current: '当前版本',
+      updater_latest: '最新版本',
+      updater_checking: '正在检查…',
+      updater_check: '检查更新',
+      updater_updating: '正在更新…',
+      updater_update_now: '立即更新至 {version}',
+      updater_up_to_date: '已是最新版本',
+      updater_failed: '检查更新失败',
+      updater_success: '更新成功，请刷新页面。',
     };
 
+    function getActiveLocale(c) {
+      try {
+        const cur = (c?.locale && typeof c.locale.get === 'function' ? c.locale.get() : c?.locale?.current) || '';
+        if (typeof cur === 'string' && cur.toLowerCase().startsWith('zh')) return 'zh';
+      } catch (_) {}
+      return 'en';
+    }
+
     function makeT(dict, fallback) {
       return function t(key, vars) {
         let val = (dict && dict[key]) || (fallback && fallback[key]) || key;
@@ -104,21 +152,28 @@ window.__ModuleLoader__.load({
 .ug-row-title{font-size:14px;font-weight:600;color:var(--dsw-alias-label-primary)}
 .ug-field-desc{font-size:13px;color:var(--dsw-alias-label-secondary);line-height:1.4}
 
-.ug-checkbox{width:18px;height:18px;accent-color:var(--dsw-alias-state-brand-primary, #6366f1);cursor:pointer}
+.ug-checkbox{width:18px;height:18px;accent-color:var(--dsw-alias-state-brand-primary);cursor:pointer}
+.ug-number-input{background:var(--dsw-alias-bg-layer-3);border:1px solid var(--dsw-alias-border-l2);border-radius:6px;padding:6px 10px;color:var(--dsw-alias-label-primary);font-size:13px;font-family:inherit;width:140px}
+.ug-number-input:focus{outline:none;border-color:var(--dsw-alias-state-brand-primary)}
 
-.ug-stats-grid{display:grid;grid-template-columns:repeat(auto-fit, minmax(200px, 1fr));gap:10px}
+.ug-stats-grid{display:grid;grid-template-columns:repeat(auto-fit, minmax(180px, 1fr));gap:10px}
 .ug-stat-box{padding:10px 12px;border:1px solid var(--dsw-alias-border-l2);border-radius:8px;background:var(--dsw-alias-bg-layer-2);display:flex;flex-direction:column;gap:2px}
 .ug-stat-val{font-size:13px;font-weight:600;color:var(--dsw-alias-label-primary)}
+.ug-stat-num{font-size:18px;font-weight:700;color:var(--dsw-alias-label-primary);letter-spacing:-0.02em}
 .ug-stat-lbl{font-size:11px;color:var(--dsw-alias-label-secondary)}
 
 .ug-btn{appearance:none;font:inherit;cursor:pointer;border:1px solid var(--dsw-alias-border-l2);border-radius:8px;padding:7px 16px;font-size:13px;background:var(--dsw-alias-bg-layer-2);color:var(--dsw-alias-label-primary);font-weight:500;display:inline-flex;align-items:center;justify-content:center;gap:6px;transition:all .15s ease}
 .ug-btn:hover:not(:disabled){background:var(--dsw-alias-bg-layer-4, var(--dsw-alias-bg-layer-2));border-color:var(--dsw-alias-label-dimmed, var(--dsw-alias-border-l2))}
+.ug-btn-sm{padding:4px 10px;font-size:12px;border-radius:6px}
 .ug-btn-primary{background:var(--dsw-alias-label-primary);color:var(--dsw-alias-bg-layer-3);border-color:transparent}
 .ug-btn-primary:hover:not(:disabled){opacity:0.9}
+.ug-btn-accent{background:var(--dsw-alias-state-brand-primary);color:#ffffff;border-color:transparent}
+.ug-btn-accent:hover:not(:disabled){opacity:0.9}
 .ug-btn:disabled{opacity:0.5;cursor:not-allowed}
 
 .ug-alert-ok{padding:10px 14px;border-radius:8px;background:rgba(16,185,129,0.1);color:var(--dsw-alias-state-success-primary);font-size:13px;border:1px solid rgba(16,185,129,0.2)}
 .ug-alert-bad{padding:10px 14px;border-radius:8px;background:rgba(239,68,68,0.1);color:var(--dsw-alias-state-error-primary);font-size:13px;border:1px solid rgba(239,68,68,0.2)}
+.ug-incident-box{margin-top:6px;padding:8px 10px;border-radius:6px;background:var(--dsw-alias-bg-layer-3);border:1px solid var(--dsw-alias-border-l2);font-size:12px;font-family:monospace;color:var(--dsw-alias-label-secondary);overflow-x:auto}
 `;
       document.head.appendChild(style);
     }
@@ -149,8 +204,8 @@ window.__ModuleLoader__.load({
                 'button',
                 {
                   type: 'button',
-                  className: 'ug-btn',
-                  style: { marginTop: '8px', fontSize: '12px', padding: '4px 10px' },
+                  className: 'ug-btn ug-btn-sm',
+                  style: { marginTop: '8px' },
                   onClick: () => this.setState({ hasError: false, error: null }),
                 },
                 'Retry'
@@ -163,9 +218,222 @@ window.__ModuleLoader__.load({
     }
     const ErrorBoundary = createErrorBoundary();
 
+    function TelemetrySection({ t }) {
+      const [telemetry, setTelemetry] = React.useState(null);
+      const [loading, setLoading] = React.useState(false);
+      const [err, setErr] = React.useState(null);
+
+      const fetchTelemetry = React.useCallback(async () => {
+        setLoading(true);
+        setErr(null);
+        try {
+          const res = await fetch('/api/dsh-usage-guard/telemetry', {
+            headers: { accept: 'application/json' },
+            cache: 'no-store',
+          });
+          if (!res.ok) throw new Error(`HTTP ${res.status}`);
+          const data = await res.json();
+          setTelemetry(data);
+        } catch (e) {
+          setErr(e?.message || String(e));
+        } finally {
+          setLoading(false);
+        }
+      }, []);
+
+      React.useEffect(() => {
+        fetchTelemetry();
+      }, [fetchTelemetry]);
+
+      const recent = telemetry?.recentIncidents || [];
+      const lastIncident = recent.length > 0 ? recent[recent.length - 1] : null;
+
+      return React.createElement(
+        'div',
+        { className: 'ug-field-card' },
+        React.createElement(
+          'div',
+          { style: { display: 'flex', alignItems: 'center', justifyContent: 'space-between' } },
+          React.createElement('span', { className: 'ug-row-title' }, t('telemetry_title')),
+          React.createElement(
+            'button',
+            {
+              type: 'button',
+              className: 'ug-btn ug-btn-sm',
+              onClick: fetchTelemetry,
+              disabled: loading,
+            },
+            loading ? t('telemetry_refreshing') : t('telemetry_refresh')
+          )
+        ),
+        err
+          ? React.createElement('div', { className: 'ug-alert-bad', style: { padding: '6px 10px', fontSize: '12px' } }, err)
+          : null,
+        React.createElement(
+          'div',
+          { className: 'ug-stats-grid', style: { marginTop: '8px' } },
+          React.createElement(
+            'div',
+            { className: 'ug-stat-box' },
+            React.createElement('span', { className: 'ug-stat-lbl' }, t('telemetry_rescued')),
+            React.createElement('span', { className: 'ug-stat-num', style: { color: 'var(--dsw-alias-state-success-primary)' } }, String(telemetry?.rescuedEvents ?? 0))
+          ),
+          React.createElement(
+            'div',
+            { className: 'ug-stat-box' },
+            React.createElement('span', { className: 'ug-stat-lbl' }, t('telemetry_tokens')),
+            React.createElement('span', { className: 'ug-stat-num', style: { color: 'var(--dsw-alias-state-brand-primary)' } }, Number(telemetry?.fixedTokens ?? 0).toLocaleString())
+          ),
+          React.createElement(
+            'div',
+            { className: 'ug-stat-box' },
+            React.createElement('span', { className: 'ug-stat-lbl' }, t('telemetry_clamped')),
+            React.createElement('span', { className: 'ug-stat-num', style: { color: 'var(--dsw-alias-state-warning-primary)' } }, String(telemetry?.clampedSpikes ?? 0))
+          )
+        ),
+        React.createElement(
+          'div',
+          { style: { marginTop: '8px' } },
+          React.createElement('div', { className: 'ug-stat-lbl' }, t('telemetry_last_incident')),
+          lastIncident
+            ? React.createElement(
+                'div',
+                { className: 'ug-incident-box' },
+                `[${lastIncident.timestamp}] ${lastIncident.kind || 'incident'} | Turn: ${lastIncident.turn ?? '-'} Step: ${lastIncident.step ?? '-'} | Target: ${lastIncident.target || '-'}`
+              )
+            : React.createElement(
+                'div',
+                { style: { fontSize: '12px', color: 'var(--dsw-alias-state-success-primary)', marginTop: '4px' } },
+                `✓ ${t('telemetry_no_incidents')}`
+              )
+        )
+      );
+    }
+
+    function UpdaterSection({ t }) {
+      const [status, setStatus] = React.useState(null);
+      const [loading, setLoading] = React.useState(false);
+      const [updating, setUpdating] = React.useState(false);
+      const [feedback, setFeedback] = React.useState({ text: '', ok: true });
+
+      const checkUpdate = React.useCallback(async () => {
+        setLoading(true);
+        setFeedback({ text: '', ok: true });
+        try {
+          const res = await fetch('/api/dsh-usage-guard/update', {
+            headers: { accept: 'application/json' },
+            cache: 'no-store',
+          });
+          if (!res.ok) throw new Error(`HTTP ${res.status}`);
+          const data = await res.json();
+          setStatus(data);
+        } catch (e) {
+          setFeedback({ text: `${t('updater_failed')}: ${e?.message || String(e)}`, ok: false });
+        } finally {
+          setLoading(false);
+        }
+      }, [t]);
+
+      const onUpdateNow = async () => {
+        setUpdating(true);
+        setFeedback({ text: '', ok: true });
+        try {
+          const res = await fetch('/api/dsh-usage-guard/update', {
+            method: 'POST',
+            headers: {
+              'x-dsh-plugin-update': '1',
+              'content-type': 'application/json',
+            },
+          });
+          const data = await res.json();
+          if (!res.ok) throw new Error(data?.error || `HTTP ${res.status}`);
+          setStatus(data);
+          setFeedback({ text: t('updater_success'), ok: true });
+        } catch (e) {
+          setFeedback({ text: e?.message || String(e), ok: false });
+        } finally {
+          setUpdating(false);
+        }
+      };
+
+      React.useEffect(() => {
+        checkUpdate();
+      }, [checkUpdate]);
+
+      const currentVer = status?.currentVersion || '0.1.9';
+      const latestVer = status?.latestVersion;
+      const updateAvailable = !!status?.updateAvailable && !!latestVer && latestVer !== currentVer;
+
+      return React.createElement(
+        'div',
+        { className: 'ug-field-card' },
+        React.createElement(
+          'div',
+          { style: { display: 'flex', alignItems: 'center', justifyContent: 'space-between' } },
+          React.createElement('span', { className: 'ug-row-title' }, t('updater_title')),
+          React.createElement(
+            'button',
+            {
+              type: 'button',
+              className: 'ug-btn ug-btn-sm',
+              onClick: checkUpdate,
+              disabled: loading || updating,
+            },
+            loading ? t('updater_checking') : t('updater_check')
+          )
+        ),
+        React.createElement(
+          'div',
+          { style: { display: 'flex', alignItems: 'center', gap: '16px', marginTop: '6px', fontSize: '13px' } },
+          React.createElement(
+            'div',
+            null,
+            React.createElement('span', { className: 'ug-stat-lbl' }, t('updater_current') + ': '),
+            React.createElement('strong', { style: { color: 'var(--dsw-alias-label-primary)' } }, `v${currentVer}`)
+          ),
+          latestVer
+            ? React.createElement(
+                'div',
+                null,
+                React.createElement('span', { className: 'ug-stat-lbl' }, t('updater_latest') + ': '),
+                React.createElement(
+                  'strong',
+                  { style: { color: updateAvailable ? 'var(--dsw-alias-state-warning-primary)' : 'var(--dsw-alias-state-success-primary)' } },
+                  `v${latestVer}`
+                )
+              )
+            : null
+        ),
+        updateAvailable
+          ? React.createElement(
+              'div',
+              { style: { marginTop: '8px', display: 'flex', alignItems: 'center', justifyContent: 'space-between', padding: '8px 12px', background: 'rgba(245,158,11,0.08)', borderRadius: '6px', border: '1px solid rgba(245,158,11,0.2)' } },
+              React.createElement('span', { style: { fontSize: '12px', color: 'var(--dsw-alias-state-warning-primary)', fontWeight: 500 } }, `New release available: v${latestVer}`),
+              React.createElement(
+                'button',
+                {
+                  type: 'button',
+                  className: 'ug-btn ug-btn-sm ug-btn-accent',
+                  onClick: onUpdateNow,
+                  disabled: updating,
+                },
+                updating ? t('updater_updating') : t('updater_update_now', { version: latestVer })
+              )
+            )
+          : null,
+        feedback.text
+          ? React.createElement(
+              'div',
+              { className: feedback.ok ? 'ug-alert-ok' : 'ug-alert-bad', style: { marginTop: '8px', padding: '6px 10px', fontSize: '12px' } },
+              feedback.text
+            )
+          : null
+      );
+    }
+
     function SettingsPage({ ctx, t }) {
       const [snap, setSnap] = React.useState({ status: 'loading', value: {} });
-      const [draft, setDraft] = React.useState({ repair: true, report: true });
+      const [draft, setDraft] = React.useState({ repair: true, report: true, maxStepTokens: 1000000 });
       const [saving, setSaving] = React.useState(false);
       const [msg, setMsg] = React.useState({ text: '', ok: true });
       const isDirtyRef = React.useRef(false);
@@ -190,6 +458,7 @@ window.__ModuleLoader__.load({
                   setDraft({
                     repair: res.repair !== false,
                     report: res.report !== false,
+                    maxStepTokens: typeof res.maxStepTokens === 'number' ? res.maxStepTokens : 1000000,
                   });
                 }
               }
@@ -206,6 +475,7 @@ window.__ModuleLoader__.load({
                   setDraft({
                     repair: next.repair !== false,
                     report: next.report !== false,
+                    maxStepTokens: typeof next.maxStepTokens === 'number' ? next.maxStepTokens : 1000000,
                   });
                 }
               })
@@ -243,13 +513,23 @@ window.__ModuleLoader__.load({
         setDraft((prev) => ({ ...prev, [field]: checked }));
       };
 
+      const handleNumberChange = (field, rawVal) => {
+        isDirtyRef.current = true;
+        if (msg.text) {
+          if (msgTimerRef.current) clearTimeout(msgTimerRef.current);
+          setMsg({ text: '', ok: true });
+        }
+        const val = rawVal === '' ? 0 : Number(rawVal);
+        setDraft((prev) => ({ ...prev, [field]: isNaN(val) ? 0 : val }));
+      };
+
       const onSave = async () => {
         if (!ctx?.settingsScope || typeof ctx.settingsScope.bind !== 'function') return;
         setSaving(true);
         try {
           const scope = ctx.settingsScope.bind({ namespace: NS });
           const errs = [];
-          for (const k of ['repair', 'report']) {
+          for (const k of ['repair', 'report', 'maxStepTokens']) {
             try {
               await scope.set(k, draft[k]);
             } catch (e) {
@@ -353,6 +633,27 @@ window.__ModuleLoader__.load({
           React.createElement('div', { className: 'ug-field-desc' }, t('reportDesc'))
         ),
 
+        // Field 3: maxStepTokens
+        React.createElement(
+          'div',
+          { className: 'ug-field-card' },
+          React.createElement(
+            'div',
+            { className: 'ug-row' },
+            React.createElement('label', { className: 'ug-row-title', htmlFor: 'ug-tokens-input' }, t('maxStepTokens')),
+            React.createElement('input', {
+              id: 'ug-tokens-input',
+              type: 'number',
+              className: 'ug-number-input',
+              min: 0,
+              step: 10000,
+              value: draft.maxStepTokens ?? 1000000,
+              onChange: (e) => handleNumberChange('maxStepTokens', e.target.value),
+            })
+          ),
+          React.createElement('div', { className: 'ug-field-desc' }, t('maxStepTokensDesc'))
+        ),
+
         // Feedback message
         msg.text
           ? React.createElement(
@@ -362,7 +663,7 @@ window.__ModuleLoader__.load({
             )
           : null,
 
-        // Actions
+        // Save action
         React.createElement(
           'div',
           { style: { display: 'flex', justifyContent: 'flex-end', gap: '8px', marginTop: '4px' } },
@@ -376,14 +677,23 @@ window.__ModuleLoader__.load({
             },
             saving ? t('saving') : t('save')
           )
-        )
+        ),
+
+        // Live Telemetry section
+        React.createElement(TelemetrySection, { t }),
+
+        // Updater section
+        React.createElement(UpdaterSection, { t })
       );
     }
 
     // Accordion PluginCard for settings.plugin.item
     function PluginCard(props) {
       const [open, setOpen] = React.useState(false);
-      const t = props?.t || makeT(ru, en);
+      const hostCtx = (props && props.ctx) || ctx;
+      const locale = getActiveLocale(hostCtx);
+      const dict = locale === 'zh' ? zh : en;
+      const t = props?.t || makeT(dict, en);
 
       React.useEffect(() => {
         ensureCss();
@@ -430,7 +740,7 @@ window.__ModuleLoader__.load({
               null,
               React.createElement(SettingsPage, {
                 ...props,
-                ctx: (props && props.ctx) || ctx,
+                ctx: hostCtx,
                 t,
               })
             )
@@ -438,10 +748,10 @@ window.__ModuleLoader__.load({
       );
     }
 
-    function refreshMirrorUntilVisible(ctx) {
+    function refreshMirrorUntilVisible(c) {
       const visible = () => {
         try {
-          const s = (ctx?.get && ctx.get('lanSettings')) || ctx?.settingsScope;
+          const s = (c?.get && c.get('lanSettings')) || c?.settingsScope;
           const view = s?.describe?.()?.getSnapshot?.()?.view;
           return !!view && Array.isArray(view.namespaces) && view.namespaces.some((row) => row.ns === NS);
         } catch (_) {
@@ -457,7 +767,7 @@ window.__ModuleLoader__.load({
         }
         tries += 1;
         try {
-          const s = (ctx?.get && ctx.get('lanSettings')) || ctx?.settingsScope;
+          const s = (c?.get && c.get('lanSettings')) || c?.settingsScope;
           s?.describe?.()?.load?.();
         } catch (_) {}
       }, 1000);
@@ -482,14 +792,14 @@ window.__ModuleLoader__.load({
       if (ctx.locale && typeof ctx.locale.register === 'function') {
         if (typeof ctx.effect === 'function') {
           ctx.effect(() => {
-            const undo = [addLocale('en', en), addLocale('ru', ru)];
+            const undo = [addLocale('en', en), addLocale('zh', zh)];
             return () => {
               for (const off of undo) off();
             };
           }, 'dsh-usage-guard: dictionaries');
         } else {
           addLocale('en', en);
-          addLocale('ru', ru);
+          addLocale('zh', zh);
         }
       }
 
@@ -549,6 +859,7 @@ window.__ModuleLoader__.load({
       makeT,
       ensureCss,
       createErrorBoundary,
+      getActiveLocale,
     };
     return module.exports;
   },