@goodandready/dsh-cost-meter 0.8.25 → 0.8.26

package/lib/commands.js

@@ -0,0 +1,260 @@
+// dsh-cost-meter — slash command /cost and receipt generator (Issue #125).
+
+export function formatNumber(num) {
+  if (typeof num !== 'number' || Number.isNaN(num)) return '0'
+  return num.toLocaleString('en-US')
+}
+
+export function formatMoney(amount, currency = '$') {
+  const n = Number(amount) || 0
+  if (n === 0) return `${currency}0.00`
+  if (n < 0.0001) return `${currency}${n.toExponential(2)}`
+  if (n < 0.1) return `${currency}${n.toFixed(4)}`
+  return `${currency}${n.toFixed(2)}`
+}
+
+/**
+ * Format structured receipt markdown from session spend stats.
+ */
+export function formatCostReceipt(data) {
+  const {
+    model = 'unknown',
+    provider = '',
+    currency = '$',
+    fx = 1,
+    costUsd = 0,
+    tokens = {},
+    cacheSavingsUsd = 0,
+    cacheSavingsPercent = 0,
+    tier = 'Standard',
+    rates = {},
+    burnRatePerHourUsd = 0,
+    projectedCostUsd = 0,
+    turnsCount = 0,
+  } = data || {}
+
+  const totalCost = costUsd * fx
+  const uncachedInput = Number(tokens.uncachedInputTokens || tokens.inputTokens) || 0
+  const output = Number(tokens.outputTokens) || 0
+  const cacheRead = Number(tokens.cacheReadTokens) || 0
+  const cacheWrite = Number(tokens.cacheWriteTokens) || 0
+  const totalTokens = uncachedInput + output + cacheRead + cacheWrite
+
+  const totalPromptTokens = uncachedInput + cacheRead
+  const cacheHitRate = totalPromptTokens > 0
+    ? Math.round((cacheRead / totalPromptTokens) * 100)
+    : 0
+
+  const routeLabel = provider ? `${provider}/${model}` : model
+
+  const lines = [
+    `### 🧾 Cost Meter — Session Spend Receipt`,
+    ``,
+    `| Metric | Value |`,
+    `| :--- | :--- |`,
+    `| **Model** | \`${routeLabel}\` |`,
+    `| **Session Spend** | **${formatMoney(totalCost, currency)}** |`,
+    `| **Total Tokens** | ${formatNumber(totalTokens)} (${turnsCount} ${turnsCount === 1 ? 'turn' : 'turns'}) |`,
+    `| **Uncached Input** | ${formatNumber(uncachedInput)} |`,
+    `| **Prompt Cache Read** | ${formatNumber(cacheRead)} (${cacheHitRate}% hit rate) |`,
+    `| **Output Tokens** | ${formatNumber(output)} |`,
+  ]
+
+  if (cacheWrite > 0) {
+    lines.push(`| **Cache Write** | ${formatNumber(cacheWrite)} |`)
+  }
+
+  if (cacheSavingsUsd > 0) {
+    lines.push(`| **Cache Savings** | **≈ ${formatMoney(cacheSavingsUsd * fx, currency)}** (${cacheSavingsPercent}% saved) |`)
+  }
+
+  lines.push(`| **Tariff Tier** | ${tier} |`)
+
+  if (rates.input !== undefined) {
+    const inR = rates.input ? `$${rates.input}/1M` : '—'
+    const outR = rates.output ? `$${rates.output}/1M` : '—'
+    const hitR = rates.cacheHit ? `$${rates.cacheHit}/1M` : '—'
+    lines.push(`| **Rates (1M tok)** | In ${inR} · Out ${outR} · Cache ${hitR} |`)
+  }
+
+  if (burnRatePerHourUsd > 0) {
+    lines.push(`| **Burn Rate** | ≈ ${formatMoney(burnRatePerHourUsd * fx, currency)}/hr (proj. ${formatMoney(projectedCostUsd * fx, currency)}) |`)
+  }
+
+  return lines.join('\n')
+}
+
+/**
+ * Format compact 1-line or 2-line summary.
+ */
+export function formatCostSummary(data) {
+  const {
+    model = 'model',
+    currency = '$',
+    fx = 1,
+    costUsd = 0,
+    tokens = {},
+    cacheSavingsPercent = 0,
+  } = data || {}
+
+  const totalCost = costUsd * fx
+  const uncachedInput = Number(tokens.uncachedInputTokens || tokens.inputTokens) || 0
+  const output = Number(tokens.outputTokens) || 0
+  const cacheRead = Number(tokens.cacheReadTokens) || 0
+  const totalTokens = uncachedInput + output + cacheRead
+  const totalPrompt = uncachedInput + cacheRead
+  const cacheHit = totalPrompt > 0 ? Math.round((cacheRead / totalPrompt) * 100) : 0
+
+  return `💰 **Cost Meter**: ≈ ${formatMoney(totalCost, currency)} · ${formatNumber(totalTokens)} tokens (${cacheHit}% cache hit) · \`${model}\``
+}
+
+/**
+ * Register DSH slash command /cost and /cost-summary.
+ */
+export function registerSlashCommand(ctx, options) {
+  if (typeof ctx?.inject !== 'function') return
+  const {
+    getCurrentConfig,
+    getCachedTariff,
+    getLastTurns,
+    resetLastTurns,
+    calculateBurnRateAndProjection,
+    calculateCacheSavings,
+    ratesAt,
+    splitRoute,
+    defaultRoute,
+  } = options || {}
+
+  ctx.inject(['commands'], (cmdCtx) => {
+    const commands = cmdCtx.commands
+    if (typeof commands?.register !== 'function') return
+
+    const executeCommand = async (rawArgs) => {
+      try {
+        const subcmd = String(rawArgs || '').trim().toLowerCase().split(/\s+/)[0] || 'receipt'
+        const cfg = typeof getCurrentConfig === 'function' ? getCurrentConfig() : {}
+        const currency = cfg.currency || '$'
+        const fx = Number(cfg.usdRate) || 1
+        const route = defaultRoute ? (defaultRoute(ctx) || { model: 'default' }) : { model: 'default' }
+        const tariff = typeof getCachedTariff === 'function' ? getCachedTariff(cfg, route) : null
+        const schedule = tariff?.schedule
+        const minute = (new Date().getUTCHours() * 60 + new Date().getUTCMinutes()) % 1440
+        const activeRates = (schedule && typeof ratesAt === 'function')
+          ? ratesAt(schedule, minute)
+          : (schedule?.base || {})
+
+        const turns = typeof getLastTurns === 'function' ? getLastTurns() : []
+
+        if (subcmd === 'reset') {
+          if (typeof resetLastTurns === 'function') resetLastTurns()
+          return '✨ Cost Meter: session turn spend history has been reset.'
+        }
+
+        if (subcmd === 'help') {
+          return [
+            '**Cost Meter Commands**:',
+            '- `/cost` or `/cost receipt`: generate detailed markdown spend receipt for this session',
+            '- `/cost summary`: compact spend and token usage summary',
+            '- `/cost reset`: reset per-session turn counter',
+            '- `/cost help`: show this help message',
+          ].join('\n')
+        }
+
+        // Aggregate tokens across turns
+        let totalUncachedInput = 0
+        let totalOutput = 0
+        let totalCacheRead = 0
+        let totalCacheWrite = 0
+        let totalCostUsd = 0
+
+        for (const t of turns) {
+          totalUncachedInput += Number(t.uncachedInputTokens) || 0
+          totalOutput += Number(t.outputTokens) || 0
+          totalCacheRead += Number(t.cacheReadTokens) || 0
+          totalCacheWrite += Number(t.cacheWriteTokens) || 0
+          totalCostUsd += Number(t.costDeltaUsd) || 0
+        }
+
+        const tokensObj = {
+          uncachedInputTokens: totalUncachedInput,
+          outputTokens: totalOutput,
+          cacheReadTokens: totalCacheRead,
+          cacheWriteTokens: totalCacheWrite,
+        }
+
+        const savings = (typeof calculateCacheSavings === 'function' && activeRates)
+          ? calculateCacheSavings(tokensObj, activeRates)
+          : { savedUsd: 0, percent: 0 }
+
+        const analytics = typeof calculateBurnRateAndProjection === 'function'
+          ? calculateBurnRateAndProjection(turns, totalCostUsd)
+          : { burnRatePerHourUsd: 0, projectedCostUsd: 0 }
+
+        const payload = {
+          model: route.model || 'active model',
+          provider: route.provider || '',
+          currency,
+          fx,
+          costUsd: totalCostUsd,
+          tokens: tokensObj,
+          cacheSavingsUsd: savings.savedUsd,
+          cacheSavingsPercent: savings.percent,
+          tier: tariff?.source === 'deepseek' ? 'DeepSeek Tariff' : (tariff?.source || 'Standard'),
+          rates: activeRates,
+          burnRatePerHourUsd: analytics.burnRatePerHourUsd,
+          projectedCostUsd: analytics.projectedCostUsd,
+          turnsCount: turns.length,
+        }
+
+        if (subcmd === 'summary' || subcmd === 'brief') {
+          return formatCostSummary(payload)
+        }
+
+        return formatCostReceipt(payload)
+      } catch (err) {
+        return `Cost Meter error: ${String(err?.message || err)}`
+      }
+    }
+
+    const commandHandler = async (invocation) => {
+      const rawArgs = typeof invocation === 'string'
+        ? invocation
+        : (invocation?.rawInput || invocation?.input || invocation?.text || invocation?.args || '')
+      const text = await executeCommand(rawArgs)
+      return {
+        kind: 'success',
+        text,
+        toString() { return text },
+      }
+    }
+
+    const commandExecute = async (rawArgs, invocation = null) => {
+      const result = await commandHandler(invocation || rawArgs)
+      return result.text
+    }
+
+    const unregister1 = commands.register({
+      definitionId: '@goodandready/dsh-cost-meter',
+      name: 'cost',
+      description: 'Show session spend receipt, tokens, cache savings and burn rate (/cost [receipt|summary|reset|help])',
+      input: { hint: '[receipt|summary|reset|help]' },
+      handler: commandHandler,
+      execute: commandExecute,
+    })
+
+    const unregister2 = commands.register({
+      definitionId: '@goodandready/dsh-cost-meter',
+      name: 'cost-summary',
+      description: 'Show compact 1-line session spend summary',
+      handler: async () => commandHandler('summary'),
+      execute: async () => commandExecute('summary'),
+    })
+
+    if (typeof ctx.effect === 'function') {
+      ctx.effect(() => () => {
+        unregister1?.()
+        unregister2?.()
+      }, 'dsh-cost-meter: slash-command')
+    }
+  })
+}

package/lib/index.js

@@ -30,11 +30,15 @@ try {
 export * from './tariff.js'
 export * from './projection.js'
 export * from './fx.js'
+export * from './alerts.js'
+export * from './commands.js'
 export { STATE_PATH, REFRESH_PATH } from './routes.js'
-import { indexCatalog, resolveTariff, matchModel, unwrapVolatile } from './tariff.js'
-import { usageByModelProjection } from './projection.js'
+import { indexCatalog, resolveTariff, matchModel, unwrapVolatile, calculateCacheSavings } from './tariff.js'
+import { usageByModelProjection, getLastTurns, resetLastTurns } from './projection.js'
 import { getFxRate, refreshFxRates } from './fx.js'
-
+import { registerSlashCommand } from './commands.js'
+import { calculateBurnRateAndProjection } from './analytics.js'
+import { ratesAt } from './alerts.js'
 
 export const name = '@goodandready/dsh-cost-meter'
 export const inject = ['webServer', 'settings', 'sessionProjections']
@@ -84,7 +88,6 @@ export function isTrustedCaller(request, ctx = null) {
         if (isLoopback(url.hostname) && loopback) return true
         return false
       }
-      // Non-http/https origin (e.g. dsh-app://app in DSH Desktop)
       if (loopback) return true
       return false
     } catch {
@@ -101,7 +104,6 @@ export function isTrustedCaller(request, ctx = null) {
         if (isLoopback(url.hostname) && loopback) return true
         return false
       }
-      // Non-http/https referer (e.g. dsh-app://app/ in DSH Desktop)
       if (loopback) return true
       return false
     } catch {
@@ -110,7 +112,6 @@ export function isTrustedCaller(request, ctx = null) {
   }
 
   if (loopback) return true
-
   return false
 }
 
@@ -126,6 +127,9 @@ export function normalizeConfig(raw) {
     displayTimeZone: typeof u.displayTimeZone === 'string' && u.displayTimeZone ? u.displayTimeZone : 'Europe/Moscow',
     budgetThreshold: Number(u.budgetThreshold) || 0,
     displayMode: (u.displayMode === 'compact' || u.displayMode === 'full') ? u.displayMode : 'auto',
+    alertBeforeSwitch: u.alertBeforeSwitch !== false,
+    alertLeadMinutes: Math.max(1, Math.min(30, Number(u.alertLeadMinutes) || 5)),
+    browserNotifications: Boolean(u.browserNotifications),
     useOpenRouter: u.useOpenRouter !== false,
     refreshHours: Number(u.refreshHours) || 24,
     deepseekPeakPrices: u.deepseekPeakPrices || {},
@@ -154,6 +158,9 @@ export const Config = z.object({
   displayTimeZone: z.string().description('IANA zone the widget shows tariff hours in.').default('Europe/Moscow').volatile(),
   budgetThreshold: z.number().description('Optional session budget threshold in USD. 0 disables threshold warnings.').default(0).volatile(),
   displayMode: z.union(['auto', 'full', 'compact']).description('Widget display mode: auto, full, or compact.').default('auto').volatile(),
+  alertBeforeSwitch: z.boolean().description('Pre-switch notification and visual alert before tariff change.').default(true).volatile(),
+  alertLeadMinutes: z.number().description('Minutes before tariff change to trigger pre-switch alert.').default(5).volatile(),
+  browserNotifications: z.boolean().description('Enable desktop browser notifications for tariff switches.').default(false).volatile(),
   deepseekPeakPrices: z.dict(PriceRow).description('Override the built-in DeepSeek peak rates, by model id.').default({}).volatile(),
   useOpenRouter: z.boolean().description('Pull rates and discount windows from the public OpenRouter catalog.').default(true).volatile(),
   refreshHours: z.number().description('How often to refetch the catalog.').default(24).volatile(),
@@ -163,9 +170,6 @@ export const Config = z.object({
   manualOffPeakMultiplier: z.number().description('Multiplier outside the manual peak windows.').default(1).volatile(),
 })
 
-
-// Per-model usage projection is defined in and exported from ./projection.js
-
 /** The agent's default route, read off settings descriptors when available. */
 function defaultRoute(ctx) {
   const settings = (ctx?.get && typeof ctx.get === 'function' ? ctx.get('settings') : null) || ctx?.settings
@@ -195,17 +199,13 @@ export function apply(ctx, config) {
   void refreshFxRates()
   let current = normalizeConfig(config)
   let catalog = { index: { byId: {}, byLowerId: {}, bySuffix: {} }, fetchedAt: 0, error: null }
-
-  // Server-side cache for resolved tariffs: key -> { schedule, source, matchedId }
   const resolveCache = new Map()
 
-
   function getCachedTariff(cfg, route) {
     if (!route) return resolveTariff(cfg, catalog.index, route)
     const cacheKey = (route.provider || '') + '/' + (route.model || '')
     if (resolveCache.has(cacheKey)) return resolveCache.get(cacheKey)
     const res = resolveTariff(cfg, catalog.index, route)
-    // Limit cache size to prevent runaway memory
     if (resolveCache.size >= 500) resolveCache.clear()
     resolveCache.set(cacheKey, res)
     return res
@@ -215,15 +215,12 @@ export function apply(ctx, config) {
     resolveCache.clear()
   }
 
-  // Disk cache survives restarts, so a boot without network still prices.
   try {
     const cached = JSON.parse(readFileSync(CACHE_FILE, 'utf8'))
     if (cached && Array.isArray(cached.models)) {
       catalog = { index: indexCatalog(cached.models), fetchedAt: cached.fetchedAt || 0, error: null }
     }
-  } catch {
-    // absent or unreadable cache is normal on first run
-  }
+  } catch {}
 
   async function refresh(signal, force = false) {
     const cfg = current ?? config
@@ -244,9 +241,7 @@ export function apply(ctx, config) {
       try {
         mkdirSync(dirname(CACHE_FILE), { recursive: true })
         writeFileSync(CACHE_FILE, JSON.stringify({ fetchedAt: catalog.fetchedAt, models: slim }))
-      } catch {
-        // a read-only storages dir only costs us the restart-time cache
-      }
+      } catch {}
     } catch (error) {
       catalog = { ...catalog, error: String((error && error.message) || error) }
     }
@@ -287,6 +282,19 @@ export function apply(ctx, config) {
     eff(() => pctx.sessionProjections.register(usageByModelProjection))
   })
 
+  // Register slash command /cost and /cost-summary
+  registerSlashCommand(ctx, {
+    getCurrentConfig: () => (current ? normalizeConfig(current) : normalizeConfig(config)),
+    getCachedTariff,
+    getLastTurns,
+    resetLastTurns,
+    calculateBurnRateAndProjection,
+    calculateCacheSavings,
+    ratesAt,
+    splitRoute,
+    defaultRoute,
+  })
+
   // Register HTTP routes (refresh, state, update) via webServer service
   registerRoutes(ctx, {
     name,
@@ -299,5 +307,3 @@ export function apply(ctx, config) {
     getCatalog: () => catalog,
   })
 }
-
-

package/lib/projection.js

@@ -32,6 +32,8 @@ export const turnRecordSchema = zod.object({
   cacheWriteTokens: zod.number().nonnegative().optional(),
   costDeltaUsd: zod.number().nonnegative().optional(),
   timestamp: zod.number().nonnegative(),
+  durationMs: zod.number().nonnegative().optional(),
+  cacheHitRate: zod.number().min(0).max(100).optional(),
 }).passthrough()
 
 /** Pull the four buckets out of one provider usage record. */
@@ -152,7 +154,20 @@ export const usageByModelProjection = {
       ? event.time
       : (event.time instanceof Date && !Number.isNaN(event.time.getTime()) ? event.time.getTime() : Date.now())
 
+    const promptTokens = buckets.uncachedInputTokens + buckets.cacheReadTokens
+    const cacheHitRate = promptTokens > 0
+      ? Math.round((buckets.cacheReadTokens / promptTokens) * 100)
+      : 0
+
     const currentTurns = Array.isArray(state.turns) ? state.turns : []
+    let durationMs = 0
+    if (currentTurns.length > 0) {
+      const prevTs = currentTurns[currentTurns.length - 1].timestamp
+      if (timestamp > prevTs && timestamp - prevTs < 600000) {
+        durationMs = timestamp - prevTs
+      }
+    }
+
     const existingIndex = currentTurns.findIndex((t) => t.turn === turnNum && t.step === stepNum)
     let nextTurns
     if (existingIndex >= 0) {
@@ -167,6 +182,8 @@ export const usageByModelProjection = {
         cacheWriteTokens: buckets.cacheWriteTokens,
         costDeltaUsd: nextTurns[existingIndex].costDeltaUsd || 0,
         timestamp,
+        durationMs: nextTurns[existingIndex].durationMs || durationMs,
+        cacheHitRate,
       }
     } else {
       const newEntry = {
@@ -179,6 +196,8 @@ export const usageByModelProjection = {
         cacheWriteTokens: buckets.cacheWriteTokens,
         costDeltaUsd: 0,
         timestamp,
+        durationMs,
+        cacheHitRate,
       }
       nextTurns = [...currentTurns, newEntry].slice(-MAX_TURNS_HISTORY)
     }

package/lib/routes.js

@@ -110,6 +110,9 @@ export function registerRoutes(ctx, options) {
             displayTimeZone: typeof cfg?.displayTimeZone === 'string' && cfg.displayTimeZone ? cfg.displayTimeZone : 'Europe/Moscow',
             budgetThreshold: Number(cfg?.budgetThreshold) || 0,
             displayMode: cfg?.displayMode || 'auto',
+            alertBeforeSwitch: cfg?.alertBeforeSwitch !== false,
+            alertLeadMinutes: Number(cfg?.alertLeadMinutes) || 5,
+            browserNotifications: Boolean(cfg?.browserNotifications),
             route,
             source: own.source,
             matchedId: own.matchedId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-cost-meter",
-  "version": "0.8.25",
+  "version": "0.8.26",
   "description": "DeepSeek Harness plugin: a session cost chip in the conversation header - live token usage by bucket, peak/off-peak tariff, and a countdown to the next tariff switch.",
   "type": "module",
   "main": "lib/index.js",