@ljwei-stak/dsh-model-router 0.21.1 → 0.22.0

package/.dsh-plugin/shared/package-assignments.mjs

@@ -0,0 +1,71 @@
+import { getOfficialTool } from './official-tool-registry.mjs'
+
+const plain = value => value !== null && typeof value === 'object'
+  && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null)
+const safeText = (value, limit) => typeof value === 'string' && value.trim().length > 0
+  && value.trim().length <= limit && !/[\u0000-\u001f\u007f]/u.test(value)
+const safeKey = key => typeof key === 'string' && key === key.trim() && safeText(key, 128)
+  && !['__proto__', 'constructor', 'prototype'].includes(key)
+
+/** Explicit package targets only; callers must separately match the current plan and catalog. */
+export function parsePackageAssignments(value) {
+  if (value === undefined) return undefined
+  if (!plain(value)) throw new TypeError('packageAssignments must be an object')
+  const keys = Reflect.ownKeys(value)
+  if (!keys.length || keys.length > 32 || keys.some(key => !safeKey(key))) {
+    throw new TypeError('packageAssignments requires 1..32 safe package ids')
+  }
+  const result = {}
+  for (const id of keys) {
+    const target = value[id]
+    if (!plain(target)) throw new TypeError(`Invalid package assignment: ${id}`)
+    const allowed = target.kind === 'api' ? ['kind', 'provider', 'model']
+      : target.kind === 'tool' ? ['kind', 'toolId'] : null
+    if (!allowed || Reflect.ownKeys(target).some(key => !allowed.includes(key))) {
+      throw new TypeError(`Unsupported package assignment fields: ${id}`)
+    }
+    if (target.kind === 'api') {
+      if (!safeText(target.provider, 160) || !safeText(target.model, 240)) {
+        throw new TypeError(`API assignment requires provider and model: ${id}`)
+      }
+      result[id] = { kind: 'api', provider: target.provider.trim(), model: target.model.trim() }
+    } else {
+      if (!safeText(target.toolId, 64) || !getOfficialTool(target.toolId.trim())) {
+        throw new TypeError(`Unknown official tool assignment: ${id}`)
+      }
+      result[id] = { kind: 'tool', toolId: target.toolId.trim() }
+    }
+  }
+  return result
+}
+
+/** Bounded intent metadata shared by execution, storage and retries. */
+export function packageSelectionFields(item) {
+  if (item?.manualAssignment === undefined) return {}
+  const target = parsePackageAssignments({ target: item.manualAssignment }).target
+  const recommendation = {}
+  for (const key of ['provider', 'model', 'reasoningEffort', 'channel', 'executionChannel', 'qualitySource',
+    'recommendedProvider', 'recommendedModel', 'recommendedReasoningEffort']) {
+    const value = item.algorithmRecommendation?.[key]
+    if (safeText(value, 240)) recommendation[key] = value.trim()
+  }
+  return { manualAssignment: target, selectionSource: 'manual',
+    ...(Object.keys(recommendation).length ? { algorithmRecommendation: recommendation } : {}) }
+}
+
+/** Browser/Host identity for the task decomposition, not an authentication signature. */
+export function packagePlanKey(plan, task = '') {
+  const packages = plan?.team?.workPackages
+  if (plan?.routingBypassed || plan?.mode === 'direct' || !Array.isArray(packages) || !packages.length) return null
+  const fields = packages.map(item => [item?.id ?? '', item?.name ?? '', item?.objective ?? '',
+    item?.type ?? '', item?.purpose ?? '', Array.isArray(item?.dependsOn) ? [...item.dependsOn] : []])
+  const text = JSON.stringify([String(task ?? '').trim(), fields])
+  let first = 2166136261
+  let second = 2246822507
+  for (let index = 0; index < text.length; index++) {
+    const code = text.charCodeAt(index)
+    first = Math.imul(first ^ code, 16777619) >>> 0
+    second = Math.imul(second ^ code, 3266489909) >>> 0
+  }
+  return `package-plan-v1-${first.toString(16).padStart(8, '0')}${second.toString(16).padStart(8, '0')}`
+}

package/.dsh-plugin/shared/quality-gates.mjs

@@ -0,0 +1,169 @@
+/** Structural output checks only: passing these checks does not establish semantic correctness. */
+const TYPES = new Set(['string', 'number', 'boolean', 'object', 'array', 'null'])
+const FIELDS = new Set(['kind', 'requiredKeys', 'fieldTypes'])
+const STRUCTURE_ERROR = '输出未满足配置的结构验收要求。'
+const plainObject = value => value !== null && typeof value === 'object'
+  && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null)
+const safeKey = key => typeof key === 'string' && key.length > 0 && key.length <= 128
+  && key.trim().length > 0 && !/[\u0000-\u001f\u007f]/u.test(key)
+  && !['__proto__', 'prototype', 'constructor'].includes(key)
+
+function normalizeGate(value) {
+  if (!plainObject(value)) throw new TypeError('Quality gate must be a JSON object')
+  const keys = Object.keys(value)
+  if (!keys.length) return null
+  if (keys.some(key => !FIELDS.has(key)) || value.kind !== 'json-object') {
+    throw new TypeError('Unsupported quality gate field or kind')
+  }
+  const requiredKeys = Object.hasOwn(value, 'requiredKeys') ? value.requiredKeys : []
+  if (!Array.isArray(requiredKeys) || requiredKeys.length > 32 || requiredKeys.some(key => !safeKey(key))) {
+    throw new TypeError('requiredKeys must contain at most 32 safe keys')
+  }
+  const fieldTypes = Object.hasOwn(value, 'fieldTypes') ? value.fieldTypes : {}
+  if (!plainObject(fieldTypes) || Object.keys(fieldTypes).length > 32
+    || Object.entries(fieldTypes).some(([key, type]) => !safeKey(key) || !TYPES.has(type))) {
+    throw new TypeError('fieldTypes must map safe keys to supported JSON types')
+  }
+  return { kind: 'json-object', requiredKeys: [...requiredKeys], fieldTypes: { ...fieldTypes } }
+}
+
+export function parseQualityGateJson(text = '') {
+  if (typeof text !== 'string') throw new TypeError('Quality gate JSON must be a string')
+  if (!text.trim()) return null
+  let value
+  try { value = JSON.parse(text) } catch { throw new TypeError('Quality gate must be valid JSON') }
+  return normalizeGate(value)
+}
+
+function matchesType(value, type) {
+  if (type === 'null') return value === null
+  if (type === 'array') return Array.isArray(value)
+  if (type === 'object') return plainObject(value)
+  return typeof value === type && (type !== 'number' || Number.isFinite(value))
+}
+
+export function validateAnswer(answer, gate) {
+  if (gate == null) return { ok: true, kind: null, errors: [] }
+  const rule = normalizeGate(gate)
+  if (!rule) return { ok: true, kind: null, errors: [] }
+  const errors = []
+  let object
+  try {
+    if (typeof answer !== 'string') throw new TypeError('text required')
+    object = JSON.parse(answer)
+    if (!plainObject(object)) throw new TypeError('object required')
+  } catch {
+    return { ok: false, kind: rule.kind, errors: ['Expected one complete JSON object.'] }
+  }
+  // JSON.parse accepts overflows such as 1e999; reject them even in nested data.
+  const pending = [object]
+  while (pending.length) {
+    const value = pending.pop()
+    if (typeof value === 'number' && !Number.isFinite(value)) {
+      errors.push('JSON numbers must be finite.')
+      break
+    }
+    if (value !== null && typeof value === 'object') for (const child of Object.values(value)) pending.push(child)
+  }
+  for (const key of rule.requiredKeys) {
+    if (!Object.hasOwn(object, key)) errors.push(`Missing required key: ${key}`)
+  }
+  for (const [key, type] of Object.entries(rule.fieldTypes)) {
+    if (Object.hasOwn(object, key) && !matchesType(object[key], type)) errors.push(`Invalid type for ${key}: expected ${type}`)
+  }
+  return { ok: errors.length === 0, kind: rule.kind, errors }
+}
+
+const ATTEMPT_FIELDS = [
+  'ok', 'answer', 'error', 'usage', 'usageIncomplete', 'reportedCostUsd', 'channel', 'billing', 'billingMode',
+  'actualModel', 'reportedModel', 'source', 'cancelled', 'blocked', 'paused', 'truncated', 'timedOut',
+  'notStarted', 'ran', 'status', 'finishReason', 'reasoningEffort', 'plannedReasoningEffort', 'requestedReasoningEffort', 'reasoningEffortStatus', 'inputChars',
+]
+function copyEvidence(value, seen = new WeakMap()) {
+  if (value === null || typeof value !== 'object') return typeof value === 'function' ? undefined : value
+  if (!Array.isArray(value) && !plainObject(value)) return undefined
+  if (seen.has(value)) return undefined
+  const copy = Array.isArray(value) ? [] : {}
+  seen.set(value, copy)
+  for (const key of Object.keys(value)) {
+    if (key === 'attempts' || key === '__proto__') continue
+    copy[key] = copyEvidence(value[key], seen)
+  }
+  return copy
+}
+function attemptRecord(result, route, startedAt, finishedAt) {
+  const attempt = {}
+  for (const key of ATTEMPT_FIELDS) if (Object.hasOwn(result, key)) attempt[key] = copyEvidence(result[key])
+  return { ...attempt, provider: result.provider ?? route.provider, model: result.model ?? route.model,
+    pricingSnapshot: plainObject(route.pricing) ? { ...route.pricing } : null,
+    startedAt, finishedAt, durationMs: Math.max(0, finishedAt - startedAt) }
+}
+const cancelledResult = result => ({ ...result, ok: false, cancelled: true, error: '执行已取消。' })
+const stopped = result => ['cancelled', 'blocked', 'paused', 'truncated', 'timedOut', 'notStarted']
+  .find(key => result[key] === true || result.status === key)
+const configuredRoute = route => plainObject(route) && typeof route.provider === 'string'
+  && route.provider.trim().length > 0 && typeof route.model === 'string' && route.model.trim().length > 0
+
+/** At most two externally supplied API calls. approveUpgrade owns budget and billing authorization. */
+export async function runQualityCascade({ route, task, gate = null, call, alternatives = [], approveUpgrade, signal } = {}) {
+  if (!configuredRoute(route) || typeof call !== 'function') throw new TypeError('A configured route and call function are required')
+  const rule = gate == null ? null : normalizeGate(gate)
+  const attempts = []
+  const check = result => validateAnswer(result?.answer, rule)
+  if (signal?.aborted) {
+    const result = cancelledResult({ answer: '', notStarted: true })
+    return { result, attempts, validation: check(result) }
+  }
+  async function invoke(selected) {
+    const startedAt = Date.now()
+    let result
+    try {
+      result = await call({ route: selected, task, signal })
+      if (!plainObject(result)) result = { ok: false, error: 'API未返回有效结果。', ran: 'unknown', usageIncomplete: true }
+    } catch (error) {
+      result = { ok: false, error: 'API调用失败。', ran: 'unknown', usageIncomplete: true,
+        ...(signal?.aborted || error?.name === 'AbortError' ? { cancelled: true } : {}) }
+    }
+    attempts.push(attemptRecord(result, selected, startedAt, Date.now()))
+    return result
+  }
+  const first = await invoke(route)
+  let validation = check(first)
+  if (!rule || first.ok !== true) return { result: first, attempts, validation }
+  let result = first
+  let escalated = false
+  let upgradeReason = validation.ok ? 'passed' : 'no-alternative'
+  const stop = stopped(first)
+  if (!validation.ok && stop) upgradeReason = stop
+  else if (!validation.ok && signal?.aborted) {
+    result = cancelledResult(first)
+    upgradeReason = 'cancelled'
+  } else if (!validation.ok) {
+    const alternative = (Array.isArray(alternatives) ? alternatives : []).find(candidate => configuredRoute(candidate)
+      && (candidate.provider !== route.provider || candidate.model !== route.model))
+    if (alternative) {
+      if (typeof approveUpgrade !== 'function') upgradeReason = 'approval-required'
+      else {
+        let approved = false
+        try {
+          // Pass snapshots so a callback cannot erase already incurred attempt evidence.
+          approved = await approveUpgrade({ from: copyEvidence(route), to: copyEvidence(alternative),
+            attempts: attempts.map(item => copyEvidence(item)) })
+          upgradeReason = approved === true ? 'approved' : 'approval-denied'
+        } catch { upgradeReason = 'approval-error' }
+        if (signal?.aborted) {
+          result = cancelledResult(first)
+          upgradeReason = 'cancelled'
+        } else if (approved === true) {
+          escalated = true
+          result = await invoke(alternative)
+          validation = check(result)
+          upgradeReason = validation.ok && result.ok === true && !stopped(result) ? 'passed-after-upgrade' : 'upgrade-failed'
+        }
+      }
+    }
+  }
+  const qualityValidation = { ...validation, escalated, upgradeReason }
+  if (!validation.ok && !result.cancelled) result = { ...result, ok: false, error: STRUCTURE_ERROR }
+  return { result: { ...result, qualityValidation }, attempts, validation }
+}

package/.dsh-plugin/shared/reasoning-execution.mjs

@@ -0,0 +1,92 @@
+// "requested" records an exact SDK control sent by the caller. It does not
+// establish the provider's actual effort, which requires separate evidence.
+const EFFORT_STATUSES = new Set(['requested', 'unsupported', 'unapplied'])
+
+const nonEmptyEffort = value => (typeof value === 'string' && value.length > 0 ? value : null)
+
+const allowedEffortIds = route => (Array.isArray(route?.reasoningEfforts)
+  ? route.reasoningEfforts.map(item => {
+    if (typeof item === 'string' && item.length > 0) return item
+    if (item && typeof item === 'object' && typeof item.id === 'string' && item.id.length > 0) return item.id
+    return null
+  }).filter(item => item !== null)
+  : [])
+
+/** Copy only trusted reasoning-effort fields; never infer actual effort. */
+export function reasoningExecutionFields(value) {
+  if (!value || typeof value !== 'object') return {}
+  const fields = {}
+  const planned = nonEmptyEffort(value.plannedReasoningEffort)
+  if (planned) fields.plannedReasoningEffort = planned
+  const requested = nonEmptyEffort(value.requestedReasoningEffort)
+  if (requested) fields.requestedReasoningEffort = requested
+  if (EFFORT_STATUSES.has(value.reasoningEffortStatus)) fields.reasoningEffortStatus = value.reasoningEffortStatus
+  return fields
+}
+
+/**
+ * Validate an explicit API-call effort against the route's exact allowed IDs.
+ * A valid request is returned separately so the caller can spread it into the
+ * SDK call only after validation. No default or aliased effort is chosen.
+ */
+export function apiReasoningRequest(route) {
+  const source = route && typeof route === 'object' ? route : {}
+  if (!Object.hasOwn(source, 'reasoningEffort') || source.reasoningEffort === undefined || source.reasoningEffort === null) {
+    return { options: {}, fields: {} }
+  }
+  const effort = source.reasoningEffort
+  const planned = nonEmptyEffort(effort)
+  const fields = planned ? { plannedReasoningEffort: planned } : {}
+  if (planned && allowedEffortIds(source).includes(effort)) {
+    return {
+      options: { reasoningEffort: effort },
+      fields: { ...fields, requestedReasoningEffort: effort, reasoningEffortStatus: 'requested' },
+    }
+  }
+  return {
+    options: {},
+    fields: { ...fields, reasoningEffortStatus: 'unsupported' },
+    error: `不支持的推理强度 ID：${String(effort)}；请使用 route.reasoningEfforts 中的精确 ID。`,
+  }
+}
+
+/** CLI mappings are not verified, so an explicit route effort stays unsupported. */
+export function unsupportedCliReasoning(route) {
+  const effort = nonEmptyEffort(route?.reasoningEffort)
+  return effort ? { plannedReasoningEffort: effort, reasoningEffortStatus: 'unsupported' } : {}
+}
+
+/**
+ * Build the execution route for one work package. The planned adapter-owned
+ * effort survives only when the package keeps its planned identity. A manual
+ * override on another provider/model must not inherit the original effort.
+ */
+export function reasoningRouteForAssignment(route, item, override) {
+  const next = { ...(route && typeof route === 'object' ? route : {}) }
+  delete next.reasoningEffort
+  const plannedProvider = nonEmptyEffort(item?.recommendedProvider) ?? nonEmptyEffort(next.provider)
+  const plannedModel = nonEmptyEffort(item?.recommendedModel) ?? nonEmptyEffort(next.model)
+  const overrideProvider = nonEmptyEffort(override?.provider)
+  const overrideModel = nonEmptyEffort(override?.model)
+  const samePlannedIdentity = (!overrideProvider || overrideProvider === plannedProvider)
+    && (!overrideModel || overrideModel === plannedModel)
+  if (samePlannedIdentity) {
+    const recommended = nonEmptyEffort(item?.recommendedReasoningEffort)
+    if (recommended) next.reasoningEffort = recommended
+  }
+  const explicitOverride = nonEmptyEffort(override?.reasoningEffort)
+  if (explicitOverride) next.reasoningEffort = explicitOverride
+  return next
+}
+
+/** Preserve an effort across billing only for the same provider/model identity. */
+export function routeForReasoningSwitch(source, target) {
+  let next = { ...(target && typeof target === 'object' ? target : {}) }
+  const sameIdentity = String(source?.provider ?? '') === String(next.provider ?? '')
+    && String(source?.model ?? '') === String(next.model ?? '')
+  if (sameIdentity) next = { ...source, ...next }
+  const effort = nonEmptyEffort(source?.reasoningEffort)
+  if (sameIdentity && effort) next.reasoningEffort = effort
+  else delete next.reasoningEffort
+  return next
+}

package/.dsh-plugin/shared/router-state.mjs

@@ -82,7 +82,8 @@ function invalidRunSpending(run) {
     if (!Array.isArray(run[field])) return true
     for (const item of run[field]) {
       if (!record(item) || (item.ran !== undefined && typeof item.ran !== 'boolean')) return true
-      if (['costUsd', 'referenceCostUsd'].some(name => item[name] !== undefined && item[name] !== null && !nonnegative(item[name]))) return true
+      if (['costUsd', 'referenceCostUsd', 'knownCostUsd'].some(name => item[name] !== undefined && item[name] !== null && !nonnegative(item[name]))) return true
+      if (item.unknownAttemptCount !== undefined && (!Number.isInteger(item.unknownAttemptCount) || item.unknownAttemptCount < 1 || item.unknownAttemptCount > 2)) return true
       if (item.ran === true || nonnegative(item.costUsd)) {
         const at = item.finishedAt ?? run.createdAt
         if (!nonnegative(at) || !Number.isFinite(new Date(at).getTime())) return true

package/.dsh-plugin/shared/router.mjs

@@ -9,6 +9,7 @@
 import { DEFAULT_ROUTING_PRESET, normalizeRoutingPreset, presetFloor, presetWeights } from './routing-presets.mjs'
 import { liveBenchRow } from './livebench.mjs'
 import { solveCandidateAssignments } from './assignment-solver.mjs'
+import { predictQuality, predictResources } from './routing-evidence.mjs'
 
 export const OBJECTIVE_WEIGHTS = Object.freeze({
   simple: Object.freeze({ quality: 0.28, cost: 0.45, latency: 0.14, specialty: 0.04, reasoning: 0.07, risk: 0.02 }),
@@ -135,7 +136,8 @@ export function textFromMessages(messages) {
 
 export function classifyTask(text) {
   const value = String(text ?? '')
-  if (value.length < 80 && /翻译|解释|translate|explain/i.test(value)) return 'general'
+  if (value.length < 80 && /翻译|解释|translate|explain/i.test(value)
+    && !detectTaskTypes(value).some(type => ['vision', 'math', 'code', 'research'].includes(type))) return 'general'
   return detectTaskTypes(value)[0] ?? 'general'
 }
 
@@ -195,6 +197,7 @@ function specialtyMatch(model, taskType, liveScores = {}) {
 }
 
 function qualityForTask(row, taskType) {
+  if (row?.queryEvidence?.type === taskType) return row.queryEvidence.quality
   const base = asScore(row?.liveScores?.[taskType]) ?? asScore(row?.liveOverall) ?? row?.metadata?.quality ?? row?.baseQuality ?? row?.quality ?? 0
   // Legacy programmatic scalar bias only. Production feedback uses an
   // independent preferenceAdjustments utility term, never this quality path.
@@ -202,6 +205,7 @@ function qualityForTask(row, taskType) {
 }
 
 function qualitySourceForTask(row, taskType) {
+  if (row?.queryEvidence?.type === taskType) return 'recorded-query-evidence'
   return asScore(row?.liveScores?.[taskType]) !== undefined || asScore(row?.liveOverall) !== undefined
     ? 'livebench' : row?.fallbackQualitySource ?? row?.qualitySource ?? 'unknown'
 }
@@ -616,6 +620,7 @@ function compareText(left, right) {
 
 function compareRowsStable(left, right) {
   return compareText(routeKey(left.provider, left.model), routeKey(right.provider, right.model))
+    || compareText(String(left.actionId ?? ''), String(right.actionId ?? ''))
 }
 
 function reasoningEffortRank(effort) {
@@ -648,6 +653,12 @@ export function selectReasoningEffort(efforts, preferred = 'medium') {
 
 function reasoningDecision(row, task) {
   const preferred = String(task.preferredReasoningEffort ?? 'medium')
+  if (row.reasoningExecution === 'unsupported-cli' || row.reasoningExecution === 'default') return {
+    reasoningEffort: undefined, reasoningFit: 0.55, preferredReasoningEffort: preferred,
+    multiplier: REASONING_EFFORT_MULTIPLIERS.medium,
+    reasoningExecutionNotice: row.reasoningExecution === 'default' ? '指定模型使用适配器默认推理档位。'
+      : 'CLI 推理档位尚无经验证的映射，按厂商默认档位执行。',
+  }
   const efforts = Array.isArray(row.reasoningEfforts) ? row.reasoningEfforts : []
   if (efforts.length === 0) {
     const knownUnsupported = row.reasoningKnown === true
@@ -662,7 +673,7 @@ function reasoningDecision(row, task) {
   const preferredRank = reasoningEffortRank(preferred)
   // On an equal distance the shared selector prefers the lower effort to
   // avoid unnecessary latency and output-token cost.
-  const chosen = selectReasoningEffort(efforts, preferred)
+  const chosen = Object.hasOwn(row, 'actionEffort') ? row.actionEffort : selectReasoningEffort(efforts, preferred)
   const distance = Math.abs(reasoningEffortRank(chosen) - preferredRank)
   return {
     reasoningEffort: chosen,
@@ -683,9 +694,13 @@ function candidateUtility(row, task, weights, cacheReadRatio = 0, cacheWriteRati
   const reasoning = reasoningDecision(row, task)
   const reference = taskCost({ pricing: COST_REFERENCE_PRICING, reasoningKnown: true, reasoningEfforts: [] }, task, text, complexity, cacheReadRatio, cacheWriteRatio)
   const cost = row.pricing === null ? 0 : 1 / (1 + taskCost(row, task, text, complexity, cacheReadRatio, cacheWriteRatio) / Math.max(reference, 1e-12))
+  const resources = resourceTokenBudget(row, task, text, complexity, cacheReadRatio, cacheWriteRatio)
+  const latencyUtility = Number.isFinite(resources.estimatedLatencyMs)
+    ? 1 / (1 + resources.estimatedLatencyMs / 10_000)
+    : 1 - clamp(row.latency * reasoning.multiplier.latency)
   const score = weights.quality * quality
     + weights.cost * cost
-    + weights.latency * (1 - clamp(row.latency * reasoning.multiplier.latency))
+    + weights.latency * latencyUtility
     + weights.specialty * specialtyForTask(row, task.type)
     + (weights.reasoning ?? 0) * reasoning.reasoningFit
     - weights.risk * row.risk
@@ -696,8 +711,7 @@ function candidateUtility(row, task, weights, cacheReadRatio = 0, cacheWriteRati
 
 function taskCost(row, task, text, complexity, cacheReadRatio = 0, cacheWriteRatio = 0) {
   if (row?.pricing === null) return 0 // Search sentinel; the public estimate remains null.
-  const decision = row === null ? null : reasoningDecision(row, task)
-  const tokens = taskTokenBudget(text, { ...task, reasoningEffort: decision?.reasoningEffort }, complexity, cacheReadRatio, cacheWriteRatio)
+  const tokens = resourceTokenBudget(row, task, text, complexity, cacheReadRatio, cacheWriteRatio)
   return row === null
     ? 0
     : (((tokens.inputTokens - tokens.cacheReadTokens - tokens.cacheWriteTokens) * row.pricing.input)
@@ -706,6 +720,81 @@ function taskCost(row, task, text, complexity, cacheReadRatio = 0, cacheWriteRat
       + (tokens.outputTokens * row.pricing.output)) / 1_000_000
 }
 
+/** Empirical quantiles are predictions, never a joint budget certificate. */
+function resourceTokenBudget(row, task, text, complexity, cacheReadRatio = 0, cacheWriteRatio = 0) {
+  const effort = row ? reasoningDecision(row, task).reasoningEffort : undefined
+  const fallback = taskTokenBudget(text, { ...task, reasoningEffort: effort }, complexity, cacheReadRatio, cacheWriteRatio)
+  if (!row?.routingEvidence) return { ...fallback, estimateSource: 'heuristic', resourceSampleCount: 0 }
+  const key = JSON.stringify([task.type, task.purpose, effort ?? '', String(text).length, cacheReadRatio, cacheWriteRatio])
+  if (row.resourceCache.has(key)) return row.resourceCache.get(key)
+  const observed = predictResources(row.routingEvidence, {
+    provider: row.provider, model: row.model, reasoningEffort: effort ?? '',
+    channel: row.executionChannel ?? 'harness-llm', type: task.type, purpose: task.purpose,
+    inputChars: String(text).length,
+  })
+  let result = { ...fallback, estimateSource: 'heuristic', resourceSampleCount: 0 }
+  if (observed) {
+    const promptRatio = observed.p90?.promptCharRatio ?? observed.promptCharRatio
+    const chars = Number.isFinite(promptRatio) ? String(text).length * promptRatio : fallback.inputTokens * 3.7
+    const inputTokens = Math.ceil(chars * observed.p90.inputTokenRatio)
+    const outputTokens = Math.ceil(observed.p90.outputTokens)
+    if (Number.isSafeInteger(inputTokens) && inputTokens >= 0 && Number.isSafeInteger(outputTokens) && outputTokens >= 0) {
+      const ratios = normalizedCacheRatios(cacheReadRatio, cacheWriteRatio)
+      const cacheReadTokens = Math.min(inputTokens, Math.round(inputTokens * ratios.read))
+      const cacheWriteTokens = Math.min(inputTokens - cacheReadTokens, Math.round(inputTokens * ratios.write))
+      result = { inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens,
+        estimateSource: observed.source, resourceSampleCount: observed.sampleCount,
+        estimatedLatencyMs: observed.p90.durationMs, empiricalQuantile: 0.9 }
+    }
+  }
+  row.resourceCache.set(key, result)
+  return result
+}
+
+/** Estimate one pinned API package without changing the task decomposition or choosing an effort. */
+export function estimateAssignedPackage(route, task, text, complexity = 'balanced', {
+  pricing = {}, routingEvidence = null, cacheReadRatio = 0, cacheWriteRatio = 0,
+} = {}) {
+  const prices = normalizePricing(pricing)
+  const override = prices[normalize(`${route.provider}/${route.model}`)] ?? prices[normalize(route.model)]
+  const selectedPrice = override ?? normalizePricing({ route: route.pricing }).route ?? null
+  const row = { provider: route.provider, model: route.model, pricing: selectedPrice,
+    reasoningExecution: 'default', executionChannel: 'harness-llm', routingEvidence,
+    resourceCache: new Map() }
+  const resources = resourceTokenBudget(row, task, text, complexity, cacheReadRatio, cacheWriteRatio)
+  const cost = selectedPrice === null ? null : taskCost(row, task, text, complexity, cacheReadRatio, cacheWriteRatio)
+  return { provider: route.provider, model: route.model, purpose: task.purpose, difficulty: task.difficulty,
+    ...resources, estimatedCost: Number.isFinite(cost) ? Number(cost.toFixed(6)) : null,
+    pricingSource: selectedPrice === null ? 'unknown' : override ? 'user' : route.pricingSource ?? 'route',
+    quality: null, qualitySource: 'manual-selection', handoffPenalty: 0 }
+}
+
+/** Expand only actions with their own task evidence; cold starts keep the old selector. */
+function taskActions(row, task) {
+  const text = task.objective || row.routingText
+  const key = JSON.stringify([task.type, task.purpose, task.preferredReasoningEffort, text])
+  if (row.actionCache.has(key)) return row.actionCache.get(key)
+  const nearest = reasoningDecision(row, task).reasoningEffort
+  const qualityAt = effort => {
+    const qualityKey = JSON.stringify([task.type, effort ?? '', text])
+    if (!row.qualityCache.has(qualityKey)) row.qualityCache.set(qualityKey, predictQuality(row.routingEvidence, {
+      text, type: task.type, provider: row.provider, model: row.model,
+      reasoningEffort: effort ?? '', channel: row.executionChannel ?? 'harness-llm',
+    }))
+    return row.qualityCache.get(qualityKey)
+  }
+  let alternatives = []
+  if (row.reasoningExecution === 'api') alternatives = (row.reasoningEfforts ?? []).map(effort => ({ effort, quality: qualityAt(effort) })).filter(item => item.quality)
+  const joint = alternatives.length >= 2
+  const actions = joint ? alternatives : [{ effort: nearest, quality: qualityAt(nearest) }]
+  const variants = actions.map(({ effort, quality }) => ({ ...row, actionEffort: effort,
+    actionId: JSON.stringify([row.provider, row.model, effort ?? null]), jointEffort: joint,
+    queryEvidence: quality ? { ...quality, type: task.type } : null,
+  }))
+  row.actionCache.set(key, variants)
+  return variants
+}
+
 function dominates(left, right, task, text, complexity, cacheReadRatio, cacheWriteRatio) {
   if (left.pricing === null || right.pricing === null) return false
   const leftReasoning = reasoningDecision(left, task)
@@ -742,9 +831,10 @@ function dominates(left, right, task, text, complexity, cacheReadRatio, cacheWri
 }
 
 function eligibleRowsForTask(rows, task) {
-  return task.type === 'vision'
+  const eligible = task.type === 'vision'
     ? rows.filter(row => row.inputModalities.length === 0 || row.inputModalities.includes('image'))
     : rows
+  return eligible.flatMap(row => taskActions(row, task))
 }
 
 function candidatePool(rows, task, weights, text, complexity, cacheReadRatio, cacheWriteRatio, dependencySensitive = false) {
@@ -795,13 +885,14 @@ function solveAssignments({ rows, tasks, weights, text, complexity, budget, cach
   const pools = tasks.map(task => candidatePool(rows, task, weights, text, complexity, cacheReadRatio, cacheWriteRatio, dependencySensitive))
   const result = solveCandidateAssignments({ tasks, pools: pools.map((pool, index) => pool.options.map(option => ({
     route: routeKey(option.row.provider, option.row.model), score: option.decision.score, cost: option.cost,
+    actionId: option.row.actionId, handoffRoute: routeKey(option.row.provider, option.row.model),
     qualityShortfall: Math.max(0, option.decision.floor - qualityForTask(option.row, tasks[index].type)),
     pricingKnown: option.row.pricing !== null, payload: option,
   }))), budget, beamWidth: ROUTING_BEAM_WIDTH, minimizeCost })
   if (!result) return null
   return {
     ...result,
-    assignments: result.choices.map((choice, index) => ({ task: tasks[index], row: choice.payload.row,
+    assignments: result.choices.map((choice, index) => ({ task: tasks[index], row: { ...choice.payload.row, estimatedCost: choice.payload.row.pricing === null ? null : choice.cost },
       decision: { ...choice.payload.decision, relaxed: choice.qualityShortfall > 0 },
       estimatedCost: choice.cost, handoffPenalty: choice.handoffPenalty })),
     usedRoutes: new Set(result.choices.map(choice => choice.route)),
@@ -810,7 +901,7 @@ function solveAssignments({ rows, tasks, weights, text, complexity, budget, cach
   }
 }
 
-export function buildPlan({ text = '', available = [], mode = 'collective', pricing = {}, liveBench = null, liveBenchError = '', dataVersions = null, learning = null, budgetUsd = 0, cacheReadRatio = 0, cacheWriteRatio = 0, preset = DEFAULT_ROUTING_PRESET } = {}) {
+export function buildPlan({ text = '', available = [], mode = 'collective', pricing = {}, liveBench = null, liveBenchError = '', dataVersions = null, learning = null, routingEvidence = null, budgetUsd = 0, cacheReadRatio = 0, cacheWriteRatio = 0, preset = DEFAULT_ROUTING_PRESET } = {}) {
   const presetId = normalizeRoutingPreset(preset)
   const firstLine = String(text ?? '').split(/\r?\n/u)[0].trim()
   const transformOnly = /^(?:请|帮我)?(?:总结|概括|翻译|摘要|解释)(?:以下|下列|下面|这份|这些)/u.test(firstLine)
@@ -830,6 +921,8 @@ export function buildPlan({ text = '', available = [], mode = 'collective', pric
         return {
           provider: String(entry.provider ?? ''),
           model: String(entry.model ?? ''),
+          executionChannel: ['harness-llm', 'official-cli'].includes(entry.executionChannel) ? entry.executionChannel : undefined,
+          reasoningExecution: ['api', 'unsupported-cli', 'default'].includes(entry.reasoningExecution) ? entry.reasoningExecution : undefined,
           benchmarkModel: typeof entry.benchmarkModel === 'string' ? entry.benchmarkModel : undefined,
           reasoningEfforts: [...new Set(reasoningEfforts)],
           defaultReasoningEffort: entry.defaultReasoningEffort === undefined ? undefined : String(entry.defaultReasoningEffort),
@@ -902,6 +995,9 @@ export function buildPlan({ text = '', available = [], mode = 'collective', pric
       reasoningEfforts: route.reasoningEfforts,
       defaultReasoningEffort: route.defaultReasoningEffort,
       reasoningKnown: route.reasoningKnown,
+      reasoningExecution: route.reasoningExecution,
+      executionChannel: route.executionChannel,
+      routingEvidence, routingText: text, actionCache: new Map(), qualityCache: new Map(), resourceCache: new Map(),
       inputModalities: route.inputModalities,
       pricing: pricingRow,
       score: 0,
@@ -982,13 +1078,14 @@ export function buildPlan({ text = '', available = [], mode = 'collective', pric
     recommendedReasoningEffort: decision?.reasoningEffort,
     preferredReasoningEffort: decision?.preferredReasoningEffort ?? task.preferredReasoningEffort,
     reasoningFit: Number(Number(decision?.reasoningFit ?? 0).toFixed(3)),
+    ...(decision?.reasoningExecutionNotice ? { reasoningExecutionNotice: decision.reasoningExecutionNotice } : {}),
     purpose: task.purpose,
     criticality: task.criticality,
     qualityFloor: Number(task.qualityFloor.toFixed(3)),
     dependsOn: [...(task.dependsOn ?? [])],
   }))
   const costBreakdown = assignments.map(({ task, row, decision, estimatedCost, handoffPenalty }, index) => {
-    const tokens = taskTokenBudget(text, { ...task, reasoningEffort: decision?.reasoningEffort }, complexity.band, cacheReadRatio, cacheWriteRatio)
+    const tokens = resourceTokenBudget(row, task, text, complexity.band, cacheReadRatio, cacheWriteRatio)
     const taskEstimate = estimatedCost ?? taskCost(row, task, text, complexity.band, cacheReadRatio, cacheWriteRatio)
     return {
       stage: index + 1,
@@ -1004,6 +1101,11 @@ export function buildPlan({ text = '', available = [], mode = 'collective', pric
       cacheReadTokens: tokens.cacheReadTokens,
       cacheWriteTokens: tokens.cacheWriteTokens,
       outputTokens: tokens.outputTokens,
+      estimateSource: tokens.estimateSource,
+      resourceSampleCount: tokens.resourceSampleCount,
+      ...(Number.isFinite(tokens.estimatedLatencyMs) ? { estimatedLatencyMs: tokens.estimatedLatencyMs } : {}),
+      ...(tokens.empiricalQuantile ? { empiricalQuantile: tokens.empiricalQuantile } : {}),
+      ...(row?.queryEvidence ? { queryEvidenceCount: row.queryEvidence.sampleCount, querySimilarity: row.queryEvidence.similarity } : {}),
       estimatedCost: row?.pricing === null || row === null ? null : Number(taskEstimate.toFixed(6)),
       quality: qualitySourceForTask(row, task.type) === 'unknown' || row === null ? null : Number(qualityForTask(row, task.type).toFixed(3)),
       qualitySource: qualitySourceForTask(row, task.type),
@@ -1021,8 +1123,9 @@ export function buildPlan({ text = '', available = [], mode = 'collective', pric
   const baselineCost = baselineRows.every(item => item.strongest?.pricing !== null && item.strongest !== null)
     ? baselineRows.reduce((sum, { task, strongest }) => sum + taskCost(strongest, task, text, complexity.band, cacheReadRatio, cacheWriteRatio), 0)
     : null
-  const qualityEvidenceComplete = assignments.length > 0 && assignments.every(({ row, task }) => ['livebench', 'route', 'user'].includes(qualitySourceForTask(row, task.type)))
-    && baselineRows.every(({ strongest, task }) => ['livebench', 'route', 'user'].includes(qualitySourceForTask(strongest, task.type)))
+  const knownQualitySources = ['livebench', 'route', 'user', 'recorded-query-evidence']
+  const qualityEvidenceComplete = assignments.length > 0 && assignments.every(({ row, task }) => knownQualitySources.includes(qualitySourceForTask(row, task.type)))
+    && baselineRows.every(({ strongest, task }) => knownQualitySources.includes(qualitySourceForTask(strongest, task.type)))
   const budgetExceeded = Number(budgetUsd) > 0 && totalEstimate !== null ? totalEstimate > Number(budgetUsd) : null
   const savings = baselineCost === null || totalEstimate === null || !qualityEvidenceComplete
     ? null : baselineCost <= 0 ? 0 : clamp((baselineCost - totalEstimate) / baselineCost)
@@ -1043,7 +1146,11 @@ export function buildPlan({ text = '', available = [], mode = 'collective', pric
     taskType,
     taskTypes: [...new Set(taskNodes.map(task => task.type).filter(type => type !== 'reasoning'))],
     objectiveWeights: weights,
-    candidates: rows.slice(0, 8).map(row => {
+    candidates: eligibleRowsForTask(rows, taskNodes[0]).map(row => ({ ...row,
+      score: candidateUtility(row, taskNodes[0], weights, cacheReadRatio, cacheWriteRatio, text, complexity.band).score,
+      quality: qualityForTask(row, taskNodes[0].type), qualitySource: qualitySourceForTask(row, taskNodes[0].type),
+      estimatedCost: row.pricing === null ? null : taskCost(row, taskNodes[0], text, complexity.band, cacheReadRatio, cacheWriteRatio),
+    })).sort((left, right) => right.score - left.score || compareRowsStable(left, right)).slice(0, 8).map(row => {
       const decision = candidateUtility(row, taskNodes[0] ?? { type: taskType, qualityFloor: QUALITY_FLOORS[complexity.band], preferredReasoningEffort: complexity.band === 'simple' ? 'low' : 'medium' }, weights, cacheReadRatio, cacheWriteRatio, text, complexity.band)
       return { provider: row.provider, model: row.model, score: Number(row.score.toFixed(3)), preferenceAdjustment: decision.preferenceAdjustment, quality: row.qualitySource === 'unknown' ? null : Number(row.quality.toFixed(3)), qualitySource: row.qualitySource, specialty: Number(row.specialty.toFixed(3)), reasoningEffort: decision.reasoningEffort, preferredReasoningEffort: decision.preferredReasoningEffort, reasoningFit: Number(decision.reasoningFit.toFixed(3)), reasoningKnown: row.reasoningKnown, reasoningEfforts: row.reasoningEfforts, estimatedCost: row.estimatedCost === null ? null : Number(row.estimatedCost.toFixed(6)), inputPrice: row.pricing?.input ?? null, outputPrice: row.pricing?.output ?? null, pricingSource: row.pricingSource, pricingVersion: row.pricingVersion, pricingAsOf: row.snapshotAsOf }
     }),
@@ -1055,6 +1162,11 @@ export function buildPlan({ text = '', available = [], mode = 'collective', pric
     costBreakdown,
     optimization: {
       dataVersions,
+      evidenceRevision: routingEvidence?.revision ?? null,
+      qualityEvidenceCount: assignments.filter(({ row }) => row.queryEvidence).length,
+      resourceEvidenceCount: costBreakdown.filter(item => item.estimateSource === 'recorded-resource-evidence').length,
+      jointEffortCandidates: (optimized?.candidatePools ?? []).reduce((sum, pool) => sum + pool.options.filter(item => item.row.jointEffort).length, 0),
+      uncertaintySemantics: 'empirical-prediction-not-calibrated-probability-or-joint-budget-guarantee',
       personalization: learning ? {
         policyVersion: learning.policyVersion, revision: learning.revision,
         enabled: learning.enabled, scope: learning.scope, window: learning.window,