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

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
+}

package/index.mjs

@@ -0,0 +1,307 @@
+// mydsh-auto-model-router plugin entry. Registers the routing layers onto the
+// DSH agent lifecycle:
+//
+//   agent/pre-step          → token accounting + user-input boundary detection
+//   system-prompt/assemble  → keep {{model}} consistent with routing
+//   agent/request           → reuse the per-input decision (no re-judging per step)
+//   agent/request-error     → fallback chain (retry with next route)
+//   session/event           → token spend tracking
+//   agent/session-start     → per-session state reset + one-time status
+//                             report & cost-mode question (no client UI)
+//
+// A NEW user input is detected when the last user message's text changes
+// between requests. Only then does the router make a fresh decision (heuristic
+// lock / fixed model / fully-auto). All agent/request steps within the same
+// user input reuse that decision — the LLM classifier is never called per step.
+//
+// The plugin also registers a virtual `auto` provider adapter so the model
+// selector shows an "Auto Router" entry. When the user picks Auto, this
+// plugin routes the session; any real provider/model picked by the user passes
+// through untouched.
+
+import { resolveConfig } from './config.mjs'
+import { ModelRouter } from './router.mjs'
+import { AutoAdapter, isAutoSelection } from './auto-adapter.mjs'
+import {
+  reportStatus, persistStatusReport, statusReport, notifyDowngrade,
+  askDowngrade, resolveLocale, askModeSelection, askFixedLevel,
+  notifyFreeQuotaFallback,
+} from './notify.mjs'
+
+export const name = 'mydsh-auto-model-router'
+export const inject = ['agents', 'sessions', 'tools', 'llm', 'tokenMeter']
+
+export function apply(ctx, input = {}) {
+  const config = resolveConfig(input)
+  const router = new ModelRouter(config, {
+    llm: ctx.llm,
+    tokenMeter: ctx.tokenMeter,
+  })
+  ctx.provide('modelRouter', router)
+  // Global backstop so the virtual auto adapter can forward a request that
+  // reaches it without an agent/request interception.
+  globalThis.__dshAutoModelRouter = router
+  globalThis.__dshLl = ctx.llm
+  ctx.effect(
+    () => () => {
+      router.cost.reset()
+      delete globalThis.__dshAutoModelRouter
+      delete globalThis.__dshLl
+    },
+    'modelRouter.reset()',
+  )
+
+  // Register the virtual "auto" provider so the model selector shows it.
+  const autoRegistration = ctx.llm?.registerAdapter?.(
+    ['auto'],
+    AutoAdapter,
+  )
+  ctx.effect(
+    () => () => autoRegistration?.(),
+    'modelRouter.unregisterAutoAdapter()',
+  )
+
+  // ── catalog freshness: read provider catalogs at activation, then poll ──
+  // A retired model id makes its level stale; the router then drifts around it
+  // and the status report names same-family candidates for the one-line fix.
+  ctx.effect(() => {
+    if (typeof ctx.llm?.listModels !== 'function') return undefined
+    void router.refreshCatalogs()
+    const timer = setInterval(() => void router.refreshCatalogs(), config.modelsGuard.refreshMs)
+    timer.unref?.()
+    return () => clearInterval(timer)
+  }, 'modelRouter.catalogWatch()')
+
+  // ── 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).
+  //
+  // The webserver is claimed through a *scoped injection* instead of a hard
+  // `inject` entry: headless deployments have no webserver and must still
+  // route. A plain `ctx.get('webServer')` is not enough — at boot the service
+  // is not up yet, so the lookup returns nothing, the registration is skipped,
+  // and the exact route is never claimed (requests then fall through to the
+  // `/api` prefix owner and answer 401). `ctx.inject` runs the callback when —
+  // and only when — the service exists.
+  const statusRoute = {
+    kind: 'exact',
+    path: '/api/mydsh-auto-model-router/status',
+    handler: (_req, res) => {
+      const body = JSON.stringify({
+        ok: true,
+        report: statusReport(config, resolveLocale(ctx), { stale: router.staleLevels() }),
+        levels: config.levels,
+        costControl: config.costControl,
+        freeQuota: config.freeQuota,
+        contextGuard: config.contextGuard,
+        modelsGuard: config.modelsGuard,
+        staleLevels: router.staleLevels(),
+        rules: config.rules,
+        scoring: config.scoring,
+        fallbackChain: config.fallbackChain,
+      })
+      res.writeHead(200, {
+        'content-type': 'application/json; charset=utf-8',
+        'cache-control': 'no-cache',
+      })
+      res.end(body)
+    },
+  }
+  const registerStatusRoute = (scope) => scope.effect(
+    () => scope.webServer.register(statusRoute),
+    'modelRouter.statusEndpoint()',
+  )
+  if (typeof ctx.inject === 'function') {
+    ctx.inject(['webServer'], registerStatusRoute)
+  } else {
+    // Fallback for contexts without scoped injection (tests, older hosts).
+    const webServer = ctx.get?.('webServer')
+    if (webServer?.register !== undefined) {
+      registerStatusRoute({ effect: (fn) => fn(), webServer })
+    }
+  }
+
+  // ── session start: fresh routing state per session ─────────────────────
+  // Injects the status report into the session (visible, non-blocking) but
+  // never pops a dialog — configuration changes are guided through the
+  // Auto Router settings section instead.
+  ctx.on('agent/session-start', async ({ agent }) => {
+    router.resetSession(agent.session.id)
+    if (agent.status === 'idle') {
+      const locale = resolveLocale(ctx)
+      persistStatusReport(config, locale)
+      await reportStatus(agent, config, locale)
+    }
+    return true
+  })
+
+  // ── pre-step: token accounting + cache the latest user input ──────────
+  // The latest user message text changes only here (a new user input); every
+  // subsequent agent/request step of the SAME input reuses this cached text,
+  // so we never re-scan the full derived message history per step.
+  ctx.on('agent/pre-step', async ({ agent, messages, signal }, next) => {
+    const decision = await next()
+    if (decision.kind !== 'enter' || signal.aborted) return decision
+    const last = messages.at(-1)
+    if (last) router.recordTokens(agent.session.id, last)
+    // Cache the latest user text ONLY when the newest message is a user
+    // message — that is the event that opens a new user input.
+    if (last?.role === 'user') {
+      const text = messageText(last)
+      if (text !== '') router.rememberInput(agent.session.id, text)
+    }
+    return decision
+  })
+
+  // ── prompt assembly: keep {{model}} consistent with the routed model ────
+  ctx.on('system-prompt/assemble', async (assembly, _context, next) => {
+    const assembled = await next()
+    const sessionId = assembly.variables?.sessionId
+    if (!sessionId) return assembled
+    if (!router.isAutoActive(sessionId)) return assembled
+    const route = router.current(sessionId)
+    return {
+      ...assembled,
+      variables: {
+        ...assembled.variables,
+        provider: route.provider,
+        model: route.model,
+      },
+    }
+  })
+
+  // ── ★ agent/request: reuse the per-input decision ──────────────────────
+  // Only a NEW user input triggers a fresh decision (and only when the
+  // session picked the virtual auto provider). Steps within the same input
+  // reuse state.current — no per-step re-judging, no per-step classifier.
+  ctx.on('agent/request', async ({ agent }, next) => {
+    const proposed = await next()
+    const sessionId = agent.session.id
+    ctx.logger?.info?.(
+      `[mydsh-auto-model-router] agent/request session=${sessionId} proposed=${proposed?.provider}/${proposed?.model} isAuto=${isAutoSelection(proposed)}`,
+    )
+    if (!isAutoSelection(proposed)) {
+      router.markAutoInactive(sessionId)
+      return proposed
+    }
+    router.markAutoActive(sessionId)
+
+    // Use the cached latest user input (set in agent/pre-step) — do NOT
+    // re-scan the full derived message history on every step.
+    const input = router.currentInput(sessionId) ?? ''
+    const decision = await router.decideOnInput(sessionId, {
+      inputText: input,
+      prevInputText: router.lastInputText(sessionId) ?? '',
+      lastReplyText: router.lastReplyText(sessionId) ?? '',
+    })
+
+    if (decision?.needsAsk) {
+      const locale = resolveLocale(ctx)
+      if (decision.needsAsk === 'above-lock') {
+        // Ask: 固定模型 or 开启全自动.
+        const picked = await askModeSelection(ctx, agent, router, sessionId)
+        if (picked?.kind === 'fixed') {
+          router.setMode(sessionId, 'fixed', { fixedLevel: picked.level })
+        } else if (picked?.kind === 'auto') {
+          router.setMode(sessionId, 'auto')
+        }
+        // fallback: user dismissed → stay in heuristic mode.
+        const route = router.current(sessionId)
+        return { ...proposed, provider: route.provider, model: route.model,
+          ...route.reasoningEffort === undefined ? {} : { reasoningEffort: route.reasoningEffort } }
+      }
+      if (decision.needsAsk === 'fixed-reelect') {
+        const picked = await askFixedLevel(ctx, agent, router, sessionId)
+        if (picked) router.setMode(sessionId, 'fixed', { fixedLevel: picked })
+        const route = router.current(sessionId)
+        return { ...proposed, provider: route.provider, model: route.model,
+          ...route.reasoningEffort === undefined ? {} : { reasoningEffort: route.reasoningEffort } }
+      }
+    }
+
+    const route = router.current(sessionId)
+    const downgraded = router.consumeDowngradeFlag(sessionId)
+    if (downgraded) {
+      const behavior = config.costControl.downgradeBehavior
+      const locale = resolveLocale(ctx)
+      if (behavior === 'notify') {
+        await notifyDowngrade(agent, config, sessionId, locale)
+      } else if (behavior === 'ask') {
+        const keep = await askDowngrade(ctx, agent, router, sessionId)
+        if (keep) router.waiveBudget(sessionId)
+      }
+    }
+    // A free route that burned its quota earlier in this session was replaced
+    // by a paid one while routing — tell the user once.
+    const demotion = router.consumeFreeDemotionFlag(sessionId)
+    if (demotion && config.freeQuota.notify) {
+      await notifyFreeQuotaFallback(agent, sessionId, demotion, resolveLocale(ctx))
+    }
+    return {
+      ...proposed,
+      provider: route.provider,
+      model: route.model,
+      // Levels always carry an explicit reasoningEffort (default 'off'), so
+      // the routed effort is always stated — including 'off' for no thinking.
+      reasoningEffort: route.reasoningEffort,
+    }
+  })
+
+  // ── agent/request-error: fallback chain (auto mode only) ────────────────
+  // A free-quota route that fails (quota exhausted, rate limited, rejected) is
+  // demoted for the rest of the session: the retry runs on the next viable
+  // route, and every later decision for that level skips the burned route.
+  ctx.on('agent/request-error', async ({ agent, failure }, next) => {
+    const sessionId = agent.session.id
+    if (!router.isAutoActive(sessionId)) return next()
+    const failedRoute = router.current(sessionId)
+    const burned = config.freeQuota.enabled && config.freeQuota.demoteOnError
+      ? router.markFreeExhausted(sessionId, failedRoute)
+      : false
+    const fallback = router.nextOnFailure(sessionId, failedRoute)
+    if (fallback) {
+      ctx.logger?.info?.(
+        `[mydsh-auto-model-router] ${sessionId}: request failed (${failure?.error?.code ?? 'unknown'})`
+        + `${burned ? ' on a free route, which is now demoted for this session' : ''},`
+        + ` falling back to ${fallback.provider}/${fallback.model}`,
+      )
+      // The user-visible notice is owned by the routing path, which knows the
+      // level and the paid replacement: announcing it here too would report the
+      // same demotion twice.
+      return { kind: 'retry' }
+    }
+    return next()
+  })
+
+  // ── session/event: track spend from assistant messages ──────────────────
+  ctx.on('session/event', (session, event) => {
+    if (event.type === 'assistant/message') {
+      router.recordTokens(session.id, event.data?.message)
+      // The input side of the request that produced this message is the best
+      // context-size signal the context guard has.
+      router.recordUsage(session.id, event.data?.usage)
+    }
+    if (event.type === 'message') {
+      const message = event.data?.message
+      if (message?.role === 'assistant' && Array.isArray(message.content)) {
+        const text = message.content
+          .map((block) => (typeof block?.text === 'string' ? block.text : ''))
+          .join('\n')
+        if (text) router.rememberReply(session.id, text)
+      }
+    }
+  })
+}
+
+/** Extract the text content of a single message. */
+function messageText(message) {
+  const content = message?.content
+  if (typeof content === 'string') return content.trim()
+  if (Array.isArray(content)) {
+    return content
+      .map((block) => (typeof block?.text === 'string' ? block.text : ''))
+      .join('\n')
+      .trim()
+  }
+  return ''
+}