@twinsearth/dsh-master 3.2.9 → 3.3.0

package/src/cost/toolface.ts

@@ -0,0 +1,151 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+// @ts-nocheck — host JS→TS 迁移阶段：运行时行为优先，类型注解逐步补齐（worker/ 仍严格检查）。
+
+/**
+ * 3.3.0 · M2 交付物：**工具面 token 下降 + 归因**。
+ *
+ * 两件事必须分开算，因为它们属于两本不同的账：
+ *
+ *   * **A1 紧凑输出**：回执变短 ⇒ 每次交互更便宜 ⇒ **execution 节省**。
+ *     默认 `shadow` 时只能报「本可节省」，不许算成真节省。
+ *   * **A2 渐进纰漏**：常驻工具面收敛 ⇒ 每轮 schema 更少；但 `load_tools` 的装载
+ *     是**作者/选择成本** ⇒ **governance 账**（与 §5.1 一致），永不混进节省。
+ *
+ * 关闭 A2 时必须 `reductionRatio === 0`（fail-open 回全量工具面），这是可测的。
+ */
+
+const num = (value) => {
+  const n = Number(value)
+  return Number.isFinite(n) && n >= 0 ? n : 0
+}
+const tokensOf = (text) => (String(text ?? '').length > 0 ? Math.ceil(String(text).length / 4) : 0)
+
+/**
+ * 计算工具面：全量（基线）vs 可见（常驻 + 已加载）。
+ * @param {{
+ *   schemas: Array<{name: string, description?: string, parameters?: unknown}>,
+ *   enabled?: boolean,
+ *   resident?: string[],
+ *   loaded?: string[],
+ * }} input
+ */
+export function planToolFace(input = {}) {
+  const schemas = Array.isArray(input.schemas) ? input.schemas : []
+  const enabled = input.enabled === true
+  const resident = new Set(Array.isArray(input.resident) ? input.resident.map(String) : [])
+  const loaded = new Set(Array.isArray(input.loaded) ? input.loaded.map(String) : [])
+
+  const tokenOfSchema = (schema) => tokensOf(JSON.stringify({ name: schema?.name, description: schema?.description, parameters: schema?.parameters }))
+  const baselineTokens = schemas.reduce((sum, schema) => sum + tokenOfSchema(schema), 0)
+  const visible = enabled ? schemas.filter((schema) => resident.has(String(schema?.name)) || loaded.has(String(schema?.name))) : schemas
+  const residentTokens = visible.reduce((sum, schema) => sum + tokenOfSchema(schema), 0)
+  const savedTokens = Math.max(0, baselineTokens - residentTokens)
+  return Object.freeze({
+    enabled,
+    baseline: Object.freeze({ count: schemas.length, tokens: baselineTokens }),
+    resident: Object.freeze({ count: visible.length, tokens: residentTokens, names: visible.map((schema) => String(schema?.name)) }),
+    savedTokens,
+    reductionRatio: baselineTokens > 0 ? savedTokens / baselineTokens : 0,
+    /** 关闭时必须是 0（fail-open 回全量），调用方可直接断言。 */
+    perTurn: Object.freeze({ tokensBefore: baselineTokens, tokensAfter: residentTokens }),
+  })
+}
+
+/**
+ * M2 报表：工具面下降（A2） + 回执压缩（A1） + 归因分列。
+ *
+ * @param {{
+ *   schemas?: object[],
+ *   disclosure?: {enabled?: boolean, resident?: string[], loaded?: string[]},
+ *   compactions?: Array<{toolName?: string, applied?: boolean, evaluated?: boolean, estimated?: boolean, savedTokens?: number, savedChars?: number}>,
+ *   loads?: Array<{toolName?: string, tokens?: number}>,
+ *   mode?: 'off' | 'shadow' | 'enforce',
+ * }} input
+ */
+export function buildToolFaceReport(input = {}) {
+  const disclosure = input.disclosure ?? {}
+  const face = planToolFace({ schemas: input.schemas, enabled: disclosure.enabled === true, resident: disclosure.resident, loaded: disclosure.loaded })
+  const mode = input.mode === 'off' || input.mode === 'enforce' ? input.mode : 'shadow'
+
+  const byTool = {}
+  let evaluated = 0
+  let applied = 0
+  let appliedSaved = 0
+  let wouldSave = 0
+  let estimatedSaved = 0
+  for (const event of Array.isArray(input.compactions) ? input.compactions : []) {
+    if (event?.evaluated === false) continue
+    evaluated += 1
+    const saved = num(event?.savedTokens ?? (num(event?.savedChars) / 4))
+    if (event?.applied === true) {
+      applied += 1
+      appliedSaved += saved
+      if (event?.estimated === true) estimatedSaved += saved
+    } else {
+      wouldSave += saved
+    }
+    const toolName = String(event?.toolName ?? 'unknown')
+    if (!byTool[toolName]) byTool[toolName] = { evaluated: 0, applied: 0, savedTokens: 0 }
+    byTool[toolName].evaluated += 1
+    if (event?.applied === true) {
+      byTool[toolName].applied += 1
+      byTool[toolName].savedTokens += saved
+    }
+  }
+
+  // A2 的装载成本：进 governance，不进节省
+  const loadEvents = Array.isArray(input.loads) ? input.loads.length : 0
+  const governanceTokens = (Array.isArray(input.loads) ? input.loads : []).reduce((sum, event) => sum + num(event?.tokens), 0)
+
+  // A1 的节省口径：只有 enforce 且真的替换了才算执行节省
+  const a1ExecutionSaved = mode === 'enforce' ? appliedSaved : 0
+  const a1WouldSaveTokens = mode === 'enforce' ? 0 : wouldSave + appliedSaved
+  const executionSaved = a1ExecutionSaved
+  return Object.freeze({
+    ok: true,
+    mode,
+    toolFace: face,
+    a1: Object.freeze({
+      module: 'a1-compact',
+      evaluated,
+      applied,
+      /** enforce 且替换成功时才算的节省。 */
+      executionSavedTokens: a1ExecutionSaved,
+      /** shadow 下「本可节省」——不是节省，报表必须显式标出。 */
+      wouldSaveTokens: a1WouldSaveTokens,
+      estimatedSavedTokens: estimatedSaved,
+      byTool: Object.freeze(byTool),
+    }),
+    a2: Object.freeze({
+      module: 'a2-disclosure',
+      enabled: face.enabled,
+      loadEvents,
+      /** 装载成本属于作者/选择成本 ⇒ governance（永不并入节省）。 */
+      governanceTokens,
+      perTurnSavedTokens: face.savedTokens,
+    }),
+    attribution: Object.freeze({
+      /** 工具面下降算 A2 的贡献，但**只有在 enabled 时才非 0**。 */
+      'a2-disclosure': face.savedTokens,
+      'a1-compact': a1ExecutionSaved,
+      governance: governanceTokens,
+    }),
+    totals: Object.freeze({
+      executionSaved,
+      governanceTokens,
+      /** 净收益 = 执行节省（A1，enforce 才有） + 工具面下降（A2，per-turn） − 装载治理成本。 */
+      netBenefit: executionSaved + face.savedTokens - governanceTokens,
+      /** 两项分列（图省事合并会导致 §8 的重复计风险）。 */
+      byKind: Object.freeze({
+        toolFaceSavedTokens: face.savedTokens,
+        receiptSavedTokens: a1ExecutionSaved,
+      }),
+    }),
+    discipline: Object.freeze({
+      shadowNeverCountedAsSavings: mode !== 'enforce',
+      loadCostIsGovernance: true,
+      disabledDisclosureReducesNothing: face.enabled !== true || face.savedTokens >= 0,
+    }),
+  })
+}

package/src/cost/types.ts

@@ -0,0 +1,298 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+
+/**
+ * 3.3.0 成本优化系统层的共享类型（M1）。
+ *
+ * 只放类型与常量，不含运行时逻辑；host 侧 `src/cost/*` 与插件编排器共用。
+ * 对齐 `docs/DESIGN-v3.3.0-cost-optimization.md` §5（系统层）与 §9（安全不变量）。
+ */
+
+/** 两本账：执行节省 vs 治理成本（HarnessMM 论文要求分开核算）。 */
+export type CostAccount = 'execution' | 'governance'
+
+/** 归因模块 id；a* = 工具面（dsh-ops 方向），b* = 决策复用（HarnessMM 方向）。 */
+export type CostModuleId =
+  | 'a1-compact'
+  | 'a2-disclosure'
+  | 'a3-batch'
+  | 'b1-edg'
+  | 'b2-gdr'
+  | 'b3-ccs'
+  | 'b4-rsi'
+  | 'unattributed'
+
+export type CostSource = 'model' | 'tool' | 'substitution' | 'retry' | 'authoring' | 'offline'
+
+/** 事件相位（设计 §5.1）：prompt / completion / tool / authoring / substitution。 */
+export type CostPhase = 'prompt' | 'completion' | 'tool' | 'authoring' | 'substitution'
+
+export const COST_PHASES: readonly CostPhase[] = Object.freeze(['prompt', 'completion', 'tool', 'authoring', 'substitution'])
+
+/**
+ * 作用面（设计 §3.3）：宿主会话工具面与 master Worker 工具面是**两个不同面板**，
+ * 节省必须分开记账，否则会把「装了别人的宿主插件」算成自己的收益。
+ *   * `worker` —— 本项目 Worker 自带工具面（`worker/tools.ts`），A1–A3 在这里生效；
+ *   * `host`   —— 宿主会话工具面（dsh-ops 一类宿主插件生效的地方），本项目只做
+ *                 **可选适配器 + 归因**，不重写、不冒领。
+ */
+export type CostSurface = 'worker' | 'host'
+
+export interface CostTokens {
+  input: number
+  output: number
+  total: number
+}
+
+export interface CostEntryInput {
+  account: CostAccount
+  module?: CostModuleId
+  source?: CostSource
+  /** 相位；缺省由 source 推导（见 ledger.ts PHASE_OF_SOURCE）。 */
+  phase?: CostPhase
+  /** 作用面；缺省为 worker（本项目的自研模块都在这面）。 */
+  surface?: CostSurface
+  /** 外部适配器上报（如 dsh-ops 在宿主面的收益）：只展示，永不计入本项目 executionSaved。 */
+  external?: boolean
+  taskId?: string
+  forkId?: string
+  sessionId?: string
+  /** 会话内轮次与循环步号（可回放定位）。 */
+  turn?: number
+  step?: number
+  provider?: string
+  model?: string
+  toolName?: string
+  ticketId?: string
+  inputTokens?: number
+  outputTokens?: number
+  cachedTokens?: number
+  totalTokens?: number
+  /** 对照组（observe）同任务基线；给出时才计算 saved。 */
+  baselineTokens?: number
+  /** 显式节省归因；给出时优先于 baseline 推导。 */
+  savedTokens?: number
+  /** provider 未返回 usage 时的兜底估算：报表与实测分开列，不混算。 */
+  estimated?: boolean
+  meta?: Record<string, unknown>
+}
+
+export interface CostEntry extends CostTokens {
+  id: string
+  at: number
+  account: CostAccount
+  module: CostModuleId
+  source: CostSource
+  phase: CostPhase
+  surface: CostSurface
+  external: boolean
+  taskId: string | null
+  forkId: string | null
+  sessionId: string | null
+  turn: number
+  step: number
+  provider: string | null
+  model: string | null
+  toolName: string | null
+  ticketId: string | null
+  cached: number
+  baselineTokens: number | null
+  savedTokens: number
+  estimated: boolean
+  meta: Record<string, unknown>
+}
+
+export interface CostBlock {
+  input: number
+  output: number
+  total: number
+  saved: number
+  entries: number
+}
+
+export interface CostSurfaceRow extends CostBlock {
+  surface: CostSurface
+  external: boolean
+}
+
+export interface CostTaskRow extends CostBlock {
+  key: string
+}
+
+export interface CostModuleRow extends CostBlock {
+  module: CostModuleId
+}
+
+export interface CostForkRow extends CostBlock {
+  forkId: string
+}
+
+/** 估算与实测必须分开列（设计 §5.1）：总量各自累计，绝不相加。 */
+export interface CostEstimateSplit {
+  measuredTokens: number
+  measuredEntries: number
+  estimatedTokens: number
+  estimatedEntries: number
+  /** 估算值占全部 token 的比例（0..1），用于报表标注可信度。 */
+  estimatedRatio: number
+}
+
+export interface CostLedgerSnapshot {
+  ok: true
+  count: number
+  dropped: number
+  execution: CostBlock
+  governance: CostBlock
+  netSaved: number
+  ownExecutionSaved: number
+  externalSaved: number
+  /** 按作用面拆分：本项目（worker）与外部适配器（host）永不相加。 */
+  bySurface: CostSurfaceRow[]
+  byModule: CostModuleRow[]
+  byTask: CostTaskRow[]
+  byFork: CostForkRow[]
+  /** 实测 vs 估算（不混算）。 */
+  tokens: CostEstimateSplit
+  persistence: { enabled: boolean; file: string | null; appended: number; failed: number }
+}
+
+export interface CostQuery {
+  taskId?: string
+  forkId?: string
+  sessionId?: string
+  ticketId?: string
+  module?: string
+  account?: CostAccount
+  phase?: CostPhase
+  surface?: CostSurface
+  external?: boolean
+  estimated?: boolean
+  /** 时间窗（含边界）。 */
+  from?: number
+  to?: number
+  limit?: number
+}
+
+export type BudgetUnit = 'task' | 'fork' | 'day'
+export type BudgetExhaustAction = 'hard-stop' | 'degrade'
+
+export interface BudgetRule {
+  unit: BudgetUnit
+  /** token 上限（> 0）。与 limitCost 至少给一个，否则规则无效（fail-closed）。 */
+  limitTokens?: number
+  /** 成本上限（同一货币单位；需要调用方在 authorize 时给 cost 才可判定）。 */
+  limitCost?: number
+  /** 超限策略；默认 hard-stop。 */
+  onExhaust?: BudgetExhaustAction
+  /** degrade 档目标模型；必须在 degradeModels 白名单内，否则自动退化为 hard-stop。 */
+  degradeTo?: string
+}
+
+/** @deprecated 使用 BudgetRule（保留别名以兼容早期调用）。 */
+export type BudgetLimit = BudgetRule
+
+export interface BudgetStateRow {
+  unit: BudgetUnit
+  key: string
+  consumedTokens: number
+  consumedCost: number
+  limitTokens: number | null
+  limitCost: number | null
+  remainingTokens: number | null
+  remainingCost: number | null
+  onExhaust: BudgetExhaustAction
+}
+
+export type PolicyMode = 'observe' | 'shadow' | 'enforce'
+
+export interface EnforceEvidence {
+  /** shadow 期守卫准确率（0..1）。 */
+  accuracy?: number
+  /** shadow 期样本数。 */
+  samples?: number
+  /** shadow 期破坏性工具命中次数（必须为 0）。 */
+  destructiveHits?: number
+}
+
+export interface PolicyDescription {
+  mode: PolicyMode
+  requestedMode: PolicyMode
+  allowlist: string[]
+  gate: { minAccuracy: number; minSamples: number; allowlistRequired: true }
+  lastRefusal: { at: number; next: PolicyMode; reasons: string[] } | null
+}
+
+export interface AuditRecord {
+  seq: number
+  at: number
+  type: string
+  actor: string
+  payload: Record<string, unknown>
+  prevHash: string
+  hash: string
+}
+
+/**
+ * 替换证书（设计 §5.5）：每一次「用已解决决策替换慢模型回调」都必须留下这张凭证。
+ * 与 ledger 事件用同一 `taskId + step` 关联，因此可回放「这一省是怎么来的」。
+ */
+export interface SubstitutionCert {
+  /** 可执行决策图（B1）中的边标识。 */
+  edgeId: string
+  /** 被替换回调原本要调用的工具。 */
+  toolName: string
+  /** 工具 schema 的哈希：schema 变了，旧决策不得复用。 */
+  schemaHash: string
+  /** 守卫表达式（B2 判据），保留原文以便复核。 */
+  guardExpr: string
+  /** 命中时工具回执的摘要（B2 依据它判断守卫）。 */
+  receiptDigest: string
+  /** 被替换掉的模型回调标识（慢模型那一次）。 */
+  replacedCallbackId: string
+  /** 必须经 DSH 原生派发器执行：恒为 true（false 一律拒绝）。 */
+  viaNativeDispatcher: true
+  /** 关联键（与 ledger 事件一致）。 */
+  taskId: string
+  step: number
+  /** 本次替换的归因节省（token）。 */
+  savedTokens?: number
+  moduleId?: string
+  forkId?: string
+  sessionId?: string
+  ticketId?: string
+  at?: number
+}
+
+export const COST_MODULES: readonly CostModuleId[] = Object.freeze([
+  'a1-compact',
+  'a2-disclosure',
+  'a3-batch',
+  'b1-edg',
+  'b2-gdr',
+  'b3-ccs',
+  'b4-rsi',
+  'unattributed',
+])
+
+export const COST_SOURCES: readonly CostSource[] = Object.freeze([
+  'model',
+  'tool',
+  'substitution',
+  'retry',
+  'authoring',
+  'offline',
+])
+
+export const POLICY_MODES: readonly PolicyMode[] = Object.freeze(['observe', 'shadow', 'enforce'])
+
+/** 两个作用面（设计 §3.3）：不可合并统计。 */
+export const COST_SURFACES: readonly CostSurface[] = Object.freeze(['worker', 'host'])
+
+/** 默认预算：与 Worker 现有 maxTokens 对齐（task=50k），fork=500k。 */
+export const DEFAULT_BUDGET_LIMITS: readonly BudgetLimit[] = Object.freeze([
+  Object.freeze({ unit: 'task' as BudgetUnit, limitTokens: 50_000, onExhaust: 'hard-stop' as BudgetExhaustAction }),
+  Object.freeze({ unit: 'fork' as BudgetUnit, limitTokens: 500_000, onExhaust: 'hard-stop' as BudgetExhaustAction }),
+])
+
+/** enforce 门禁（设计 §13）：准确率 ≥0.98、样本 ≥20、零破坏性命中、非空白名单。 */
+export const ENFORCE_GATE = Object.freeze({ minAccuracy: 0.98, minSamples: 20 })

package/src/kernel.ts

@@ -10,7 +10,7 @@
 
 import crypto from 'node:crypto'
 
-export const MASTER_VERSION = '3.2.9'
+export const MASTER_VERSION = '3.3.0'
 export const FANG_CONTRACT_MIN = '3.1.14'
 
 export const SERVICE = Object.freeze({
@@ -21,6 +21,31 @@ export const SERVICE = Object.freeze({
   dual: 'dshMasterDual',
 })
 
+/**
+ * 3.3.0 §11：成本系统的**可选子服务**。
+ *
+ * 主服务 `SERVICE.cost` 的形态不变（向后兼容）；子服务由 cost-optimizer 在能力允许时
+ * 额外 `provide`，消费方必须用 `probeOptionalServices(ctx)` **探测**而不是假定存在 ——
+ * 缺了就是缺了，不能假装拿到空壳对象。
+ */
+export const OPTIONAL_SERVICE = Object.freeze({
+  costLedger: 'dshMasterCostLedger',
+  costBudget: 'dshMasterCostBudget',
+  costPolicy: 'dshMasterCostPolicy',
+  costAudit: 'dshMasterCostAudit',
+})
+
+/** 探测可选子服务是否就位（只读、无副作用）。 */
+export function probeOptionalServices(ctx) {
+  const present = {}
+  for (const [key, name] of Object.entries(OPTIONAL_SERVICE)) {
+    try {
+      present[key] = typeof ctx?.get === 'function' ? Boolean(ctx.get(name)) : false
+    } catch { present[key] = false }
+  }
+  return present
+}
+
 export const FANG_SERVICE = Object.freeze({
   orchestrator: 'fang',
   forker: 'fangForker',
@@ -41,16 +66,17 @@ export const ROW = Object.freeze({
 export const ROLE = Object.freeze({ mother: 'mother', essence: 'essence', fork: 'fork' })
 
 /**
- * 角色矩阵（v3.2.3）：
- *   * Router 常驻原身（essence）：只评估/建票/派发，不执行代码；母体不接纳。
- *   * Worker 是研究原型，只在 fork：编译后的 Worker preset 行 master-superagent-loop 也只 fork。
- *   * 成本优化 fork；双主管 mother/essence。
+ * 角色矩阵：
+ *   * Router 在 essence 与 mother 激活：只评估/建票/派发，不执行代码；fork 不注册。
+ *   * Worker / Worker Agent Loop 在 fork 与 essence 激活：原身可直接执行工单，
+ *     分身仍是默认执行体；mother 不执行。
+ *   * 成本优化仍只 fork；双主管 mother/essence。
  */
 export const ROLE_MATRIX = Object.freeze({
   'master-core': Object.freeze(Object.values(ROLE)),
-  'master-superagent-router': Object.freeze([ROLE.essence]),
-  'master-superagent-worker': Object.freeze([ROLE.fork]),
-  'master-superagent-loop': Object.freeze([ROLE.fork]),
+  'master-superagent-router': Object.freeze([ROLE.essence, ROLE.mother]),
+  'master-superagent-worker': Object.freeze([ROLE.fork, ROLE.essence]),
+  'master-superagent-loop': Object.freeze([ROLE.fork, ROLE.essence]),
   'master-cost-optimizer': Object.freeze([ROLE.fork]),
   'master-dual-manager': Object.freeze([ROLE.mother, ROLE.essence]),
 })
@@ -59,17 +85,17 @@ export const SUBPLUGIN_CATALOG = Object.freeze([
   Object.freeze({
     id: 'superagent-router', row: ROW.superagentRouter, name: '超级智能体 Router', nameEn: 'SuperAgent Router',
     roles: ROLE_MATRIX[ROW.superagentRouter], roadmap: '3.2.1',
-    description: '常驻原身：Webhook → 评估 → Ticket/Mandate → 派发；不执行代码改动。',
+    description: '常驻原身/母体：Webhook → 评估 → Ticket/Mandate → 派发；不执行代码改动。',
   }),
   Object.freeze({
     id: 'superagent-worker', row: ROW.superagentWorker, name: '超级智能体 Worker', nameEn: 'SuperAgent Worker',
     roles: ROLE_MATRIX[ROW.superagentWorker], roadmap: '3.2.1',
-    description: '每个工单一个隔离分身：在 Mandate 作用域内执行；研究原型，仅 fork。',
+    description: '每个工单一个隔离执行体：在 Mandate 作用域内执行；fork 与 essence 可用。',
   }),
   Object.freeze({
     id: 'superagent-loop', row: ROW.superagentLoop, name: 'Worker Agent Loop', nameEn: 'SuperAgent Worker Loop',
     roles: ROLE_MATRIX[ROW.superagentLoop], roadmap: '3.2.3',
-    description: '编译后的 Worker preset：有 Ticket 的 fork 自动跑多轮工具循环并流式回传。',
+    description: '编译后的 Worker preset：有 Ticket 的在 fork/essence 自动跑多轮工具循环并流式回传。',
   }),
   Object.freeze({
     id: 'cost-optimizer', row: ROW.cost, name: '成本优化', nameEn: 'HarnessMM',