@apinggithub/mydsh-auto-model-router 0.2.6 → 0.3.1

package/config.mjs

@@ -22,7 +22,7 @@
 //   fallbackChain:  [route, ...]  (model-level, appended with the default)
 //   maxRetries:     per-route retry budget on request-error
 
-export const PLUGIN_VERSION = '0.2.6'
+export const PLUGIN_VERSION = '0.3.1'
 
 export const LEVEL_IDS = Object.freeze(['L0', 'L1', 'L2', 'L3'])
 export const COST_MODES = Object.freeze(['cost-first', 'quality-first', 'balanced'])
@@ -114,6 +114,33 @@ const DEFAULT_CONFIG = Object.freeze({
     // Re-read provider catalogs every N ms (also validated once at activation).
     refreshMs: 600_000,
   },
+  // Tier 7: quota watchdog. Reads the cloud bill (read-only, via the provider's
+  // billing API) and retires a route the moment a "free" model starts billing;
+  // a balance floor stops paid routes entirely. Off by default — it needs
+  // cloud credentials.
+  quotaWatch: {
+    enabled: false,
+    // Which configured provider the bill belongs to (routes to retire).
+    provider: 'bailian-dell-vostro',
+    // Cloud product code the bill is filtered by (`sfm` = 百炼).
+    productCode: 'sfm',
+    pollMs: 1_800_000,
+    // Stop choosing paid routes once the available balance drops below this.
+    // 0 disables the floor.
+    balanceFloorCny: 10,
+    // Retire a route whose model shows any spend in the current billing cycle.
+    demoteOnSpend: true,
+    // Per-provider floor for DeepSeek's own platform balance (`/user/balance`),
+    // which no cloud bill covers. 0 disables it.
+    deepseekBalanceFloor: 0,
+    deepseekApiKeyRef: 'DEEPSEEK_API_KEY',
+    deepseekProvider: 'deepseek-official',
+    deepseekEndpoint: 'https://api.deepseek.com/user/balance',
+    // Credential refs resolved through ctx.credentials (never inline secrets).
+    accessKeyIdRef: 'ALIBABA_CLOUD_ACCESS_KEY_ID',
+    accessKeySecretRef: 'ALIBABA_CLOUD_ACCESS_KEY_SECRET',
+    timeoutMs: 20_000,
+  },
   askEveryInputs: 3,
   fallbackChain: [],
   maxRetries: 1,
@@ -139,6 +166,7 @@ export function resolveConfig(input = {}) {
   cfg.freeQuota = normalizeFreeQuota(cfg.freeQuota)
   cfg.contextGuard = normalizeContextGuard(cfg.contextGuard)
   cfg.modelsGuard = normalizeModelsGuard(cfg.modelsGuard)
+  cfg.quotaWatch = normalizeQuotaWatch(cfg.quotaWatch)
   cfg.askEveryInputs = clampInt(cfg.askEveryInputs, 1, 100, DEFAULT_CONFIG.askEveryInputs)
   cfg.fallbackChain = normalizeChain(cfg.fallbackChain)
   cfg.maxRetries = clampInt(cfg.maxRetries, 0, 5, DEFAULT_CONFIG.maxRetries)
@@ -251,11 +279,63 @@ function normalizeHeuristic(heuristic) {
   return h
 }
 
+/**
+ * The quota watchdog: read-only cloud-billing polling.
+ *
+ * `provider` names which configured provider the bill describes (that is what
+ * gets retired when a model starts billing); the credential refs are resolved
+ * through `ctx.credentials`, so no secret ever lands in the profile.
+ */
+function normalizeQuotaWatch(quotaWatch) {
+  const q = {
+    ...DEFAULT_CONFIG.quotaWatch,
+    ...(quotaWatch ?? {}),
+  }
+  q.enabled = q.enabled === true
+  q.demoteOnSpend = q.demoteOnSpend !== false
+  q.provider = String(q.provider ?? '').trim()
+  q.productCode = String(q.productCode ?? '').trim()
+  q.accessKeyIdRef = String(q.accessKeyIdRef ?? '').trim()
+  q.accessKeySecretRef = String(q.accessKeySecretRef ?? '').trim()
+  q.pollMs = clampInt(q.pollMs, 60_000, 24 * 60 * 60 * 1000, DEFAULT_CONFIG.quotaWatch.pollMs)
+  q.balanceFloorCny = Number.isFinite(Number(q.balanceFloorCny)) && Number(q.balanceFloorCny) >= 0
+    ? Number(q.balanceFloorCny)
+    : DEFAULT_CONFIG.quotaWatch.balanceFloorCny
+  q.timeoutMs = clampInt(q.timeoutMs, 5_000, 120_000, DEFAULT_CONFIG.quotaWatch.timeoutMs)
+  q.deepseekBalanceFloor = Number.isFinite(Number(q.deepseekBalanceFloor)) && Number(q.deepseekBalanceFloor) >= 0
+    ? Number(q.deepseekBalanceFloor)
+    : DEFAULT_CONFIG.quotaWatch.deepseekBalanceFloor
+  q.deepseekApiKeyRef = String(q.deepseekApiKeyRef ?? '').trim()
+  q.deepseekProvider = String(q.deepseekProvider ?? '').trim()
+  q.deepseekEndpoint = String(q.deepseekEndpoint ?? '').trim() || DEFAULT_CONFIG.quotaWatch.deepseekEndpoint
+  if (q.deepseekBalanceFloor > 0) {
+    for (const [field, value] of [
+      ['deepseekApiKeyRef', q.deepseekApiKeyRef],
+      ['deepseekProvider', q.deepseekProvider],
+    ]) {
+      if (value === '') {
+        throw new Error(`mydsh-auto-model-router: quotaWatch.${field} must be a non-empty string when deepseekBalanceFloor is set`)
+      }
+    }
+  }
+  if (q.enabled) {
+    for (const [field, value] of [
+      ['provider', q.provider],
+      ['accessKeyIdRef', q.accessKeyIdRef],
+      ['accessKeySecretRef', q.accessKeySecretRef],
+    ]) {
+      if (value === '') {
+        throw new Error(`mydsh-auto-model-router: quotaWatch.${field} must be a non-empty string`)
+      }
+    }
+  }
+  return q
+}
+
 function normalizeScoring(scoring) {
   const s = {
     ...DEFAULT_CONFIG.scoring,
-    ...(scoring ?? {}),
-  }
+    ...(scoring ?? {}),  }
   const weights = {}
   for (const id of LEVEL_IDS) {
     const value = Number(s.weights?.[id])

package/index.mjs

@@ -29,6 +29,7 @@
 import { resolveConfig } from './config.mjs'
 import { ModelRouter } from './router.mjs'
 import { createAutoAdapter, isAutoSelection } from './auto-adapter.mjs'
+import { createQuotaWatch } from './quota-watch.mjs'
 import {
   reportStatus, persistStatusReport, statusReport, notifyDowngrade,
   askDowngrade, resolveLocale, askModeSelection, askFixedLevel,
@@ -135,6 +136,30 @@ export function apply(ctx, input = {}) {
     return () => clearInterval(timer)
   }, 'modelRouter.catalogWatch()')
 
+  // ── quota watchdog: retire routes that stopped being free ───────────────
+  // Read-only billing poll (Aliyun RPC via a cloud key resolved from
+  // ctx.credentials); off unless configured, and inert when the host exposes no
+  // credentials service.
+  let quotaWatch
+  if (config.quotaWatch.enabled) {
+    const credentials = readService(ctx, 'credentials')
+    if (typeof credentials?.resolve === 'function') {
+      quotaWatch = createQuotaWatch({
+        config: config.quotaWatch,
+        router,
+        credentials,
+        logger: ctx.logger,
+      })
+      ctx.effect?.(() => quotaWatch.start(), 'modelRouter.quotaWatch()')
+    } else {
+      warn(
+        'quotaWatch',
+        'quotaWatch is enabled but the host exposes no credentials service; '
+        + 'the watchdog stays off and routes are never retired for spend.',
+      )
+    }
+  }
+
   // ── HTTP status endpoint for the browser settings section ─────────────
   // The client fetch()es /api/mydsh-auto-model-router/status to render the
   // current routing policy (no localStorage / DOM-transcript dependency).
@@ -159,6 +184,7 @@ export function apply(ctx, input = {}) {
         freeQuota: config.freeQuota,
         contextGuard: config.contextGuard,
         modelsGuard: config.modelsGuard,
+        quotaWatch: quotaWatch?.snapshot() ?? { enabled: false },
         staleLevels: router.staleLevels(),
         rules: config.rules,
         scoring: config.scoring,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apinggithub/mydsh-auto-model-router",
-  "version": "0.2.6",
+  "version": "0.3.1",
   "description": "Hybrid model router for DeepSeek Harness: declarative rules, user-configurable cost control (cost-first / quality-first / balanced), optional LLM task classifier, and failure fallback chains.",
   "type": "module",
   "main": "index.mjs",
@@ -20,6 +20,7 @@
     "notify.mjs",
     "auto-adapter.mjs",
     "compat.mjs",
+    "quota-watch.mjs",
     "text-width.mjs",
     "scoring.mjs",
     "client.js",

package/quota-watch.mjs

@@ -0,0 +1,333 @@
+// Quota watchdog: read the cloud bill and retire routes that stopped being free.
+//
+// A "free" tier is only free until the provider silently switches it to
+// pay-as-you-go; the router cannot see that from the request path (no error is
+// raised). This module asks the billing API instead: once a model that should
+// be free shows any spend in the current cycle, its route is retired for the
+// session and the router drifts to the next candidate. A balance floor stops
+// paid routes entirely before the account runs dry.
+//
+// Read-only: two GETs per poll (`QueryAccountBalance`, `DescribeInstanceBill`),
+// signed with the Aliyun RPC scheme (HMAC-SHA1). No SDK, no dependencies.
+import { createHmac, randomUUID } from 'node:crypto'
+
+/** Default bailian product code on the Aliyun bill. */
+export const BILL_PRODUCT_CODE = 'sfm'
+
+/** RFC 3986 encoding as Aliyun's RPC signature expects. */
+function percentEncode(value) {
+  return encodeURIComponent(String(value))
+    .replace(/[!'()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`)
+    .replace(/%7E/g, '~')
+}
+
+/**
+ * Build a signed Aliyun RPC GET URL.
+ * @param {object} options
+ * @param {string} options.action
+ * @param {Record<string, string|number>} [options.params]
+ * @param {string} options.accessKeyId
+ * @param {string} options.accessKeySecret
+ * @param {string} [options.endpoint]
+ * @param {string} [options.version]
+ * @param {Date} [options.now]
+ * @returns {string}
+ */
+export function signedUrl({
+  action,
+  params = {},
+  accessKeyId,
+  accessKeySecret,
+  endpoint = 'https://business.aliyuncs.com/',
+  version = '2017-12-14',
+  now = new Date(),
+}) {
+  const common = {
+    Format: 'JSON',
+    Version: version,
+    AccessKeyId: accessKeyId,
+    SignatureMethod: 'HMAC-SHA1',
+    SignatureVersion: '1.0',
+    SignatureNonce: randomUUID(),
+    Timestamp: now.toISOString().replace(/\.\d{3}Z$/, 'Z'),
+    Action: action,
+    ...params,
+  }
+  const canonical = Object.keys(common)
+    .sort()
+    .map((key) => `${percentEncode(key)}=${percentEncode(common[key])}`)
+    .join('&')
+  const stringToSign = `GET&${percentEncode('/')}&${percentEncode(canonical)}`
+  const signature = createHmac('sha1', `${accessKeySecret}&`).update(stringToSign).digest('base64')
+  return `${endpoint}?${canonical}&Signature=${percentEncode(signature)}`
+}
+
+/** Extract the model id from a 百炼 bill line (`id;instance;model;item;..`). */
+export function modelOfBillItem(item) {
+  const parts = String(item?.InstanceID ?? '').split(';')
+  return (parts[2] ?? '').trim()
+}
+
+/**
+ * Sum this cycle's bill by model.
+ * @param {object[]} items - DescribeInstanceBill `Items`
+ * @returns {{ byModel: Record<string, number>, total: number, lines: number }}
+ */
+export function aggregateBillItems(items = []) {
+  const byModel = {}
+  let total = 0
+  let lines = 0
+  for (const item of items) {
+    const model = modelOfBillItem(item)
+    if (model === '') continue
+    const cost = Number(item.AfterDiscountAmount ?? item.PretaxGrossAmount ?? 0)
+    if (!Number.isFinite(cost)) continue
+    byModel[model] = (byModel[model] ?? 0) + cost
+    total += cost
+    lines += 1
+  }
+  return { byModel, total, lines }
+}
+
+/** Read the account's available balance in CNY. */
+export async function fetchBalance({ accessKeyId, accessKeySecret, timeoutMs = 20_000, fetchImpl = fetch }) {
+  const url = signedUrl({ action: 'QueryAccountBalance', accessKeyId, accessKeySecret })
+  const response = await fetchImpl(url, { signal: AbortSignal.timeout(timeoutMs) })
+  const body = JSON.parse(await response.text())
+  const data = body?.Data ?? {}
+  return {
+    availableCny: Number(data.AvailableAmount ?? 0),
+    currency: data.Currency ?? 'CNY',
+    raw: data,
+  }
+}
+
+/**
+ * Read the DeepSeek platform balance (`GET /user/balance`).
+ *
+ * The `deepseek-official` provider bills against that account rather than any
+ * cloud bill, so it needs its own floor: the Aliyun watch cannot see it.
+ *
+ * @param {object} options
+ * @param {string} options.apiKey
+ * @param {string} [options.endpoint]
+ * @param {number} [options.timeoutMs]
+ * @param {Function} [options.fetchImpl]
+ */
+export async function fetchDeepSeekBalance({
+  apiKey,
+  endpoint = 'https://api.deepseek.com/user/balance',
+  timeoutMs = 20_000,
+  fetchImpl = fetch,
+}) {
+  const response = await fetchImpl(endpoint, {
+    headers: { authorization: `Bearer ${apiKey}` },
+    signal: AbortSignal.timeout(timeoutMs),
+  })
+  const body = JSON.parse(await response.text())
+  const infos = Array.isArray(body?.balance_infos) ? body.balance_infos : []
+  const cny = infos.find((info) => info?.currency === 'CNY') ?? infos[0]
+  return {
+    available: body?.is_available !== false,
+    totalCny: Number(cny?.total_balance ?? 0),
+    grantedCny: Number(cny?.granted_balance ?? 0),
+    toppedUpCny: Number(cny?.topped_up_balance ?? 0),
+    currency: cny?.currency ?? 'CNY',
+  }
+}
+
+/** Read one billing cycle, following NextToken until exhausted. */
+export async function fetchBill({
+  accessKeyId,
+  accessKeySecret,
+  cycle = new Date().toISOString().slice(0, 7),
+  maxPages = 10,
+  timeoutMs = 20_000,
+  fetchImpl = fetch,
+}) {
+  const items = []
+  let token
+  for (let page = 0; page < maxPages; page += 1) {
+    const url = signedUrl({
+      action: 'DescribeInstanceBill',
+      params: { BillingCycle: cycle, MaxResults: 300, ...token === undefined ? {} : { NextToken: token } },
+      accessKeyId,
+      accessKeySecret,
+    })
+    const response = await fetchImpl(url, { signal: AbortSignal.timeout(timeoutMs) })
+    const body = JSON.parse(await response.text())
+    const data = body?.Data ?? {}
+    items.push(...(data.Items ?? []))
+    token = data.NextToken
+    if (token === undefined || (data.Items ?? []).length === 0) break
+  }
+  return { cycle, items, ...aggregateBillItems(items) }
+}
+
+/**
+ * Build the watchdog bound to one plugin mount.
+ *
+ * @param {object} options
+ * @param {object} options.config - resolved `quotaWatch` config
+ * @param {object} options.router - ModelRouter
+ * @param {object} [options.credentials] - ctx.credentials (`resolve(ref) → {value}`)
+ * @param {object} [options.logger]
+ * @param {Function} [options.fetchImpl] - injection point for tests
+ * @param {() => Date} [options.now]
+ */
+export function createQuotaWatch({ config, router, credentials, logger, fetchImpl = fetch, now = () => new Date() }) {
+  let timer
+  let running = false
+  const retired = new Set()
+  let balanceWarned = false
+  let deepseekWarned = false
+  let snapshot = {
+    enabled: config.enabled === true,
+    lastCheckAt: null,
+    lastError: null,
+    balanceCny: null,
+    cycle: null,
+    spendByModel: {},
+    totalCny: null,
+    exhausted: [],
+    balanceLow: false,
+    deepseekBalanceCny: null,
+    deepseekBlocked: false,
+    deepseekError: null,
+  }
+
+  async function readSecret(ref) {
+    if (typeof credentials?.resolve !== 'function') {
+      throw new Error(`mydsh-auto-model-router: no credentials service for "${ref}"`)
+    }
+    const resolved = await credentials.resolve(ref)
+    const value = typeof resolved === 'string' ? resolved : resolved?.value
+    if (typeof value !== 'string' || value === '') {
+      throw new Error(`mydsh-auto-model-router: credential "${ref}" is not set`)
+    }
+    return value
+  }
+
+  /** Routes this watchdog guards: levels plus declared free routes. */
+  function guardedRoutes() {
+    const routes = []
+    for (const route of Object.values(router.levels ?? {})) if (route) routes.push(route)
+    for (const route of router.config?.freeQuota?.routes ?? []) if (route) routes.push(route)
+    return routes.filter((route) => route.provider === config.provider)
+  }
+
+  async function check() {
+    if (running) return snapshot
+    running = true
+    try {
+      const accessKeyId = await readSecret(config.accessKeyIdRef)
+      const accessKeySecret = await readSecret(config.accessKeySecretRef)
+      const io = { accessKeyId, accessKeySecret, timeoutMs: config.timeoutMs, fetchImpl }
+      const balance = await fetchBalance(io)
+      const bill = await fetchBill({ ...io, cycle: now().toISOString().slice(0, 7) })
+
+      const floor = Number(config.balanceFloorCny) || 0
+      const low = floor > 0 && balance.availableCny < floor
+      if (low !== router.isBalanceLow()) {
+        router.setBalanceLow(low)
+        if (low) {
+          logger?.warn?.(`[mydsh-auto-model-router] balance ¥${balance.availableCny.toFixed(2)} is below the ¥${floor} floor: paid routes are paused`)
+          balanceWarned = true
+        } else if (balanceWarned) {
+          logger?.info?.(`[mydsh-auto-model-router] balance ¥${balance.availableCny.toFixed(2)} is above the floor again: paid routes resumed`)
+          balanceWarned = false
+        }
+      }
+
+      // DeepSeek bills against its own platform account, which the cloud bill
+      // never covers: give that provider its own floor.
+      let deepseekBalance = null
+      let deepseekError = null
+      const dsFloor = Number(config.deepseekBalanceFloor) || 0
+      if (dsFloor > 0) {
+        try {
+          const apiKey = await readSecret(config.deepseekApiKeyRef)
+          deepseekBalance = await fetchDeepSeekBalance({
+            apiKey,
+            endpoint: config.deepseekEndpoint,
+            timeoutMs: config.timeoutMs,
+            fetchImpl,
+          })
+          const blocked = deepseekBalance.totalCny < dsFloor
+          router.setProviderBlocked(config.deepseekProvider, blocked)
+          if (blocked && !deepseekWarned) {
+            deepseekWarned = true
+            logger?.warn?.(
+              `[mydsh-auto-model-router] ${config.deepseekProvider} balance ¥${deepseekBalance.totalCny.toFixed(2)} `
+              + `is below the ¥${dsFloor} floor: that provider is paused`,
+            )
+          } else if (!blocked && deepseekWarned) {
+            deepseekWarned = false
+            logger?.info?.(`[mydsh-auto-model-router] ${config.deepseekProvider} balance recovered: provider resumed`)
+          }
+        } catch (error) {
+          deepseekError = String(error?.message ?? error)
+          logger?.warn?.(`[mydsh-auto-model-router] deepseek balance check failed: ${deepseekError}`)
+        }
+      }
+
+      if (config.demoteOnSpend) {
+        for (const route of guardedRoutes()) {
+          const spend = bill.byModel[route.model]
+          if (!(spend > 0)) continue
+          router.markRouteExhausted(route)
+          const key = `${route.provider}/${route.model}`
+          if (!retired.has(key)) {
+            retired.add(key)
+            logger?.warn?.(
+              `[mydsh-auto-model-router] ${key} billed ¥${spend.toFixed(4)} this cycle — `
+              + 'it is not a free route any more; retired for this session',
+            )
+          }
+        }
+      }
+
+      snapshot = {
+        enabled: true,
+        lastCheckAt: now().toISOString(),
+        lastError: null,
+        balanceCny: balance.availableCny,
+        cycle: bill.cycle,
+        spendByModel: bill.byModel,
+        totalCny: bill.total,
+        exhausted: router.exhaustedRouteKeys(),
+        balanceLow: router.isBalanceLow(),
+        deepseekBalanceCny: deepseekBalance?.totalCny ?? null,
+        deepseekBlocked: router.isProviderBlocked(config.deepseekProvider),
+        deepseekError,
+      }
+    } catch (error) {
+      snapshot = { ...snapshot, lastCheckAt: now().toISOString(), lastError: String(error?.message ?? error) }
+      logger?.warn?.(`[mydsh-auto-model-router] quota check failed: ${error?.message ?? error}`)
+    } finally {
+      running = false
+    }
+    return snapshot
+  }
+
+  return {
+    check,
+    snapshot: () => snapshot,
+    /** Start polling; returns a disposer. */
+    start() {
+      if (config.enabled !== true) return () => {}
+      if (timer !== undefined) return () => stop()
+      // Kick off immediately, then on the configured cadence.
+      void check()
+      timer = setInterval(() => void check(), config.pollMs)
+      timer.unref?.()
+      return () => stop()
+    },
+    stop,
+  }
+
+  function stop() {
+    if (timer !== undefined) clearInterval(timer)
+    timer = undefined
+  }
+}

package/router.mjs

@@ -63,6 +63,12 @@ export class ModelRouter {
     /** provider/model → context window learned from the host catalog. */
     this.contextWindows = new Map()
     this.contextWindowsAt = 0
+    /** Routes retired by the quota watchdog (provider/model keys). */
+    this.exhaustedRoutes = new Set()
+    /** True while the account balance sits below the configured floor. */
+    this.balanceLow = false
+    /** Providers paused by a per-provider balance floor (e.g. deepseek-official). */
+    this.blockedProviders = new Set()
     /** @type {Map<string, object>} */
     this.states = new Map()
   }
@@ -208,12 +214,103 @@ export class ModelRouter {
       const fresh = this.nearestFreshLevel(level)
       if (fresh !== null) use = fresh
     }
-    const route = this.effectiveRoute(state, sessionId, use)
+    let route = this.effectiveRoute(state, sessionId, use)
+    // A route the quota watchdog retired (a "free" model that started billing,
+    // or any paid route once the balance floor is crossed) must not be picked.
+    if (this.routeBlocked(route)) {
+      for (const id of LEVEL_IDS) {
+        if (id === use) continue
+        const alternative = this.effectiveRoute(state, sessionId, id)
+        if (!this.routeBlocked(alternative)) {
+          use = id
+          route = alternative
+          break
+        }
+      }
+    }
     state.level = use
     state.current = route
     return route
   }
 
+  // ── quota watchdog state ────────────────────────────────────────────────
+
+  /**
+   * Retire a route: the watchdog keeps this out of routing until it is cleared.
+   * Fired when a route that should be free starts showing billable spend.
+   * @param {object} route - { provider, model }
+   */
+  markRouteExhausted(route) {
+    if (!route?.provider || !route?.model) return
+    this.exhaustedRoutes.add(this.routeKey(route))
+  }
+
+  /** Re-admit a retired route (the next billing cycle resets every month). */
+  clearRouteExhausted(route) {
+    if (!route?.provider || !route?.model) return
+    this.exhaustedRoutes.delete(this.routeKey(route))
+  }
+
+  /** Every route the watchdog retired, as `provider/model` keys. */
+  exhaustedRouteKeys() {
+    return [...this.exhaustedRoutes]
+  }
+
+  /** Whether a route was retired by the watchdog. */
+  isRouteExhausted(route) {
+    if (!route?.provider || !route?.model) return false
+    return this.exhaustedRoutes.has(this.routeKey(route))
+  }
+
+  /**
+   * Account balance crossed the configured floor: paid routes stop being
+   * chosen until the watchdog clears the flag.
+   * @param {boolean} low
+   */
+  setBalanceLow(low) {
+    this.balanceLow = low === true
+  }
+
+  /** Whether paid routes are currently refused. */
+  isBalanceLow() {
+    return this.balanceLow === true
+  }
+
+  /**
+   * Pause every route of one provider (a provider whose own balance is below
+   * its floor). The rest of the ladder keeps working.
+   * @param {string} provider
+   * @param {boolean} blocked
+   */
+  setProviderBlocked(provider, blocked) {
+    if (typeof provider !== 'string' || provider === '') return
+    if (blocked) this.blockedProviders.add(provider)
+    else this.blockedProviders.delete(provider)
+  }
+
+  /** Whether a provider is paused by its own balance floor. */
+  isProviderBlocked(provider) {
+    return this.blockedProviders.has(provider)
+  }
+
+  /** Every provider currently paused, for the status report. */
+  blockedProviderList() {
+    return [...this.blockedProviders]
+  }
+
+  /**
+   * Whether this route must not be dispatched to right now.
+   * @param {object} route
+   * @returns {boolean}
+   */
+  routeBlocked(route) {
+    if (!route) return true
+    if (this.isRouteExhausted(route)) return true
+    if (this.isProviderBlocked(route.provider)) return true
+    if (this.balanceLow && !this.isFreeRoute(route)) return true
+    return false
+  }
+
   /**
    * Set the session mode (called by the index layer after a user answer).
    * @param {string} sessionId