@goodandready/dsh-clinebot 0.6.2 → 0.6.3

package/CHANGELOG.md

@@ -5,6 +5,13 @@ 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.3] - 2026-10-21
+
+### Added
+- **Quota forecast**: each 5-hour, weekly and monthly quota row now shows an estimated burn-down (`~2h 15m left`, `holds until reset`, `no usage yet`) based on the current pace and reset time. Forecasts appear in the sidebar and the center-column panel.
+- **Budget guard**: optional `dailyBudgetUsd` and `monthlyBudgetUsd` limits (0 disables). The adapter rejects new ClineBot requests with `BUDGET_EXCEEDED` once the local estimated spend for the UTC day/month reaches the limit; both fields are available in Settings → ClineBot → Advanced and the TUI.
+- Budget fields are wired through `publicConfig`, and the budget guard is covered by unit/integration tests.
+
 ## [0.6.2] - 2026-10-21
 
 ### Removed

package/README.md

@@ -4,7 +4,7 @@
 
 <h3>Native ClineBot / ClinePass Provider Companion for DeepSeek Harness</h3>
 
-<p><b>0.6.2</b> is adapter-only: 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 have been removed.</p>
+<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 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,8 @@ dsh-clinebot:
     your-reasoning-model: high
   modelContextOverrides: []
   statsPath: ~/.dsh/clinebot-stats.json
+  dailyBudgetUsd: 0
+  monthlyBudgetUsd: 0
   timeoutMs: 30000
   smokeTimeoutMs: 60000
   streamIdleTimeoutMs: 60000
@@ -218,6 +220,8 @@ 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 |
+| `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 }]`) |
 | `activeAccount` | `string` | `""` | Manually pinned active account env name (empty for least-used auto routing) |
 | `timeoutMs` | `number` | `15000` | HTTP probe timeout in milliseconds |

package/README.ru.md

@@ -4,7 +4,7 @@
 
 <h3>Нативное подключение провайдера ClineBot / ClinePass для DeepSeek Harness</h3>
 
-<p><b>0.6.2</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.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 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,8 @@ dsh-clinebot:
     your-reasoning-model: high
   modelContextOverrides: []
   statsPath: ~/.dsh/clinebot-stats.json
+  dailyBudgetUsd: 0
+  monthlyBudgetUsd: 0
   timeoutMs: 30000
   smokeTimeoutMs: 60000
   streamIdleTimeoutMs: 60000
@@ -187,6 +189,8 @@ dsh-clinebot:
 | `modelReasoningDefaults` | `object` | `{}` | Значения thinking effort по умолчанию для моделей (`low`, `medium`, `high`, `max`) |
 | `modelContextOverrides` | `array` | `[]` | Пользовательские переопределения размера контекста и лимита токенов |
 | `statsPath` | `string` | `"~/.dsh/clinebot-stats.json"` | Путь к файлу персистентной аналитики использования токенов |
+| `dailyBudgetUsd` | `number` | `0` | Опциональный дневной лимит оценочных трат; 0 отключает |
+| `monthlyBudgetUsd` | `number` | `0` | Опциональный месячный лимит оценочных трат; 0 отключает |
 | `accounts` | `array` | `[]` | Дополнительные аккаунты для ротации квоты и failover (`[{ label, apiKeyEnv }]`) |
 | `activeAccount` | `string` | `""` | Принудительно закреплённый аккаунт (пусто для автоматического выбора least-used) |
 | `timeoutMs` | `number` | `15000` | Таймаут HTTP-запросов (мс) |

package/README.zh.md

@@ -4,7 +4,7 @@
 
 <h3>适用于 DeepSeek Harness 的 ClineBot / ClinePass 原生模型提供商伴侣插件</h3>
 
-<p><b>0.6.2</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.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 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,8 @@ dsh-clinebot:
     your-reasoning-model: high
   modelContextOverrides: []
   statsPath: ~/.dsh/clinebot-stats.json
+  dailyBudgetUsd: 0
+  monthlyBudgetUsd: 0
   timeoutMs: 30000
   smokeTimeoutMs: 60000
   streamIdleTimeoutMs: 60000
@@ -189,6 +191,8 @@ dsh-clinebot:
 | `modelReasoningDefaults` | `object` | `{}` | 各模型默认思考强度配置 (`low`, `medium`, `high`, `max`) |
 | `modelContextOverrides` | `array` | `[]` | 用户自定义模型上下文窗口与最大 Token 数量覆盖 |
 | `statsPath` | `string` | `"~/.dsh/clinebot-stats.json"` | 本地持久化 Token 用量统计文件路径 |
+| `dailyBudgetUsd` | `number` | `0` | 可选的每日估算花费上限；0 表示关闭 |
+| `monthlyBudgetUsd` | `number` | `0` | 可选的每月估算花费上限；0 表示关闭 |
 | `accounts` | `array` | `[]` | 额外轮转账号池 (`[{ label, apiKeyEnv }]`) |
 | `activeAccount` | `string` | `""` | 手动指定的主账号（为空时自动按最低配额消耗优先路由） |
 | `timeoutMs` | `number` | `15000` | HTTP 请求探测超时时间（毫秒） |

package/lib/adapter.js

@@ -12,7 +12,8 @@ import { getAllModels, findModel, formatModelDescription } from './models.js'
 import { resolveAccountPool } from './account-pool.js'
 import { resolveSessionAccount, markAccountCooldown } from './session-router.js'
 import { recordSessionRequest } from './telemetry.js'
-import { recordUsage } from './stats-storage.js'
+import { recordUsage, getBudgetSpend } from './stats-storage.js'
+import { budgetStatus, budgetErrorMessage } from './budget.js'
 import { estimateCost } from './model-prices.js'
 import { buildOpenAiPayload } from './adapter-messages.js'
 import { streamJsonCompletion, streamOpenAiChunks } from './adapter-stream.js'
@@ -244,6 +245,10 @@ export class ClineBotAdapter extends LlmAdapter {
     if (!pub.enabled) {
       throw new LlmError('ClineBot provider is disabled', 'PROVIDER_DISABLED')
     }
+    const budget = budgetStatus(pub, getBudgetSpend())
+    if (budget.blocked) {
+      throw new LlmError(budgetErrorMessage(budget), 'BUDGET_EXCEEDED')
+    }
 
     const signal = options.signal
     const sessionId = options.sessionId ? String(options.sessionId) : ''

package/lib/budget.js

@@ -0,0 +1,37 @@
+/**
+ * Estimated-spend budget guard.
+ *
+ * ClinePass does not expose a per-token invoice; spend comes from the local
+ * price table and is therefore explicit about being an estimate. A guard of 0
+ * disables the corresponding limit.
+ */
+
+/**
+ * @param {{ dailyBudgetUsd?: number, monthlyBudgetUsd?: number }} config
+ * @param {{ dayCost?: number, monthCost?: number }} spend
+ * @returns {{ blocked: boolean, scope: 'daily'|'monthly'|null, spent: number, limit: number }}
+ */
+export function budgetStatus(config, spend) {
+  const dailyLimit = Math.max(0, Number(config?.dailyBudgetUsd) || 0)
+  const monthlyLimit = Math.max(0, Number(config?.monthlyBudgetUsd) || 0)
+  const dayCost = Math.max(0, Number(spend?.dayCost) || 0)
+  const monthCost = Math.max(0, Number(spend?.monthCost) || 0)
+
+  if (dailyLimit > 0 && dayCost >= dailyLimit) {
+    return { blocked: true, scope: 'daily', spent: dayCost, limit: dailyLimit }
+  }
+  if (monthlyLimit > 0 && monthCost >= monthlyLimit) {
+    return { blocked: true, scope: 'monthly', spent: monthCost, limit: monthlyLimit }
+  }
+  return { blocked: false, scope: null, spent: 0, limit: 0 }
+}
+
+/**
+ * Human-readable error for an exhausted budget guard.
+ * @param {ReturnType<typeof budgetStatus>} status
+ */
+export function budgetErrorMessage(status) {
+  if (!status?.blocked) return ''
+  const label = status.scope === 'monthly' ? 'Monthly' : 'Daily'
+  return `${label} ClineBot budget reached (estimated $${status.spent.toFixed(4)} of $${status.limit.toFixed(2)}). Raise the limit in Settings -> ClineBot -> Advanced.`
+}

package/lib/client.js

@@ -112,6 +112,10 @@ const en = {
       'quota.countdown': 'Resets in {time}',
       'quota.resetting': 'Resetting…',
       'quota.warning_low': 'Quota is below 10%. Requests may be throttled soon.',
+      'quota.forecast_no_usage': 'No usage yet',
+      'quota.forecast_holds': 'Holds until reset at the current pace',
+      'quota.forecast_left': '~{time} left at the current pace',
+      'quota.forecast_exhausted': 'Exhausted',
       'quota.exhausted_5h': '5-hour rolling limit is almost exhausted ({percentUsed}%). New requests may be rejected until quota reset.',
       'quota.warning_5h': 'Low quota warning: {percentUsed}% of 5-hour limit consumed (<10% remaining).',
       'quota.warning_weekly': 'Low weekly quota warning: {percentUsed}% consumed ({remainingPercent}% remaining).',
@@ -256,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.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)',
       'providerCard.hint': 'Paste a ClinePass API key or manage the full account pool in Settings → ClineBot.',
@@ -389,6 +394,10 @@ const zh = {
       'quota.countdown': '{time}后重置',
       'quota.resetting': '正在重置',
       'quota.warning_low': '额度低于 10%，请求可能很快会受到限制。',
+      'quota.forecast_no_usage': '尚未使用',
+      'quota.forecast_holds': '按当前速度可坚持到重置',
+      'quota.forecast_left': '按当前速度约剩 {time}',
+      'quota.forecast_exhausted': '已耗尽',
       'quota.exhausted_5h': '5 小时滚动限额已接近耗尽（已用 {percentUsed}%）。在额度重置前新请求可能会被拒绝。',
       'quota.warning_5h': '低额度警告：5 小时限额已消耗 {percentUsed}%（剩余不足 10%）。',
       'quota.warning_weekly': '周限额偏低警告：已消耗 {percentUsed}%（剩余 {remainingPercent}%）。',
@@ -533,6 +542,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.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）',
       'providerCard.hint': '粘贴 ClinePass API 密钥，或前往“设置 → ClineBot”管理完整账户池。',
@@ -785,6 +795,7 @@ function ensureCss() {
 .cb-progress-meta, .cb-bar-meta{flex:1 1 140px;min-width:0;margin-left:auto;color:var(--dsw-alias-label-secondary);font-size:12px;line-height:18px;text-align:right;white-space:normal;overflow-wrap:anywhere}
 .cb-progress-meta-bad{color:var(--dsw-alias-state-error-primary)}
 .cb-progress-low{display:inline-flex;align-items:center;gap:4px;margin-left:6px;font-size:11px;color:var(--dsw-alias-state-error-primary)}
+.cb-progress-forecast{color:var(--dsw-alias-label-tertiary);font-size:11px;line-height:16px}
 .cb-progress-track, .cb-bar-track{width:100%;height:6px;border-radius:var(--dsw-radius-xs);background:var(--dsw-alias-bg-layer-2);overflow:hidden}
 .cb-progress-bar-fill, .cb-bar-fill{height:100%;border-radius:var(--dsw-radius-xs);background:var(--dsw-alias-brand-primary);transition:width .3s ease}
 .cb-progress-bar-warn{height:100%;border-radius:var(--dsw-radius-xs);background:var(--dsw-alias-state-warn-primary);transition:width .3s ease}
@@ -827,6 +838,7 @@ function ensureCss() {
 .cb-footBar{display:block;height:4px;border-radius:var(--dsw-radius-xs);background:var(--dsw-alias-bg-layer-2);overflow:hidden}
 .cb-footFill{display:block;height:100%;border-radius:var(--dsw-radius-xs);background:var(--dsw-alias-brand-primary);transition:width .3s ease}
 .cb-footFillWarn{background:var(--dsw-alias-state-error-primary)}
+.cb-footForecast{color:var(--dsw-alias-label-tertiary);font-size:11px;line-height:14px}
 .cb-footPct{margin-left:auto;flex:none;width:34px;color:var(--dsw-alias-label-secondary);text-align:right;font-size:12px;font-weight:600;line-height:16px;font-variant-numeric:tabular-nums}
 .cb-footPctWarn{color:var(--dsw-alias-state-error-primary)}
 .cb-railButton{box-sizing:border-box;flex:none;display:inline-flex;justify-content:center;align-items:center;width:36px;height:36px;margin:0 0 4px;padding:0;border:.5px solid transparent;border-radius:var(--dsw-radius-md);background:transparent;color:var(--dsw-alias-label-secondary);cursor:pointer}
@@ -1453,13 +1465,45 @@ function formatResetTime(isoString) {
   }
 }
 
-function ProgressBar({ label, percentUsed, remainingPercent, resetsAt, t }) {
+function formatForecastDuration(ms) {
+  const totalMinutes = Math.max(1, Math.round(Number(ms) / 60000))
+  const days = Math.floor(totalMinutes / 1440)
+  const hours = Math.floor((totalMinutes % 1440) / 60)
+  const minutes = totalMinutes % 60
+  if (days > 0) return `${days}d ${hours}h`
+  if (hours > 0) return `${hours}h ${minutes}m`
+  return `${minutes}m`
+}
+
+function quotaForecast(window, windowMs, t) {
+  const used = Number(window?.percentUsed)
+  const remaining = Number.isFinite(Number(window?.remainingPercent))
+    ? Number(window.remainingPercent)
+    : 100 - used
+  const resetAt = new Date(window?.resetsAt).getTime()
+  const span = Number(windowMs)
+  if (!Number.isFinite(used) || !Number.isFinite(resetAt) || !Number.isFinite(span) || span <= 0) return ''
+  const untilReset = resetAt - Date.now()
+  if (untilReset <= 0) return ''
+  if (remaining <= 0) return t('quota.forecast_exhausted')
+  if (used <= 0) return t('quota.forecast_no_usage')
+  const elapsed = Math.max(1, span - untilReset)
+  const burnPerMs = used / elapsed
+  if (!Number.isFinite(burnPerMs) || burnPerMs <= 0) return ''
+  const etaMs = remaining / burnPerMs
+  if (!Number.isFinite(etaMs) || etaMs <= 0) return ''
+  if (etaMs >= untilReset) return t('quota.forecast_holds')
+  return t('quota.forecast_left', { time: formatForecastDuration(etaMs) })
+}
+
+function ProgressBar({ label, percentUsed, remainingPercent, resetsAt, windowMs, t }) {
   const pct = Math.max(0, Math.min(100, Math.round(percentUsed || 0)))
   const isWarn = pct >= 80 && pct < 90
   const isBad = pct >= 90
   const barClass = isBad ? 'cb-progress-bar-bad' : isWarn ? 'cb-progress-bar-warn' : 'cb-progress-bar-fill'
   const resetCountdown = formatResetCountdown(resetsAt)
   const resetClock = formatResetTime(resetsAt)
+  const forecast = windowMs ? quotaForecast({ percentUsed, remainingPercent, resetsAt }, windowMs, t) : ''
 
   return React.createElement(
     'div',
@@ -1493,7 +1537,8 @@ function ProgressBar({ label, percentUsed, remainingPercent, resetsAt, t }) {
       'div',
       { className: 'cb-progress-track' },
       React.createElement('div', { className: barClass, style: { width: `${pct}%` } })
-    )
+    ),
+    forecast ? React.createElement('div', { className: 'cb-progress-forecast' }, forecast) : null
   )
 }
 
@@ -1717,6 +1762,22 @@ function AdvancedSection({ draft, onStage, t }) {
       type: 'number',
       onChange: numeric('maxPayloadMb', 0),
     }),
+    React.createElement(AdvancedField, {
+      id: 'cb-daily-budget',
+      label: t('settings.daily_budget'),
+      hint: t('settings.daily_budget_hint'),
+      value: current.dailyBudgetUsd,
+      type: 'number',
+      onChange: numeric('dailyBudgetUsd', -1),
+    }),
+    React.createElement(AdvancedField, {
+      id: 'cb-monthly-budget',
+      label: t('settings.monthly_budget'),
+      hint: t('settings.monthly_budget_hint'),
+      value: current.monthlyBudgetUsd,
+      type: 'number',
+      onChange: numeric('monthlyBudgetUsd', -1),
+    }),
     React.createElement(AdvancedField, {
       id: 'cb-stats-path',
       label: t('settings.stats_path'),
@@ -2444,6 +2505,7 @@ function QuotaSection({ keyPresent, status, usage, busy, handleRefreshQuota, sho
                   percentUsed: usage.windows.fiveHour.percentUsed || 0,
                   remainingPercent: usage.windows.fiveHour.remainingPercent || 100,
                   resetsAt: usage.windows.fiveHour.resetsAt,
+                  windowMs: 5 * 60 * 60 * 1000,
                   t,
                 })
               : null,
@@ -2452,6 +2514,7 @@ function QuotaSection({ keyPresent, status, usage, busy, handleRefreshQuota, sho
               percentUsed: usage?.windows?.weekly?.percentUsed || 0,
               remainingPercent: usage?.windows?.weekly?.remainingPercent || 100,
               resetsAt: usage?.windows?.weekly?.resetsAt,
+              windowMs: 7 * 24 * 60 * 60 * 1000,
               t,
             }),
             usage?.windows?.monthly
@@ -2460,6 +2523,7 @@ function QuotaSection({ keyPresent, status, usage, busy, handleRefreshQuota, sho
                   percentUsed: usage.windows.monthly.percentUsed || 0,
                   remainingPercent: usage.windows.monthly.remainingPercent || 100,
                   resetsAt: usage.windows.monthly.resetsAt,
+                  windowMs: 30 * 24 * 60 * 60 * 1000,
                   t,
                 })
               : null
@@ -3780,7 +3844,14 @@ function SidebarQuota({ ctx, wide, t: propT, open: openPanel }) {
               className: warn ? 'cb-footFill cb-footFillWarn' : 'cb-footFill',
               style: { width: hasData ? `${Math.min(100, Math.max(2, value))}%` : '0%' },
             })
-          )
+          ),
+          hasData
+            ? React.createElement(
+                'span',
+                { className: 'cb-footForecast' },
+                quotaForecast(window.value, window.key === 'fiveHour' ? 5 * 60 * 60 * 1000 : window.key === 'weekly' ? 7 * 24 * 60 * 60 * 1000 : 30 * 24 * 60 * 60 * 1000, t)
+              )
+            : null
         )
       }),
       rows.some((window) => windowPct(window) !== null)
@@ -4068,6 +4139,7 @@ function QuotaPanelView({
               percentUsed: selectedUsage.windows.fiveHour.percentUsed || 0,
               remainingPercent: selectedUsage.windows.fiveHour.remainingPercent || 100,
               resetsAt: selectedUsage.windows.fiveHour.resetsAt,
+              windowMs: 5 * 60 * 60 * 1000,
               t,
             })
           : null,
@@ -4077,6 +4149,7 @@ function QuotaPanelView({
               percentUsed: selectedUsage.windows.weekly.percentUsed || 0,
               remainingPercent: selectedUsage.windows.weekly.remainingPercent || 100,
               resetsAt: selectedUsage.windows.weekly.resetsAt,
+              windowMs: 7 * 24 * 60 * 60 * 1000,
               t,
             })
           : null,
@@ -4086,6 +4159,7 @@ function QuotaPanelView({
               percentUsed: selectedUsage.windows.monthly.percentUsed || 0,
               remainingPercent: selectedUsage.windows.monthly.remainingPercent || 100,
               resetsAt: selectedUsage.windows.monthly.resetsAt,
+              windowMs: 30 * 24 * 60 * 60 * 1000,
               t,
             })
           : null,

package/lib/config.js

@@ -99,6 +99,10 @@ 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(),
+  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)
+    .description('Optional monthly estimated-spend guard in USD. 0 disables the guard.').volatile(),
   timeoutMs: z.number().default(DEFAULT_TIMEOUT_MS)
     .description('HTTP probe timeout in milliseconds.').volatile(),
   smokeTimeoutMs: z.number().default(DEFAULT_SMOKE_TIMEOUT_MS)
@@ -238,6 +242,8 @@ export function publicConfig(cfg) {
     modelRoutes: cfg?.modelRoutes && typeof cfg.modelRoutes === 'object' ? cfg.modelRoutes : {},
     customModels: custom,
     statsPath: String(cfg?.statsPath || '~/.dsh/clinebot-stats.json'),
+    dailyBudgetUsd: Math.max(0, Number(cfg?.dailyBudgetUsd) || 0),
+    monthlyBudgetUsd: Math.max(0, Number(cfg?.monthlyBudgetUsd) || 0),
     disabledModels: disabledList,
     filterModelsByPlan,
     visibleModels,

package/lib/stats-storage.js

@@ -361,6 +361,21 @@ export function getSessionStats(sessionId) {
   return bucket ? JSON.parse(JSON.stringify(bucket)) : null
 }
 
+/**
+ * Current UTC day/month estimated spend for budget guards.
+ * @param {number} [now]
+ */
+export function getBudgetSpend(now = Date.now()) {
+  const dayKey = new Date(now).toISOString().slice(0, 10)
+  const monthKey = dayKey.slice(0, 7)
+  return {
+    dayKey,
+    monthKey,
+    dayCost: Number(inMemoryStats.byDay?.[dayKey]?.costUsd || 0),
+    monthCost: Number(inMemoryStats.byMonth?.[monthKey]?.costUsd || 0),
+  }
+}
+
 export function resetStats(customPath) {
   inMemoryStats = createEmptyStats()
   saveStatsSync(customPath)

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.2'
+let packageVersion = '0.6.3'
 try {
   packageVersion = require('../../package.json').version || packageVersion
 } catch {

package/lib/tui-settings.js

@@ -114,6 +114,30 @@ export function buildTuiSection({ live }) {
         return Number.isInteger(value) && value >= -1 ? { kind: 'set', value } : undefined
       },
     },
+    {
+      path: ['dailyBudgetUsd'],
+      group: 'advanced',
+      kind: 'number',
+      label: 'Daily budget (USD)',
+      hint: 'Estimated spend guard; 0 disables it.',
+      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: ['monthlyBudgetUsd'],
+      group: 'advanced',
+      kind: 'number',
+      label: 'Monthly budget (USD)',
+      hint: 'Estimated spend guard; 0 disables it.',
+      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' }
+      },
+    },
   ]
 
   return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-clinebot",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "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",