@twinsearth/dsh-master 3.2.10 → 3.3.0

package/src/plugins/cost-optimizer.ts

@@ -3,15 +3,22 @@
 // @ts-nocheck — host JS→TS 迁移阶段：运行时行为优先，类型注解逐步补齐（worker/ 仍严格检查）。
 
 /**
- * 子插件 2：成本优化（HarnessMM 观察层）—— 为分身装“燃油表”。
+ * 子插件 2：成本优化（3.3.0 M1：系统层接入，observe-only）。
  *
- * 3.2.0 先交付可观测/可估算的骨架，不做推理拦截：
- *   * `observe` 模式只统计/估算，不改写任何模型调用；
- *   * HarnessMM 的 EGD/GDR/CCS 真实接入在 3.3.0 里程碑（见 docs/ROADMAP.md）；
- *   * 角色：只允许 fork（分身生产盘），母体/元主不加载。
+ * 本行在 3.2.x 的 observe 骨架上扩展，**保持** `estimate/record/summary/reset/status`
+ * 兼容面，内部改为委托 3.3.0 系统层（`src/cost`）：
+ *   * ledger：两本账（execution / governance）+ 归因；
+ *   * budget：task/fork 预算闸（fail-closed，附 remaining）；
+ *   * policy：observe → shadow → enforce 三档与 enforce 门禁；
+ *   * audit：治理事件哈希链。
+ *
+ * M1 只记账：不拦截模型调用、不改写工具输出、不替换推理回调；
+ * 工具面（A1–A3）与决策复用（B1–B4）在 M2/M3/M4 接入。
+ * 角色：仍只允许 fork（分身生产盘）。
  */
 
 import {
+  OPTIONAL_SERVICE,
   ROW,
   ROLE,
   SERVICE,
@@ -21,12 +28,13 @@ import {
   roleAllowed,
   safeGet,
 } from '../kernel.ts'
+import { createCostSystem, DEFAULT_BUDGET_LIMITS } from '../cost/index.ts'
 
 export const name = 'dsh-master-cost-optimizer'
 export const inject = ['dshMaster']
 export const ROW_ID = ROW.cost
 
-/** HarnessMM 官方基准（3.2.0 文档引用；3.3.0 接入后应被实测值覆盖）。 */
+/** HarnessMM 官方基准（3.2.0 文档引用；3.3.0 的实测值应覆盖它，而不是替代对标）。 */
 export const HARNESSMM_BENCHMARK = Object.freeze({
   baselineTokens: 96280,
   optimizedTokens: 11620,
@@ -41,7 +49,11 @@ function finiteNonNegative(value) {
 
 /**
  * @param {object} ctx
- * @param {{enabled?:boolean, mode?:string, targetSavingsRatio?:number}} [config]
+ * @param {{
+ *   enabled?: boolean, mode?: string, targetSavingsRatio?: number,
+ *   budget?: Array<{unit: string, limitTokens: number, onExhaust?: string}>,
+ *   enforceAllowlist?: string[],
+ * }} [config]
  */
 export function apply(ctx, config = {}) {
   if (!enabledOf(config)) return { skipped: true, reason: 'disabled-by-config' }
@@ -58,11 +70,20 @@ export function apply(ctx, config = {}) {
   }
 
   const targetSavingsRatio = finiteNonNegative(config.targetSavingsRatio)
-  const policy = Object.freeze({
-    mode: 'observe', // 3.2.0 只允许 observe；replay 在 3.3.0 打开
-    requestedMode: String(config.mode ?? 'observe'),
-    targetSavingsRatio: targetSavingsRatio !== null && targetSavingsRatio <= 1 ? targetSavingsRatio : 0.8,
+  const system = createCostSystem({
+    mode: config.mode,
+    allowlist: config.enforceAllowlist ?? config.allowlist,
+    policyScopes: config.scopes,
+    budgetLimits: Array.isArray(config.budget) && config.budget.length > 0 ? config.budget : DEFAULT_BUDGET_LIMITS,
+    degradeModels: config.degradeModels,
+    // 宿主会话工具面适配器：默认关闭；开启也只做外部收益登记，不重写任何宿主插件。
+    hostSurface: config.hostSurface && typeof config.hostSurface === 'object'
+      ? { enabled: config.hostSurface.enabled === true, source: config.hostSurface.source }
+      : undefined,
   })
+  const policy = system.policy.describe()
+
+  // 3.2.x 兼容计数器（任务级实测汇总；系统层另有账本，两者口径不同、互不覆盖）。
   const metrics = {
     tasks: 0,
     baselineTokens: 0,
@@ -74,19 +95,22 @@ export function apply(ctx, config = {}) {
 
   const service = {
     id: SERVICE.cost,
-    version: '3.2.5',
+    version: '3.3.0',
     role,
-    mode: policy.mode,
-    /** 基于 HarnessMM 基准 + 目标比例做派生前预估。 */
+    get mode() {
+      return system.policy.describe().mode
+    },
+    /** 基于 HarnessMM 基准 + 目标比例做派生前预估（不承诺节省）。 */
     estimate({ baselineTokens } = {}) {
       const baseline = finiteNonNegative(baselineTokens)
       if (baseline === null) return masterError('baseline-tokens-invalid', 'baselineTokens must be a non-negative number')
-      const projectedOptimized = Math.round(baseline * (1 - policy.targetSavingsRatio))
+      const current = system.policy.describe()
+      const projectedOptimized = Math.round(baseline * (1 - (targetSavingsRatio !== null && targetSavingsRatio <= 1 ? targetSavingsRatio : 0.8)))
       return {
         ok: true,
-        mode: policy.mode,
+        mode: current.mode,
         baselineTokens: baseline,
-        targetSavingsRatio: policy.targetSavingsRatio,
+        targetSavingsRatio: targetSavingsRatio !== null && targetSavingsRatio <= 1 ? targetSavingsRatio : 0.8,
         projectedOptimizedTokens: projectedOptimized,
         projectedSavingsTokens: baseline - projectedOptimized,
         basis: {
@@ -97,8 +121,8 @@ export function apply(ctx, config = {}) {
         },
       }
     },
-    /** 归档后记录实测；3.3.0 起由 HarnessMM 的 EGD/GDR/CCS 自动上报。 */
-    record({ taskId, baselineTokens, optimizedTokens, success } = {}) {
+    /** 归档后记录实测；3.3.0 起同时写系统层 execution 账本（baseline 给定时才算 saved）。 */
+    record({ taskId, baselineTokens, optimizedTokens, success, estimated = false, estimatedTokens = 0, forkId, sessionId } = {}) {
       const baseline = finiteNonNegative(baselineTokens)
       const optimized = finiteNonNegative(optimizedTokens)
       if (baseline === null) return masterError('baseline-tokens-invalid', 'baselineTokens must be a non-negative number')
@@ -112,13 +136,125 @@ export function apply(ctx, config = {}) {
         metrics.observedTotal += 1
         if (success) metrics.observedSuccess += 1
       }
+      const meta = { success: success === undefined ? null : Boolean(success) }
+      // §5.1：估算与实测分列，绝不混算。两部分各自入账（baseline 按比例拆分，保证 sum 一致）。
+      const estimatedPart = Math.min(optimized, Math.max(0, Number(estimatedTokens) || 0))
+      const measuredPart = optimized - estimatedPart
+      const entries = []
+      if (measuredPart > 0 || estimatedPart === 0) {
+        const measuredBaseline = estimatedPart === 0 ? baseline : Math.round(baseline * (measuredPart / optimized))
+        const measured = system.recordUsage({
+          account: 'execution',
+          module: 'unattributed',
+          source: 'model',
+          phase: 'completion',
+          taskId: taskId === undefined ? null : String(taskId),
+          forkId,
+          sessionId,
+          totalTokens: measuredPart,
+          baselineTokens: measuredBaseline,
+          estimated: estimated === true && estimatedPart === 0,
+          meta,
+        })
+        if (!measured.ok) return masterError(measured.code, 'ledger append failed')
+        entries.push(measured.entry.id)
+      }
+      if (estimatedPart > 0) {
+        const estimatedBaseline = Math.max(0, baseline - Math.round(baseline * (measuredPart / optimized)))
+        const measured = system.recordUsage({
+          account: 'execution',
+          module: 'unattributed',
+          source: 'model',
+          phase: 'completion',
+          taskId: taskId === undefined ? null : String(taskId),
+          forkId,
+          sessionId,
+          totalTokens: estimatedPart,
+          baselineTokens: estimatedBaseline,
+          estimated: true,
+          meta: { ...meta, estimatedFallback: true },
+        })
+        if (!measured.ok) return masterError(measured.code, 'ledger append failed')
+        entries.push(measured.entry.id)
+      }
       return {
         ok: true,
         taskId: taskId === undefined ? null : String(taskId),
         savedTokens: baseline - optimized,
+        ledger: { ids: entries, measuredTokens: measuredPart, estimatedTokens: estimatedPart },
         summary: service.summary(),
       }
     },
+    /** 3.3.0 M2：A1 归因。enforce 记入 execution 账本；shadow 只累计「本可节省」。 */
+    recordAttribution({ taskId, module, savedTokens, mode = 'shadow', meta, forkId, sessionId } = {}) {
+      return system.attribute({ taskId, forkId, sessionId, module, savedTokens, mode, meta })
+    },
+    /** 3.3.0 §5.5：写替换证书 + 对应账本事件（共用 taskId+step）。 */
+    recordSubstitution(cert = {}) {
+      return system.substitute(cert)
+    },
+    /** 3.3.0 §5.5：按 taskId(+step) 回放「这一省是怎么来的」。 */
+    trace({ taskId, step } = {}) {
+      return system.trace({ taskId, step })
+    },
+    /** 3.3.0 §6 A2：工具装载成本记 **governance**（明确归类，绝不算节省）。 */
+    recordGovernance({ taskId, module = 'a2-disclosure', tokens = 0, kind = 'tools.load', meta, forkId, sessionId } = {}) {
+      const amount = finiteNonNegative(tokens)
+      if (amount === null) return masterError('tokens-invalid', 'tokens must be a non-negative number')
+      const out = system.recordUsage({
+        account: 'governance',
+        module,
+        source: 'authoring',
+        phase: 'authoring',
+        taskId: taskId === undefined ? null : String(taskId),
+        forkId,
+        sessionId,
+        totalTokens: amount,
+        meta: { ...(meta && typeof meta === 'object' ? meta : {}), kind },
+      })
+      if (!out.ok) return masterError(out.code, out.message ?? 'governance ledger append failed')
+      return { ok: true, account: 'governance', module, tokens: amount, ledger: { id: out.entry.id } }
+    },
+    /** M1 交付物：记账报表（估算/实测分列、两本账不合并、外部面单列）。 */
+    ledgerReport(input = {}) {
+      return system.ledgerReport(input)
+    },
+    /** 3.3.0 §10.1：七项验收指标（必须给全；缺项返回 complete:false + missing[]）。 */
+    metrics(input = {}) {
+      return system.metrics(input)
+    },
+    /** 3.3.0 §8：A（单价）/ B（跳过调用）分列报表 + 逐任务净额（净亏不隐藏）。 */
+    savingsReport(input = {}) {
+      return system.savingsReport(input)
+    },
+    /** 3.3.0 §5.4：总额结算，差额自动进 unattributed（不 blame 到任何模块）。 */
+    recordAttributionTotal({ taskId, totalSavedTokens, items = [], mode = 'shadow', forkId, sessionId } = {}) {
+      return system.attributeTotal({ taskId, totalSavedTokens, items, mode, forkId, sessionId })
+    },
+    /** 3.3.0 目标 2.1-5：模块异常降级留痕（审计 + 事件总线，不计入节省）。 */
+    recordDegraded({ taskId, module, phase = 'transform', message = '', count = 1 } = {}) {
+      return system.degraded({ taskId, module, phase, message, count })
+    },
+    /** 3.3.0：宿主会话工具面（外部插件）收益登记；只作对照，不计入本项目节省。 */
+    recordHostSurface({ taskId, savedTokens, meta } = {}) {
+      return system.hostSurface.record({ taskId, savedTokens, meta })
+    },
+    /** 3.3.0 §5.1：按维度查询账本（task/fork/session/module/account/phase/时间窗）。 */
+    query(filter = {}) {
+      return system.query(filter)
+    },
+    /** 3.3.0 §5.1：从 JSONL 回放。 */
+    replayLedger(direction = 'forward') {
+      return system.replay(direction)
+    },
+    /** 3.3.0：归因快照（按模块与任务聚合）。 */
+    attribution() {
+      return system.attribution.snapshot()
+    },
+    /** 3.3.0：订阅成本事件（宿主可转发给瓮城回流/信息栏）；返回取消订阅函数。 */
+    subscribeCost(listener) {
+      return system.subscribe(listener)
+    },
     summary() {
       const ratio = metrics.baselineTokens > 0 ? metrics.savedTokens / metrics.baselineTokens : 0
       const successRate = metrics.observedTotal > 0 ? metrics.observedSuccess / metrics.observedTotal : null
@@ -126,30 +262,139 @@ export function apply(ctx, config = {}) {
     },
     reset() {
       Object.assign(metrics, { tasks: 0, baselineTokens: 0, optimizedTokens: 0, savedTokens: 0, observedSuccess: 0, observedTotal: 0 })
+      system.ledger.reset()
+      system.budget.reset()
+      system.attribution.reset()
+      system.bus.reset()
       return { ok: true }
     },
+    /** 3.3.0 系统层：账本快照（两本账 + 归因）。 */
+    ledger() {
+      return system.ledger.snapshot()
+    },
+    /** M4：账本事件查询（证书链核对需要原始事件，不只要快照）。 */
+    ledgerEntries(filter = {}) {
+      return system.query(filter)
+    },
+    /** 3.3.0 系统层：预算授权（① 唯一检查点；超限 masterError + 结构化 remaining）。 */
+    authorizeBudget({ unit, key = 'default', tokens = 0, cost = 0 } = {}) {
+      return system.authorize({ unit, key, tokens, cost })
+    },
+    /** 3.3.0 系统层：当前账单 + 预算 + 审计 + 节省口径。 */
+    cost() {
+      return system.status()
+    },
+    /** 3.3.0 §5.3：解析某上下文的生效档（global → fork → task，取最严格）。 */
+    resolvePolicy(context = {}) {
+      return system.policy.resolve(context)
+    },
+    /** 3.3.0 §5.3：守卫命中上报（observe 只计数 / shadow 落证书不替换 / enforce 才替换）。 */
+    recordGuardHit(input = {}) {
+      return system.policy.recordHit(input)
+    },
+    /** 3.3.0 §5.3：设置 fork/task 级档位。 */
+    setScope(scope, id, next) {
+      return system.policy.setScope(scope, id, next)
+    },
+    /** 3.3.0 §5.3：三档命中统计与证书。 */
+    policyStats() {
+      return system.policy.stats()
+    },
+    /** 3.3.0 系统层：灰度模式（enforce 需过门禁，见 policy.requestMode）。 */
+    requestMode(next, evidence = {}) {
+      return system.policy.requestMode(next, evidence)
+    },
+    /** 回滚：任何时刻可降级（observe 一行回滚）。 */
+    setMode(next) {
+      return system.policy.setMode(next)
+    },
+    audit() {
+      return system.audit.snapshot()
+    },
+    /** M4：证书列表（供证书链核对报表用；只读）。 */
+    substitutions(filter = {}) {
+      return system.audit.substitutions(filter)
+    },
     status() {
+      const current = system.policy.describe()
       return {
         ok: true,
         id: 'cost-optimizer',
-        version: '3.2.5',
+        version: '3.3.0',
         role,
-        mode: policy.mode,
-        requestedMode: policy.requestedMode,
-        targetSavingsRatio: policy.targetSavingsRatio,
+        mode: current.mode,
+        requestedMode: current.requestedMode,
+        targetSavingsRatio: targetSavingsRatio !== null && targetSavingsRatio <= 1 ? targetSavingsRatio : 0.8,
         benchmark: HARNESSMM_BENCHMARK,
         summary: service.summary(),
-        note: '3.2.0 observe-only：不拦截/不改写模型调用；EGD/GDR/CCS 在 3.3.0 接入。',
+        policy: current,
+        policyStats: system.policy.stats(),
+        budget: system.budget.state(),
+        ledger: system.ledger.snapshot(),
+        audit: system.audit.verify(),
+        shadow: Object.fromEntries(system.attribution.snapshot().modules.map((row) => [row.module, {
+          events: row.events,
+          projectedTokens: row.projectedTokens,
+          appliedTokens: row.enforceSavedTokens,
+        }])),
+        attribution: system.attribution.snapshot(),
+        attributionSummary: system.status().attributionSummary,
+        bus: system.bus.snapshot(1),
+    /** §5.6：内部事件类型（冒号命名）与对外出口状态（fang 未就绪 ⇒ unavailable）。 */
+    events: { types: ['cost:event', 'cost:degraded', 'cost:substitution'], relays: system.bus.snapshot(1).relays },
+        degraded: system.status().degraded,
+        surfaces: system.status().surfaces,
+        hostSurface: system.hostSurface.status(),
+        tokens: system.status().tokens,
+        savings: system.status().savings,
+        /** §8：两项分列的总节省（单价项 + 跳过调用项），避免只报合计。 */
+        savingsColumns: (() => {
+          const report = system.savingsReport({ limit: 5000 })
+          return {
+            unitPriceSaved: report.columns.unitPrice.savedTokens,
+            skippedCallSaved: report.columns.skippedCalls.savedTokens,
+            skippedCalls: report.columns.skippedCalls.calls,
+            governanceTotal: report.governance.totalTokens,
+            netSaved: report.netSaved,
+            netLossTasks: report.netLossTasks.map((task) => task.taskId),
+            doubleCountGuard: report.doubleCountGuard,
+          }
+        })(),
+        note: '3.3.0 M1+M2：系统层记账/预算/灰度/审计 + A1 工具输出紧凑化（默认 shadow）；工具面 A2–A3 与决策复用 B1–B4 在 M3–M4 接入。',
       }
     },
   }
 
   try { ctx.effect(() => ctx.provide(SERVICE.cost, service)) } catch { /* fake ctx */ }
+  // 3.3.0 §11：可选子服务（主服务形态不变；消费方必须探测，不能假定存在）。
+  const optionalFaces = {
+    [OPTIONAL_SERVICE.costLedger]: Object.freeze({
+      query: (input) => system.query(input),
+      replay: (direction) => system.replay(direction),
+      snapshot: () => system.status().ledger,
+    }),
+    [OPTIONAL_SERVICE.costBudget]: Object.freeze({
+      authorize: (input) => system.authorize(input),
+      snapshot: () => system.status().budget,
+    }),
+    [OPTIONAL_SERVICE.costPolicy]: Object.freeze({
+      snapshot: () => system.status().policy,
+      stats: () => system.status().policyStats,
+    }),
+    [OPTIONAL_SERVICE.costAudit]: Object.freeze({
+      verify: () => system.audit().verify(),
+      substitutions: (filter) => system.audit().substitutions(filter),
+      trace: (input) => system.trace(input),
+    }),
+  }
+  for (const [name, face] of Object.entries(optionalFaces)) {
+    try { ctx.effect(() => ctx.provide(name, face)) } catch { /* 不支持可选子服务的运行时也无妨 */ }
+  }
   master.registerSubplugin({
     id: 'cost-optimizer',
     name: 'dsh-master-cost-optimizer',
-    capabilities: ['token-estimate', 'savings-record', 'cost-status'],
-    description: 'HarnessMM observe 层（仅 fork）',
+    capabilities: ['token-estimate', 'savings-record', 'cost-status', 'cost-ledger', 'cost-budget', 'cost-policy', 'cost-audit'],
+    description: 'HarnessMM observe 层（仅 fork；3.3.0 M1 系统层）',
   })
   return service
 }

package/src/plugins/superagent-router.ts

@@ -49,6 +49,8 @@ const EVENTS_PATH = '/dsh-master/api/superagent/worker-events'
 const STREAM_PATH = '/dsh-master/api/superagent/stream'
 const STREAM_TOKEN_PATH = '/dsh-master/api/superagent/stream-token'
 const STATUS_PATH = '/dsh-master/api/superagent/status'
+/** §5.6：成本事件摘要（状态页 / 分身信息栏读取）。 */
+const COST_PATH = '/dsh-master/api/superagent/cost'
 const SESSION_PATH = '/dsh-master/api/superagent/session'
 const PR_PATH = '/dsh-master/api/superagent/pr'
 const GITHUB_PATH = '/dsh-master/api/superagent/github'
@@ -281,6 +283,73 @@ export function apply(ctx, config = {}) {
     if (token) tokenManager.revoke(token, 'ticket-done')
   }
 
+  /**
+   * §5.6：把 Worker 上报的 `cost` 事件按 ticket 汇成只读摘要，
+   * 供状态页与「分身信息栏」读取（不暴露任何 token）。
+   */
+  const costSummary = (ticketId) => {
+    const id = ticketId === undefined ? null : String(ticketId)
+    // §11：只读成本块的数据源——系统层 savings 两列（A 单价 / B 跳过调用）+ 命中率。
+    const serviceBlock = (() => {
+      try {
+        const cost = safeGet(ctx, SERVICE.cost)
+        if (!cost) return null
+        const status = typeof cost.status === 'function' ? cost.status() : null
+        const report = typeof cost.savingsReport === 'function' ? cost.savingsReport({ amortize: 'even', limit: 2000 }) : null
+        return {
+          savings: status?.savings ?? null,
+          columns: status?.savingsColumns ?? null,
+          policy: status?.policy ?? null,
+          ledger: status?.ledger?.entries !== undefined ? { entries: status.ledger.entries } : null,
+          unitPriceSaved: report?.columns?.unitPrice?.savedTokens ?? 0,
+          skippedCallSaved: report?.columns?.skippedCalls?.savedTokens ?? 0,
+          skippedCalls: report?.columns?.skippedCalls?.calls ?? 0,
+          netLossTasks: report?.netLossTasks?.map((task) => task.taskId) ?? [],
+          doubleCountGuard: report?.doubleCountGuard === true,
+          /** 守卫命中率需要各任务上报的 guard 统计聚合；未聚合前如实给 null，不猜。 */
+          hitRate: null,
+        }
+      } catch { return null }
+    })()
+    const tickets = id === null ? [...workerEvents.keys()] : [id]
+    const rows = []
+    const totals = { events: 0, degraded: 0, substitutions: 0, estimated: 0, savedTokens: 0 }
+    for (const key of tickets) {
+      const events = (workerEvents.get(key) ?? []).filter((event) => event && event.type === 'cost')
+      if (events.length === 0) continue
+      const row = { ticketId: key, events: 0, degraded: 0, substitutions: 0, estimated: 0, savedTokens: 0, points: {}, modules: {} }
+      for (const event of events) {
+        const payload = event.payload ?? {}
+        row.events += 1
+        row.points[String(payload.point ?? 'unknown')] = (row.points[String(payload.point ?? 'unknown')] ?? 0) + 1
+        if (payload.point === 'degraded') row.degraded += 1
+        if (payload.estimated === true) row.estimated += 1
+        const compaction = payload.compaction
+        if (compaction && compaction.applied === true) {
+          row.savedTokens += Math.max(0, Number(compaction.estimatedTokens ?? 0) || 0)
+          const moduleKey = String(compaction.module ?? 'a1-compact')
+          row.modules[moduleKey] = (row.modules[moduleKey] ?? 0) + Math.max(0, Number(compaction.estimatedTokens ?? 0) || 0)
+        }
+      }
+      totals.events += row.events
+      totals.degraded += row.degraded
+      totals.substitutions += row.substitutions
+      totals.estimated += row.estimated
+      totals.savedTokens += row.savedTokens
+      rows.push(row)
+    }
+    return {
+      ok: true,
+      ticketId: id,
+      tickets: rows,
+      totals,
+      /* §11：只读成本块（A 单价项 / B 跳过调用项分列 + 命中率），面板只读消费。 */
+      service: serviceBlock,
+      /* §5.6：瓮城「产物回流」尚未就绪 —— 显式 unavailable，不假装成功、不阻塞主线。 */
+      relay: { target: 'fang', available: false, reason: 'fang-channel-not-ready' },
+    }
+  }
+
   const service = {
     id: 'superagent-router',
     version: '3.2.5',
@@ -290,6 +359,8 @@ export function apply(ctx, config = {}) {
       forkerService: hasForker(),
       streaming: { configured: Boolean(origin), ...broadcaster.describe(), tokens: tokenManager.counts() },
       workerEvents: Object.fromEntries([...workerEvents.entries()].map(([k, v]) => [k, v.length])),
+      cost: costSummary().totals,
+      costRelay: costSummary().relay,
       writeback: writeback.describe(),
       quota: quotaStatus(),
       sessions: { count: sessionMap.size, last: [...sessionMap.values()].slice(-3) },
@@ -307,6 +378,8 @@ export function apply(ctx, config = {}) {
     workerEvents(ticketId) {
       return { ok: true, ticketId: String(ticketId ?? ''), events: workerEvents.get(String(ticketId ?? '')) ?? [] }
     },
+    /** §5.6：成本事件摘要（状态页/分身信息栏的数据源）。 */
+    cost(ticketId) { return costSummary(ticketId) },
     tokenAudit(limit) { return tokenManager.audit(limit) },
     rotateStreamToken(oldToken = '') { return tokenManager.rotate(oldToken, { kind: 'ui' }) },
     quota: () => quotaStatus(),
@@ -431,6 +504,14 @@ export function apply(ctx, config = {}) {
             return jsonResponse(res, 200, { ok: true, session: mapped })
           },
         })
+        register({
+          kind: 'exact', path: COST_PATH, method: 'GET',
+          handler: async (req, res) => {
+            const query = new URL(String(req?.url ?? '/'), 'http://x').searchParams
+            const ticketId = query.get('ticketId')
+            return jsonResponse(res, 200, service.cost(ticketId === null ? undefined : String(ticketId)))
+          },
+        })
         register({
           kind: 'exact', path: GITHUB_PATH, method: 'POST',
           handler: async (req, res) => {
@@ -462,4 +543,4 @@ export function apply(ctx, config = {}) {
   return service
 }
 
-export { EVENTS_PATH, STREAM_PATH, STREAM_TOKEN_PATH, STATUS_PATH, SESSION_PATH, readRawBody }
+export { EVENTS_PATH, STREAM_PATH, STREAM_TOKEN_PATH, STATUS_PATH, SESSION_PATH, COST_PATH, readRawBody }

package/src/superagent/types.ts

@@ -133,3 +133,73 @@ export function publicTicket(ticket, extra = {}) {
     ...extra,
   }
 }
+
+/* ------------------------------------------------------------------ *
+ * 3.3.0 §11：成本域对外类型（宿主侧）
+ *
+ * 这些是**跨进程/跨插件边界的形状**：Worker 侧同名类型在 worker/*.ts，
+ * 宿主侧以本文件为准。字段名保持一致，便于证书与事件在两侧无损传递。
+ * ------------------------------------------------------------------ */
+
+/** 成本事件类型（§5.6 事件总线）。 */
+export const COST_EVENT_TYPE = Object.freeze(['cost:event', 'cost:degraded', 'cost:substitution'])
+
+/** 单条成本事件（宿主 → 订阅者 / 瓮城回流）。 */
+export interface CostEventEnvelope {
+  type: 'cost:event' | 'cost:degraded' | 'cost:substitution'
+  ticketId?: string
+  module?: string
+  phase?: string
+  account?: 'execution' | 'governance'
+  savedTokens?: number
+  totalTokens?: number
+  at: number
+  detail?: Record<string, unknown>
+}
+
+/** 可执行决策图的一条边（B1，宿主侧镜像）。 */
+export interface EdgEdgeView {
+  id: string
+  toolName: string
+  schemaHash: string
+  argSource: Array<{ arg: string; from: 'literal' | 'regex' | 'jsonpath'; expr: string }>
+  guard: { kind: 'regex' | 'jsonpath' | 'equals'; expr: string; negate?: boolean }
+  destructive: boolean
+  dependsOn?: string[]
+}
+
+/** 替换证书（B3，宿主侧镜像；审计链里的记录也长这样）。 */
+export interface SubstitutionCertView {
+  edgeId: string
+  toolName: string
+  schemaHash: string
+  guardExpr: string
+  receiptDigest: string
+  replacedCallbackId: string
+  viaNativeDispatcher: true
+  taskId: string
+  step: number
+  dispatched?: boolean
+  error?: string
+  savedTokens?: number
+  moduleId?: string
+  at?: number
+}
+
+/** 只读成本块（§11 client.js「房主」抽屉用；不含任何业务状态写入能力）。 */
+export interface CostSummaryView {
+  enabled: boolean
+  mode?: string
+  savings: { executionSaved: number; governanceCost: number; netSaved: number }
+  savingsColumns?: {
+    unitPriceSaved: number
+    skippedCallSaved: number
+    skippedCalls: number
+    governanceTotal: number
+    netSaved: number
+    netLossTasks: string[]
+    doubleCountGuard: boolean
+  }
+  hitRate?: number | null
+  degraded?: number
+}