@goodandready/dsh-clinebot 0.6.3 → 0.6.4

package/CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to `@goodandready/dsh-clinebot` will be documented in this f
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.6.4] - 2026-10-21
+
+### Added
+- **Analytics UX**: latency percentiles P50/P95 (compact histograms), a clickable weekday×hour heatmap with cell detail, JSON export at `GET /stats/export?format=json`, and configurable `statsRetentionDays` for day/hour/session telemetry (default 95, 0 keeps everything).
+- Retention is exposed in Settings → ClineBot → Advanced and the TUI; JSON export is available beside CSV.
+
 ## [0.6.3] - 2026-10-21
 
 ### Added

package/README.md

@@ -4,7 +4,7 @@
 
 <h3>Native ClineBot / ClinePass Provider Companion for DeepSeek Harness</h3>
 
-<p><b>0.6.3</b> adds quota burn-down forecasts and optional daily/monthly spend guards on top of the adapter-only line. Chat runs on the native <code>ctx.llm</code> adapter and requires DSH <code>0.2.1-rc.2</code>; the legacy <code>llm-pi-ai</code>, loopback proxy and <code>llm/stream</code> path are removed.</p>
+<p><b>0.6.4</b> adds P50/P95 latency, clickable heatmap detail, JSON export and configurable retention on top of quota forecasts and spend guards. Chat runs on the native <code>ctx.llm</code> adapter and requires DSH <code>0.2.1-rc.2</code>; the legacy <code>llm-pi-ai</code>, loopback proxy and <code>llm/stream</code> path are removed.</p>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/@goodandready/dsh-clinebot"><img src="https://img.shields.io/npm/v/@goodandready/dsh-clinebot.svg?style=for-the-badge&color=6366f1&labelColor=1e1b4b" alt="npm version"></a>
@@ -197,6 +197,7 @@ dsh-clinebot:
     your-reasoning-model: high
   modelContextOverrides: []
   statsPath: ~/.dsh/clinebot-stats.json
+  statsRetentionDays: 95
   dailyBudgetUsd: 0
   monthlyBudgetUsd: 0
   timeoutMs: 30000
@@ -220,6 +221,7 @@ dsh-clinebot:
 | `modelReasoningDefaults` | `object` | `{}` | Configured default reasoning effort per model (`low`, `medium`, `high`, `max`) |
 | `modelContextOverrides` | `array` | `[]` | User-defined model context length and max token overrides |
 | `statsPath` | `string` | `"~/.dsh/clinebot-stats.json"` | Persistent on-disk path for token usage analytics |
+| `statsRetentionDays` | `number` | `95` | Retention for day/hour/session telemetry; 0 keeps everything |
 | `dailyBudgetUsd` | `number` | `0` | Optional estimated daily spend guard; 0 disables it |
 | `monthlyBudgetUsd` | `number` | `0` | Optional estimated monthly spend guard; 0 disables it |
 | `accounts` | `array` | `[]` | Additional accounts for multi-account failover and quota rotation (`[{ label, apiKeyEnv }]`) |

package/README.ru.md

@@ -4,7 +4,7 @@
 
 <h3>Нативное подключение провайдера ClineBot / ClinePass для DeepSeek Harness</h3>
 
-<p><b>0.6.3</b> добавляет прогноз расхода квоты и опциональные дневной/месячный лимиты трат. Чат работает через нативный адаптер <code>ctx.llm</code>, требуется DSH <code>0.2.1-rc.2</code>; старые <code>llm-pi-ai</code>, loopback-прокси и <code>llm/stream</code> удалены.</p>
+<p><b>0.6.4</b> добавляет P50/P95 задержки, кликабельный heatmap, JSON-экспорт и настраиваемый retention поверх прогноза квоты и лимитов трат. Чат работает через нативный адаптер <code>ctx.llm</code>, требуется DSH <code>0.2.1-rc.2</code>; старые <code>llm-pi-ai</code>, loopback-прокси и <code>llm/stream</code> удалены.</p>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/@goodandready/dsh-clinebot"><img src="https://img.shields.io/npm/v/@goodandready/dsh-clinebot.svg?style=for-the-badge&color=6366f1&labelColor=1e1b4b" alt="npm version"></a>
@@ -166,6 +166,7 @@ dsh-clinebot:
     your-reasoning-model: high
   modelContextOverrides: []
   statsPath: ~/.dsh/clinebot-stats.json
+  statsRetentionDays: 95
   dailyBudgetUsd: 0
   monthlyBudgetUsd: 0
   timeoutMs: 30000
@@ -189,6 +190,7 @@ dsh-clinebot:
 | `modelReasoningDefaults` | `object` | `{}` | Значения thinking effort по умолчанию для моделей (`low`, `medium`, `high`, `max`) |
 | `modelContextOverrides` | `array` | `[]` | Пользовательские переопределения размера контекста и лимита токенов |
 | `statsPath` | `string` | `"~/.dsh/clinebot-stats.json"` | Путь к файлу персистентной аналитики использования токенов |
+| `statsRetentionDays` | `number` | `95` | Срок хранения дневной/часовой/сессионной телеметрии; 0 — хранить всё |
 | `dailyBudgetUsd` | `number` | `0` | Опциональный дневной лимит оценочных трат; 0 отключает |
 | `monthlyBudgetUsd` | `number` | `0` | Опциональный месячный лимит оценочных трат; 0 отключает |
 | `accounts` | `array` | `[]` | Дополнительные аккаунты для ротации квоты и failover (`[{ label, apiKeyEnv }]`) |

package/README.zh.md

@@ -4,7 +4,7 @@
 
 <h3>适用于 DeepSeek Harness 的 ClineBot / ClinePass 原生模型提供商伴侣插件</h3>
 
-<p><b>0.6.3</b> 添加配额消耗预测和可选的每日/每月花费上限。聊天使用原生 <code>ctx.llm</code> 适配器，需要 DSH <code>0.2.1-rc.2</code>；旧的 <code>llm-pi-ai</code>、回环代理和 <code>llm/stream</code> 已删除。</p>
+<p><b>0.6.4</b> 添加 P50/P95 延迟、可点击热力图、JSON 导出和可配置保留期，并保留配额预测与花费上限。聊天使用原生 <code>ctx.llm</code> 适配器，需要 DSH <code>0.2.1-rc.2</code>；旧的 <code>llm-pi-ai</code>、回环代理和 <code>llm/stream</code> 已删除。</p>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/@goodandready/dsh-clinebot"><img src="https://img.shields.io/npm/v/@goodandready/dsh-clinebot.svg?style=for-the-badge&color=6366f1&labelColor=1e1b4b" alt="npm version"></a>
@@ -168,6 +168,7 @@ dsh-clinebot:
     your-reasoning-model: high
   modelContextOverrides: []
   statsPath: ~/.dsh/clinebot-stats.json
+  statsRetentionDays: 95
   dailyBudgetUsd: 0
   monthlyBudgetUsd: 0
   timeoutMs: 30000
@@ -191,6 +192,7 @@ dsh-clinebot:
 | `modelReasoningDefaults` | `object` | `{}` | 各模型默认思考强度配置 (`low`, `medium`, `high`, `max`) |
 | `modelContextOverrides` | `array` | `[]` | 用户自定义模型上下文窗口与最大 Token 数量覆盖 |
 | `statsPath` | `string` | `"~/.dsh/clinebot-stats.json"` | 本地持久化 Token 用量统计文件路径 |
+| `statsRetentionDays` | `number` | `95` | 日/小时/会话遥测保留天数；0 表示永久保留 |
 | `dailyBudgetUsd` | `number` | `0` | 可选的每日估算花费上限；0 表示关闭 |
 | `monthlyBudgetUsd` | `number` | `0` | 可选的每月估算花费上限；0 表示关闭 |
 | `accounts` | `array` | `[]` | 额外轮转账号池 (`[{ label, apiKeyEnv }]`) |

package/lib/client.js

@@ -195,7 +195,7 @@ const en = {
       'stats.requests': 'Successful / Total Requests',
       'stats.tokens': 'Estimated Session Tokens',
       'stats.reasoning_tokens': 'Reasoning Tokens (Thinking)',
-      'stats.export_csv': 'Export CSV',
+      'stats.export_csv': 'Export CSV', 'stats.export_json': 'Export JSON',
       'stats.latency': 'Last Request Latency',
       'stats.last_req': 'Last Request Time',
       'models.custom_add_title': 'Custom Models',
@@ -260,6 +260,7 @@ const en = {
       'settings.base_url': 'API base URL', 'settings.base_url_hint': 'ClinePass API root. Remote endpoints must use https://.',
       'settings.timeout': 'Connect timeout (ms)', 'settings.timeout_hint': 'Maximum wait for the upstream response headers.', 'settings.smoke_timeout': 'Smoke-test timeout (ms)', 'settings.smoke_timeout_hint': 'Maximum wait for the diagnostic chat completion.',
       'settings.stream_idle': 'Stream idle timeout (ms)', 'settings.stream_idle_hint': 'Maximum gap between SSE chunks before the stream is treated as dead.', 'settings.max_payload': 'Max multimodal payload (MB)', 'settings.max_payload_hint': 'Oldest images are evicted once the request exceeds this budget.',
+      'settings.stats_retention': 'Stats retention (days)', 'settings.stats_retention_hint': 'Trim day/hour/session telemetry older than this. 0 keeps everything.',
       'settings.daily_budget': 'Daily budget (USD)', 'settings.daily_budget_hint': 'Estimated spend guard for the current UTC day. 0 disables it.', 'settings.monthly_budget': 'Monthly budget (USD)', 'settings.monthly_budget_hint': 'Estimated spend guard for the current UTC month. 0 disables it.',
       'settings.stats_path': 'Stats file path', 'settings.stats_path_hint': 'Persistent JSON telemetry path (supports ~/).', 'settings.models_cache_path': 'Models cache path', 'settings.models_cache_path_hint': 'Offline model catalogue cache (supports ~/).',
       'providerCard.title': 'ClineBot (ClinePass)',
@@ -286,7 +287,9 @@ const en = {
       'analytics.heatmap_empty': 'No hourly data yet. Send a message to start the heatmap.',
       'analytics.input': 'Input', 'analytics.output': 'Output', 'analytics.reasoning': 'Reasoning',
       'analytics.cache_read': 'Cache read', 'analytics.cache_write': 'Cache write',
-      'analytics.avg_ttft': 'Avg TTFT', 'analytics.avg_latency': 'Avg latency', 'analytics.errors': 'Errors',
+      'analytics.avg_ttft': 'Avg TTFT', 'analytics.avg_latency': 'Avg latency',
+      'analytics.p50_latency': 'P50 latency', 'analytics.p95_latency': 'P95 latency',
+      'analytics.heatmap_selected': '{day} {hour}:00 — {count} requests. Click the cell again to clear.', 'analytics.errors': 'Errors',
       'analytics.no_key': 'ClinePass key is not configured.',
       'analytics.no_key_hint': 'Open Settings → ClineBot and paste a key, or import a discovered local key.',
       'analytics.health_error': 'ClinePass endpoint is unreachable.',
@@ -477,7 +480,7 @@ const zh = {
       'stats.requests': '成功 / 总请求次数',
       'stats.tokens': '会话累计 Token 估算',
       'stats.reasoning_tokens': '深度思考 Token 消耗',
-      'stats.export_csv': '导出 CSV',
+      'stats.export_csv': '导出 CSV', 'stats.export_json': '导出 JSON',
       'stats.latency': '最近一次请求延迟',
       'stats.last_req': '最近请求时间',
       'models.custom_add_title': '自定义模型',
@@ -542,6 +545,7 @@ const zh = {
       'settings.base_url': 'API 基础地址', 'settings.base_url_hint': 'ClinePass API 根地址。远程端点必须使用 https://。',
       'settings.timeout': '连接超时（毫秒）', 'settings.timeout_hint': '等待上游响应头的最大时间。', 'settings.smoke_timeout': '烟雾测试超时（毫秒）', 'settings.smoke_timeout_hint': '等待诊断聊天补全的最大时间。',
       'settings.stream_idle': '流空闲超时（毫秒）', 'settings.stream_idle_hint': 'SSE 数据块之间的最大间隔，超过后视为断流。', 'settings.max_payload': '多模态负载上限（MB）', 'settings.max_payload_hint': '请求超过预算时会淘汰最旧的图片。',
+      'settings.stats_retention': '统计保留天数', 'settings.stats_retention_hint': '超过该天数的日/小时/会话遥测会被清理。0 表示永久保留。',
       'settings.daily_budget': '每日预算（USD）', 'settings.daily_budget_hint': '按当前 UTC 日估算的花费上限。0 表示关闭。', 'settings.monthly_budget': '每月预算（USD）', 'settings.monthly_budget_hint': '按当前 UTC 月估算的花费上限。0 表示关闭。',
       'settings.stats_path': '统计文件路径', 'settings.stats_path_hint': '持久化 JSON 遥测路径（支持 ~/）。', 'settings.models_cache_path': '模型缓存路径', 'settings.models_cache_path_hint': '离线模型目录缓存（支持 ~/）。',
       'providerCard.title': 'ClineBot（ClinePass）',
@@ -569,6 +573,8 @@ const zh = {
       'analytics.input': '输入', 'analytics.output': '输出', 'analytics.reasoning': '推理',
       'analytics.cache_read': '缓存读取', 'analytics.cache_write': '缓存写入',
       'analytics.avg_ttft': '平均首字延迟', 'analytics.avg_latency': '平均延迟', 'analytics.errors': '错误',
+      'analytics.p50_latency': 'P50 延迟', 'analytics.p95_latency': 'P95 延迟',
+      'analytics.heatmap_selected': '{day} {hour}:00 — {count} 次请求。再次点击可清除。',
       'analytics.no_key': '尚未配置 ClinePass 密钥。',
       'analytics.no_key_hint': '打开“设置 → ClineBot”粘贴密钥，或导入已发现的本地密钥。',
       'analytics.health_error': 'ClinePass 端点不可达。',
@@ -1033,7 +1039,9 @@ function ensureCss() {
 .cb-heat-hour{color:var(--dsw-alias-label-tertiary);font-size:9px;line-height:12px;text-align:center}
 .cb-heat-day{color:var(--dsw-alias-label-secondary);font-size:10px;line-height:14px;white-space:nowrap}
 .cb-heat-cell,.cb-heat-swatch{display:block;border-radius:3px;background:var(--dsw-alias-bg-layer-2)}
-.cb-heat-cell{height:14px}
+.cb-heat-cell{height:14px;border:0;padding:0;cursor:pointer}
+.cb-heat-cell:focus-visible{outline:2px solid var(--dsw-alias-brand-primary);outline-offset:-2px}
+.cb-heat-cell.cb-heat-selected{outline:2px solid var(--dsw-alias-brand-primary);outline-offset:-2px}
 .cb-heat-swatch{width:12px;height:12px;border-radius:2px}
 .cb-heat-l0{background:var(--dsw-alias-bg-layer-2)}
 .cb-heat-l1{background:color-mix(in srgb,var(--dsw-alias-brand-primary) 18%,var(--dsw-alias-bg-layer-2))}
@@ -1762,6 +1770,14 @@ function AdvancedSection({ draft, onStage, t }) {
       type: 'number',
       onChange: numeric('maxPayloadMb', 0),
     }),
+    React.createElement(AdvancedField, {
+      id: 'cb-retention',
+      label: t('settings.stats_retention'),
+      hint: t('settings.stats_retention_hint'),
+      value: current.statsRetentionDays,
+      type: 'number',
+      onChange: numeric('statsRetentionDays', -1),
+    }),
     React.createElement(AdvancedField, {
       id: 'cb-daily-budget',
       label: t('settings.daily_budget'),
@@ -3519,6 +3535,16 @@ function StatsSection({ status, onResetStats, busy, t }) {
       React.createElement(
         'div',
         { className: 'cb-section-actions' },
+        React.createElement(
+          'a',
+          {
+            href: '/dsh-clinebot/stats/export?format=json',
+            download: 'clinebot-stats.json',
+            className: 'cb-btn cb-btn-link',
+          },
+          React.createElement(CbIcon, { name: 'download', size: 13 }),
+          ` ${t('stats.export_json')}`
+        ),
         React.createElement(
           'a',
           {
@@ -3957,7 +3983,7 @@ function heatHourLabel(hour) {
   return hour % 3 === 0 ? String(hour).padStart(2, '0') : ''
 }
 
-function HeatmapView({ heatmap, model, onModelChange, t }) {
+function HeatmapView({ heatmap, model, onModelChange, onSelect, selected, t }) {
   if (!heatmap || !Array.isArray(heatmap.grid)) {
     return React.createElement('div', { className: 'cb-hint' }, t('analytics.heatmap_empty'))
   }
@@ -4021,10 +4047,14 @@ function HeatmapView({ heatmap, model, onModelChange, t }) {
           React.Fragment,
           { key: `day-${day}` },
           React.createElement('span', { className: 'cb-heat-day' }, label),
-          (grid[day] || []).map((value, hour) => React.createElement('span', {
+          (grid[day] || []).map((value, hour) => React.createElement('button', {
             key: `cell-${day}-${hour}`,
-            className: `cb-heat-cell cb-heat-l${level(value)}`,
+            type: 'button',
+            className: `cb-heat-cell cb-heat-l${level(value)}${selected?.day === day && selected?.hour === hour ? ' cb-heat-selected' : ''}`,
             title: `${label} ${String(hour).padStart(2, '0')}:00 — ${value} ${t('analytics.requests')}`,
+            'aria-label': `${label} ${String(hour).padStart(2, '0')}:00 — ${value}`,
+            'aria-pressed': selected?.day === day && selected?.hour === hour,
+            onClick: () => onSelect && onSelect({ day, hour, value, label }),
           }))
         ))
       ),
@@ -4196,6 +4226,7 @@ function DashboardDialog(props) {
   const [selectedAccount, setSelectedAccount] = React.useState('')
   const [analyticsDays, setAnalyticsDays] = React.useState(7)
   const [heatmapModel, setHeatmapModel] = React.useState('')
+  const [selectedHeat, setSelectedHeat] = React.useState(null)
 
   const loadData = React.useCallback(async () => {
     setLoading(true)
@@ -4370,6 +4401,8 @@ function DashboardDialog(props) {
         [t('analytics.cache_write'), fmtTokens(totals.cacheWriteTokens)],
         [t('analytics.avg_ttft'), fmtMs(totals.avgTtftMs)],
         [t('analytics.avg_latency'), fmtMs(totals.avgLatencyMs)],
+        [t('analytics.p50_latency'), fmtMs(totals.p50LatencyMs)],
+        [t('analytics.p95_latency'), fmtMs(totals.p95LatencyMs)],
         [t('analytics.errors'), String(Math.round(Number(totals.failed) || 0))],
       ]
     : []
@@ -4522,8 +4555,19 @@ function DashboardDialog(props) {
       heatmap: analytics?.heatmap,
       model: heatmapModel,
       onModelChange: setHeatmapModel,
+      selected: selectedHeat,
+      onSelect: (cell) => setSelectedHeat((current) => (
+        current && current.day === cell.day && current.hour === cell.hour ? null : cell
+      )),
       t,
-    })
+    }),
+    selectedHeat
+      ? React.createElement('div', { className: 'cb-hint' }, t('analytics.heatmap_selected', {
+          day: selectedHeat.label,
+          hour: String(selectedHeat.hour).padStart(2, '0'),
+          count: selectedHeat.value,
+        }))
+      : null
   )
 
   const panelBody = React.createElement(

package/lib/config.js

@@ -99,6 +99,8 @@ export const Config = z.object({
     .description('User-defined custom gateway models.').volatile(),
   statsPath: z.string().default('~/.dsh/clinebot-stats.json')
     .description('Local on-disk persistent path for token usage analytics.').volatile(),
+  statsRetentionDays: z.number().min(0).max(3650).default(95)
+    .description('Retention for day/hour/session telemetry in days. 0 keeps everything.').volatile(),
   dailyBudgetUsd: z.number().min(0).default(0)
     .description('Optional daily estimated-spend guard in USD. 0 disables the guard.').volatile(),
   monthlyBudgetUsd: z.number().min(0).default(0)
@@ -242,6 +244,9 @@ export function publicConfig(cfg) {
     modelRoutes: cfg?.modelRoutes && typeof cfg.modelRoutes === 'object' ? cfg.modelRoutes : {},
     customModels: custom,
     statsPath: String(cfg?.statsPath || '~/.dsh/clinebot-stats.json'),
+    statsRetentionDays: Number.isFinite(Number(cfg?.statsRetentionDays))
+      ? Math.max(0, Math.min(3650, Number(cfg.statsRetentionDays)))
+      : 95,
     dailyBudgetUsd: Math.max(0, Number(cfg?.dailyBudgetUsd) || 0),
     monthlyBudgetUsd: Math.max(0, Number(cfg?.monthlyBudgetUsd) || 0),
     disabledModels: disabledList,

package/lib/index.js

@@ -20,7 +20,7 @@ import { ClineBotAdapter } from './adapter.js'
 import { registerSlashCommand } from './slash-command.js'
 import { ClineBotSearchProvider, CLINEBOT_SEARCH_PROVIDER_ID } from './web-search.js'
 import { resolveAccountPool } from './account-pool.js'
-import { loadStats, flushStats, resolvePath, switchStatsStorage } from './stats-storage.js'
+import { loadStats, flushStats, resolvePath, switchStatsStorage, setStatsRetentionDays } from './stats-storage.js'
 import { service, migrateLegacyPiAiProvider } from './services.js'
 import { applyTuiSettings } from './tui-settings.js'
 
@@ -91,10 +91,13 @@ export function apply(ctx, config) {
   }
 
   let activeStatsPath = resolvePath(publicConfig(live()).statsPath)
+  setStatsRetentionDays(publicConfig(live()).statsRetentionDays)
   loadStats(activeStatsPath)
 
   const syncStatsStorage = (cfg) => {
-    const nextPath = resolvePath(publicConfig(cfg).statsPath)
+    const pub = publicConfig(cfg)
+    setStatsRetentionDays(pub.statsRetentionDays)
+    const nextPath = resolvePath(pub.statsPath)
     if (nextPath !== activeStatsPath) {
       switchStatsStorage(nextPath)
       activeStatsPath = nextPath

package/lib/routes/settings.js

@@ -4,6 +4,7 @@ import { publicConfig, plainConfig, Config } from '../config.js'
 import { buildStatus } from '../provider-sync.js'
 import { saveCredentialKey, smokeChat, DEFAULT_API_KEY_ENV } from '../cline-client.js'
 import { getStatsSummary, getSessionStats, resetStats, exportStatsAsCsv, getAnalytics } from '../stats-storage.js'
+import { exportStatsAsJson } from '../stats-export.js'
 import { priceTable } from '../model-prices.js'
 
 export function registerSettingsRoutes(ctx, { live, getSettingsApi, syncProviderState, triggerAutoDiscover }) {
@@ -241,11 +242,21 @@ export function registerSettingsRoutes(ctx, { live, getSettingsApi, syncProvider
       if (!assertTrustedSettingsRequest(req, res, ctx)) return
       try {
         let detailed = false
+        let format = 'csv'
         try {
-          detailed = new URL(req.url, 'http://127.0.0.1').searchParams.get('detailed') === '1'
+          const url = new URL(req.url, 'http://127.0.0.1')
+          detailed = url.searchParams.get('detailed') === '1'
+          format = url.searchParams.get('format') === 'json' ? 'json' : 'csv'
         } catch {
           detailed = false
         }
+        if (format === 'json') {
+          res.statusCode = 200
+          res.setHeader('Content-Type', 'application/json; charset=utf-8')
+          res.setHeader('Content-Disposition', 'attachment; filename="clinebot-stats.json"')
+          res.end(exportStatsAsJson())
+          return
+        }
         const csv = exportStatsAsCsv(detailed)
         res.statusCode = 200
         res.setHeader('Content-Type', 'text/csv; charset=utf-8')

package/lib/stats-export.js

@@ -0,0 +1,11 @@
+import { getStatsSummary } from './stats-storage.js'
+
+/**
+ * Export the complete persisted telemetry document as JSON.
+ */
+export function exportStatsAsJson() {
+  return JSON.stringify({
+    exportedAt: new Date().toISOString(),
+    stats: getStatsSummary(),
+  }, null, 2)
+}

package/lib/stats-metrics.js

@@ -0,0 +1,68 @@
+/**
+ * Compact latency histograms and retention pruning for the stats store.
+ */
+
+const LATENCY_BOUNDS = [50, 100, 200, 400, 800, 1600, 3200, 6400, 12800, 25600, 51200, 102400, Infinity]
+
+export function latencyBucketIndex(ms) {
+  const value = Math.max(0, Number(ms) || 0)
+  const index = LATENCY_BOUNDS.findIndex((bound) => value <= bound)
+  return index < 0 ? LATENCY_BOUNDS.length - 1 : index
+}
+
+export function mergeHistogram(target, source) {
+  if (!Array.isArray(source)) return target
+  for (let index = 0; index < source.length; index += 1) {
+    target[index] = Number(target[index] || 0) + Number(source[index] || 0)
+  }
+  return target
+}
+
+export function percentileFromHistogram(histogram, percentile) {
+  if (!Array.isArray(histogram)) return 0
+  const total = histogram.reduce((sum, value) => sum + Number(value || 0), 0)
+  if (total <= 0) return 0
+  const target = Math.max(1, Math.ceil((Math.max(1, Math.min(99, percentile)) / 100) * total))
+  let seen = 0
+  for (let index = 0; index < histogram.length; index += 1) {
+    seen += Number(histogram[index] || 0)
+    if (seen >= target) {
+      const bound = LATENCY_BOUNDS[index]
+      return bound === Infinity ? LATENCY_BOUNDS[LATENCY_BOUNDS.length - 2] : bound
+    }
+  }
+  return 0
+}
+
+function localDateKey(date) {
+  return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}-${String(date.getDate()).padStart(2, '0')}`
+}
+
+/**
+ * Prune time buckets and sessions older than the configured retention window.
+ * @param {Record<string, any>} stats
+ * @param {number} days 0 keeps everything
+ * @param {number} [now]
+ */
+export function pruneRetentionOnStats(stats, days, now = Date.now()) {
+  const retentionDays = Math.max(0, Number(days) || 0)
+  if (!stats || retentionDays <= 0) return
+  const cutoffMs = now - retentionDays * 24 * 60 * 60 * 1000
+  const cutoffDay = new Date(cutoffMs).toISOString().slice(0, 10)
+  const cutoffMonth = cutoffDay.slice(0, 7)
+  const cutoffHourDay = localDateKey(new Date(cutoffMs))
+  for (const key of Object.keys(stats.byDay || {})) {
+    if (key < cutoffDay) delete stats.byDay[key]
+  }
+  for (const key of Object.keys(stats.byMonth || {})) {
+    if (key < cutoffMonth) delete stats.byMonth[key]
+  }
+  for (const container of [stats.byHour, stats.byHourModel]) {
+    for (const key of Object.keys(container || {})) {
+      if (key.slice(0, 10) < cutoffHourDay) delete container[key]
+    }
+  }
+  for (const [key, bucket] of Object.entries(stats.bySession || {})) {
+    if (Number(bucket?.lastAt || 0) < cutoffMs) delete stats.bySession[key]
+  }
+}

package/lib/stats-storage.js

@@ -8,6 +8,12 @@
 import { readFileSync, writeFileSync, renameSync, mkdirSync, existsSync, copyFileSync, readdirSync, unlinkSync } from 'node:fs'
 import { homedir } from 'node:os'
 import path from 'node:path'
+import {
+  latencyBucketIndex,
+  mergeHistogram,
+  percentileFromHistogram,
+  pruneRetentionOnStats,
+} from './stats-metrics.js'
 
 const MAX_SESSIONS = 500
 const SESSION_TTL_MS = 90 * 24 * 60 * 60 * 1000
@@ -16,6 +22,17 @@ const HEATMAP_RETENTION_MS = 95 * 24 * 60 * 60 * 1000
 let inMemoryStats = createEmptyStats()
 let saveTimer = null
 let activeStatsPath = ''
+let statsRetentionDays = 95
+
+export function setStatsRetentionDays(days) {
+  statsRetentionDays = Math.max(0, Math.min(3650, Number(days) || 0))
+  pruneRetentionOnStats(inMemoryStats, statsRetentionDays)
+  return statsRetentionDays
+}
+
+export function getStatsRetentionDays() {
+  return statsRetentionDays
+}
 
 function emptyBucket() {
   return {
@@ -122,6 +139,7 @@ export function loadStats(customPath) {
           byHourModel: parsed.byHourModel || {},
         }
         backfillHourlyFromSessions()
+        pruneRetentionOnStats(inMemoryStats, statsRetentionDays)
         return inMemoryStats
       }
     }
@@ -142,6 +160,7 @@ export function loadStats(customPath) {
     } catch {}
   }
   inMemoryStats = createEmptyStats()
+  pruneRetentionOnStats(inMemoryStats, statsRetentionDays)
   return inMemoryStats
 }
 
@@ -203,6 +222,11 @@ function addToBucket(bucket, entry) {
   else bucket.unpricedRequests += 1
   bucket.ttftMsSum += entry.ttftMs
   bucket.latencyMsSum += entry.latencyMs
+  if (entry.latencyMs > 0) {
+    if (!Array.isArray(bucket.latencyHistogram)) bucket.latencyHistogram = []
+    const index = latencyBucketIndex(entry.latencyMs)
+    bucket.latencyHistogram[index] = Number(bucket.latencyHistogram[index] || 0) + 1
+  }
   bucket.firstAt = bucket.firstAt || entry.now
   bucket.lastAt = entry.now
   if (entry.model) bucket.model = entry.model
@@ -335,6 +359,7 @@ export function recordUsage({
   if (!inMemoryStats.byHourModel[hourKey]) inMemoryStats.byHourModel[hourKey] = {}
   inMemoryStats.byHourModel[hourKey][model] = Number(inMemoryStats.byHourModel[hourKey][model] || 0) + 1
   pruneHours(now)
+  pruneRetentionOnStats(inMemoryStats, statsRetentionDays, now)
   if (sessionId) {
     const key = String(sessionId)
     incrementBucket(inMemoryStats.bySession, key, entry)
@@ -450,6 +475,7 @@ export function getAnalytics(query = {}) {
         : inMemoryStats.byModel
 
   const groups = []
+  const totalsHistogram = []
   for (const [key, bucket] of Object.entries(source || {})) {
     const at = groupBy === 'day' ? Date.parse(`${key}T00:00:00Z`) : Number(bucket.lastAt || 0)
     if (Number.isFinite(at) && (at < from || at > to)) continue
@@ -457,6 +483,9 @@ export function getAnalytics(query = {}) {
     if (query.account && bucket.accountId && bucket.accountId !== query.account && key !== query.account) continue
     const requests = Number(bucket.requests || 0)
     const successful = Number(bucket.successful || 0)
+    const histogram = Array.isArray(bucket.latencyHistogram) ? bucket.latencyHistogram : []
+    mergeHistogram(totalsHistogram, histogram)
+    const avgLatencyMs = requests > 0 ? Number(bucket.latencyMsSum || 0) / requests : 0
     groups.push({
       key,
       label: key,
@@ -475,7 +504,9 @@ export function getAnalytics(query = {}) {
       unpricedRequests: Number(bucket.unpricedRequests || 0),
       successRate: requests > 0 ? (successful / requests) * 100 : 0,
       avgTtftMs: successful > 0 ? Number(bucket.ttftMsSum || 0) / successful : 0,
-      avgLatencyMs: requests > 0 ? Number(bucket.latencyMsSum || 0) / requests : 0,
+      avgLatencyMs,
+      p50LatencyMs: percentileFromHistogram(histogram, 50) || avgLatencyMs,
+      p95LatencyMs: percentileFromHistogram(histogram, 95) || avgLatencyMs,
       ttftMsSum: Number(bucket.ttftMsSum || 0),
       latencyMsSum: Number(bucket.latencyMsSum || 0),
       model: bucket.model || '',
@@ -514,6 +545,8 @@ export function getAnalytics(query = {}) {
   totals.successRate = totals.requests > 0 ? (totals.successful / totals.requests) * 100 : 0
   totals.avgTtftMs = totals.successful > 0 ? totals.ttftMsSum / totals.successful : 0
   totals.avgLatencyMs = totals.requests > 0 ? totals.latencyMsSum / totals.requests : 0
+  totals.p50LatencyMs = percentileFromHistogram(totalsHistogram, 50) || totals.avgLatencyMs
+  totals.p95LatencyMs = percentileFromHistogram(totalsHistogram, 95) || totals.avgLatencyMs
 
   return {
     range: { from, to },
@@ -559,3 +592,4 @@ export function exportStatsAsCsv(detailed = false) {
   }
   return lines.join('\n')
 }
+

package/lib/transport/cline-transport.js

@@ -9,7 +9,7 @@
 import { createRequire } from 'node:module'
 
 const require = createRequire(import.meta.url)
-let packageVersion = '0.6.3'
+let packageVersion = '0.6.4'
 try {
   packageVersion = require('../../package.json').version || packageVersion
 } catch {

package/lib/tui-settings.js

@@ -114,6 +114,18 @@ export function buildTuiSection({ live }) {
         return Number.isInteger(value) && value >= -1 ? { kind: 'set', value } : undefined
       },
     },
+    {
+      path: ['statsRetentionDays'],
+      group: 'advanced',
+      kind: 'number',
+      label: 'Stats retention (days)',
+      hint: 'Trim day/hour/session telemetry; 0 keeps everything.',
+      format: (value) => (Number(value) > 0 ? String(Number(value)) : ''),
+      parse: (text) => {
+        const value = Number(text)
+        return Number.isFinite(value) && value >= 0 ? { kind: 'set', value } : { kind: 'clear' }
+      },
+    },
     {
       path: ['dailyBudgetUsd'],
       group: 'advanced',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-clinebot",
-  "version": "0.6.3",
+  "version": "0.6.4",
   "description": "DeepSeek Harness companion for ClineBot / ClinePass: dynamic subscription models sync, quota exhaustion warnings, session metrics, dedicated settings page, live usage limits, and /cline slash-command.",
   "license": "MIT",
   "type": "module",