@ljwei-stak/dsh-model-router 0.23.1 → 0.25.0

package/.dsh-plugin/shared/budget-reservations.mjs

@@ -0,0 +1,273 @@
+/**
+ * Durable execution holds. Every transition uses router-state's one file-lock
+ * transaction, so another Host cannot approve against an out-of-date balance.
+ * A hold is a remaining estimate, never an invoice or proof of a zero charge.
+ */
+import { randomUUID } from 'node:crypto'
+import { budgetCheck, spending } from './run-ledger.mjs'
+
+export const MAX_EXECUTION_RESERVATIONS = 100
+const record = value => value !== null && typeof value === 'object' && !Array.isArray(value)
+const amount = value => typeof value === 'number' && Number.isFinite(value) && value >= 0
+const identifier = value => typeof value === 'string' && value.length > 0 && value.length <= 512 && !/[\u0000-\u001f\u007f]/u.test(value)
+const timestamp = value => amount(value) && Number.isFinite(new Date(value).getTime())
+
+/** Unknown/corrupt holds make history incomplete; silently losing them is unsafe. */
+export function sanitizeBudgetReservations(value) {
+  if (value === undefined) return { reservations: {}, invalid: false }
+  if (!record(value)) return { reservations: {}, invalid: true }
+  const reservations = {}
+  let invalid = false
+  for (const [key, entry] of Object.entries(value)) {
+    if (!identifier(key) || !record(entry) || entry.id !== key || entry.runId !== key
+      || !identifier(entry.ownerToken) || !Number.isSafeInteger(entry.ownerPid) || entry.ownerPid < 1
+      || !['active', 'interrupted'].includes(entry.status) || !timestamp(entry.createdAt) || !timestamp(entry.updatedAt)
+      || !Array.isArray(entry.packages) || !Array.isArray(entry.completedIds)
+      || entry.completedIds.some(id => !identifier(id))
+      || entry.packages.some(item => !record(item) || !identifier(item.id)
+        || (item.billing !== undefined && !['api', 'subscription'].includes(item.billing))
+        || (item.estimatedCostUsd !== null && !amount(item.estimatedCostUsd)) || typeof item.started !== 'boolean')
+      || new Set(entry.packages.map(item => item.id)).size !== entry.packages.length
+      || entry.packages.some(item => entry.completedIds.includes(item.id))) {
+      invalid = true
+      continue
+    }
+    reservations[key] = {
+      id: key, runId: key, ownerToken: entry.ownerToken, ownerPid: entry.ownerPid,
+      status: entry.status, createdAt: entry.createdAt, updatedAt: entry.updatedAt,
+      ...(timestamp(entry.interruptedAt) ? { interruptedAt: entry.interruptedAt } : {}),
+      packages: entry.packages.map(item => ({ id: item.id, estimatedCostUsd: item.estimatedCostUsd, started: item.started, ...(item.billing ? { billing: item.billing } : {}) })),
+      completedIds: [...new Set(entry.completedIds)],
+    }
+  }
+  return { reservations, invalid }
+}
+
+/** Live and unreconciled interrupted work occupies today's and this month's room. */
+export function reservationSpending(state, { excludeReservationId = null } = {}) {
+  let reservedUsd = 0
+  let unknownReservations = 0
+  for (const entry of Object.values(state?.budgetReservations ?? {})) {
+    if (!record(entry) || entry.id === excludeReservationId) continue
+    for (const item of Array.isArray(entry.packages) ? entry.packages : []) {
+      if (item.billing === 'subscription') continue
+      if (amount(item.estimatedCostUsd)) reservedUsd += item.estimatedCostUsd
+      if (!amount(item.estimatedCostUsd) || (entry.status === 'interrupted' && item.started)) unknownReservations += 1
+    }
+  }
+  return { today: reservedUsd, month: reservedUsd, unknownToday: unknownReservations,
+    unknownMonth: unknownReservations, reservedUsd, unknownReservations }
+}
+
+function normalizedEstimates(value, run) {
+  const values = value ?? (run?.packages ?? []).map(item => ({ id: item.id, estimatedCostUsd: item.estimatedCost ?? null }))
+  if (!Array.isArray(values) || values.some(item => !record(item) || !identifier(item.id))) {
+    throw new TypeError('工作包预占必须包含有效的工作包 ID。')
+  }
+  const seen = new Set()
+  return values.map(item => {
+    if (seen.has(item.id)) throw new TypeError('工作包预占 ID 不能重复。')
+    seen.add(item.id)
+    const estimatedCostUsd = Object.hasOwn(item, 'estimatedCostUsd') ? item.estimatedCostUsd : item.estimatedCost ?? null
+    if (estimatedCostUsd !== null && !amount(estimatedCostUsd)) throw new TypeError('工作包预估费用必须是非负有限数字或 null。')
+    if (item.billing !== undefined && !['api', 'subscription'].includes(item.billing)) throw new TypeError('预占计费通道无效。')
+    return { id: item.id, estimatedCostUsd: item.billing === 'subscription' ? 0 : estimatedCostUsd,
+      started: item.started === true, ...(item.billing ? { billing: item.billing } : {}) }
+  })
+}
+
+function checkedRun(run, id = run?.id) {
+  if (!record(run) || !identifier(id) || run.id !== id || !Array.isArray(run.packages)) {
+    throw new TypeError('执行检查点必须包含对应的完整运行记录。')
+  }
+  return structuredClone(run)
+}
+
+function upsertRun(current, run) {
+  const index = current.runs.findIndex(item => item.id === run.id)
+  if (index < 0) current.runs.push(run)
+  else current.runs[index] = run
+}
+
+function ownedReservation(current, reservationId, ownerToken) {
+  const entry = current.budgetReservations?.[reservationId]
+  if (!entry || entry.ownerToken !== ownerToken || entry.status !== 'active') {
+    const error = new Error('执行预占不存在、已中断或属于其他执行；原记录未修改。')
+    error.code = 'ROUTER_RESERVATION_OWNERSHIP'
+    throw error
+  }
+  return entry
+}
+
+function estimateTotal(packages) {
+  packages = packages.filter(item => item.billing !== 'subscription')
+  if (packages.some(item => item.estimatedCostUsd === null)) return null
+  const total = packages.reduce((sum, item) => sum + item.estimatedCostUsd, 0)
+  return Number.isFinite(total) ? total : null
+}
+
+function currentBudget(current, at, packages, options, excludeReservationId = null) {
+  const recorded = spending(current.runs, at, current.archivedSpending)
+  const holds = reservationSpending(current, { excludeReservationId })
+  const spent = { ...recorded, today: recorded.today + holds.today, month: recorded.month + holds.month,
+    unknownToday: recorded.unknownToday + holds.unknownToday, unknownMonth: recorded.unknownMonth + holds.unknownMonth }
+  const budget = budgetCheck({ estimateUsd: estimateTotal(packages), spent,
+    dailyLimitUsd: options.dailyLimitUsd, monthlyLimitUsd: options.monthlyLimitUsd })
+  const apiExposure = packages.some(item => item.billing !== 'subscription')
+  budget.apiExposure = apiExposure
+  if (!apiExposure) { budget.exceeded = null; budget.message = '订阅按用量单独统计，不占用 API 金额预算。' }
+  const unknownBudget = apiExposure && budget.limited && (!budget.estimateKnown
+    || (options.dailyLimitUsd > 0 && spent.unknownToday > 0)
+    || (options.monthlyLimitUsd > 0 && spent.unknownMonth > 0))
+  if (unknownBudget && !budget.exceeded) budget.message = '存在未核对费用或缺少单价，无法保证本次执行符合预算；请先核对账单或明确确认继续。'
+  return { budget, spent, recorded, unknownBudget, ...holds }
+}
+
+/** false means definitely dead; permission failures and PID reuse stay conservative. */
+function processAlive(pid) {
+  try { process.kill(pid, 0); return true }
+  catch (error) { return error?.code === 'ESRCH' ? false : null }
+}
+
+export function createBudgetReservations({ state, now = Date.now, pid = process.pid, isProcessAlive = processAlive,
+  maxReservations = MAX_EXECUTION_RESERVATIONS } = {}) {
+  if (!state || typeof state.update !== 'function' || typeof state.read !== 'function') throw new TypeError('需要持久状态存储。')
+  if (!Number.isSafeInteger(pid) || pid < 1) throw new TypeError('需要有效的执行进程 ID。')
+  if (!Number.isInteger(maxReservations) || maxReservations < 1 || maxReservations > MAX_EXECUTION_RESERVATIONS) throw new RangeError('执行预占数量上限无效。')
+  const snapshot = async () => reservationSpending(await state.read())
+  const beginExecution = options => {
+    const run = checkedRun(options?.run)
+    const ownerToken = options.ownerToken ?? randomUUID()
+    if (!identifier(ownerToken)) throw new TypeError('需要有效的执行所有权标记。')
+    const packages = normalizedEstimates(options.packageEstimates, run)
+    return state.update(current => {
+      const checks = currentBudget(current, now(), packages, options)
+      if (current.historyIncomplete && checks.budget.apiExposure) return { accepted: false, reason: 'history-incomplete', ...checks }
+      current.budgetReservations ??= {}
+      if (current.budgetReservations[run.id]) return { accepted: false, reason: 'active-run', ...checks }
+      if (Object.keys(current.budgetReservations).length >= maxReservations) return { accepted: false, reason: 'reservation-capacity', ...checks }
+      if (checks.budget.exceeded && options.confirmOverBudget !== true) return { accepted: false, reason: 'budget', ...checks }
+      if (checks.unknownBudget && options.confirmOverBudget !== true) return { accepted: false, reason: 'budget-unknown', ...checks }
+      const at = now()
+      const entry = { id: run.id, runId: run.id, ownerToken, ownerPid: pid, status: 'active',
+        createdAt: at, updatedAt: at, packages, completedIds: [] }
+      current.budgetReservations[run.id] = entry
+      upsertRun(current, run)
+      return { accepted: true, reservationId: entry.id, ownerToken, run, ...checks }
+    })
+  }
+  const checkpointExecution = ({ reservationId, ownerToken, run: nextRun, completedIds = [], startedIds = [],
+    checkBudget = false, budgetRun: affordabilityRun, ...options }) => {
+    const run = checkedRun(nextRun, reservationId)
+    const budgetRun = affordabilityRun === undefined ? run : checkedRun(affordabilityRun, reservationId)
+    if (![completedIds, startedIds].every(ids => Array.isArray(ids) && ids.every(identifier))) throw new TypeError('检查点工作包 ID 无效。')
+    return state.update(current => {
+      const entry = ownedReservation(current, reservationId, ownerToken)
+      const completed = new Set([...entry.completedIds, ...completedIds])
+      const started = new Set(startedIds)
+      const known = new Set([...entry.completedIds, ...entry.packages.map(item => item.id)])
+      if ([...completed, ...started].some(id => !known.has(id))) throw new TypeError('检查点包含未预占的工作包。')
+      const remaining = entry.packages.filter(item => !completed.has(item.id)).map(item => ({ ...item, started: item.started || started.has(item.id) }))
+      if (checkBudget) {
+        // Receipts may exceed their original estimates, or another execution
+        // may have settled meanwhile. Recheck the full remaining occupancy at
+        // this dispatch boundary without double-counting our previous hold.
+        const prospective = { ...current, runs: current.runs.map(item => item.id === run.id ? budgetRun : item) }
+        const checks = currentBudget(prospective, now(), remaining, options, entry.id)
+        const starting = entry.packages.filter(item => started.has(item.id) && !item.started)
+        if (starting.length && starting.every(item => item.billing === 'subscription')) {
+          // A later API step retains its hold and will be checked at its own
+          // dispatch boundary; it cannot make this subscription consume money.
+          Object.assign(checks.budget, { apiExposure: false, exceeded: null, estimateUsd: 0, estimateKnown: true,
+            message: '当前订阅步骤单独统计用量，不占用 API 金额预算。' })
+          checks.unknownBudget = false
+        }
+        if (current.historyIncomplete && checks.budget.apiExposure) return { accepted: false, reason: 'history-incomplete', ...checks }
+        if (checks.budget.exceeded && options.confirmOverBudget !== true) return { accepted: false, reason: 'budget', ...checks }
+        if (checks.unknownBudget && options.confirmOverBudget !== true) return { accepted: false, reason: 'budget-unknown', ...checks }
+      }
+      entry.packages = remaining
+      entry.completedIds = [...completed]
+      entry.updatedAt = now()
+      upsertRun(current, run)
+      return { accepted: true, reservationId, run, ...reservationSpending(current) }
+    })
+  }
+  const resizeExecution = options => {
+    const packages = normalizedEstimates(options.packageEstimates)
+    return state.update(current => {
+      const entry = ownedReservation(current, options.reservationId, options.ownerToken)
+      const checks = currentBudget(current, now(), packages, options, entry.id)
+      if (current.historyIncomplete && checks.budget.apiExposure) return { accepted: false, reason: 'history-incomplete', ...checks }
+      if (checks.budget.exceeded && options.confirmOverBudget !== true) return { accepted: false, reason: 'budget', ...checks }
+      if (checks.unknownBudget && options.confirmOverBudget !== true) return { accepted: false, reason: 'budget-unknown', ...checks }
+      if (packages.some(item => entry.completedIds.includes(item.id))) throw new TypeError('已完成工作包不能重新加入剩余预占。')
+      // An already-started call may still incur charges; resizing cannot erase it.
+      for (const previous of entry.packages.filter(item => item.started)) {
+        const next = packages.find(item => item.id === previous.id)
+        if (!next) throw new TypeError('执行中的工作包必须先保存结果，才能释放其预占。')
+        if (previous.billing !== 'subscription' && next.billing === 'subscription') {
+          throw new TypeError('执行中的 API 调用不能通过改为订阅释放金额预占；请先保存收据。')
+        }
+        next.started = true
+      }
+      entry.packages = packages
+      entry.updatedAt = now()
+      return { accepted: true, reservationId: entry.id, ...checks }
+    })
+  }
+  const finishExecution = ({ reservationId, ownerToken, run: nextRun }) => {
+    const run = checkedRun(nextRun, reservationId)
+    return state.update(current => {
+      ownedReservation(current, reservationId, ownerToken)
+      upsertRun(current, run)
+      delete current.budgetReservations[reservationId]
+      return { reservationId, run, ...reservationSpending(current) }
+    })
+  }
+  const markInterrupted = (current, entry, run, at) => {
+    entry.status = 'interrupted'
+    entry.interruptedAt = at
+    entry.updatedAt = at
+    if (run) {
+      run.status = 'interrupted'
+      run.finishedAt = at
+      for (const pending of entry.packages.filter(item => item.started)) {
+        const item = [...run.packages, ...(run.reviews ?? [])].find(item => item.id === pending.id)
+        if (!item || (!item.inFlight && !['pending', 'running'].includes(item.status))
+          || amount(item.costUsd) || amount(item.knownCostUsd) || Array.isArray(item.qualityAttempts)) continue
+        // We know a request began, but never observed its receipt. Keep that
+        // uncertainty in the ledger as well as the durable estimate hold.
+        item.status = 'interrupted'
+        item.inFlight = false
+        item.ran = true
+        item.costUsd = null
+        item.costSource = 'interrupted-usage-unknown'
+        item.billing = pending.billing === 'subscription' || item.billing === 'subscription' ? 'subscription' : 'api'
+        item.finishedAt = at
+      }
+      run.interruption = { at, unreconciled: true, pendingPackageIds: entry.packages.map(item => item.id),
+        startedPackageIds: entry.packages.filter(item => item.started).map(item => item.id) }
+    } else current.historyIncomplete = true
+  }
+  const interruptExecution = ({ reservationId, ownerToken, run: nextRun }) => {
+    const run = checkedRun(nextRun, reservationId)
+    return state.update(current => {
+      const entry = ownedReservation(current, reservationId, ownerToken)
+      markInterrupted(current, entry, run, now())
+      upsertRun(current, run)
+      return { reservationId, run, ...reservationSpending(current) }
+    })
+  }
+  const recoverInterruptedExecutions = () => state.update(async current => {
+    const recovered = []
+    for (const entry of Object.values(current.budgetReservations ?? {})) {
+      if (entry.status !== 'active' || await isProcessAlive(entry.ownerPid) !== false) continue
+      const run = current.runs.find(item => item.id === entry.runId)
+      markInterrupted(current, entry, run, now())
+      recovered.push({ reservationId: entry.id, runId: entry.runId, ...entry })
+    }
+    return { recovered, ...reservationSpending(current) }
+  })
+  return { beginExecution, checkpointExecution, resizeExecution, finishExecution, interruptExecution, recoverInterruptedExecutions, snapshot }
+}

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

@@ -0,0 +1,61 @@
+/** API money and subscription quantities are separate dimensions. */
+import { plannedPackages } from './run-ledger.mjs'
+import { billingPlan } from './subscription-billing.mjs'
+import { toolForProvider } from './official-tool-registry.mjs'
+import { estimateAssignedPackage } from './router.mjs'
+
+export function initialFunding(route, { billing = null, officialCli = false, toolId = null,
+  loginBillingFor = () => 'unknown', apiKeyFor = () => false, forceApi = false, executionChannel = null } = {}) {
+  const id = toolId ?? toolForProvider(route?.provider)?.id
+  if (forceApi) return { billing: 'api', route }
+  if (officialCli) return { billing: !apiKeyFor(id) && loginBillingFor(id) === 'subscription' ? 'subscription' : 'api', route }
+  if (!billing) return { billing: 'api', route }
+  const policy = billingPlan(route, billing.routes ?? [])
+  if (policy.mode === 'subscription-only') return { billing: 'subscription', route }
+  if (policy.mode === 'api-only' || billing.choice === 'api') return { billing: 'api', route: policy.apiRoute ?? route }
+  const sub = policy.subscription
+  if (!sub) return { billing: 'api', route }
+  if (billing.quota?.status?.(sub.key)) return { billing: 'api', route: policy.apiRoute ?? route }
+  if (sub.kind === 'plan-key') return { billing: 'subscription', route }
+  if (billing.choice === 'subscription') return { billing: 'subscription', route }
+  const login = billing.loginBillingFor?.(sub.toolId) ?? loginBillingFor(sub.toolId)
+  return { billing: route?.execution === 'api' || executionChannel === 'harness-llm'
+    || login !== 'subscription' ? 'api' : 'subscription', route }
+}
+
+export function attachPlanAccounting(plan, task, routes = [], context = {}) {
+  const entries = plannedPackages(plan, task).map((item, index) => {
+    const selected = item.manualAssignment?.kind === 'api' ? item.manualAssignment
+      : { provider: item.recommendedProvider, model: item.recommendedModel }
+    const route = routes.find(route => route.provider === selected.provider && route.model === selected.model) ?? selected
+    const funding = initialFunding(route, { ...context, executionChannel: item.executionChannel ?? plan.executionChannel,
+      ...(context.billingChoices?.[item.id] && context.billing ? { billing: { ...context.billing, choice: context.billingChoices[item.id] } } : {}),
+      ...(item.manualAssignment?.kind === 'api' ? { forceApi: true } : {}),
+      ...(item.manualAssignment?.kind === 'tool' ? { officialCli: true, toolId: item.manualAssignment.toolId } : {}) })
+    const resource = plan.costBreakdown?.[index] ?? estimateAssignedPackage(route, item, task, plan.complexity?.band ?? 'balanced')
+    const changed = funding.route?.provider !== route.provider || funding.route?.model !== route.model
+    const estimate = changed || plan.subscriptionPricedRoutes?.includes(`${route.provider}/${route.model}`)
+      ? estimateAssignedPackage(funding.route, item, task, plan.complexity?.band ?? 'balanced').estimatedCost
+      : item.estimatedCost ?? null
+    return { id: item.id, billing: funding.billing,
+      apiEstimatedCostUsd: funding.billing === 'subscription' ? 0 : estimate,
+      estimatedUsage: { inputTokens: resource.inputTokens ?? null, outputTokens: resource.outputTokens ?? null } }
+  })
+  const api = entries.filter(item => item.billing === 'api')
+  plan.accounting = { packages: entries, apiExposure: api.length > 0,
+    apiEstimatedCostUsd: api.some(item => !Number.isFinite(item.apiEstimatedCostUsd)) ? null
+      : api.reduce((sum, item) => sum + item.apiEstimatedCostUsd, 0) }
+  return plan.accounting
+}
+
+export const accountingEstimates = plan => plan.accounting.packages.map(item => ({ id: item.id,
+  billing: item.billing, estimatedCostUsd: item.apiEstimatedCostUsd }))
+
+/** Zero marginal API expense for subscription routes; never rewrite real prices. */
+export function planningFundingPrices(routes, context, channelForRoute = () => null) {
+  const subscriptionPricedRoutes = routes.filter(route => initialFunding(route, {
+    ...context, executionChannel: channelForRoute(route),
+  }).billing === 'subscription').map(route => `${route.provider}/${route.model}`)
+  return { subscriptionPricedRoutes, pricing: Object.fromEntries(subscriptionPricedRoutes.map(key => [key,
+    { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }])) }
+}

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

@@ -0,0 +1,143 @@
+/** Required durable execution state, independent of advisory UI observers. */
+import { randomUUID } from 'node:crypto'
+import { createBudgetReservations } from './budget-reservations.mjs'
+
+const receiptTimestamp = value => typeof value === 'number' && Number.isFinite(value) && value >= 0
+  && Number.isFinite(new Date(value).getTime())
+
+export async function beginExecutionLifecycle({ state, buildRun, packageEstimates, settings = {}, confirmOverBudget = false }) {
+  const ownerToken = randomUUID()
+  const manager = createBudgetReservations({ state })
+  await manager.recoverInterruptedExecutions()
+  const started = new Map(), results = new Map(), completed = new Set()
+  const estimates = new Map(packageEstimates.map(item => [item.id, { estimatedCostUsd: item.estimatedCostUsd ?? item.estimatedCost ?? null, billing: item.billing ?? 'api' }]))
+  let workspace = {}, poisoned = null, closed = false
+  const current = (status = 'running') => {
+    const receipts = [...started].map(([id, item]) => results.get(id) ?? {
+      ...item, id, ok: false, notStarted: true, answer: '', channel: item.channel ?? null,
+    })
+    for (const [id, result] of results) if (!started.has(id)) receipts.push(result)
+    const run = buildRun({ status, results: receipts, workspace })
+    if (status === 'running' || status === 'interrupted') {
+      run.status = status
+      if (status === 'running') run.finishedAt = null
+      for (const item of run.packages ?? []) {
+        if (!started.has(item.id) || completed.has(item.id)) continue
+        item.status = 'running'; item.inFlight = true
+        if (!results.has(item.id) || results.get(item.id)?.notStarted) item.billing = estimates.get(item.id)?.billing ?? 'api'
+        if (!results.has(item.id)) Object.assign(item, { ran: false, costUsd: null, costSource: 'pending-receipt' })
+      }
+    }
+    run.checkpoint = { at: Date.now(), completedIds: [...completed], startedIds: [...started.keys()] }
+    return run
+  }
+  const initial = current()
+  const accepted = await manager.beginExecution({ run: initial, packageEstimates, ownerToken, ...settings, confirmOverBudget })
+  if (!accepted.accepted) return accepted
+  const identity = { reservationId: accepted.reservationId, ownerToken }
+  const rejectBudget = changed => {
+    const error = new Error(changed.budget?.message || '费用或预占已变化，已暂停启动后续步骤，请重新核对预算。')
+    error.code = 'ROUTER_BUDGET_CHANGED'
+    error.budget = { ...changed.budget, paused: true, exceeded: changed.budget?.exceeded ?? 'unknown' }
+    error.runId = initial.id
+    error.reason = changed.reason
+    throw error
+  }
+  const required = async operation => {
+    if (poisoned) throw poisoned
+    try { return await operation() }
+    catch (cause) {
+      poisoned = new Error('执行检查点保存失败，已停止启动后续步骤；请核对历史记录与费用。', { cause })
+      poisoned.code = 'ROUTER_CHECKPOINT_FAILED'
+      throw poisoned
+    }
+  }
+  const save = run => required(() => manager.checkpointExecution({ ...identity, run,
+    completedIds: [...completed], startedIds: [...started.keys()] }))
+  const preserveReceiptTimes = run => {
+    for (const item of run.packages ?? []) {
+      const receipt = results.get(item.id)
+      if (receiptTimestamp(receipt?.finishedAt)) item.finishedAt = receipt.finishedAt
+    }
+    return run
+  }
+  return {
+    ...accepted,
+    id: initial.id,
+    current,
+    results: () => [...results.values()],
+    reservationFor: id => estimates.get(id),
+    activePackageId: () => [...started.keys()].findLast(id => !completed.has(id)),
+    async onCheckpointStart(item) {
+      const previous = started.get(item.id)
+      const alreadyStarted = started.has(item.id)
+      started.set(item.id, item)
+      const changed = await required(() => manager.checkpointExecution({ ...identity, run: current(),
+        completedIds: [...completed], startedIds: [...started.keys()], checkBudget: true, ...settings, confirmOverBudget }))
+      if (changed.accepted === false) {
+        if (alreadyStarted) started.set(item.id, previous)
+        else started.delete(item.id)
+        rejectBudget(changed)
+      }
+    },
+    async onCheckpointResult(result) {
+      // Mutate the executor's receipt so later aggregate/final builds use the
+      // same observed settlement time, even after another day or month starts.
+      if (!receiptTimestamp(result.finishedAt)) result.finishedAt = Date.now()
+      results.set(result.id, result); completed.add(result.id); await save(current())
+    },
+    async onWorkspace(value) { workspace = { ...workspace, ...value }; await save(current()) },
+    async partialResult(result, { checkBudget = false } = {}) {
+      // The next attempt's unknown receipt is durable dispatch evidence, not
+      // an already-observed unknown invoice. Authorize against the previous
+      // observed receipt plus its newly reserved estimate, then save both in
+      // the same locked transaction before starting that attempt.
+      const budgetRun = checkBudget ? current() : undefined
+      const hadResult = results.has(result.id), previous = results.get(result.id)
+      if (!receiptTimestamp(result.finishedAt)) result.finishedAt = Date.now()
+      results.set(result.id, result)
+      const changed = await required(() => manager.checkpointExecution({ ...identity, run: current(), budgetRun,
+        completedIds: [...completed], startedIds: [...started.keys()], checkBudget, ...settings, confirmOverBudget: false }))
+      if (changed.accepted === false) {
+        if (hadResult) results.set(result.id, previous)
+        else results.delete(result.id)
+        rejectBudget(changed)
+      }
+    },
+    async saveRun(run, { completedIds = [], startedIds = [] } = {}) {
+      const previousCompleted = new Set(completed), previousStarted = new Map(started)
+      for (const id of completedIds) completed.add(id)
+      for (const id of startedIds) if (!started.has(id)) started.set(id, { id })
+      const changed = await required(() => manager.checkpointExecution({ ...identity, run,
+        completedIds: [...completed], startedIds: [...started.keys()], checkBudget: startedIds.length > 0,
+        ...settings, confirmOverBudget: false }))
+      if (changed.accepted === false) {
+        completed.clear(); for (const id of previousCompleted) completed.add(id)
+        started.clear(); for (const [id, item] of previousStarted) started.set(id, item)
+        rejectBudget(changed)
+      }
+    },
+    async reserveExtra(id, estimatedCostUsd, { confirmOverBudget: extraConfirmation = false } = {}) {
+      return required(async () => {
+        const next = new Map(estimates); next.set(id, { estimatedCostUsd, billing: 'api' })
+        const changed = await manager.resizeExecution({ ...identity,
+          packageEstimates: [...next].filter(([key]) => !completed.has(key)).map(([key, value]) => ({ id: key, ...value })),
+          ...settings, confirmOverBudget: extraConfirmation === true })
+        if (changed.accepted) { estimates.clear(); for (const [key, value] of next) estimates.set(key, value) }
+        return changed
+      })
+    },
+    async finish(run) {
+      if (poisoned) throw poisoned
+      const value = await required(() => manager.finishExecution({ ...identity, run: preserveReceiptTimes(run) }))
+      closed = true
+      return value
+    },
+    async interrupt(run) {
+      if (closed) return
+      // Keep the reservation when storage itself remains unavailable. It is
+      // never safe to turn an unconfirmed paid receipt into free capacity.
+      try { await manager.interruptExecution({ ...identity, run: preserveReceiptTimes(run) }) } catch { /* original hold stays durable */ }
+    },
+  }
+}

package/.dsh-plugin/shared/official-team-runtime.mjs

@@ -11,7 +11,7 @@ import { tmpdir } from 'node:os'
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path'
 import { runOfficialTool, officialToolExecutionCapabilities, officialToolReadiness } from './official-tool-executor.mjs'
 import { toolForProvider } from './official-tool-registry.mjs'
-import { observeExecutionProgress, redactDiagnostic, verifiedDiagnostic } from './task-executors.mjs'
+import { awaitExecutionCheckpoint, observeExecutionProgress, redactDiagnostic, verifiedDiagnostic } from './task-executors.mjs'
 import { unsupportedCliReasoning } from './reasoning-execution.mjs'
 
 const MAX_GIT_OUTPUT = 64_000_000
@@ -313,8 +313,10 @@ function packagePrompt(task, item, completed) {
 }
 
 /** Preflight every assignment before any model request or workspace write. */
-export function executableTeamPackages(plan, installedIds = [], mode = 'read-only', executionEnvironment = 'harness') {
-  const capabilities = new Map(officialToolExecutionCapabilities({ executionEnvironment }).map(item => [item.id, item]))
+export function executableTeamPackages(plan, installedIds = [], mode = 'read-only', executionEnvironment = 'harness',
+  executionCapabilities = officialToolExecutionCapabilities({ executionEnvironment })) {
+  if (!Array.isArray(executionCapabilities)) throw new TypeError('runtime capabilities must be an array')
+  const capabilities = new Map(executionCapabilities.map(item => [item.id, item]))
   const packages = Array.isArray(plan?.team?.workPackages) ? plan.team.workPackages : []
   const blocking = []
   const assigned = packages.map(item => {
@@ -415,7 +417,7 @@ async function seedWorktree(isolated, seedFrom, signal) {
 }
 
 /** Sequential execution preserves DAG dependencies and avoids edit conflicts. */
-export async function runOfficialTeam({ plan, task, workspace, allowedRoot, mode = 'read-only', executionEnvironment = 'harness', installedIds = [], cliModels, signal, sandbox, runtime, previous = [], onlyIds = null, seedFrom = null, onPackageStart, onPackage, onStage }) {
+export async function runOfficialTeam({ plan, task, workspace, allowedRoot, mode = 'read-only', executionEnvironment = 'harness', installedIds = [], cliModels, signal, sandbox, runtime, previous = [], onlyIds = null, seedFrom = null, onPackageStart, onPackage, onStage, onCheckpointStart, onCheckpointResult, onWorkspace }) {
   await observeExecutionProgress(onStage, 'preparing')
   if (!['harness', 'cli-native'].includes(executionEnvironment)
     || (executionEnvironment === 'cli-native' && mode !== 'workspace-write')) throw new TypeError('invalid team CLI execution environment')
@@ -427,7 +429,10 @@ export async function runOfficialTeam({ plan, task, workspace, allowedRoot, mode
   if (retry && mode !== 'read-only' && !(seedFrom && typeof seedFrom.workspace === 'string' && typeof seedFrom.baseCommit === 'string')) {
     throw new TypeError('an editable team retry needs the earlier isolated worktree (seedFrom)')
   }
-  const selected = executableTeamPackages(plan, installedIds, mode, executionEnvironment)
+  // An injected adapter can declare its own capabilities as well as readiness
+  // and execution. The Host supplies no runtime override and always checks the
+  // actual platform registry before launching any official CLI.
+  const selected = executableTeamPackages(plan, installedIds, mode, executionEnvironment, runtime?.capabilities)
   const assigned = retry ? selected.assigned.filter(item => onlyIds.includes(item.id)) : selected.assigned
   const blocking = retry ? selected.blocking.filter(item => onlyIds.includes(item.id)) : selected.blocking
   if (assigned.length === 0) return { status: 'blocked', blocking: [{ reason: '计划没有工作包。' }], results: [] }
@@ -448,6 +453,11 @@ export async function runOfficialTeam({ plan, task, workspace, allowedRoot, mode
   if (signal?.aborted) return { status: 'cancelled', workspace: source, results: [] }
   const isolated = mode === 'workspace-write' ? await isolatedWorktree(source, signal, allowedRoot) : null
   const runWorkspace = isolated?.workspace ?? source
+  const completed = []
+  const partial = () => ({ status: signal?.aborted ? 'cancelled' : 'incomplete', workspace: runWorkspace,
+    results: [...completed], ...(isolated ? { baseCommit: isolated.baseCommit } : {}) })
+  await awaitExecutionCheckpoint(onWorkspace, { workspace: runWorkspace, sourceWorkspace: source,
+    isolatedWorkspace: isolated?.workspace ?? null, baseCommit: isolated?.baseCommit ?? null }, partial, 'workspace')
   let seeded = null
   if (isolated && retry) {
     try { seeded = await seedWorktree(isolated, seedFrom, signal) }
@@ -456,7 +466,6 @@ export async function runOfficialTeam({ plan, task, workspace, allowedRoot, mode
       return { status: 'blocked', blocking: [{ reason: String(error?.message ?? error) }], results: [] }
     }
   }
-  const completed = []
   const cancelledRun = () => ({ status: 'cancelled', workspace: runWorkspace, results: completed,
     ...(isolated ? { baseCommit: isolated.baseCommit } : {}), ...(seeded ? { seeded } : {}) })
   const context = retry ? (Array.isArray(previous) ? previous : []).filter(item => item?.id && typeof item.finalText === 'string') : []
@@ -466,8 +475,11 @@ export async function runOfficialTeam({ plan, task, workspace, allowedRoot, mode
     const cliModel = teamCliModel(item, configuredCliModels)
     const prompt = packagePrompt(task, item, [...context, ...completed])
     const startedAt = Date.now()
-    await observeExecutionProgress(onPackageStart, { ...item, provider: item.recommendedProvider,
-      model: item.recommendedModel, requestedCliModel: cliModel, startedAt })
+    const starting = { ...item, provider: item.recommendedProvider,
+      model: item.recommendedModel, requestedCliModel: cliModel, startedAt }
+    await observeExecutionProgress(onPackageStart, starting)
+    if (signal?.aborted) return cancelledRun()
+    await awaitExecutionCheckpoint(onCheckpointStart, starting, partial, 'start')
     if (signal?.aborted) return cancelledRun()
     let result
     try {
@@ -503,6 +515,11 @@ export async function runOfficialTeam({ plan, task, workspace, allowedRoot, mode
       actualModel: reportedModel,
       ...(result.reportedModel !== undefined ? { reportedModel: result.reportedModel } : {}),
       ...(result.usageIncomplete === true ? { usageIncomplete: true } : {}),
+      ...(result.notStarted === true || result.status === 'unsupported' ? { notStarted: true } : {}),
+      ...(result.blocked === true ? { blocked: true } : {}),
+      ...(['api', 'subscription'].includes(result.billing) ? { billing: result.billing } : {}),
+      ...(['configured-api-key', 'process-environment', 'cli-session'].includes(result.credentialSource)
+        ? { credentialSource: result.credentialSource } : {}),
       ...(typeof result.source === 'string' ? { source: result.source } : {}),
       ...(typeof result.sandboxEnforcement === 'string' ? { sandboxEnforcement: result.sandboxEnforcement } : {}),
       executionEnvironment,
@@ -518,6 +535,7 @@ export async function runOfficialTeam({ plan, task, workspace, allowedRoot, mode
       error: modelMismatch ? '官方 CLI 实际模型与指定模型不一致。'
         : (result.error || result.reason) ? executionDiagnostic(result.error || result.reason) : null,
       outputTail: result.status === 'succeeded' ? null : executionDiagnostic(verifiedDiagnostic(result)) || null })
+    await awaitExecutionCheckpoint(onCheckpointResult, completed.at(-1), partial, 'result')
     await observeExecutionProgress(onPackage, completed.at(-1))
     if (signal?.aborted) return cancelledRun()
     if (packageStatus !== 'succeeded') return { status: packageStatus === 'cancelled' ? 'cancelled' : 'incomplete', workspace: runWorkspace, results: completed,
@@ -544,7 +562,7 @@ export async function runOfficialTeam({ plan, task, workspace, allowedRoot, mode
 }
 
 /** One editable CLI task also uses the same isolated workspace and merge gate. */
-export async function runOfficialTask({ toolId, task, workspace, allowedRoot, modelId, mode = 'read-only', signal, sandbox, runtime }) {
+export async function runOfficialTask({ toolId, task, workspace, allowedRoot, modelId, mode = 'read-only', signal, sandbox, runtime, onCheckpointStart, onCheckpointResult, onWorkspace }) {
   const source = await approvedSource(workspace, allowedRoot)
   if (signal?.aborted) return { toolId, status: 'cancelled', notStarted: true, finalText: '' }
   if (typeof sandbox?.confine !== 'function') return { toolId, status: 'unsupported', reason: '官方 Harness 进程沙箱不可用。' }
@@ -555,18 +573,29 @@ export async function runOfficialTask({ toolId, task, workspace, allowedRoot, mo
     reason: readiness.reason ?? readiness.modeReasons?.[mode] ?? `官方 CLI 尚未就绪，或不支持 ${mode} 模式。` }
   if (signal?.aborted) return { toolId, status: 'cancelled', notStarted: true, finalText: '' }
   const isolated = mode === 'workspace-write' ? await isolatedWorktree(source, signal, allowedRoot) : null
+  const runWorkspace = isolated?.workspace ?? source
+  const location = isolated ? { isolatedWorkspace: isolated.workspace, baseCommit: isolated.baseCommit } : {}
   let result
+  const partial = () => ({ id: 'direct', toolId, status: signal?.aborted ? 'cancelled' : 'failed',
+    notStarted: !result, finalText: '', ...result, ...location })
+  await awaitExecutionCheckpoint(onWorkspace, { workspace: runWorkspace, sourceWorkspace: source,
+    isolatedWorkspace: isolated?.workspace ?? null, baseCommit: isolated?.baseCommit ?? null }, partial, 'workspace')
+  if (signal?.aborted) return { ...partial(), status: 'cancelled', notStarted: true }
+  await awaitExecutionCheckpoint(onCheckpointStart, { id: 'direct', toolId, model: modelId ?? null,
+    workspace: runWorkspace, startedAt: Date.now() }, partial, 'start')
+  if (signal?.aborted) return { ...partial(), status: 'cancelled', notStarted: true }
   try {
-    result = await (runtime?.runTool ?? runOfficialTool)({ toolId, task, modelId, workspace: isolated?.workspace ?? source,
+    result = await (runtime?.runTool ?? runOfficialTool)({ toolId, task, modelId, workspace: runWorkspace,
       mode, isolatedRoot: isolated?.isolatedRoot, signal, sandbox })
     if (!result || typeof result.status !== 'string') throw new TypeError('官方 CLI 执行器没有返回有效状态。')
   } catch (error) {
     result = executionException(error, signal)
   }
   result = withFailureDiagnostic(result)
-  if (signal?.aborted) return { ...result, status: 'cancelled',
-    ...(isolated ? { isolatedWorkspace: isolated.workspace, baseCommit: isolated.baseCommit } : {}) }
-  if (!isolated || result.status !== 'succeeded') return { ...result, ...(isolated ? { isolatedWorkspace: isolated.workspace, baseCommit: isolated.baseCommit } : {}) }
+  result = { ...result, ...location, ...(signal?.aborted ? { status: 'cancelled' } : {}) }
+  await awaitExecutionCheckpoint(onCheckpointResult, { ...result, id: 'direct' }, partial, 'result')
+  if (signal?.aborted) return { ...result, status: 'cancelled' }
+  if (!isolated || result.status !== 'succeeded') return result
   try {
     const integration = await integrateWorktree(source, isolated.workspace, isolated.baseCommit, signal)
     return { ...result,

package/.dsh-plugin/shared/official-tools-runtime.mjs

@@ -14,7 +14,7 @@
 import { spawn } from 'node:child_process'
 import { mkdir, mkdtemp, readFile, realpath, rename, rm, stat, writeFile } from 'node:fs/promises'
 import { homedir, tmpdir } from 'node:os'
-import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path'
+import { dirname, isAbsolute, join, posix, relative, resolve, sep, win32 } from 'node:path'
 import {
   DEFAULT_NPM_REGISTRY,
   defaultInstallMethod,
@@ -1042,7 +1042,8 @@ let prefixPromise = null
 /** Add one directory to this process's PATH unless it is already there. */
 export function appendToProcessPath(directory, { prepend = false, env = process.env, platform = process.platform } = {}) {
   const target = String(directory ?? '').trim()
-  if (!target || !isAbsolute(target)) return
+  const paths = platform === 'win32' ? win32 : posix
+  if (!target || !paths.isAbsolute(target)) return
   const separator = platform === 'win32' ? ';' : ':'
   const key = Object.keys(env).find(name => name.toUpperCase() === 'PATH') ?? 'PATH'
   const parts = String(env[key] ?? '').split(separator).filter(Boolean)