@ljwei-stak/dsh-model-route-bot 0.66.3 → 0.67.0

package/packages/orchestration/src/independent-tool-families.mjs

@@ -0,0 +1,73 @@
+/** Add Host-selected families to the API loop without inventing a Harness Agent.
+ * Native CLI routes retain their private, typed MCP doors. Families are resolved
+ * again per catalog/call, and never supply model or funding authority.
+ */
+const fail = (code, message = code) => { throw Object.assign(new Error(message), { code }) }
+
+export function extendIndependentToolHost({ base, familiesFor, validateCall = () => {} } = {}) {
+  if (typeof base?.forBot !== 'function' || typeof familiesFor !== 'function') throw new TypeError('INDEPENDENT_FAMILIES_HOST_REQUIRED')
+  let closed = false
+  const lifetime = new AbortController()
+  const alive = () => { if (closed) fail('TOOL_HOST_CLOSED', '宿主工具服务已关闭，本次调用被拒绝。') }
+  return Object.freeze({ ...base,
+    forBot(botId, options = {}) {
+      const view = base.forBot(botId, options)
+      // The native adapter has its own schema/parser/renderers and must never
+      // convert a CLI-observed call into an SDK executable call.
+      if (options.nativeRoute) return view
+      const offered = context => {
+        alive()
+        const entries = familiesFor(botId, context) ?? []
+        if (!Array.isArray(entries)) fail('INDEPENDENT_FAMILIES_INVALID')
+        const names = new Set(view.schemas().map(entry => entry.name))
+        for (const entry of entries) {
+          const name = entry.handler?.definition?.name
+          if (typeof name !== 'string' || !entry.handler.definition.inputSchema
+            || typeof entry.handler.parse !== 'function' || typeof entry.handler.execute !== 'function'
+            || names.has(name)) fail('INDEPENDENT_FAMILIES_INVALID')
+          names.add(name)
+        }
+        return entries
+      }
+      return Object.freeze({ ...view,
+        schemas: () => [...view.schemas(), ...offered().map(({ handler }) => ({ name: handler.definition.name,
+          description: handler.definition.description, parameters: handler.definition.inputSchema }))],
+        isReadonly: name => {
+          const entry = offered().find(row => row.handler.definition.name === name)
+          return entry ? entry.readonly === true : view.isReadonly(name)
+        },
+        async call(name, args = {}, context = {}) {
+          alive()
+          if (context.botId !== undefined && context.botId !== botId) fail('SUBJECT_MISMATCH')
+          await validateCall(botId, context)
+          alive(); context.signal?.throwIfAborted()
+          const entry = offered(context).find(row => row.handler.definition.name === name)
+          if (!entry) {
+            const value = await view.call(name, args, context)
+            alive(); context.signal?.throwIfAborted()
+            await validateCall(botId, context)
+            return value
+          }
+          if (typeof context.turnId !== 'string' || !context.turnId || typeof context.callId !== 'string' || !context.callId || !context.signal) fail('INDEPENDENT_TOOL_TURN_REQUIRED')
+          const signal = AbortSignal.any([lifetime.signal, context.signal])
+          signal.throwIfAborted()
+          const parsed = entry.handler.parse(args)
+          await entry.validate?.()
+          const value = await entry.handler.execute(parsed, { context: { turnId: context.turnId, callId: context.callId,
+            ...(typeof context.conversationId === 'string' ? { conversationId: context.conversationId } : {}) }, signal })
+          alive(); signal.throwIfAborted()
+          await entry.validate?.()
+          await validateCall(botId, context)
+          alive(); signal.throwIfAborted()
+          return value
+        },
+      })
+    },
+    close() {
+      if (closed) return
+      closed = true
+      lifetime.abort(new Error('TOOL_HOST_CLOSED'))
+      base.close?.()
+    },
+  })
+}

package/packages/orchestration/src/independent-tool-host.mjs

@@ -0,0 +1,344 @@
+/**
+ * The Host's own tool service for one independent Bot.
+ *
+ * The independent loop has a transcript and a cancel signal; it has no machine, no task journal and
+ * no authority. This module is the seam the Host composes once and publishes, and it is the only
+ * way an independent turn reaches the outside world:
+ *
+ * ```
+ * ctx.provide('botIndependentToolHost', createIndependentToolHost({
+ *   directory, machines: () => machines, taskService: () => taskService,
+ *   backends: () => taskBackends ? taskBackends.catalog().map(entry => entry.id) : [], now,
+ * }))
+ * ```
+ *
+ * `forBot(botId)` answers with a live view of that Bot: `schemas()` is re-decided from committed
+ * grants on every call, `isReadonly()` says whether a call may run beside another, and `call()`
+ * re-decides everything again before a single byte leaves the process.
+ *
+ * Four rules are load-bearing:
+ *
+ * 1. **Identity is Host-owned.** The machine, the root, the task id, the attempt id, the operation
+ *    id and the request key are derived from the Bot's committed binding and the turn identity the
+ *    loop hands over. A reply may name one of its own bound machines or roots, and may reference an
+ *    operation or task the Host already issued; it can never mint one.
+ * 2. **A write is a durable Task or it does not happen.** `bot_fs_write` and `bot_command` go
+ *    through the existing task service — submit, attempt, operation, journal — with a request key
+ *    derived from the turn and the call, so a repeated call re-reads the same task instead of
+ *    dispatching a second one.
+ * 3. **An unknown outcome is reconciled, never replayed.** When the backend cannot prove what
+ *    happened the call throws with the task identity attached; nothing here submits a replacement.
+ * 4. **The cancel signal reaches the machine and the task wait.** A cancel that arrives before
+ *    dispatch produces zero machine calls; one that arrives during leaves the remote operation its
+ *    own identity and its own stop evidence.
+ *
+ * Disposal is part of the contract: `close()` aborts this service's own waits and drops its
+ * registries, and refuses further calls. It never claims a remote operation stopped — the durable
+ * task keeps its identity and the Host reconciles it. A Host that published this service should call
+ * `close()` from its own dispose effect, beside closing the task service and the machine directory.
+ */
+
+import { createHash, randomUUID } from 'node:crypto'
+import { catalogFor, independentToolEntry } from './independent-tool-catalog.mjs'
+
+const fail = (code, message, extra) => { throw Object.assign(new Error(message ?? code), { code, ...(extra ?? {}) }) }
+const ref = value => typeof value === 'string' && /^[-A-Za-z0-9_.]{1,128}$/.test(value)
+const key = value => typeof value === 'string' && /^[A-Za-z0-9_-]{1,128}$/.test(value)
+const plain = value => Boolean(value) && typeof value === 'object' && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype
+const cancelled = () => Object.assign(new Error('这一轮已被取消。'), { code: 'BOT_LOOP_CANCELLED' })
+const closedError = taskId => Object.assign(new Error('宿主工具服务已关闭，本次等待结束；远端任务保持自己的身份，由宿主对账。'), { code: 'TOOL_HOST_CLOSED', taskId })
+
+/** Task states that will not change without a Host decision. */
+const TERMINAL = new Set(['succeeded', 'failed', 'cancelled', 'blocked', 'skipped', 'needs-reconciliation', 'waiting-approval'])
+/** Task states the loop may keep waiting on. */
+const PENDING = new Set(['ready', 'admitting', 'running', 'cancelling', 'waiting-budget'])
+
+/** How many issued operation/task ids one Bot may reference. Older ones simply stop being citable. */
+const ISSUED_LIMIT = 512
+/**
+ * A stable, Host-owned reference from a turn identity and one call id. Both come from the loop, not
+ * from the model, and neither is ever echoed back into the request as authority.
+ */
+const reference = (turnId, callId) => createHash('sha256').update(`${String(turnId ?? '')}/${String(callId ?? '')}`).digest('hex').slice(0, 32)
+
+/**
+ * @param {{
+ *   directory: { forBot: (botId: string) => unknown },
+ *   authority?: { assertTool: (subject: unknown, name: string) => void } | null,
+ *   machines: object | (() => object | null),
+ *   taskService?: object | (() => object | null) | null,
+ *   backends?: string[] | (() => string[]),
+ *   supportsToolsFor?: (botId: string) => boolean,
+ *   now?: () => number,
+ *   pollMs?: number,
+ *   waitMs?: number,
+ *   issuedLimit?: number,
+ * }} options
+ */
+export function createIndependentToolHost({ directory, authority = null, machines, taskService = null, backends = [], supportsToolsFor = () => true, now = Date.now, pollMs = 50, waitMs = 120_000, issuedLimit = ISSUED_LIMIT } = {}) {
+  if (!directory || typeof directory.forBot !== 'function') throw new TypeError('INDEPENDENT_TOOL_HOST_REQUIRES_DIRECTORY')
+  if (machines === undefined || machines === null) throw new TypeError('INDEPENDENT_TOOL_HOST_REQUIRES_MACHINES')
+  if (typeof supportsToolsFor !== 'function') throw new TypeError('INDEPENDENT_TOOL_HOST_REQUIRES_MODEL_CAPABILITIES')
+  if (!Number.isSafeInteger(pollMs) || pollMs < 5 || pollMs > 1000) throw new TypeError('INVALID_TOOL_HOST_POLL')
+  if (!Number.isSafeInteger(waitMs) || waitMs < 1000 || waitMs > 3_600_000) throw new TypeError('INVALID_TOOL_HOST_WAIT')
+  if (!Number.isSafeInteger(issuedLimit) || issuedLimit < 1 || issuedLimit > 100_000) throw new TypeError('INVALID_TOOL_HOST_ISSUED_LIMIT')
+  const machineStore = () => {
+    const value = typeof machines === 'function' ? machines() : machines
+    if (!value || typeof value.call !== 'function') fail('MACHINE_DIRECTORY_UNAVAILABLE')
+    return value
+  }
+  const tasks = () => {
+    const value = typeof taskService === 'function' ? taskService() : taskService
+    return value && typeof value.submit === 'function' ? value : null
+  }
+  const backendIds = () => {
+    const value = typeof backends === 'function' ? backends() : backends
+    const ids = Array.isArray(value) ? value.filter(id => typeof id === 'string') : []
+    return tasks() ? [...ids, 'task-service'] : ids
+  }
+  // Operations and tasks this Host issued, per Bot. A reply may only reference one of these; it
+  // cannot ask about an operation it never received. The registry is bounded, and it is the only
+  // state this service keeps.
+  const issued = new Map()
+  const waits = new Set()
+  let closed = false
+  const remember = (botId, id) => {
+    const set = issued.get(botId) ?? new Set()
+    set.add(id)
+    while (set.size > issuedLimit) set.delete(set.values().next().value)
+    issued.set(botId, set)
+  }
+  const known = (botId, id) => Boolean(issued.get(botId)?.has(id))
+  const alive = () => { if (closed) fail('TOOL_HOST_CLOSED', '宿主工具服务已关闭，本次调用被拒绝。') }
+  /** Every wait this service is sitting in, so a close can end them without a stop claim. */
+  const track = waiter => { waits.add(waiter); return () => waits.delete(waiter) }
+
+  /** Live committed bindings for one Bot, straight from the machine directory. */
+  const scopesFor = botId => {
+    const store = machineStore()
+    const rows = typeof store.scopes === 'function' ? store.scopes(botId) : []
+    return rows.filter(scope => scope && ref(scope.machineId) && Array.isArray(scope.tools) && Array.isArray(scope.roots))
+  }
+
+  /**
+   * Whether this Bot's authority still holds a capability.
+   *
+   * The catalog is not allowed to offer a tool the authority would refuse, so a grant that was
+   * withdrawn takes the tool out of the request instead of leaving the model to discover the refusal
+   * one call at a time. A Host that publishes no authority keeps the machine binding as its only
+   * gate, and the call itself is still re-checked there.
+   */
+  const grantedFor = botId => capability => {
+    if (!authority || typeof authority.assertTool !== 'function') return true
+    try { authority.assertTool(directory.forBot(botId), capability); return true } catch { return false }
+  }
+
+  /**
+   * The machine and root this call runs on, re-decided now.
+   *
+   * A reply may name one of its own live bindings and one of that binding's roots; anything else is
+   * refused before the machine directory is touched.
+   */
+  const targetFor = (botId, entry, args) => {
+    const scopes = scopesFor(botId)
+    const wanted = args.machineId
+    if (wanted !== undefined && (typeof wanted !== 'string' || !scopes.some(scope => scope.machineId === wanted))) fail('MACHINE_NOT_BOUND')
+    const scope = wanted ? scopes.find(item => item.machineId === wanted) : scopes[0]
+    if (!scope) fail('MACHINE_NOT_BOUND')
+    if (!scope.tools.includes(entry.machineTool)) fail('MACHINE_BOT_DENIED', `该 Bot 未获授 ${entry.machineTool}。`)
+    if (entry.effect === 'workspace-write' && scope.mode !== 'workspace-write') fail('MACHINE_BOT_DENIED', '该授权是只读的。')
+    const rootWanted = args.rootId
+    if (rootWanted !== undefined && (typeof rootWanted !== 'string' || !scope.roots.includes(rootWanted))) fail('MACHINE_ROOT_NOT_BOUND')
+    const rootId = rootWanted ?? scope.roots[0]
+    if (typeof rootId !== 'string' || !rootId) fail('MACHINE_ROOT_NOT_BOUND')
+    return { machineId: scope.machineId, rootId }
+  }
+
+  /** The business arguments: identity keys are stripped before they can reach the machine. */
+  const businessOf = args => {
+    const calls = { ...args }
+    for (const name of ['machineId', 'rootId', 'botId', 'taskId', 'attemptId', 'operationId', 'endpoint', 'secretRef', 'grantToken', 'executable', 'env']) delete calls[name]
+    return calls
+  }
+
+  const waitForTask = async (botId, taskId, signal) => {
+    const service = tasks()
+    const deadline = now() + waitMs
+    for (;;) {
+      alive()
+      signal?.throwIfAborted()
+      const task = service.get(directory.forBot(botId), { taskId })
+      if (!task) fail('TASK_NOT_FOUND', '任务记录不存在。', { taskId })
+      if (TERMINAL.has(task.state)) return task
+      if (!PENDING.has(task.state)) fail('TASK_STATE_UNREADABLE', `任务状态无法读取：${task.state}`, { taskId, state: task.state })
+      if (now() >= deadline) fail('TASK_WAIT_TIMEOUT', '等待任务结束时超时。', { taskId, state: task.state })
+      await new Promise((resolve, reject) => {
+        let untrack = () => {}
+        const stop = why => { untrack(); clearTimeout(timer); signal?.removeEventListener('abort', onAbort); reject(why) }
+        const onAbort = () => stop(cancelled())
+        // A close ends this wait locally; it says nothing about whether the remote task stopped.
+        untrack = track(() => stop(closedError(taskId)))
+        const timer = setTimeout(() => { untrack(); resolve() }, pollMs)
+        if (signal?.aborted) return stop(cancelled())
+        signal?.addEventListener('abort', onAbort, { once: true })
+      })
+    }
+  }
+  const runMachineTool = (botId, entry, args, context) => {
+    const subject = directory.forBot(botId)
+    const target = targetFor(botId, entry, args)
+    const taskId = `bot-${reference(context.turnId, botId)}`
+    const attemptId = `attempt-${reference(context.callId, entry.name)}`
+    const calls = businessOf(args)
+    // The machine layer addresses its own workspace by root, and it requires the two spellings to
+    // agree; the root is the one the Host just chose, never one the reply named.
+    calls.rootId = target.rootId
+    // An observation carries its own operation id as Host metadata, and the machine layer requires
+    // the two spellings to agree.
+    const observation = entry.machineTool === 'operation_status' || entry.machineTool === 'operation_cancel'
+    if (observation) calls.operationId = args.operationId
+    return machineStore().call(subject, {
+      machineId: target.machineId, rootId: target.rootId, taskId, attemptId, tool: entry.machineTool, args: calls,
+      ...(observation ? { operationId: args.operationId } : {}),
+    }, { ...(context.signal ? { signal: context.signal } : {}) })
+  }
+
+  const runTaskTool = async (botId, entry, args, context) => {
+    const service = tasks()
+    const subject = directory.forBot(botId)
+    const target = targetFor(botId, entry, args)
+    // The request key is the Host's own correlation of this turn and this call: a repeated call
+    // reads the same task instead of dispatching a second one.
+    const requestKey = `${botId}-${reference(context.turnId, context.callId)}`
+    const input = { machineId: target.machineId, rootId: target.rootId, ...businessOf(args) }
+    let submitted
+    try {
+      submitted = service.submit(subject, { requestKey, backend: entry.backend, input })
+    } catch (error) {
+      if (error?.code === 'TASK_BACKEND_UNAVAILABLE') fail('TASK_BACKEND_UNAVAILABLE', '宿主未注册该持久任务后端。', { capability: entry.name })
+      throw error
+    }
+    const taskId = submitted?.taskId
+    if (!key(taskId)) fail('TASK_SUBMIT_UNREADABLE', '任务提交没有返回可读身份。')
+    remember(botId, taskId)
+    const cancel = () => { try { service.cancel(subject, { taskId }) } catch { /* the journal retains its current outcome */ } }
+    context.signal?.addEventListener('abort', cancel, { once: true })
+    let task
+    try {
+      if (context.signal?.aborted) cancel()
+      task = await waitForTask(botId, taskId, context.signal)
+    } finally { context.signal?.removeEventListener('abort', cancel) }
+    if (task.state !== 'succeeded') {
+      // Unknown stays unknown: the task keeps its identity and its evidence, and the caller is told
+      // which task to reconcile. Nothing here submits a replacement.
+      const code = task.state === 'needs-reconciliation' ? 'TASK_OUTCOME_UNKNOWN' : `TASK_${String(task.state).toUpperCase()}`
+      fail(code, `持久任务未成功完成：${task.state}`, { taskId, attemptId: task.attemptId, operationId: task.operationId, state: task.state })
+    }
+    return { taskId, attemptId: task.attemptId, operationId: task.operationId, result: task.result ?? null }
+  }
+
+  const observeTool = (botId, entry, args, context) => {
+    if (entry.machineTool === 'operation_status' || entry.machineTool === 'operation_cancel') {
+      const operationId = args.operationId
+      if (!ref(operationId)) fail('INVALID_TOOL_ARGS', 'operationId 缺失或格式不正确。')
+      // Only an operation this Host issued for this Bot may be observed or stopped.
+      if (!known(botId, operationId)) fail('OPERATION_NOT_ISSUED', '该 operationId 不是宿主发给本 Bot 的。')
+    }
+    if (entry.machineTool === 'artifact_stat' || entry.machineTool === 'artifact_read') {
+      if (!/^[a-f0-9]{64}$/.test(String(args.artifactId ?? ''))) fail('INVALID_TOOL_ARGS', 'artifactId 缺失或格式不正确。')
+    }
+    const result = runMachineTool(botId, entry, args, context)
+    if (typeof result?.operationId === 'string') remember(botId, result.operationId)
+    return result
+  }
+
+  const readTask = async (botId, args, context) => {
+    const service = tasks()
+    const taskId = args.taskId
+    if (!key(taskId)) fail('INVALID_TOOL_ARGS', 'taskId 缺失或格式不正确。')
+    if (!known(botId, taskId)) fail('TASK_NOT_ISSUED', '该 taskId 不是宿主发给本 Bot 的。')
+    context.signal?.throwIfAborted()
+    return service.get(directory.forBot(botId), { taskId })
+  }
+
+  const cancelTask = async (botId, args, context) => {
+    const service = tasks()
+    const taskId = args.taskId
+    if (!key(taskId)) fail('INVALID_TOOL_ARGS', 'taskId 缺失或格式不正确。')
+    if (!known(botId, taskId)) fail('TASK_NOT_ISSUED', '该 taskId 不是宿主发给本 Bot 的。')
+    const outcome = service.cancel(directory.forBot(botId), { taskId })
+    // A cancel is a request, not a confirmation: the attempt keeps its own identity and the Host
+    // reconciles it. The loop reports the request, never a stop proof it does not have.
+    return { taskId, cancelRequested: true, state: outcome?.state ?? null }
+  }
+
+  return Object.freeze({
+    /**
+     * One Bot's live tool surface.
+     *
+     * The returned object is cheap and stateless: every method re-reads committed grants, so a
+     * cached loop can never freeze an older grant into a turn.
+     */
+    forBot(botId, { nativeRoute = null } = {}) {
+      if (typeof botId !== 'string' || !botId) throw new TypeError('INDEPENDENT_TOOL_HOST_REQUIRES_BOT')
+      const supported = () => supportsToolsFor(botId, nativeRoute) === true
+      const view = Object.freeze({
+        botId,
+        /** The schemas this Bot may see right now. */
+        schemas() {
+          if(!supported())return []
+          return catalogFor({ scopes: scopesFor(botId), backends: backendIds(), granted: grantedFor(botId) }).tools
+        },
+        /** What this Host cannot run for this Bot, and why. */
+        unavailable() {
+          const catalog=catalogFor({ scopes: scopesFor(botId), backends: backendIds(), granted: grantedFor(botId) })
+          return supported()?catalog.unavailable:[...catalog.unavailable,...catalog.tools.map(tool=>({name:tool.name,code:'MODEL_TOOLS_UNSUPPORTED'}))]
+        },
+        /** Which machines this Bot's own live bindings cover. */
+        machines() {
+          return catalogFor({ scopes: scopesFor(botId), backends: backendIds(), granted: grantedFor(botId) }).machines
+        },
+        isReadonly(name) {
+          const entry = independentToolEntry(name)
+          return Boolean(entry) && entry.effect === 'read'
+        },
+        async call(name, args = {}, context = {}) {
+          alive()
+          if(!supported())fail('MODEL_TOOLS_UNSUPPORTED','当前对话引擎不支持工具调用；Bot 的工具权限仍保留。')
+          const entry = independentToolEntry(name)
+          // Offered-or-refused is decided here, not at schema time: a grant that changed between
+          // the request and the call stops the call.
+          if (!entry) fail('TOOL_NOT_GRANTED', `未获授的工具：${String(name)}`)
+          if (!plain(args)) fail('INVALID_TOOL_ARGS', '工具参数必须是一个普通对象。')
+          const granted = view.schemas().some(tool => tool.name === name)
+          if (!granted) fail('TOOL_NOT_GRANTED', `该 Bot 当前未获授 ${name}。`)
+          const turnId = context.turnId ?? randomUUID()
+          const callId = context.callId ?? randomUUID()
+          const scoped = { ...context, turnId, callId }
+          // Reading or stopping one of this Bot's own tasks is not a machine effect at all.
+          if (entry.backend === 'task-service') return entry.taskAction === 'cancel' ? cancelTask(botId, args, scoped) : readTask(botId, args, scoped)
+          if (entry.backend) return runTaskTool(botId, entry, args, scoped)
+          if (entry.machineTool === 'operation_status' || entry.machineTool === 'operation_cancel'
+            || entry.machineTool === 'artifact_stat' || entry.machineTool === 'artifact_read') return observeTool(botId, entry, args, scoped)
+          return runMachineTool(botId, entry, args, scoped)
+        },
+      })
+      return view
+    },
+
+    /**
+     * Dispose this service: end its own waits, drop its registries and refuse further calls.
+     *
+     * This is not a stop of anything remote. A task still in flight keeps its identity and its
+     * evidence in the journal, and the Host reconciles it; nothing here claims it stopped, and
+     * nothing here submits a replacement.
+     */
+    close() {
+      if (closed) return
+      closed = true
+      for (const stop of [...waits]) stop()
+      waits.clear()
+      issued.clear()
+    },
+  })
+}

package/packages/orchestration/src/main-bot-grant.mjs

@@ -0,0 +1,15 @@
+/** Main's full-control role comes from committed Host state. Worker checkbox
+ * grants do not narrow it. Services still own actual availability and accounting.
+ */
+export function compileMainBotGrant({ base, catalog, routes, toolNames = [], teamToolNames = [] }) {
+  return {
+    tools: [...new Set([
+      ...(base.tools ?? []), 'model/infer', 'task/execute', 'task/submit', 'task/read', 'task/cancel', 'task/retry', 'task/reconcile',
+      ...(catalog.capabilities ?? []).flatMap(item => item.tools ?? []),
+      ...(catalog.tools ?? []).flatMap(item => item.grantTools ?? []),
+      ...toolNames.map(name => `tool/${name}`), ...teamToolNames.map(name => `tool/${name}`),
+      'tool/bot_dispatch', 'tool/bot_handoff_task',
+    ])].sort(),
+    modelRoutes: routes.map(route => ({ provider: route.provider, model: route.model })),
+  }
+}

package/packages/orchestration/src/main-model-routes.mjs

@@ -0,0 +1,208 @@
+/**
+ * Main Bot per-exact-route execution/funding profiles.
+ *
+ * A pure, I/O-free helper that lives beside the closed `bot_settings` schema.
+ * It stores an optional `settings.mainRoutes` collection (schema version 1) in
+ * the same `bot_settings_records` revision, coexisting with the existing
+ * default-model binding. It never builds a second funding, price or receipt
+ * ledger, never opens SQLite and never invents a catalog: every amount, token
+ * bound, mode and cross-channel rule is delegated to the Host's own legacy
+ * funding normalizer, which the parent injects so the old rules are not copied
+ * into a second place.
+ *
+ * Roles, accounts, credentials, endpoints and paths are never read here. The
+ * Host commits the Main role, the exact model existence, the funding scope and
+ * the price facts; this helper only normalizes the declared shape, assembles a
+ * complete legacy funding record from a profile plus the unified global limits,
+ * and refuses anything it cannot prove.
+ */
+
+const MAIN_ROUTES_SCHEMA = 1
+const MAX_ROUTES = 64
+const MAX_BYTES = 64 * 1024
+
+// Legacy shapes, mirrored so this module stays free of a bot-settings import
+// (and therefore free of the circular dependency the closed schema would add).
+const plain = value => value && typeof value === 'object' && !Array.isArray(value) && [Object.prototype, null].includes(Object.getPrototypeOf(value))
+const ref = value => typeof value === 'string' && /^[A-Za-z0-9_-]{1,128}$/.test(value)
+const token = value => typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9._:/@+\-]{0,255}$/.test(value)
+const clone = value => structuredClone(value)
+const fail = (code, message, details = {}) => { throw Object.assign(new Error(message), { code, details }) }
+const keys = (value, allowed, path) => {
+  if (!plain(value) || Object.keys(value).some(key => !allowed.includes(key))) fail('BOT_SETTINGS_INVALID', `${path} 含有未知字段或格式无效。`, { field: path })
+}
+const list = (value, limit, path) => {
+  if (!Array.isArray(value) || value.length > limit) fail('BOT_SETTINGS_INVALID', `${path} 列表格式无效或超过 ${limit} 项。`, { field: path })
+  return value
+}
+// A binary tuple key, never a joined string: a model may itself contain "/", so
+// `provider/model` would let `a/b`+`c` collide with `a`+`b/c`.
+const routeKey = (provider, model) => `${provider}\u0000${model}`
+
+const requireNormalizer = options => {
+  const normalizeFunding = options?.normalizeFunding
+  if (typeof normalizeFunding !== 'function') throw new TypeError('normalizeMainModelRoutes/materializeMainRouteDefault require an injected legacy funding normalizer { normalizeFunding }')
+  return normalizeFunding
+}
+
+const normalizeApiLimit = (value, normalizeFunding) => {
+  if (value === null || value === undefined) return null
+  keys(value, ['dailyBudgetUsd', 'monthlyBudgetUsd'], 'mainRoutes.limits.api')
+  // Reuse the legacy amount bound and field checks instead of restating them.
+  const funding = normalizeFunding({ mode: 'api', scopeId: null, pricing: null, request: null, dailyBudgetUsd: value.dailyBudgetUsd, monthlyBudgetUsd: value.monthlyBudgetUsd, subscription: null })
+  // The group as a whole is either configured (both numbers, 0 included) or left
+  // null for "not configured"; a null inside a present group is never stored.
+  if (funding.dailyBudgetUsd === null || funding.monthlyBudgetUsd === null) fail('BOT_SETTINGS_INVALID', 'API 每日与每月预算必须同时填写；整组留空表示未配置，0 表示禁止付费。', { field: 'mainRoutes.limits.api' })
+  return { dailyBudgetUsd: funding.dailyBudgetUsd, monthlyBudgetUsd: funding.monthlyBudgetUsd }
+}
+
+const normalizeSubscriptionLimit = (value, normalizeFunding) => {
+  if (value === null || value === undefined) return null
+  keys(value, ['dailyCalls', 'monthlyCalls'], 'mainRoutes.limits.subscription')
+  // Reuse the legacy integer-call bound and field checks.
+  const funding = normalizeFunding({ mode: 'subscription', scopeId: null, pricing: null, request: null, dailyBudgetUsd: null, monthlyBudgetUsd: null, subscription: { dailyCalls: value.dailyCalls, monthlyCalls: value.monthlyCalls } })
+  return { dailyCalls: funding.subscription.dailyCalls, monthlyCalls: funding.subscription.monthlyCalls }
+}
+
+const normalizeRouteFunding = (value, normalizeFunding) => {
+  keys(value, ['mode', 'scopeId', 'pricing', 'request'], 'mainRoutes.routes.funding')
+  const mode = value.mode
+  if (mode !== 'api' && mode !== 'subscription') fail('BOT_SETTINGS_INVALID', '路线资金渠道必须是 api 或 subscription。', { field: 'mainRoutes.routes.funding.mode' })
+  // A subscription profile never carries API price or request bounds, and an API
+  // profile never carries a subscription group (an extra key is already refused
+  // by the closed field list). These are refused, not silently dropped.
+  if (mode === 'subscription' && ((value.pricing ?? null) !== null || (value.request ?? null) !== null)) fail('BOT_SETTINGS_INVALID', '订阅路线不能夹带 API 价格或请求上界；不会隐式切换渠道。', { field: 'mainRoutes.routes.funding' })
+  const funding = normalizeFunding(mode === 'api'
+    ? { mode, scopeId: value.scopeId ?? null, pricing: value.pricing ?? null, request: value.request ?? null, dailyBudgetUsd: null, monthlyBudgetUsd: null, subscription: null }
+    : { mode, scopeId: value.scopeId ?? null, pricing: null, request: null, dailyBudgetUsd: null, monthlyBudgetUsd: null, subscription: null })
+  return { mode: funding.mode, scopeId: funding.scopeId, pricing: funding.pricing, request: funding.request }
+}
+
+const normalizeRoute = (value, normalizeFunding) => {
+  keys(value, ['provider', 'model', 'enabled', 'funding'], 'mainRoutes.routes')
+  if (!token(value.provider) || !token(value.model)) fail('BOT_SETTINGS_INVALID', '路线需要准确的 provider/model。', { field: 'mainRoutes.routes' })
+  if (typeof value.enabled !== 'boolean') fail('BOT_SETTINGS_INVALID', 'enabled 必须是布尔值。', { field: 'mainRoutes.routes.enabled' })
+  return { provider: value.provider, model: value.model, enabled: value.enabled, funding: normalizeRouteFunding(value.funding, normalizeFunding) }
+}
+
+/**
+ * Normalize an optional `settings.mainRoutes` value. Returns `null` for the
+ * absent/null case (old records keep their shape). Otherwise returns the closed
+ * `{ schemaVersion, limits, routes }` collection: at most 64 routes, stably
+ * sorted by exact provider/model, no duplicate tuple, total JSON <= 64 KiB.
+ * Every amount, token bound, mode and cross-channel rule is checked by the
+ * injected legacy normalizer.
+ */
+export function normalizeMainModelRoutes(value, options = {}) {
+  const normalizeFunding = requireNormalizer(options)
+  if (value === null || value === undefined) return null
+  keys(value, ['schemaVersion', 'limits', 'routes'], 'mainRoutes')
+  if (value.schemaVersion !== MAIN_ROUTES_SCHEMA) fail('BOT_SETTINGS_VERSION_UNSUPPORTED', '多路线配置版本不受支持，请升级宿主。', { field: 'mainRoutes.schemaVersion' })
+  keys(value.limits, ['api', 'subscription'], 'mainRoutes.limits')
+  const limits = {
+    api: normalizeApiLimit(value.limits.api, normalizeFunding),
+    subscription: normalizeSubscriptionLimit(value.limits.subscription, normalizeFunding),
+  }
+  const routes = list(value.routes, MAX_ROUTES, 'mainRoutes.routes').map(route => normalizeRoute(route, normalizeFunding))
+  const seen = new Set()
+  for (const route of routes) {
+    const key = routeKey(route.provider, route.model)
+    if (seen.has(key)) fail('BOT_SETTINGS_DUPLICATE', `路线 ${route.provider}/${route.model} 重复。`, { field: 'mainRoutes.routes' })
+    seen.add(key)
+  }
+  routes.sort((a, b) => a.provider.localeCompare(b.provider) || a.model.localeCompare(b.model))
+  const collection = { schemaVersion: MAIN_ROUTES_SCHEMA, limits, routes }
+  if (Buffer.byteLength(JSON.stringify(collection)) > MAX_BYTES) fail('BOT_SETTINGS_LIMIT', '多路线配置不能超过 64 KiB。', { field: 'mainRoutes' })
+  return collection
+}
+
+/**
+ * The complete legacy funding record for one exact, enabled route, or `null`.
+ *
+ * `null` means the route is absent, disabled, or not ready: the required global
+ * limit group, the API price/request bounds, or the funding scope is missing.
+ * The result is a deep copy, so a caller cannot mutate the normalized profile.
+ *
+ * Every API route draws on the same global `limits.api` budget and every
+ * subscription route on the same global `limits.subscription` quota; no per-route
+ * counter is created, so the Host's aggregate ceilings keep applying across all
+ * routes. This helper does not run the ledger, so it cannot claim the aggregate
+ * was actually enforced.
+ */
+export function fundingForMainRoute(collection, target) {
+  if (!plain(collection) || !Array.isArray(collection.routes)) return null
+  const provider = target?.provider, model = target?.model
+  if (typeof provider !== 'string' || typeof model !== 'string') return null
+  const route = collection.routes.find(item => item.provider === provider && item.model === model)
+  if (!route || route.enabled !== true || !plain(route.funding)) return null
+  const scopeId = route.funding.scopeId
+  if (scopeId === null) return null
+  if (route.funding.mode === 'api') {
+    if (collection.limits.api === null || route.funding.pricing === null || route.funding.request === null) return null
+    return clone({ mode: 'api', scopeId, pricing: route.funding.pricing, request: route.funding.request,
+      dailyBudgetUsd: collection.limits.api.dailyBudgetUsd, monthlyBudgetUsd: collection.limits.api.monthlyBudgetUsd, subscription: null })
+  }
+  if (route.funding.mode !== 'subscription' || collection.limits.subscription === null) return null
+  return clone({ mode: 'subscription', scopeId, pricing: null, request: null, dailyBudgetUsd: null, monthlyBudgetUsd: null,
+    subscription: { dailyCalls: collection.limits.subscription.dailyCalls, monthlyCalls: collection.limits.subscription.monthlyCalls } })
+}
+
+/**
+ * Derive `settings.funding` from the default exact model's route plus the
+ * unified global limits, returning a clone.
+ *
+ * The default is the committed `settings.model`; a route is never silently
+ * chosen as "the first one". When `mainRoutes` is absent/null the clone is
+ * value-identical to the input (the legacy single-route case is untouched).
+ * When `mainRoutes` is present and the default route is ready, `settings.funding`
+ * is generated from that route plus the unified limits whether or not the Bot is
+ * enabled. When the default route is not ready the call is refused only if the
+ * settings are enabled; a disabled settings keeps its unfinished draft and never
+ * receives a fabricated available funding.
+ */
+export function materializeMainRouteDefault(settings, options = {}) {
+  if (!plain(settings)) throw new TypeError('materializeMainRouteDefault requires a plain settings object')
+  const next = clone(settings)
+  if (next.mainRoutes === null || next.mainRoutes === undefined) return next
+  const collection = normalizeMainModelRoutes(next.mainRoutes, options)
+  const model = plain(next.model) ? next.model : null
+  const funding = model ? fundingForMainRoute(collection, { provider: model.provider, model: model.model }) : null
+  if (funding !== null) next.funding = funding
+  else if (next.enabled === true) fail('MAIN_ROUTE_DEFAULT_UNAVAILABLE', '启用多路线前，默认模型必须对应一条已启用且已就绪的路线；不会自动选择第一条路线。', { field: 'mainRoutes' })
+  return next
+}
+
+const routeState = settings => {
+  if (!plain(settings) || !Object.hasOwn(settings, 'mainRoutes') || settings.mainRoutes === undefined) return 'absent'
+  return settings.mainRoutes === null ? 'exit' : 'present'
+}
+// Key-order-independent deep serialization, so a re-serialized legacy funding
+// still compares equal.
+const canonical = value => {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value === undefined ? null : value) ?? 'null'
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`
+  return `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${canonical(value[key])}`).join(',')}}`
+}
+const identityUnchanged = (next, previous) => canonical(next.model) === canonical(previous.model) && canonical(next.funding) === canonical(previous.funding)
+
+/**
+ * Protect a stored multi-route collection from an older client that omits the
+ * field it does not know about.
+ *
+ * An explicit `mainRoutes` value (object or null) on `next` is always honored:
+ * `null` exits multi-route, an object is the new declaration. Only a missing
+ * key triggers protection: if `previous` carried a collection and neither the
+ * default model nor the funding changed, the stored collection is re-attached;
+ * if either changed the client must re-read, so the call is refused. A previous
+ * that had no collection leaves `next` untouched.
+ */
+export function preserveMainModelRoutes(next, previous) {
+  if (!plain(next)) throw new TypeError('preserveMainModelRoutes requires a plain next settings object')
+  const previousSafe = plain(previous) ? previous : {}
+  if (routeState(next) !== 'absent') return clone(next)
+  if (routeState(previousSafe) === 'present') {
+    if (identityUnchanged(next, previousSafe)) return { ...clone(next), mainRoutes: clone(previousSafe.mainRoutes) }
+    fail('MAIN_ROUTES_RELOAD_REQUIRED', '默认模型或资金已更改，请重新读取多路线配置后再保存。', { field: 'mainRoutes' })
+  }
+  return clone(next)
+}