@apinggithub/mydsh-auto-model-router 0.2.5 → 0.3.0

package/auto-adapter.mjs

@@ -185,7 +185,11 @@ export function createAutoAdapter(resolve = {}) {
      * indistinguishable from the model it forwards to.
      */
     async resolveModel(provider, model) {
-      const route = representativeRoute(readRouter())
+      const router = readRouter()
+      // Teach the router the real windows first: the guard and this metadata
+      // must agree on what the candidates can hold.
+      await router?.refreshContextWindows?.()
+      const route = representativeRoute(router)
       const info = await underlyingInfo(readLlm(), route)
       const efforts = reasoningEfforts(info)
       const requested = route?.reasoningEffort
@@ -193,9 +197,16 @@ export function createAutoAdapter(resolve = {}) {
         ? requested
         : info?.reasoning?.defaultEffort
       const defaultEffort = efforts.some((effort) => effort.id === wanted) ? wanted : efforts[0]?.id
-      const contextWindow = Number.isInteger(info?.context?.contextWindow) && info.context.contextWindow > 0
-        ? info.context.contextWindow
-        : FALLBACK_CONTEXT_WINDOW
+      // Report the smallest window any candidate can hold: the host budgets
+      // compaction from this value, so a conversation that fits the default
+      // level but not a free route would otherwise be assembled for a model
+      // that cannot take it.
+      const own = info?.context?.contextWindow
+      const pool = [
+        ...(typeof router?.candidateContextWindows === 'function' ? router.candidateContextWindows() : []),
+        ...(Number.isInteger(own) && own > 0 ? [own] : []),
+      ].filter((value) => Number.isInteger(value) && value > 0)
+      const contextWindow = pool.length > 0 ? Math.min(...pool) : FALLBACK_CONTEXT_WINDOW
       return {
         provider,
         id: model,

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.5'
+export const PLUGIN_VERSION = '0.3.0'
 
 export const LEVEL_IDS = Object.freeze(['L0', 'L1', 'L2', 'L3'])
 export const COST_MODES = Object.freeze(['cost-first', 'quality-first', 'balanced'])
@@ -114,6 +114,27 @@ 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,
+    // 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 +160,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 +273,47 @@ 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)
+  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.5",
+  "version": "0.3.0",
   "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,260 @@
+// 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 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 snapshot = {
+    enabled: config.enabled === true,
+    lastCheckAt: null,
+    lastError: null,
+    balanceCny: null,
+    cycle: null,
+    spendByModel: {},
+    totalCny: null,
+    exhausted: [],
+    balanceLow: false,
+  }
+
+  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
+        }
+      }
+
+      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(),
+      }
+    } 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

@@ -60,6 +60,13 @@ export class ModelRouter {
     // read (or is empty): the freshness guard fails OPEN for that provider.
     this.catalogs = new Map()
     this.catalogCheckedAt = 0
+    /** 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
     /** @type {Map<string, object>} */
     this.states = new Map()
   }
@@ -83,6 +90,8 @@ export class ModelRouter {
    */
   async decideOnInput(sessionId, { inputText = '', prevInputText = '', lastReplyText = '' } = {}) {
     const state = this.stateFor(sessionId)
+    // Lazy catalog read: the guard can only honour windows it knows about.
+    await this.refreshContextWindows()
 
     // Same input as the last decision (agent step replay, tool-call loop):
     // reuse the existing decision — NO re-judging, NO re-classification.
@@ -203,12 +212,80 @@ 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
+  }
+
+  /**
+   * 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.balanceLow && !this.isFreeRoute(route)) return true
+    return false
+  }
+
   /**
    * Set the session mode (called by the index layer after a user answer).
    * @param {string} sessionId
@@ -281,6 +358,91 @@ export class ModelRouter {
       : 0.85
   }
 
+  /**
+   * Learn every candidate route's context window from the host catalog.
+   *
+   * The context guard can only skip a route whose window it knows, so an
+   * undeclared window fails open — and a long session then overflows the model.
+   * The provider truncates generation to the few tokens that still fit, which
+   * surfaces to the user as "reached the output token limit" on every retry.
+   *
+   * Runs at most once a minute; a provider that cannot answer for an id leaves
+   * that route unknown (fail open) and is retried on the next pass.
+   */
+  async refreshContextWindows() {
+    if (typeof this.llm?.resolveModelInfo !== 'function') return
+    const now = Date.now()
+    if (now - this.contextWindowsAt < 60_000) return
+    this.contextWindowsAt = now
+    const routes = []
+    for (const id of LEVEL_IDS) {
+      const route = this.levels[id]
+      if (route) routes.push(route)
+    }
+    for (const route of this.config.freeQuota?.routes ?? []) {
+      if (route) routes.push(route)
+    }
+    for (const route of routes) {
+      const key = this.routeKey(route)
+      if (this.contextWindows.has(key)) continue
+      try {
+        const info = await this.llm.resolveModelInfo(route.provider, route.model)
+        const window = info?.context?.contextWindow
+        if (Number.isSafeInteger(window) && window > 0) this.contextWindows.set(key, window)
+      } catch {
+        // Provider does not answer for this id: leave the window unknown.
+      }
+    }
+  }
+
+  /**
+   * The window for one route: the value declared in config wins, then whatever
+   * the catalog taught us.
+   * @param {object | null | undefined} route
+   * @returns {number | undefined}
+   */
+  contextWindowOf(route) {
+    if (!route) return undefined
+    if (Number.isFinite(route.contextWindow) && route.contextWindow > 0) return route.contextWindow
+    return this.contextWindows.get(this.routeKey(route))
+  }
+
+  /**
+   * Whether a route can hold `size` context tokens. An unknown window is
+   * assumed to fit, so a host without catalog access keeps working.
+   * @param {object} route
+   * @param {number} size
+   * @returns {boolean}
+   */
+  fitsContext(route, size) {
+    const window = this.contextWindowOf(route)
+    if (!Number.isFinite(window) || window <= 0) return true
+    return size <= window * this.contextHeadroom()
+  }
+
+  /**
+   * Windows of every route a request for `level` can actually be dispatched to:
+   * the level itself plus the free routes covering it. The virtual `auto` model
+   * reports the smallest of them so the host never assembles a conversation
+   * that some candidate cannot hold.
+   * @param {string} [level]
+   * @returns {number[]}
+   */
+  candidateContextWindows(level = this.config.costControl?.defaultLevel ?? 'L1') {
+    const out = []
+    const own = this.contextWindowOf(this.levels?.[level])
+    if (Number.isFinite(own)) out.push(own)
+    const index = levelIndex(level)
+    if (index !== -1 && typeof this.freeQuotaRoutes === 'function') {
+      for (const entry of this.freeQuotaRoutes()) {
+        if (levelIndex(entry.maxLevel) < index) continue
+        const window = this.contextWindowOf(entry)
+        if (Number.isFinite(window)) out.push(window)
+      }
+    }
+    return out
+  }
+
   /**
    * The conversation size the guard compares against: the input side of the
    * last completed request in this session (uncached + cache-read + cache-write).
@@ -321,13 +483,10 @@ export class ModelRouter {
     if (size <= 0) return level
     const index = levelIndex(level)
     if (index === -1) return level
-    const headroom = this.contextHeadroom()
     const fits = (id) => {
       const route = this.levels[id]
       if (!route) return false
-      const window = route.contextWindow
-      if (!Number.isFinite(window) || window <= 0) return true
-      return size <= window * headroom
+      return this.fitsContext(route, size)
     }
     if (fits(level)) return level
     const ladder = []
@@ -513,10 +672,15 @@ export class ModelRouter {
     if (!this.freeQuotaEnabled()) return null
     const index = levelIndex(level)
     if (index === -1) return null
+    // A free route that cannot hold the conversation is not a candidate: the
+    // provider would truncate the answer to whatever fits, which reads as
+    // "reached the output token limit".
+    const size = this.stateFor(sessionId).contextTokens ?? 0
     for (const entry of this.freeQuotaRoutes()) {
       if (levelIndex(entry.maxLevel) < index) continue
       if (this.isExhausted(sessionId, entry)) continue
       if (this.routeStale(entry)) continue
+      if (size > 0 && !this.fitsContext(entry, size)) continue
       return entry
     }
     return null