@apinggithub/mydsh-auto-model-router 0.0.0-stage → 0.2.1

package/config.mjs

@@ -0,0 +1,461 @@
+// Config resolution and validation for mydsh-auto-model-router (level-based design).
+//
+// The router works over four capability levels (L0…L3); each level is a
+// provider/model route the user assigns. Three routing modes live on top:
+//
+//   MODE A heuristic lock (default): counts the last N user inputs' text
+//     width and maps ranges to levels (a cheap L0/L1 lock). Crossing the top
+//     threshold asks the user once how to proceed.
+//   MODE B fixed model: user picked an explicit level; re-asks every
+//     askEveryInputs user inputs.
+//   MODE C fully-auto: keyword-scored rules (rules + scoring) decide first;
+//     zero score falls through to the LLM classifier (llmClassifier), which
+//     judges on the window of 本次输入 + 上次输入 + 上次回复.
+//
+//   levels:         { L0: route, L1: route, L2: route, L3: route }
+//   heuristic:      { windowSize, counting, thresholds }
+//   rules:          [{ match, level }]  (scored per hit)
+//   scoring:        { weights, bands }
+//   costControl:    { enabled, mode, defaultLevel, tokenBudgetPerSession }
+//   llmClassifier:  { enabled, model, requestTimeoutMs }
+//   askEveryInputs: fixed-model re-ask cadence
+//   fallbackChain:  [route, ...]  (model-level, appended with the default)
+//   maxRetries:     per-route retry budget on request-error
+
+export const PLUGIN_VERSION = '0.2.1'
+
+export const LEVEL_IDS = Object.freeze(['L0', 'L1', 'L2', 'L3'])
+export const COST_MODES = Object.freeze(['cost-first', 'quality-first', 'balanced'])
+export const DOWNGRADE_BEHAVIORS = Object.freeze(['silent', 'notify', 'ask'])
+export const DEFAULT_LEVEL = 'L1'
+/** Highest level a free route serves when `freeQuota.routes[].maxLevel` is omitted. */
+export const DEFAULT_FREE_MAX_LEVEL = 'L1'
+export const COUNTING_MODES = Object.freeze(['cjk2', 'tokens'])
+
+const DEFAULT_CONFIG = Object.freeze({
+  // Factory defaults must be valid on the 0.2.x host family: the DeepSeek
+  // catalog advertises `deepseek-flash` (V4.1 Flash) and the adapter accepts
+  // only off/low/high/max. The previous defaults (`deepseek-v4-flash`,
+  // `medium`) were stale and made a fresh install without a levels block fail.
+  levels: {
+    L0: { provider: 'deepseek-official', model: 'deepseek-flash', reasoningEffort: 'off' },
+    L1: { provider: 'deepseek-official', model: 'deepseek-flash', reasoningEffort: 'low' },
+    L2: { provider: 'deepseek-official', model: 'deepseek-flash', reasoningEffort: 'high' },
+    L3: { provider: 'deepseek-official', model: 'deepseek-flash', reasoningEffort: 'max' },
+  },
+  // Keyword rules only take part in MODE C (fully-auto). Default empty.
+  rules: [],
+  heuristic: {
+    windowSize: 3,
+    counting: 'cjk2',
+    thresholds: [
+      { maxChars: 10, level: 'L0' },
+      { maxChars: 100, level: 'L1' },
+    ],
+  },
+  scoring: {
+    weights: { L1: 1, L2: 2, L3: 3 },
+    bands: [
+      { maxScore: 0, level: 'L0' },
+      { maxScore: 5, level: 'L1' },
+      { maxScore: 15, level: 'L2' },
+      { maxScore: null, level: 'L3' },
+    ],
+  },
+  costControl: {
+    enabled: true,
+    mode: 'balanced',
+    defaultLevel: DEFAULT_LEVEL,
+    // 0 = no budget limit: the cost layer never downgrades from budget
+    // exhaustion (downgradeBehavior is then inert). Set a positive value
+    // to cap per-session spend.
+    tokenBudgetPerSession: 0,
+    downgradeBehavior: 'notify',
+  },
+  llmClassifier: {
+    enabled: true,
+    model: { provider: 'deepseek-official', model: 'deepseek-flash' },
+    requestTimeoutMs: 10_000,
+  },
+  // Tier 3: free-quota preference. Routes declared free are preferred for the
+  // levels they cover; a free route that fails is demoted for the session and
+  // the level falls back to its paid route instead of failing the turn.
+  freeQuota: {
+    // Auto-disabled when nothing is declared free (no behaviour change for
+    // existing users): see resolveConfig.
+    enabled: true,
+    // Extra free routes that are not levels themselves. `maxLevel` is the
+    // highest level the free route is trusted for (inclusive), default L1.
+    routes: [],
+    // Demote a free route for the rest of the session as soon as one request
+    // fails on it (quota exhausted, rate limited, rejected, ...).
+    demoteOnError: true,
+    // Tell the user once per session when a free route was demoted.
+    notify: true,
+  },
+  // Tier 5: context-window guard. A level whose declared `contextWindow`
+  // cannot hold the conversation is skipped — the router drifts up to the
+  // nearest level that fits — so a long session never lands on a model that
+  // has no room left for output (which surfaces as a truncated answer).
+  contextGuard: {
+    // Auto-disabled when no level declares a contextWindow.
+    enabled: true,
+    // A level "fits" while the conversation stays under window * headroom,
+    // leaving room for the answer.
+    headroom: 0.85,
+  },
+  // Tier 6: catalog freshness guard. Level/free routes are validated against
+  // what each provider actually advertises (`ctx.llm.listModels`); a route the
+  // provider no longer lists is stale — the level skips to the nearest fresh
+  // one and `/status` names it with same-family candidate ids. Inert (fail
+  // open) whenever a catalog cannot be read or comes back empty.
+  modelsGuard: {
+    enabled: true,
+    // Re-read provider catalogs every N ms (also validated once at activation).
+    refreshMs: 600_000,
+  },
+  askEveryInputs: 3,
+  fallbackChain: [],
+  maxRetries: 1,
+})
+
+/**
+ * Resolve and validate the effective router configuration.
+ * @param {object} input - the `config:` block from the cordis patch.
+ * @returns {object} validated, defaults-filled config.
+ * @throws {Error} naming the offending field on invalid input.
+ */
+export function resolveConfig(input = {}) {
+  const cfg = {
+    ...DEFAULT_CONFIG,
+    ...input,
+  }
+  cfg.levels = normalizeLevels(cfg.levels)
+  cfg.rules = normalizeRules(cfg.rules)
+  cfg.heuristic = normalizeHeuristic(cfg.heuristic)
+  cfg.scoring = normalizeScoring(cfg.scoring)
+  cfg.costControl = normalizeCostControl(cfg.costControl)
+  cfg.llmClassifier = normalizeClassifier(cfg.llmClassifier)
+  cfg.freeQuota = normalizeFreeQuota(cfg.freeQuota)
+  cfg.contextGuard = normalizeContextGuard(cfg.contextGuard)
+  cfg.modelsGuard = normalizeModelsGuard(cfg.modelsGuard)
+  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)
+  // Nothing declared free (neither a level flag nor a freeQuota.routes entry)
+  // means the whole layer is inert — keep existing profiles byte-identical in
+  // behaviour.
+  cfg.freeQuota.enabled = cfg.freeQuota.enabled
+    && (cfg.freeQuota.routes.length > 0 || LEVEL_IDS.some((id) => cfg.levels[id]?.freeQuota === true))
+  // Nothing declares a window → the guard is inert (no behaviour change).
+  cfg.contextGuard.enabled = cfg.contextGuard.enabled
+    && LEVEL_IDS.some((id) => Number.isFinite(cfg.levels[id]?.contextWindow))
+  // Exposed to the status endpoint and the browser settings page so a bug
+  // report always names the build that produced it.
+  cfg.pluginVersion = PLUGIN_VERSION
+  return cfg
+}
+
+/**
+ * Normalize the context-window guard. `headroom` is clamped into (0, 1].
+ */
+function normalizeContextGuard(contextGuard) {
+  const guard = {
+    ...DEFAULT_CONFIG.contextGuard,
+    ...(contextGuard ?? {}),
+  }
+  guard.enabled = guard.enabled !== false
+  let headroom = Number(guard.headroom)
+  if (!Number.isFinite(headroom) || headroom <= 0 || headroom > 1) {
+    headroom = DEFAULT_CONFIG.contextGuard.headroom
+  }
+  guard.headroom = headroom
+  return guard
+}
+
+/**
+ * Normalize the catalog freshness guard. `refreshMs` is clamped to a sane
+ * range so a typo cannot turn the periodic re-check into a hot loop.
+ */
+function normalizeModelsGuard(modelsGuard) {
+  const guard = {
+    ...DEFAULT_CONFIG.modelsGuard,
+    ...(modelsGuard ?? {}),
+  }
+  guard.enabled = guard.enabled !== false
+  guard.refreshMs = clampInt(guard.refreshMs, 30_000, 24 * 60 * 60 * 1000, DEFAULT_CONFIG.modelsGuard.refreshMs)
+  return guard
+}
+
+/**
+ * Normalize the free-quota layer. `routes` entries are provider/model pairs
+ * with an optional inclusive `maxLevel` ceiling.
+ */
+function normalizeFreeQuota(freeQuota) {
+  const fq = {
+    ...DEFAULT_CONFIG.freeQuota,
+    ...(freeQuota ?? {}),
+  }
+  fq.enabled = fq.enabled !== false
+  fq.demoteOnError = fq.demoteOnError !== false
+  fq.notify = fq.notify !== false
+  if (!Array.isArray(fq.routes)) {
+    throw new Error('mydsh-auto-model-router: freeQuota.routes must be an array of provider/model routes')
+  }
+  fq.routes = fq.routes.map((route, index) => {
+    const where = `freeQuota.routes[${index}]`
+    const normalized = normalizeRoute(route, where)
+    const maxLevel = route.maxLevel === undefined || route.maxLevel === null
+      ? DEFAULT_FREE_MAX_LEVEL
+      : String(route.maxLevel).trim()
+    if (!LEVEL_IDS.includes(maxLevel)) {
+      throw new Error(
+        `mydsh-auto-model-router: ${where}.maxLevel must be one of ${LEVEL_IDS.join(', ')}, got "${maxLevel}"`,
+      )
+    }
+    // Ride along with an explicit effort, exactly like a level route, so the
+    // dispatched request never falls back to the adapter's own default
+    // thinking level by accident.
+    return {
+      ...normalized,
+      reasoningEffort: normalized.reasoningEffort ?? 'off',
+      maxLevel,
+    }
+  })
+  return fq
+}
+
+function normalizeHeuristic(heuristic) {
+  const h = {
+    ...DEFAULT_CONFIG.heuristic,
+    ...(heuristic ?? {}),
+  }
+  h.windowSize = clampInt(h.windowSize, 1, 20, DEFAULT_CONFIG.heuristic.windowSize)
+  if (!COUNTING_MODES.includes(h.counting)) {
+    throw new Error(
+      `mydsh-auto-model-router: heuristic.counting must be one of ${COUNTING_MODES.join(', ')}, got "${h.counting}"`,
+    )
+  }
+  if (!Array.isArray(h.thresholds) || h.thresholds.length === 0) {
+    throw new Error('mydsh-auto-model-router: heuristic.thresholds must be a non-empty array')
+  }
+  h.thresholds = h.thresholds.map((t, index) => {
+    if (!LEVEL_IDS.includes(t.level)) {
+      throw new Error(`mydsh-auto-model-router: heuristic.thresholds[${index}].level must be one of ${LEVEL_IDS.join(', ')}`)
+    }
+    const maxChars = t.maxChars === null || t.maxChars === undefined
+      ? null
+      : clampInt(t.maxChars, 0, 1_000_000, 0)
+    return { maxChars, level: t.level }
+  })
+  return h
+}
+
+function normalizeScoring(scoring) {
+  const s = {
+    ...DEFAULT_CONFIG.scoring,
+    ...(scoring ?? {}),
+  }
+  const weights = {}
+  for (const id of LEVEL_IDS) {
+    const value = Number(s.weights?.[id])
+    weights[id] = Number.isFinite(value) && value > 0 ? value : (id === 'L0' ? 0 : 1)
+  }
+  s.weights = weights
+  if (!Array.isArray(s.bands) || s.bands.length === 0) {
+    throw new Error('mydsh-auto-model-router: scoring.bands must be a non-empty array')
+  }
+  s.bands = s.bands.map((b, index) => {
+    if (!LEVEL_IDS.includes(b.level)) {
+      throw new Error(`mydsh-auto-model-router: scoring.bands[${index}].level must be one of ${LEVEL_IDS.join(', ')}`)
+    }
+    return {
+      maxScore: b.maxScore === null || b.maxScore === undefined
+        ? null
+        : clampInt(b.maxScore, 0, 1_000_000, 0),
+      level: b.level,
+    }
+  })
+  return s
+}
+
+/**
+ * Every level may be omitted except the cost-control default level, which must
+ * exist. Returns a level map keyed by LEVEL_IDS with undefined holes. Each
+ * configured level carries an explicit reasoningEffort (default 'off').
+ */
+function normalizeLevels(levels) {
+  const source = levels ?? {}
+  const out = {}
+  for (const id of LEVEL_IDS) {
+    const route = source[id]
+    out[id] = route === undefined || route === null
+      ? undefined
+      : normalizeLevelRoute(route, `levels.${id}`)
+  }
+  return out
+}
+
+function normalizeLevelRoute(route, where) {
+  const normalized = normalizeRoute(route, where)
+  // Levels always carry an explicit reasoning effort; absent → 'off' (no
+  // thinking mode) so every level spells out its thinking intensity.
+  const contextWindow = route.contextWindow === undefined || route.contextWindow === null
+    ? undefined
+    : Number(route.contextWindow)
+  if (contextWindow !== undefined && (!Number.isSafeInteger(contextWindow) || contextWindow <= 0)) {
+    throw new Error(`mydsh-auto-model-router: "${where}.contextWindow" must be a positive integer, got ${JSON.stringify(route.contextWindow)}`)
+  }
+  return {
+    ...normalized,
+    reasoningEffort: normalized.reasoningEffort ?? 'off',
+    // A level may declare that its route is a free-quota route. The flag rides
+    // along with the route so the router can prefer/demote it.
+    ...route.freeQuota === true ? { freeQuota: true } : {},
+    // A level may declare its model's context window for the guard.
+    ...contextWindow !== undefined ? { contextWindow } : {},
+  }
+}
+
+function normalizeRoute(route, where) {
+  if (route === undefined || route === null) {
+    throw new Error(`mydsh-auto-model-router: "${where}" requires a provider/model route`)
+  }
+  const provider = String(route.provider ?? '').trim()
+  const model = String(route.model ?? '').trim()
+  if (!provider || !model) {
+    throw new Error(
+      `mydsh-auto-model-router: "${where}" needs both provider and model, got ${JSON.stringify(route)}`,
+    )
+  }
+  const reasoningEffort = route.reasoningEffort === undefined
+    ? undefined
+    : String(route.reasoningEffort).trim() || undefined
+  return {
+    provider,
+    model,
+    ...reasoningEffort === undefined ? {} : { reasoningEffort },
+  }
+}
+
+function normalizeRules(rules) {
+  if (!Array.isArray(rules)) {
+    throw new Error('mydsh-auto-model-router: "rules" must be an array')
+  }
+  return rules.map((rule, index) => {
+    if (typeof rule.match !== 'string' || rule.match.trim() === '') {
+      throw new Error(`mydsh-auto-model-router: rules[${index}] needs a non-empty "match" pattern`)
+    }
+    if (!LEVEL_IDS.includes(rule.level)) {
+      throw new Error(
+        `mydsh-auto-model-router: rules[${index}].level must be one of ${LEVEL_IDS.join(', ')}, got "${rule.level}"`,
+      )
+    }
+    return {
+      match: rule.match.trim(),
+      regex: compilePattern(rule.match.trim(), index),
+      level: rule.level,
+    }
+  })
+}
+
+function compilePattern(pattern, index) {
+  // A pattern surrounded by slashes is treated as a RegExp literal,
+  // anything else as a plain substring (case-insensitive).
+  const trimmed = pattern.trim()
+  if (trimmed.startsWith('/') && trimmed.lastIndexOf('/') > 0) {
+    const lastSlash = trimmed.lastIndexOf('/')
+    const body = trimmed.slice(1, lastSlash)
+    const flags = trimmed.slice(lastSlash + 1)
+    try {
+      return new RegExp(body, flags.includes('i') ? flags : `${flags}i`)
+    } catch (error) {
+      throw new Error(
+        `mydsh-auto-model-router: rules[${index}] has an invalid regex "${pattern}": ${error instanceof Error ? error.message : String(error)}`,
+      )
+    }
+  }
+  return null
+}
+
+function normalizeCostControl(costControl) {
+  const cc = {
+    ...DEFAULT_CONFIG.costControl,
+    ...(costControl ?? {}),
+  }
+  cc.enabled = cc.enabled !== false
+  if (!COST_MODES.includes(cc.mode)) {
+    throw new Error(
+      `mydsh-auto-model-router: costControl.mode must be one of ${COST_MODES.join(', ')}, got "${cc.mode}"`,
+    )
+  }
+  if (!LEVEL_IDS.includes(cc.defaultLevel)) {
+    throw new Error(
+      `mydsh-auto-model-router: costControl.defaultLevel must be one of ${LEVEL_IDS.join(', ')}, got "${cc.defaultLevel}"`,
+    )
+  }
+  cc.tokenBudgetPerSession = clampInt(
+    cc.tokenBudgetPerSession,
+    0, // 0 = no budget limit
+    100_000_000,
+    DEFAULT_CONFIG.costControl.tokenBudgetPerSession,
+  )
+  if (!DOWNGRADE_BEHAVIORS.includes(cc.downgradeBehavior)) {
+    throw new Error(
+      `mydsh-auto-model-router: costControl.downgradeBehavior must be one of ${DOWNGRADE_BEHAVIORS.join(', ')}, got "${cc.downgradeBehavior}"`,
+    )
+  }
+  return cc
+}
+
+function normalizeClassifier(classifier) {
+  const cl = {
+    ...DEFAULT_CONFIG.llmClassifier,
+    ...(classifier ?? {}),
+  }
+  cl.enabled = cl.enabled === true
+  if (cl.enabled) {
+    cl.model = cl.model === undefined
+      ? undefined
+      : normalizeRoute(cl.model, 'llmClassifier.model')
+  }
+  cl.requestTimeoutMs = clampInt(cl.requestTimeoutMs, 1_000, 120_000, 10_000)
+  return cl
+}
+
+function normalizeChain(chain) {
+  if (chain === undefined || chain === null) return []
+  if (!Array.isArray(chain)) {
+    throw new Error('mydsh-auto-model-router: "fallbackChain" must be an array of provider/model routes')
+  }
+  return chain.map((route, index) => normalizeRoute(route, `fallbackChain[${index}]`))
+}
+
+/**
+ * Level helper: the level index 0…3 for a LEVEL_IDS entry.
+ * @param {string} level
+ * @returns {number} 0-based index.
+ */
+export function levelIndex(level) {
+  return LEVEL_IDS.indexOf(level)
+}
+
+/**
+ * Clamp a level id by at most one step in a direction, staying inside L0…L3.
+ * @param {string} level - starting level.
+ * @param {'up'|'down'|0} direction - drift direction.
+ * @returns {string}
+ */
+export function driftLevel(level, direction) {
+  const index = levelIndex(level)
+  if (index === -1) return level
+  if (direction === 'up') return LEVEL_IDS[Math.min(3, index + 1)]
+  if (direction === 'down') return LEVEL_IDS[Math.max(0, index - 1)]
+  return level
+}
+
+function clampInt(value, minimum, maximum, fallback) {
+  const number = Math.round(Number(value))
+  if (!Number.isFinite(number)) return fallback
+  return Math.max(minimum, Math.min(maximum, number))
+}

package/cordis.patch.yml

@@ -0,0 +1,11 @@
+# mydsh-auto-model-router — the cordis patch layer. Mounts the router inside an
+# isolated group; the runtime registers model-facing hooks on agent scopes.
+- insert:
+    - id: mydsh-auto-model-router
+      name: '@deepseek-ai/cordis-plugin-group'
+      group: true
+      isolate:
+        modelRouter: true
+      config:
+        - id: mydsh-auto-model-router-runtime
+          name: '@apinggithub/mydsh-auto-model-router'

package/cost-control.mjs

@@ -0,0 +1,159 @@
+// Cost-control layer (tier 2): the user picks a mode, and that mode decides
+// (a) the default level for unmatched tasks and (b) the drift direction when
+// the router must break a tie (ambiguous classification, budget pressure).
+//
+//   cost-first:    default to the LOWEST configured level; ambiguity drifts DOWN.
+//   quality-first: default to the HIGHEST configured level; ambiguity drifts UP.
+//   balanced:      default to costControl.defaultLevel; ambiguity stays put.
+//
+// The session token budget forces a pin to the cheap level when exhausted.
+
+import { LEVEL_IDS, levelIndex, driftLevel } from './config.mjs'
+
+export class CostControl {
+  /**
+   * @param {object} config - normalized costControl config from resolveConfig.
+   * @param {object} levels - normalized levels map from resolveConfig.
+   */
+  constructor(config, levels) {
+    this.config = config
+    this.levels = levels
+    /** @type {Map<string, {spentTokens: number}>} */
+    this.states = new Map()
+  }
+
+  enabled() {
+    return this.config.enabled
+  }
+
+  /**
+   * The default level for a task that matched no rule.
+   * @returns {string} a LEVEL_IDS entry.
+   */
+  defaultLevel() {
+    const mode = this.config.mode
+    if (mode === 'cost-first') return this.lowestConfiguredLevel()
+    if (mode === 'quality-first') return this.highestConfiguredLevel()
+    return this.config.defaultLevel
+  }
+
+  /**
+   * Drift a level by one step in the mode's preferred direction when the
+   * router faces ambiguity (classifier returned a level but with low
+   * confidence, or a level with no configured model).
+   * @param {string} level
+   * @param {boolean} [ambiguous=true]
+   * @returns {string}
+   */
+  resolveAmbiguous(level, ambiguous = true) {
+    if (!ambiguous) return level
+    const mode = this.config.mode
+    if (mode === 'cost-first') return driftLevel(level, 'down')
+    if (mode === 'quality-first') return driftLevel(level, 'up')
+    return level
+  }
+
+  /**
+   * Whether a session has exhausted its budget and should be pinned to the
+   * cheap level for the rest of the session.
+   * @param {string} sessionId
+   * @param {number} [measuredTokens]
+   * @returns {boolean}
+   */
+  isOverBudget(sessionId, measuredTokens) {
+    if (!this.config.enabled) return false
+    // 0 = no budget limit.
+    if (this.config.tokenBudgetPerSession <= 0) return false
+    const state = this.states.get(sessionId)
+    if (!state) return false
+    const spent = measuredTokens ?? state.spentTokens
+    return spent >= this.config.tokenBudgetPerSession
+  }
+
+  /**
+   * Record token spend for one session.
+   * @param {string} sessionId
+   * @param {number} tokens
+   */
+  addSpend(sessionId, tokens) {
+    if (!this.config.enabled || !Number.isFinite(tokens) || tokens <= 0) return
+    const state = this.stateFor(sessionId)
+    state.spentTokens += Math.round(tokens)
+  }
+
+  /**
+   * Read the current spend for a session.
+   * @param {string} sessionId
+   * @returns {number}
+   */
+  spentTokens(sessionId) {
+    return this.states.get(sessionId)?.spentTokens ?? 0
+  }
+
+  /** Forget all per-session state (e.g. between runs in tests). */
+  reset() {
+    this.states.clear()
+  }
+
+  /** Delete one session's state (on session-start). */
+  resetSession(sessionId) {
+    this.states.delete(sessionId)
+  }
+
+  lowestConfiguredLevel() {
+    for (const id of LEVEL_IDS) {
+      if (this.levels[id]) return id
+    }
+    return this.config.defaultLevel
+  }
+
+  highestConfiguredLevel() {
+    for (let i = LEVEL_IDS.length - 1; i >= 0; i--) {
+      if (this.levels[LEVEL_IDS[i]]) return LEVEL_IDS[i]
+    }
+    return this.config.defaultLevel
+  }
+
+  /**
+   * The cheap level the budget pin uses: the lowest level with a model.
+   * @returns {string}
+   */
+  cheapLevel() {
+    return this.lowestConfiguredLevel()
+  }
+
+  stateFor(sessionId) {
+    let state = this.states.get(sessionId)
+    if (!state) {
+      state = { spentTokens: 0 }
+      this.states.set(sessionId, state)
+    }
+    return state
+  }
+}
+
+/**
+ * Estimate tokens for a message the cheap way (chars/4, CJK at 1.5/char)
+ * used only when ctx.tokenMeter is absent.
+ * @param {object} message
+ * @returns {number}
+ */
+export function estimateMessageTokens(message) {
+  const text = textOf(message)
+  let cjk = 0
+  for (let i = 0; i < text.length; i++) {
+    if (text.charCodeAt(i) >= 0x3000) cjk++
+  }
+  return Math.ceil(cjk * 1.5 + (text.length - cjk) / 4)
+}
+
+function textOf(message) {
+  const content = message?.content
+  if (typeof content === 'string') return content
+  if (Array.isArray(content)) {
+    return content
+      .map((block) => (typeof block?.text === 'string' ? block.text : ''))
+      .join('\n')
+  }
+  return ''
+}

package/fallback.mjs

@@ -0,0 +1,62 @@
+// Fallback layer (tier 4): on agent/request-error, walk the fallback chain
+// and retry with the next route. The chain is appended with the router's
+// default route (the cost default level's model) when the user does not list
+// it explicitly, so a fully custom chain still ends at a sane terminal route.
+
+import { routesEqual } from './router.mjs'
+
+export class FallbackChain {
+  /**
+   * @param {object[]} fallbackChain - normalized fallbackChain from resolveConfig.
+   * @param {object} defaultRoute - the router's default route to append.
+   * @param {number} maxRetries - per-route retry budget on request-error.
+   */
+  constructor(fallbackChain, defaultRoute, maxRetries = 1) {
+    this.config = { maxRetries }
+    this.chain = buildChain(fallbackChain ?? [], defaultRoute)
+  }
+
+  /**
+   * Find the next route after `current` in the chain, wrapping around to the
+   * head after the tail. Returns null when the chain has < 2 distinct routes
+   * (nothing to fall back to).
+   * @param {object} current - { provider, model }.
+   * @returns {object | null}
+   */
+  nextAfter(current) {
+    if (this.chain.length < 2) return null
+    const index = this.chain.findIndex((route) => routesEqual(route, current))
+    if (index === -1) return this.chain[0]
+    return this.chain[(index + 1) % this.chain.length]
+  }
+
+  /**
+   * Whether retrying makes sense after a failure on `current` given how many
+   * retries this session already burned on this route.
+   * @param {object} current
+   * @param {number} retriesOnRoute
+   * @returns {boolean}
+   */
+  canRetry(current, retriesOnRoute) {
+    if (retriesOnRoute >= this.config?.maxRetries ?? 1) return false
+    const next = this.nextAfter(current)
+    return next !== null && !routesEqual(next, current)
+  }
+}
+
+function buildChain(fallbackChain, defaultRoute) {
+  const chain = [...fallbackChain]
+  // Ensure a terminal member so a custom chain that omits the default still
+  // ends at the router's default route.
+  if (!chain.some((route) => routesEqual(route, defaultRoute))) {
+    chain.push(defaultRoute)
+  }
+  // De-duplicate consecutive identical routes (harmless but noisy).
+  const unique = []
+  for (const route of chain) {
+    if (route && (unique.length === 0 || !routesEqual(unique[unique.length - 1], route))) {
+      unique.push(route)
+    }
+  }
+  return unique
+}