@twinsearth/dsh-master 3.2.10 → 3.3.1

package/worker/agent-loop.ts

@@ -23,6 +23,7 @@
 
 import type {
   ChatMessage,
+  CostHooks,
   LLMResponse,
   RouterTicketLike,
   TicketPayload,
@@ -37,6 +38,48 @@ import { DEFAULT_LIMITS } from './types.ts'
 import { WorkerError, WorkerLimitError, WorkerTicketError, toFailure } from './errors.ts'
 import { buildSystemPrompt, buildUserPrompt } from './prompt.ts'
 import { createToolRegistry } from './tools.ts'
+import { createCostHooks, mergeCostHooks, normalizeCostUsage } from './cost-hooks.ts'
+import { createModuleRegistry, createCompactModule } from './cost-modules.ts'
+import { createBudgetGuard } from './budget-guard.ts'
+import type { WorkerBudgetGuard, WorkerBudgetOptions } from './budget-guard.ts'
+import type { ModuleRegistry } from './cost-spi.ts'
+import { createDisclosureState, createLoadToolsTool } from './tool-disclosure.ts'
+import type { DisclosureOptions, DisclosureState } from './tool-disclosure.ts'
+import { createBatchAdvisor } from './tool-batch.ts'
+import type { BatchAdvisor } from './tool-batch.ts'
+import { createCcs } from './ccs.ts'
+import type { Ccs, CcsCert } from './ccs.ts'
+import { createGdr } from './gdr.ts'
+import { schemaHashOf } from './edg.ts'
+import type { EdgGraph } from './edg.ts'
+
+/** §6 A2：从 deps/env 读取渐进式纰漏配置（默认关闭 ⇒ 全量工具面，fail-open）。 */
+function disclosureOptions(deps: WorkerDeps): DisclosureOptions {
+  const config = deps.disclosure
+  if (config && typeof config === 'object') return config
+  if (typeof process === 'undefined' || !process.env) return { enabled: false }
+  if (process.env.DSH_MASTER_DISCLOSURE !== 'on') return { enabled: false }
+  return {
+    enabled: true,
+    allowlist: String(process.env.DSH_MASTER_DISCLOSURE_ALLOWLIST ?? '').split(',').map((item) => item.trim()).filter(Boolean),
+  }
+}
+
+/** §5.2：从环境变量读取 ① 预算闸配置（未配置 ⇒ 关闭，沿用 3.2.x 的事后硬上限）。 */
+function budgetOptionsFromEnv(): WorkerBudgetOptions {
+  if (typeof process === 'undefined' || !process.env) return {}
+  const env = process.env
+  const limit = Number(env.DSH_MASTER_BUDGET_TOKENS)
+  if (!Number.isFinite(limit) || limit <= 0) return {}
+  const list = String(env.DSH_MASTER_BUDGET_DEGRADE_MODELS ?? '').split(',').map((item) => item.trim()).filter(Boolean)
+  return {
+    enabled: true,
+    limitTokens: Math.floor(limit),
+    onExhaust: env.DSH_MASTER_BUDGET_ON_EXHAUST === 'degrade' ? 'degrade' : 'hard-stop',
+    degradeModels: list,
+    degradeTo: env.DSH_MASTER_BUDGET_DEGRADE_TO,
+  }
+}
 
 /**
  * 周期检测（v3.2.7 审计收口）：识别「重复序列」而不是只看连续相同。
@@ -183,6 +226,50 @@ export class SuperAgentWorker {
   /** 本步是否已收到 provider 的真实流式 delta（true 时不再分块模拟）。 */
   private streamedThisStep = false
   private registry: ReturnType<typeof createToolRegistry>
+  /** 3.3.0：四个成本切点（默认转发 sink.cost；可被 deps.costHooks 覆盖/叠加）。 */
+  costHooks: CostHooks
+  /** 3.3.0 模块层：A/B 类模块的唯一中介（Agent Loop 不认识具体模块）。 */
+  modules: ModuleRegistry
+  /** 本次任务的 A1 归因汇总（保留原始字符口径，供 WorkerResult 上报）。 */
+  compactionStats = { evaluated: 0, applied: 0, originalChars: 0, compactChars: 0, savedChars: 0 }
+  /** 本次任务的降级留痕（模块 → 阶段 → 最近一次事件）。 */
+  degradedEvents = new Map<string, { module: string; phase: string; message: string; count: number }>()  /** 实测 / 估算 token 分开累计（设计 §5.1：报表不得混算）。 */
+  measuredUsageTokens = 0
+  estimatedUsageTokens = 0
+  /** 设计 §5.2：① 预算闸（默认关闭，opt-in 后从「超支后终止」变为「超支前拒绝」）。 */
+  budget: WorkerBudgetGuard
+  /** §6 A2：渐进式纰漏状态（常驻集合 + 按需加载）。 */
+  disclosure: DisclosureState
+  /** §6 A3：批量调用引导与形状纠偏（只追加提示，不阻断不替换）。 */
+  batch: BatchAdvisor
+  /** §7 B3：替换执行器（只有配置了原生派发器时才存在）。 */
+  ccs: Ccs | null = null
+  /** §7 B2：守卫匹配器（始终存在，换成空图时不命中）。 */
+  gdr = createGdr()
+  /** §7 B3：本次任务的决策图（作者步骤/模板产出）。 */
+  edgGraph: EdgGraph | null = null
+  /** §7 B3：哪些边已完成（依赖检查用）。 */
+  completedEdges = new Set<string>()
+  /** §7 B3：本次任务发生的替换证书。 */
+  substitutions: CcsCert[] = []
+  /** §7 B3：被跳过的慢模型回调次数。 */
+  /** I8：外部取消信号（替换路径同样受其约束）。 */
+  cancelSignal: AbortSignal | undefined
+  skippedModelCalls = 0
+  /** 各工具当前 schema 哈希（B2 第②环）。 */
+  schemaHashes: Record<string, string> = {}
+  /** 替换策略：off / shadow（算证据不替换）/ enforce（白名单）。 */
+  ccsPolicy: { mode: 'off' | 'shadow' | 'enforce'; allowed: boolean; reason: string } = { mode: 'off', allowed: false, reason: 'disabled' }
+  /** M3：每次守卫匹配尝试（命中与未命中都记，作为命中率分母）。 */
+  reuseAttempts: Array<{ toolName: string; hit: boolean; reason: string | null; stage: string | null; edgeId: string | null; wouldSaveTokens: number; stepIndex: number }> = []
+  /** M3：shadow 下算出的「本可替换」证书（不派发、不进审计链）。 */
+  shadowCertificates: CcsCert[] = []
+  /** 计划用于替换时「跳过一次模型调用」的预留 token（归因用）。 */
+  ccsReserveTokens = 0
+  /** degrade 档选中的廉价模型（仅本次调用生效）。 */
+  private callModel: string | undefined
+  /** 当前循环步号（degraded 事件需要携带，注册表回调早于 stepIndex 提升）。 */
+  private currentStepIndex = 0
 
   constructor(deps: WorkerDeps) {
     if (!deps || !deps.llm || typeof deps.llm.chat !== 'function') throw new Error('SuperAgentWorker requires deps.llm.chat')
@@ -198,7 +285,70 @@ export class SuperAgentWorker {
     this.clock = typeof deps.clock === 'function' ? deps.clock : () => Date.now()
     this.model = deps.model
     this.redactValues = Array.isArray(deps.redactValues) ? deps.redactValues.filter((value) => typeof value === 'string') : []
-    this.registry = createToolRegistry(this.tools)
+    this.cancelSignal = deps.signal
+    // §6 A2：渐进式纰漏——常驻工具面收敛，高级工具按需加载（默认关闭 ⇒ 全量工具面）。
+    this.disclosure = createDisclosureState(disclosureOptions(deps))
+    this.batch = createBatchAdvisor({
+      enabled: deps.batch?.enabled !== false,
+      mode: deps.batch?.mode,
+      maxBatchPerTurn: deps.batch?.maxBatchPerTurn ?? deps.limits?.maxToolCallsPerStep ?? this.limits.maxToolCallsPerStep,
+    })
+    const toolList = this.disclosure.enabled
+      ? [...this.tools, createLoadToolsTool(this.disclosure, this.tools)]
+      : this.tools
+    this.registry = createToolRegistry(toolList)
+    // §7 B3：只有显式给了决策图 + enforce 策略时才装替换器（默认不装 ⇒ 行为与 3.2.x 一致）。
+    const ccsConfig = deps.ccs
+    if (ccsConfig?.graph && Array.isArray(ccsConfig.graph.edges) && ccsConfig.graph.edges.length > 0) {
+      this.edgGraph = ccsConfig.graph
+      for (const tool of toolList) {
+        // 与 B1 的 schemaHashOf 同一算法：图里的 schemaHash 才能与运行时逐字对上。
+        this.schemaHashes[tool.name] = schemaHashOf(tool.name, tool.parameters, tool.description)
+      }
+      // I3：破坏性工具默认不入池 —— 图里属于破坏性工具的边在这里被剔除（除非显式放行）。
+      if (ccsConfig.allowDestructive !== true) {
+        const kept = this.edgGraph.edges.filter((edge) => !this.registry.destructive(edge.toolName))
+        if (kept.length !== this.edgGraph.edges.length) {
+          this.edgGraph = { ...this.edgGraph, edges: kept }
+        }
+      }
+      this.ccsReserveTokens = Math.max(0, Number(ccsConfig.reserveTokens ?? 0) || 0)
+      const enforce = ccsConfig.mode === 'enforce'
+      const allowlist = Array.isArray(ccsConfig.allowlist) ? ccsConfig.allowlist.map((item) => String(item)) : []
+      const allowlisted = allowlist.length === 0 ? true : allowlist.includes(String(ccsConfig.forkId ?? this.ticketId))
+      const shadow = ccsConfig.mode === 'shadow'
+      this.ccsPolicy = enforce && allowlisted
+        ? { mode: 'enforce', allowed: true, reason: 'enforce' }
+        : shadow
+          ? { mode: 'shadow', allowed: false, reason: 'shadow-only' }
+          : { mode: 'off', allowed: false, reason: enforce ? 'allowlist-miss' : 'not-enforce' }
+    }
+    this.costHooks = mergeCostHooks(createCostHooks({ sink: this.sink, clock: this.clock }), deps.costHooks)
+    const compactMode = deps.compactMode ?? (typeof process !== 'undefined' ? process.env.DSH_MASTER_COMPACT_MODE : undefined)
+    this.budget = createBudgetGuard(deps.budget ?? budgetOptionsFromEnv())
+    // §7 B3：替换器必须在 budget 就绪之后创建（它要在派发前过预算闸）。
+    if (this.ccsPolicy.allowed) {
+      this.ccs = createCcs({
+        dispatcher: { execute: (call, context) => this.registry.execute(call, context) },
+        budget: this.budget,
+        clock: this.clock,
+      })
+    }
+    this.modules = createModuleRegistry({
+      modules: [createCompactModule(compactMode, { workspace: this.workspace }), ...(deps.costModules ?? [])],
+      // 目标 2.1-5：模块异常必须留痕（degraded 事件），且不中断 Agent Loop。
+      onDegraded: (event) => {
+        this.degradedEvents.set(`${event.module}|${event.phase}`, { ...event })
+        this.costHooks.degraded({
+          ticketId: this.ticketId,
+          stepIndex: this.currentStepIndex,
+          module: event.module,
+          phase: event.phase,
+          message: event.message,
+          count: event.count,
+        })
+      },
+    })
   }
 
   private redact(text: string): string {
@@ -212,6 +362,12 @@ export class SuperAgentWorker {
     this.tokenUsage = 0
     this.finalAnswer = ''
     this.prDelivery = undefined
+    this.compactionStats = { evaluated: 0, applied: 0, originalChars: 0, compactChars: 0, savedChars: 0 }
+    this.degradedEvents.clear()
+    this.measuredUsageTokens = 0
+    this.estimatedUsageTokens = 0
+    this.callModel = undefined
+    this.currentStepIndex = 0
     let ticket: TicketPayload
     try {
       ticket = normalizeTicket(input)
@@ -237,6 +393,11 @@ export class SuperAgentWorker {
       { role: 'system', content: buildSystemPrompt(ticket) },
       { role: 'user', content: buildUserPrompt(ticket) },
     ]
+    // §6 A3：首轮一次教学——写进**历史**（不是系统提示词），之后不再重复。
+    if (this.batch.status().state === 'active' && !this.batch.taught()) {
+      this.history.push({ role: 'user', content: this.batch.guidance() })
+      this.batch.markTaught()
+    }
 
     try {
       this.setPhase('initializing')
@@ -263,10 +424,34 @@ export class SuperAgentWorker {
           throw new WorkerLimitError('max-steps', `Worker 超出最大循环次数 (${this.limits.maxSteps})，判定为死循环，强制终止。`)
         }
         stepIndex += 1
+        this.currentStepIndex = stepIndex
         this.setPhase('thinking')
         this.log(`[Worker] === 循环 Step ${stepIndex}/${this.limits.maxSteps} ===`)
         this.assertContextBudget()
 
+        const modelStartedAt = this.clock()
+        // 设计 §5.2：预算检查点**只在 ①**，且 fail-closed（付不起就不启动调用）。
+        const budgetDecision = this.budget.beforeModelCall({
+          model: this.model,
+          historyChars: JSON.stringify(this.history).length,
+          stepIndex,
+        })
+        if (!budgetDecision.ok) {
+          throw new WorkerLimitError('budget-exhausted', budgetDecision.message ?? '预算不足，拒绝启动模型调用')
+        }
+        this.callModel = budgetDecision.degraded === true && budgetDecision.model ? budgetDecision.model : undefined
+        this.costHooks.beforeModelCall({
+          ticketId: this.ticketId,
+          stepIndex,
+          model: this.callModel ?? this.model,
+          historyChars: JSON.stringify(this.history).length,
+        })
+        this.modules.beforeModelCall({
+          ticketId: this.ticketId,
+          stepIndex,
+          model: this.callModel ?? this.model,
+          historyChars: JSON.stringify(this.history).length,
+        })
         const response = await this.callLLM()
         const rawContent = String(response.message?.content ?? '')
         if (rawContent.length > this.limits.maxContextChars) {
@@ -274,11 +459,30 @@ export class SuperAgentWorker {
         }
         const usage = response.usage
         let used = Number(usage?.totalTokens ?? ((usage?.promptTokens ?? 0) + (usage?.completionTokens ?? 0))) || 0
+        let usedEstimated = false
         if (used <= 0) {
-          // provider 不返回 usage 时的兜底估算，防止 Token 预算被绕过。
+          // provider 不返回 usage 时的兜底估算，防止 Token 预算被绕过；报表里必须标 estimated。
           used = Math.ceil((JSON.stringify(this.history).length + rawContent.length) / 4)
+          usedEstimated = true
         }
         this.tokenUsage += used
+        if (usedEstimated) this.estimatedUsageTokens += used
+        else this.measuredUsageTokens += used
+        const normalized = normalizeCostUsage(usage)
+        this.costHooks.afterModelResponse({
+          ticketId: this.ticketId,
+          stepIndex,
+          usage: normalized.total > 0 ? normalized : { input: 0, output: 0, total: used },
+          latencyMs: Math.max(0, this.clock() - modelStartedAt),
+          estimated: usedEstimated,
+        })
+        this.modules.afterModelResponse({
+          ticketId: this.ticketId,
+          stepIndex,
+          usage: normalized.total > 0 ? normalized : { input: 0, output: 0, total: used },
+          latencyMs: Math.max(0, this.clock() - modelStartedAt),
+          estimated: usedEstimated,
+        })
         if (this.tokenUsage > this.limits.maxTokens) {
           throw new WorkerLimitError('token-budget-exceeded', `超出最大 Token 预算 (${this.limits.maxTokens})，强制终止。`)
         }
@@ -296,6 +500,12 @@ export class SuperAgentWorker {
         }
 
         const toolCalls = validateToolCalls(response)
+        // §6 A3：只做形状纠偏（追加提示），从不阻断、从不改写模型程序。
+        const batchReview = this.batch.review(toolCalls)
+        if (batchReview.correction) {
+          this.history.push({ role: 'user', content: batchReview.correction })
+          this.log(`[Worker] A3 批量纠偏: ${batchReview.reason}`)
+        }
         if (toolCalls.length === 0) {
           this.finalAnswer = String(assistantMessage.content ?? '').trim() || '任务执行完成，无返回内容。'
           this.setPhase('reporting')
@@ -339,8 +549,71 @@ export class SuperAgentWorker {
           this.record({ type: 'tool_call', content: call.args, toolName: call.name, toolArgs: safeParseArgs(call.args) })
           this.setPhase('executing_tool')
           this.stream(undefined, call.name)
-          const result = await this.executeTool(call)
-          const safeResult = this.redact(result)
+          this.costHooks.beforeToolDispatch({
+            ticketId: this.ticketId,
+            stepIndex,
+            toolName: call.name,
+            argsChars: String(call.args ?? '').length,
+          })
+          // ③ 派发前：A 类模块可改写工具名/参数，或在 enforce 档屏蔽该工具。
+          const dispatch = this.modules.beforeToolDispatch({
+            ticketId: this.ticketId,
+            stepIndex,
+            call: { id: call.id, name: call.name, args: safeParseArgs(call.args) ?? {} },
+          })
+          let result: string
+          let dispatchedName = call.name
+          if (dispatch.hidden) {
+            // 屏蔽：不执行工具，回一条结构化拒绝给模型（可读、可恢复、不进死循环判定）。
+            result = `【模块屏蔽】${dispatch.hiddenBy} 已隐藏工具 ${call.name}（${dispatch.reason}）；请改用其它可用工具或直接给出结论。`
+            this.record({ type: 'tool_result', content: result, toolName: call.name })
+          } else {
+            dispatchedName = dispatch.call.name
+            result = await this.executeTool(
+              dispatchedName === call.name
+                ? call
+                : { ...call, name: dispatchedName, args: JSON.stringify(dispatch.call.args ?? {}) },
+            )
+          }
+          const transformed = this.modules.afterToolReceipt({
+            ticketId: this.ticketId,
+            stepIndex,
+            toolName: dispatchedName,
+            args: safeParseArgs(call.args),
+            text: result,
+          })
+          const toolResultText = transformed.text
+          const a1 = transformed.attributions.find((item) => item.module === 'a1-compact')
+          if (a1) {
+            const stats = this.compactionStats
+            stats.evaluated += 1
+            stats.originalChars += a1.originalChars
+            stats.compactChars += a1.applied ? a1.resultChars : a1.originalChars
+            stats.savedChars += a1.applied ? Math.max(0, a1.savedChars) : 0
+            if (a1.applied) stats.applied += 1
+          }
+          {
+            const potentialChars = a1 ? Math.max(0, Number((a1.meta as { wouldSaveChars?: number } | undefined)?.wouldSaveChars ?? a1.savedChars) || 0) : 0
+            this.costHooks.afterToolReceipt({
+              ticketId: this.ticketId,
+              stepIndex,
+              toolName: call.name,
+              resultChars: toolResultText.length,
+              truncated: toolResultText.length > this.limits.maxToolResultChars,
+              compaction: {
+                module: 'a1-compact',
+                mode: a1?.mode ?? 'off',
+                applicable: Boolean(a1),
+                applied: a1?.applied === true,
+                originalChars: result.length,
+                compactChars: toolResultText.length,
+                // shadow 时这里是「本可节省」；是否真的省下由 applied 表示（账本只认 applied）。
+                savedChars: potentialChars,
+                estimatedTokens: potentialChars > 0 ? Math.ceil(potentialChars / 4) : 0,
+              },
+            })
+          }
+          const safeResult = this.redact(toolResultText)
           const truncated = safeResult.length > this.limits.maxToolResultChars
             ? safeResult.slice(0, this.limits.maxToolResultChars) + `\n…[工具结果截断，原长 ${safeResult.length} 字符]`
             : safeResult
@@ -353,6 +626,14 @@ export class SuperAgentWorker {
           })
           this.setPhase('thinking')
         }
+
+        // §7 B3：尝试用已存决策图替代「下一次慢模型回调」。
+        // 只有 enforce + 策略放行 + GDR 命中 + 派发成功才真的跳过；任何失败都回落慢模型。
+        const substituted = await this.trySubstitute(stepIndex)
+        if (substituted) {
+          this.setPhase('thinking')
+          continue
+        }
         // 循环继续：带着 tool 结果再次询问模型。
       }
     } catch (error) {
@@ -364,7 +645,101 @@ export class SuperAgentWorker {
     }
   }
 
-  /** 最近一步（供宿主轮询推送）。 */
+  /** §7 B3：用决策图替代一次慢模型回调；成功返回 true（已注入历史），失败返回 false。 */
+  private async trySubstitute(stepIndex: number): Promise<boolean> {
+    // M3：shadow 也做守卫匹配并产出「本可节省」证据，但**从不替换**。
+    if (!this.edgGraph || this.ccsPolicy.mode === 'off') return false
+    const lastTool = [...this.steps].reverse().find((step) => step.type === 'tool_result')
+    if (!lastTool || !lastTool.toolName) return false
+    const receipt = {
+      toolName: lastTool.toolName,
+      args: lastTool.toolArgs ?? {},
+      text: String(lastTool.content ?? ''),
+      digest: `sha256:${this.currentStepIndex.toString(36)}:${String(lastTool.content ?? '').length.toString(36)}`,
+      stepIndex,
+      ticketId: this.ticketId,
+    }
+    const guard = this.gdr.match({
+      receipt,
+      graph: this.edgGraph,
+      completed: [...this.completedEdges],
+      schemaHashOf: (toolName) => this.schemaHashes[toolName],
+      estimateSavedTokens: () => this.ccsReserveTokens,
+    })
+    // 每次复用尝试都留痕（命中与未命中都算分母）。
+    this.reuseAttempts.push({
+      toolName: receipt.toolName,
+      hit: guard.hit === true,
+      reason: guard.reason ?? null,
+      stage: guard.stage ?? null,
+      edgeId: guard.edgeId ?? null,
+      wouldSaveTokens: guard.hit === true ? Math.max(0, Number(guard.wouldSaveTokens ?? this.ccsReserveTokens) || 0) : 0,
+      stepIndex,
+    })
+    if (!guard.hit || !guard.edgeId || !guard.args) return false
+    const edge = this.edgGraph.edges.find((item) => item.id === guard.edgeId)
+    if (!edge) return false
+
+    const replacedCallbackId = `cb_${this.ticketId}_${stepIndex}_${guard.edgeId}`
+    // M3 shadow：只产证书，不派发、不跳过模型调用（证书标 dispatched:false，不进审计链）。
+    if (this.ccsPolicy.mode !== 'enforce' || !this.ccs) {
+      this.shadowCertificates.push({
+        edgeId: edge.id,
+        toolName: edge.toolName,
+        schemaHash: edge.schemaHash,
+        guardExpr: edge.guard.expr,
+        receiptDigest: receipt.digest,
+        replacedCallbackId,
+        viaNativeDispatcher: true,
+        taskId: this.ticketId,
+        step: stepIndex,
+        dispatched: false,
+        error: 'shadow-not-dispatched',
+        savedTokens: Math.max(0, Number(guard.wouldSaveTokens ?? this.ccsReserveTokens) || 0),
+        moduleId: 'b3-ccs',
+        at: this.clock(),
+      })
+      return false
+    }
+    const controller = new AbortController()
+    const abort = () => controller.abort()
+    if (this.cancelSignal) {
+      if (this.cancelSignal.aborted) controller.abort()
+      else this.cancelSignal.addEventListener('abort', abort, { once: true })
+    }
+    const result = await this.ccs.substitute({
+      edge,
+      args: guard.args,
+      receipt,
+      replacedCallbackId,
+      taskId: this.ticketId,
+      step: stepIndex,
+      workspace: this.workspace,
+      mandate: { ...this.effectiveMandate },
+      signal: controller.signal,
+      timeoutMs: this.limits.toolTimeoutMs,
+      savedTokens: this.ccsReserveTokens,
+    })
+    this.substitutions.push(result.certificate)
+    if (!result.ok || result.fallback || result.text === null) {
+      // 失败 ⇒ 记账留痕，然后**回落慢模型**（不吞错继续）。
+      this.log(`[Worker] B3 替换失败(${result.certificate.error ?? 'unknown'})，回落慢模型`)
+      return false
+    }
+    this.completedEdges.add(edge.id)
+    this.skippedModelCalls += 1
+    // 注入「这次调用本来会由模型发出」的两条消息，从而跳过这次模型推理。
+    this.history.push({
+      role: 'assistant',
+      content: '',
+      tool_calls: [{ id: replacedCallbackId, type: 'function', function: { name: edge.toolName, arguments: JSON.stringify(guard.args) } }],
+    })
+    const safe = this.redact(result.text)
+    this.history.push({ role: 'tool', tool_call_id: replacedCallbackId, name: edge.toolName, content: safe })
+    this.record({ type: 'tool_result', content: safe, toolName: edge.toolName })
+    try { this.sink?.cost?.({ point: 'afterToolReceipt', at: this.clock(), ticketId: this.ticketId, stepIndex, toolName: edge.toolName, resultChars: safe.length, truncated: false }) } catch { /* ignore */ }
+    return true
+  }
   getLatestStep(): WorkerStep | null {
     return this.steps.length > 0 ? this.steps[this.steps.length - 1] : null
   }
@@ -393,6 +768,67 @@ export class SuperAgentWorker {
       tokenUsage: this.tokenUsage,
       elapsedMs: Math.max(0, this.clock() - this.startedAt),
       ...(this.prDelivery ? { pr: this.prDelivery } : {}),
+      cost: {
+        compaction: {
+          mode: this.modules.describe().find((item) => item.id === 'a1-compact')?.mode ?? 'off',
+          ...this.compactionStats,
+          estimatedTokens: this.compactionStats.savedChars > 0 ? Math.ceil(this.compactionStats.savedChars / 4) : 0,
+        },
+        ...(this.degradedEvents.size > 0
+          ? {
+              degraded: {
+                count: [...this.degradedEvents.values()].reduce((sum, event) => sum + event.count, 0),
+                events: [...this.degradedEvents.values()].map((event) => ({ ...event })),
+              },
+            }
+          : {}),
+        tokens: {
+          measured: this.measuredUsageTokens,
+          estimated: this.estimatedUsageTokens,
+        },
+        disclosure: ((): { enabled: boolean; residentCount: number; loaded: string[]; loadEvents: number; schemaTokens: number; schemaCount: number } => {
+          const stats = this.disclosure.stats()
+          const visible = this.disclosure.visible(this.registry.names())
+          return {
+            enabled: this.disclosure.enabled,
+            residentCount: this.disclosure.enabled ? visible.length : this.registry.names().length,
+            loaded: stats.loaded,
+            loadEvents: stats.loadEvents,
+            schemaTokens: stats.schemaTokens,
+            schemaCount: stats.schemaCount,
+          }
+        })(),
+        batch: (() => {
+          const status = this.batch.status()
+          const stats = this.batch.stats()
+          return { state: status.state, reason: status.reason, mode: status.mode, taught: stats.taught, corrections: stats.corrections }
+        })(),
+        ccs: (() => {
+          const guardStats = this.gdr.stats()
+          return {
+            mode: this.ccsPolicy.mode,
+            skippedModelCalls: this.skippedModelCalls,
+            attempts: this.reuseAttempts.map((attempt) => ({ ...attempt })),
+            shadowCertificates: this.shadowCertificates.map((cert) => ({ ...cert })),
+            substitutions: this.substitutions.map((cert) => ({ ...cert })),
+            guard: { matches: guardStats.matches, hits: guardStats.hits, hitRate: guardStats.hitRate, byReason: { ...guardStats.byReason } },
+          }
+        })(),
+        ...((): { toolPrompt?: WorkerResult['cost'] extends undefined ? never : { moduleTokens: number; moduleSchemas: number; schemaTokens: number; schemaCount: number } } => {
+          // §6：工具面常驻成本 = 模块自报 + 实际注入 schema（chars/4）。
+          const moduleCost = this.modules.promptCost()
+          const schemas = this.registry.schemas()
+          const schemaChars = JSON.stringify(schemas).length
+          return {
+            toolPrompt: {
+              moduleTokens: moduleCost.toolTokens,
+              moduleSchemas: moduleCost.schemaCount,
+              schemaTokens: Math.ceil(schemaChars / 4),
+              schemaCount: schemas.length,
+            },
+          }
+        })(),
+      },
       error,
     }
   }
@@ -422,9 +858,10 @@ export class SuperAgentWorker {
       }, this.limits.llmTimeoutMs)
     })
     const request = {
-      model: this.model,
+      model: this.callModel ?? this.model,
       messages: this.history,
-      tools: this.registry.schemas(),
+      // A2：只注入当前可见的工具 schema（常驻 + 已加载）；关闭时不做任何过滤。
+      tools: this.registry.schemas().filter((schema) => this.disclosure.visible(this.registry.names()).includes(schema.name)),
       signal: controller.signal,
     }
     try {

package/worker/baseline-fit.ts

@@ -0,0 +1,80 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+
+/**
+ * 3.3.0 · A1 归因拟合式（设计 §5.4，**冻结参数**）。
+ *
+ * 归因算法（工具面）：
+ *
+ *     savedTokens = baselineOutputTokens(toolName, 原始长度) − actualOutputTokens(紧凑长度)
+ *
+ * `baselineOutputTokens` 由本文件的**固定拟合式**给出，参数在
+ * `docs/DESIGN-v3.3.0-cost-optimization.md` §5.4.1 冻结；**变更参数必须同步升版本号
+ * 并在 CHANGELOG 声明**，否则 `test/worker-baseline-fit.test.ts` 会失败。
+ *
+ * 公式（v1）：
+ *
+ *     baseline = ceil((chars + overheadChars[toolName]) / charsPerToken)
+ *     actual   = ceil(chars / charsPerToken)
+ *
+ * 其中 overhead 只补偿工具回执的**结构性固定开销**（如 shell 回执的 `STDOUT:/STDERR:` 头），
+ * 不是「估算魔法」：它必须能从工具的固定输出模板直接数出来。
+ */
+
+/** 拟合式版本；改参数必须同时改这里（测试会锁死这一约定）。 */
+export const A1_FIT_VERSION = 'a1-fit-v1'
+
+export interface A1FitParams {
+  version: string
+  charsPerToken: number
+  /** 每个工具的固定结构开销（字符）。必须是「模板里数得出来」的常量。 */
+  overheadChars: Record<string, number>
+  defaultOverheadChars: number
+}
+
+export const A1_FIT_PARAMS: A1FitParams = Object.freeze({
+  version: A1_FIT_VERSION,
+  charsPerToken: 4,
+  overheadChars: Object.freeze({
+    fs_read_file: 0,
+    fs_list_dir: 0,
+    fs_write_file: 0,
+    // exec_shell_in_vm 的回执固定带 "STDOUT:\n"（8）+ "\nSTDERR:\n"（9）+ 末尾换行（1）
+    exec_shell_in_vm: 18,
+  }) as Record<string, number>,
+  defaultOverheadChars: 0,
+})
+
+const nonNegative = (value: unknown): number => {
+  const n = Number(value)
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : 0
+}
+
+function overheadOf(toolName: string): number {
+  const key = String(toolName ?? '')
+  const table = A1_FIT_PARAMS.overheadChars
+  return Object.prototype.hasOwnProperty.call(table, key) ? table[key] : A1_FIT_PARAMS.defaultOverheadChars
+}
+
+/** baseline：不经 A1 时模型会看到的回执 token 数（拟合式，v1 冻结）。 */
+export function baselineOutputTokens(toolName: string, rawChars: number): number {
+  const chars = nonNegative(rawChars)
+  if (chars === 0) return 0
+  return Math.ceil((chars + overheadOf(toolName)) / A1_FIT_PARAMS.charsPerToken)
+}
+
+/** actual：紧凑后模型实际看到的回执 token 数。 */
+export function actualOutputTokens(compactChars: number): number {
+  const chars = nonNegative(compactChars)
+  if (chars === 0) return 0
+  return Math.ceil(chars / A1_FIT_PARAMS.charsPerToken)
+}
+
+/**
+ * 单次工具的归因节省（永不为负：紧凑后更长时记 0，并由调用方标 `applied: false`）。
+ */
+export function attributedSavedTokens(toolName: string, rawChars: number, compactChars: number): number {
+  const baseline = baselineOutputTokens(toolName, rawChars)
+  const actual = actualOutputTokens(compactChars)
+  return Math.max(0, baseline - actual)
+}