📦 @goodandready/dsh-cost-meter

⚡ Overview & The Problem

AI development and agentic coding consume large volumes of tokens across prompt generation, reasoning, and context caches. Without continuous financial feedback, developers risk unexpected billing spikes, missing off-peak discount windows, or failing to identify runaway subagent expenses.

@goodandready/dsh-cost-meter embeds a high-precision cost telemetry chip directly into the DeepSeek Harness conversation header (conversation.session.header.utilities):

● ≈ $0.12  0:17     ← Live session cost chip with tariff countdown

Clicking the chip expands an interactive breakdown modal displaying 1M token rate tables across peak and off-peak tiers, active UTC window status, and per-model session expenditure summaries.

🏛️ Architecture

graph TD
    subgraph StreamTelemetry ["DeepSeek Harness Runtime"]
        Req["LLM Request / Header<br/>(provider, model)"]
        StreamHook["Incremental Streaming Chunks"]
        Proj["costByModel Projection<br/>(30-min UTC Slots)"]
    end

    subgraph PricingCatalog ["Tariff Resolution Engine"]
        Manual["Manual Config Rates<br/>(settings.yaml: prices)"]
        DeepSeekTier["DeepSeek Official Tier<br/>(Peak vs Off-Peak 50% discount)"]
        OpenRouterTier["OpenRouter API Catalog<br/>(Cached Daily)"]
    end

    subgraph UI ["User Interface Surfaces"]
        Chip["Header Cost Chip<br/>(Active tariff + countdown)"]
        Modal["Breakdown Drawer<br/>(Rates per 1M, UTC windows, model table)"]
        Settings["Settings Card<br/>(Currency, USD rate, timezones)"]
    end

    Req --> Proj
    StreamHook --> Proj
    Proj --> Chip
    PricingCatalog --> Proj
    Manual --> PricingCatalog
    DeepSeekTier --> PricingCatalog
    OpenRouterTier --> PricingCatalog
    Chip --> Modal

✨ Features & Key Capabilities

1. Incremental Streaming Telemetry: Computes prompt, completion, and cache read/write tokens in real-time without polling or UI stutter.
2. Dual-Tier Tariff Engine: Official DeepSeek peak windows (01:00–04:00 and 06:00–10:00 UTC) with automatic 50% off-peak discount detection.
3. UTC Half-Hour Slot Immutability: Historical session expenditure is permanently anchored to the rate active at the moment of execution.
4. Provider-Aware Routing: Distinguishes direct provider connections from hosted gateways (e.g. OpenRouter vs native endpoints).
5. Interactive UI Modal & Settings: Custom currency symbols ($, €, ₽, ¥), exchange rates, and timezone configurations.

📦 Installation

dsh plugin --profile web add @goodandready/dsh-cost-meter

Restart your DeepSeek Harness instance and refresh the browser.

⚙️ Configuration Reference (settings.yaml)

dsh-cost-meter:
  currency: "$"
  usdRate: 1.0
  displayTimeZone: "UTC"
  useOpenRouter: true
  prices: {}
  modelMap: {}

Configuration Parameters

Note on GUI vs YAML: Primary scalar parameters (currency, usdRate, displayTimeZone, useOpenRouter, refreshHours) are directly editable in the GUI Settings Card under Settings → Plugins → Plugin Settings → Cost Meter. Advanced structured rules (prices, modelMap, deepseekPeakPrices, manualPeakWindowsUtc, manualOffPeakMultiplier) are configured in settings.yaml due to their complex dictionary/array schema.

🧪 Testing

Run the automated test suite:

npm test

📄 License

MIT © GooDAnDReaDY