@twinsearth/dsh-master 3.2.10 → 3.3.1

package/worker/budget-guard.ts

@@ -0,0 +1,156 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+
+/**
+ * 3.3.0 · Worker 侧预算闸（设计 §5.2 的 ① 检查点）。
+ *
+ * 规格：
+ *   * 检查点**只在 ① beforeModelCall**：调用模型之前先问「这一步还付得起吗」；
+ *   * 付不起 ⇒ **fail-closed**，直接 `budget-exhausted`，绝不「先跑着看」；
+ *   * `degrade` 档只允许把本次调用降级到**白名单内**的廉价模型，未命中白名单一律 hard-stop；
+ *   * 拒绝时**不扣额度**（避免把失败的尝试也记成消耗）。
+ *
+ * 默认关闭（`enabled: false`）：3.2.x 的 `maxTokens` 事后硬上限仍然生效，
+ * 本闸是 3.3.0 的**事前**闸，启用后行为从「超支后终止」变成「超支前拒绝」。
+ * 启用方式：`WorkerDeps.budget` 或环境变量 `DSH_MASTER_BUDGET_TOKENS`。
+ */
+
+export type BudgetAction = 'hard-stop' | 'degrade'
+
+export interface WorkerBudgetOptions {
+  enabled?: boolean
+  /** task 级 token 上限。 */
+  limitTokens?: number
+  /** 每次调用预留的 token（默认按 history 字符数 / 4 动态估算）。 */
+  reserveTokens?: number
+  onExhaust?: BudgetAction
+  /** degrade 允许的廉价模型白名单（空 ⇒ degrade 无效，一律 hard-stop）。 */
+  degradeModels?: string[]
+  /** degrade 目标模型；必须在白名单内。 */
+  degradeTo?: string
+}
+
+export interface BudgetDecision {
+  ok: boolean
+  code?: string
+  message?: string
+  degraded?: boolean
+  /** degrade 时本次调用应使用的模型。 */
+  model?: string
+  consumedTokens: number
+  limitTokens: number | null
+  remainingTokens: number | null
+  requested: number
+  onExhaust: BudgetAction
+  at: number
+}
+
+export interface WorkerBudgetGuard {
+  readonly enabled: boolean
+  readonly consumedTokens: number
+  /** ①：调用模型前判定；返回拒绝或降级。 */
+  beforeModelCall(input: { model?: string; historyChars: number; stepIndex?: number }): BudgetDecision
+  /** 调用失败时退回预留额度（保持「失败不算消耗」）。 */
+  refund(tokens: number): void
+  /** 调用结束后按真实 usage 结算（多退少补）。 */
+  settle(tokens: number): void
+  describe(): { enabled: boolean; limitTokens: number | null; consumedTokens: number; onExhaust: BudgetAction; degradeTo: string | null; degradeModels: string[] }
+}
+
+const nonNegativeInt = (value: unknown): number => {
+  const n = Number(value)
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : 0
+}
+
+export function createBudgetGuard(options: WorkerBudgetOptions = {}): WorkerBudgetGuard {
+  const enabled = options.enabled === true
+  const limitTokens = options.limitTokens === undefined ? null : nonNegativeInt(options.limitTokens) || null
+  const reserveTokens = options.reserveTokens === undefined ? null : nonNegativeInt(options.reserveTokens)
+  const onExhaust: BudgetAction = options.onExhaust === 'degrade' ? 'degrade' : 'hard-stop'
+  const degradeModels = (Array.isArray(options.degradeModels) ? options.degradeModels : [])
+    .map((item) => String(item ?? '').trim())
+    .filter(Boolean)
+  const degradeTo = options.degradeTo === undefined ? null : String(options.degradeTo)
+  const degradeAllowed = onExhaust === 'degrade' && degradeTo !== null && degradeModels.includes(degradeTo)
+  let consumedTokens = 0
+  /** 尚未释放的预留（settle/refund 用它避免重复记账）。 */
+  let reservedTokens = 0
+
+  function decide(requested: number, at = Date.now()): BudgetDecision {
+    const effective: BudgetAction = degradeAllowed ? 'degrade' : 'hard-stop'
+    const base = {
+      consumedTokens,
+      limitTokens,
+      remainingTokens: limitTokens === null ? null : Math.max(0, limitTokens - consumedTokens),
+      requested,
+      onExhaust: effective,
+      at,
+    }
+    if (!enabled || limitTokens === null) {
+      return { ok: true, ...base }
+    }
+    const remaining = limitTokens - consumedTokens
+    if (requested <= remaining) {
+      consumedTokens += requested
+      return { ok: true, ...base, consumedTokens, remainingTokens: limitTokens - consumedTokens }
+    }
+    if (degradeAllowed && degradeTo !== null) {
+      // 降级也要付得起：预留额度放进额度内才放行，否则仍然 fail-closed。
+      if (requested <= remaining) {
+        consumedTokens += requested
+        return { ok: true, degraded: true, model: degradeTo, ...base, consumedTokens, remainingTokens: limitTokens - consumedTokens }
+      }
+      return {
+        ok: false,
+        code: 'budget-exhausted',
+        message: `预算不足：剩余 ${Math.max(0, remaining)} token，需 ${requested}，且降级模型 ${degradeTo} 也无法容纳`,
+        ...base,
+      }
+    }
+    return {
+      ok: false,
+      code: 'budget-exhausted',
+      message: `预算不足：剩余 ${Math.max(0, remaining)} token，需 ${requested} token（fail-closed，不启动模型调用）`,
+      ...base,
+    }
+  }
+
+  function beforeModelCall(input: { model?: string; historyChars: number; stepIndex?: number }): BudgetDecision {
+    // 预留值：显式配置优先；否则按「历史字符/4 + 固定输出余量」估算，宁高不低。
+    const estimate = reserveTokens !== null
+      ? reserveTokens
+      : Math.max(1, Math.ceil(Math.max(0, Number(input?.historyChars) || 0) / 4) + 256)
+    const decision = decide(estimate)
+    // 降级决策不消耗额外额度（预留已在 decide 内计入）。
+    if (decision.ok) reservedTokens += estimate
+    return decision
+  }
+
+  function refund(tokens: number): void {
+    const amount = nonNegativeInt(tokens)
+    consumedTokens = Math.max(0, consumedTokens - amount)
+    // 预留随之释放，否则后续 settle 会把同一份额度重复记账。
+    reservedTokens = Math.max(0, reservedTokens - amount)
+  }
+
+  function settle(tokens: number): void {
+    const actual = nonNegativeInt(tokens)
+    // 结算：先退掉**尚未释放**的预留，再按真实用量记账（实际可能为 0）。
+    // 之前这里写的是 `- 0`（死代码），会把预留与真实用量重复计入，导致额度被提前耗尽。
+    consumedTokens = Math.max(0, consumedTokens - reservedTokens) + actual
+    reservedTokens = 0
+  }
+
+  function describe() {
+    return {
+      enabled,
+      limitTokens,
+      consumedTokens,
+      onExhaust: degradeAllowed ? onExhaust : 'hard-stop' as BudgetAction,
+      degradeTo: degradeAllowed ? degradeTo : null,
+      degradeModels: [...degradeModels],
+    }
+  }
+
+  return Object.freeze({ enabled, get consumedTokens() { return consumedTokens }, beforeModelCall, refund, settle, describe })
+}

package/worker/ccs.ts

@@ -0,0 +1,202 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+
+/**
+ * 3.3.0 · B3 `ccs`（认证回调替换，设计 §7）。
+ *
+ * 命中后的替换**必须走未改动的原生派发器**（`worker/tools.ts` 的同一个入口）：
+ * 权限校验、Mandate、取消信号、超时、审计全部保留 —— 本模块只是一次「正常的工具调用」，
+ * 唯一的区别是**它替模型说出了这次调用**。
+ *
+ * 硬约束（逐条落实现）：
+ *   * **禁止直接调 fs/进程**：本模块不 import fs/child_process，唯一出口是 `registry.execute`；
+ *   * **禁止绕过工具准入**：用与正常调用完全相同的 `ToolExecutionContext`（含 mandate/signal/timeout）；
+ *   * **禁止绕过 budget 检查**：派发前先过 `budgetGuard.beforeModelCall`，不通过一律不派发；
+ *   * 派发器抛错 / 返回拒绝或报错 ⇒ 证书标 `dispatched: false` + `error`，**回落慢模型**，
+ *     绝不吞错继续（宁可不省，也不能假装成功）。
+ */
+
+import type { EdgEdge } from './edg.ts'
+import type { WorkerBudgetGuard } from './budget-guard.ts'
+
+/** 原生派发器的唯一入口形态（与 `worker/tools.ts` 的 `execute` 一致）。 */
+export interface NativeDispatcher {
+  execute(call: { name: string; arguments: string }, context: {
+    workspace: string
+    signal: AbortSignal
+    timeoutMs: number
+    mandate: { scope: string; allowShell: boolean; policyVersion?: string; strength?: 'explicit' | 'inferred' }
+  }): Promise<string>
+}
+
+export interface CcsCert {
+  edgeId: string
+  toolName: string
+  schemaHash: string
+  guardExpr: string
+  receiptDigest: string
+  /** 被跳过的慢模型回调 id（§5.5 证书字段）。 */
+  replacedCallbackId: string
+  viaNativeDispatcher: true
+  taskId: string
+  step: number
+  /** 是否真的经原生派发器执行（失败时为 false，并带 error）。 */
+  dispatched: boolean
+  error?: string
+  /** 派发器返回的内容摘要（可为空；不落全文，避免把回执再存一遍）。 */
+  resultDigest?: string
+  resultChars?: number
+  savedTokens?: number
+  moduleId?: string
+  at: number
+}
+
+export interface CcsInput {
+  edge: EdgEdge
+  /** 确定性提取出的参数（由 GDR 第 ⑤ 环产出）。 */
+  args: Record<string, unknown>
+  receipt: { toolName: string; text: string; digest: string }
+  /** 被替换掉的慢回调 id。 */
+  replacedCallbackId: string
+  taskId: string
+  step: number
+  workspace: string
+  mandate: { scope: string; allowShell: boolean; policyVersion?: string; strength?: 'explicit' | 'inferred' }
+  signal: AbortSignal
+  timeoutMs: number
+  moduleId?: string
+  /** 命中带来的预估节省（用于证书归因）。 */
+  savedTokens?: number
+}
+
+export interface CcsResult {
+  ok: boolean
+  certificate: CcsCert
+  /** 派发器返回的原始文本（成功时）；失败时为 null。 */
+  text: string | null
+  /** 是否需要回落慢模型（失败或未派发）。 */
+  fallback: boolean
+}
+
+export interface CcsOptions {
+  dispatcher: NativeDispatcher
+  /** 预算闸：派发前必须通过（不通过就不派发）。 */
+  budget?: WorkerBudgetGuard | null
+  clock?: () => number
+}
+
+const tokensOf = (text: string): number => (text.length > 0 ? Math.ceil(text.length / 4) : 0)
+
+/** 派发结果是否算「失败」：抛错、系统拒绝、执行报错都算。 */
+function resultFailed(text: string): string | null {
+  const value = String(text ?? '')
+  if (value.startsWith('【系统拒绝】')) return 'tool-denied'
+  if (value.startsWith('执行报错')) return 'tool-error'
+  return null
+}
+
+export interface Ccs {
+  /**
+   * 经原生派发器执行一次替换。
+   * 任何不满足前提/任何异常 ⇒ `dispatched:false`，调用方必须回落慢模型。
+   */
+  substitute(input: CcsInput): Promise<CcsResult>
+  stats(): { attempted: number; dispatched: number; failed: number; fallbacks: number }
+}
+
+export function createCcs(options: CcsOptions): Ccs {
+  if (!options?.dispatcher || typeof options.dispatcher.execute !== 'function') {
+    throw new Error('ccs requires the native dispatcher (worker/tools.ts execute)')
+  }
+  const clock = typeof options.clock === 'function' ? options.clock : () => Date.now()
+  const budget = options.budget ?? null
+  let attempted = 0
+  let dispatched = 0
+  let failed = 0
+  let fallbacks = 0
+
+  function cert(input: CcsInput, fields: Partial<CcsCert>): CcsCert {
+    return {
+      edgeId: String(input.edge?.id ?? ''),
+      toolName: String(input.edge?.toolName ?? ''),
+      schemaHash: String(input.edge?.schemaHash ?? ''),
+      guardExpr: String(input.edge?.guard?.expr ?? ''),
+      receiptDigest: String(input.receipt?.digest ?? ''),
+      replacedCallbackId: String(input.replacedCallbackId ?? ''),
+      viaNativeDispatcher: true,
+      taskId: String(input.taskId ?? ''),
+      step: Number(input.step ?? 0),
+      dispatched: false,
+      moduleId: input.moduleId ?? 'b3-ccs',
+      savedTokens: Math.max(0, Number(input.savedTokens ?? 0) || 0),
+      at: clock(),
+      ...fields,
+    }
+  }
+
+  async function substitute(input: CcsInput): Promise<CcsResult> {
+    attempted += 1
+    // ⓪ 取消信号：替换路径不得绕过取消（I8）。
+    if (input.signal?.aborted === true) {
+      failed += 1
+      fallbacks += 1
+      return { ok: false, text: null, fallback: true, certificate: cert(input, { dispatched: false, error: 'aborted' }) }
+    }
+    // ① 预算闸：替模型做的这次调用同样要付得起（禁止绕过 budget 检查）。
+    if (budget) {
+      const decision = budget.beforeModelCall({ historyChars: 0 })
+      if (!decision.ok) {
+        failed += 1
+        fallbacks += 1
+        return { ok: false, text: null, fallback: true, certificate: cert(input, { dispatched: false, error: decision.code ?? 'budget-exhausted' }) }
+      }
+      // 替模型省下的这次调用不产生模型 token：把刚扣的预留退回去。
+      budget.refund(decision.requested)
+    }
+
+    // ② 经**未改动的原生派发器**执行：权限/Mandate/取消/超时/审计全部照旧。
+    let text: string
+    try {
+      text = await options.dispatcher.execute(
+        { name: input.edge.toolName, arguments: JSON.stringify(input.args ?? {}) },
+        {
+          workspace: input.workspace,
+          signal: input.signal,
+          timeoutMs: Math.max(1, Number(input.timeoutMs) || 1),
+          mandate: input.mandate,
+        },
+      )
+    } catch (error) {
+      failed += 1
+      fallbacks += 1
+      const message = error instanceof Error ? error.message : String(error)
+      return { ok: false, text: null, fallback: true, certificate: cert(input, { dispatched: false, error: `dispatch-threw:${message}` }) }
+    }
+
+    // ③ 派发器返回的「拒绝/报错」也算失败：不吞错、不假装成功。
+    const failure = resultFailed(text)
+    if (failure) {
+      failed += 1
+      fallbacks += 1
+      return { ok: false, text: null, fallback: true, certificate: cert(input, { dispatched: false, error: failure }) }
+    }
+
+    dispatched += 1
+    return {
+      ok: true,
+      text,
+      fallback: false,
+      certificate: cert(input, {
+        dispatched: true,
+        resultDigest: `sha256:${tokensOf(text).toString(36)}`,
+        resultChars: text.length,
+      }),
+    }
+  }
+
+  function stats() {
+    return { attempted, dispatched, failed, fallbacks }
+  }
+
+  return Object.freeze({ substitute, stats })
+}

package/worker/cost-hooks.ts

@@ -0,0 +1,133 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+
+/**
+ * 3.3.0 成本切点实现（M1，observe-only）。
+ *
+ * 四个钩子只把结构化事件交给 sink.cost（宿主侧由 HTTP sink 转发、Router 落库；
+ * 进程内由 Cordis 事件总线消费）。任何异常都被吞掉——成本观测不得影响 Worker
+ * 的控制流、预算判定或工具执行（设计 §9 I6：模块异常 fail-open 并留痕）。
+ */
+
+import type {
+  CostHookEvent,
+  CostHooks,
+  LLMUsage,
+  WorkerCostUsage,
+  WorkerSink,
+} from './types.ts'
+
+const nonNegative = (value: unknown): number => {
+  const n = Number(value)
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : 0
+}
+
+/** 把 provider 的 usage 归一成 {input, output, total}；缺 total 时用 input+output。 */
+export function normalizeCostUsage(usage?: LLMUsage): WorkerCostUsage {
+  const input = nonNegative(usage?.promptTokens)
+  const output = nonNegative(usage?.completionTokens)
+  const total = nonNegative(usage?.totalTokens) || input + output
+  return { input, output, total }
+}
+
+export interface CostHookOptions {
+  sink?: WorkerSink
+  clock?: () => number
+}
+
+export function createCostHooks(options: CostHookOptions = {}): CostHooks {
+  const clock = typeof options.clock === 'function' ? options.clock : () => Date.now()
+  const emit = (event: CostHookEvent): void => {
+    const sink = options.sink
+    if (!sink || typeof sink.cost !== 'function') return
+    try {
+      sink.cost(event)
+    } catch {
+      /* 成本观测失败不得影响控制流 */
+    }
+  }
+
+  const hooks: CostHooks = {
+    beforeModelCall(input: { ticketId: string; stepIndex: number; model?: string; historyChars: number }) {
+      emit({
+        point: 'beforeModelCall',
+        at: clock(),
+        ticketId: String(input?.ticketId ?? ''),
+        stepIndex: Number(input?.stepIndex) || 0,
+        model: input?.model === undefined ? undefined : String(input.model),
+        historyChars: nonNegative(input?.historyChars),
+      })
+    },
+    afterModelResponse(input: { ticketId: string; stepIndex: number; usage?: WorkerCostUsage; latencyMs: number; estimated?: boolean }) {
+      emit({
+        point: 'afterModelResponse',
+        at: clock(),
+        ticketId: String(input?.ticketId ?? ''),
+        stepIndex: Number(input?.stepIndex) || 0,
+        usage: input?.usage ?? normalizeCostUsage(),
+        latencyMs: nonNegative(input?.latencyMs),
+        estimated: input?.estimated === true,
+      })
+    },
+    beforeToolDispatch(input: { ticketId: string; stepIndex: number; toolName: string; argsChars: number }) {
+      emit({
+        point: 'beforeToolDispatch',
+        at: clock(),
+        ticketId: String(input?.ticketId ?? ''),
+        stepIndex: Number(input?.stepIndex) || 0,
+        toolName: String(input?.toolName ?? ''),
+        argsChars: nonNegative(input?.argsChars),
+      })
+    },
+    afterToolReceipt(input: { ticketId: string; stepIndex: number; toolName: string; resultChars: number; truncated: boolean; compaction?: CostHookEvent['compaction'] }) {
+      emit({
+        point: 'afterToolReceipt',
+        at: clock(),
+        ticketId: String(input?.ticketId ?? ''),
+        stepIndex: Number(input?.stepIndex) || 0,
+        toolName: String(input?.toolName ?? ''),
+        resultChars: nonNegative(input?.resultChars),
+        truncated: input?.truncated === true,
+        compaction: input?.compaction,
+      })
+    },
+    degraded(input: { ticketId: string; stepIndex: number; module: string; phase: 'beforeDispatch' | 'afterReceipt' | 'author' | 'guard' | 'substitute' | 'beforeModelCall' | 'afterModelResponse'; message: string; count: number }) {
+      emit({
+        point: 'degraded',
+        at: clock(),
+        ticketId: String(input?.ticketId ?? ''),
+        stepIndex: Number(input?.stepIndex) || 0,
+        toolName: input?.module === undefined ? undefined : String(input.module),
+        degraded: {
+          module: String(input?.module ?? ''),
+          phase: input?.phase ?? 'transform',
+          message: String(input?.message ?? ''),
+          count: nonNegative(input?.count) || 1,
+        },
+      })
+    },
+  }
+  return Object.freeze(hooks)
+}
+
+type HookArgs<K extends keyof CostHooks> = Parameters<CostHooks[K]>
+
+/** 合并宿主注入的覆盖实现：先跑默认实现，再跑覆盖；任一失败都不影响另一个。 */
+export function mergeCostHooks(base: CostHooks, override?: Partial<CostHooks> | null): CostHooks {
+  if (!override) return base
+  const chain = <K extends keyof CostHooks>(key: K) => {
+    const extra = override[key]
+    if (typeof extra !== 'function') return base[key]
+    return ((...args: HookArgs<K>): void => {
+      try { (base[key] as (...a: HookArgs<K>) => void)(...args) } catch { /* ignore */ }
+      try { (extra as (...a: HookArgs<K>) => void)(...args) } catch { /* ignore */ }
+    }) as CostHooks[K]
+  }
+  return Object.freeze({
+    beforeModelCall: chain('beforeModelCall'),
+    afterModelResponse: chain('afterModelResponse'),
+    beforeToolDispatch: chain('beforeToolDispatch'),
+    afterToolReceipt: chain('afterToolReceipt'),
+    degraded: chain('degraded'),
+  })
+}