@twinsearth/dsh-master 3.2.10 → 3.3.0

package/worker/types.ts

@@ -88,6 +88,8 @@ export interface LLMUsage {
   promptTokens?: number
   completionTokens?: number
   totalTokens?: number
+  /** §11：provider 若返回缓存命中（prompt cache），透传给账本；未返回则省略。 */
+  cachedTokens?: number
 }
 
 export interface LLMResponse {
@@ -133,6 +135,8 @@ export interface WorkerTool {
   name: string
   description: string
   parameters: Record<string, unknown>
+  /** §11：破坏性动作（写文件/执行命令/建 PR）默认不得进入 EDG 复用池（不变量 I3）。 */
+  destructive?: boolean
   execute(args: Record<string, unknown>, context: ToolExecutionContext): Promise<string>
 }
 
@@ -176,6 +180,91 @@ export interface WorkerSink {
   phase?(phase: WorkerPhase): void
   /** 流式片段（无真实 streaming 时按块模拟；宿主可转发到 UI）。 */
   stream?(delta: { content?: string; toolName?: string }): void
+  /** 3.3.0 成本观测事件（只读；宿主/路由用于记账，不参与控制流）。 */
+  cost?(event: CostHookEvent): void
+}
+
+/* ------------------------------------------------------------------ *
+ * 3.3.0 成本切点（M1，observe-only）
+ *
+ * 这是 Worker 内**唯一**的成本观测面：四个函数只在对应时机发出结构化事件，
+ * 不改变状态机、预算判定或工具执行；实现方（createCostHooks）负责吞掉所有异常，
+ * 保证「省钱可以失败，执行不能受影响」。
+ * ------------------------------------------------------------------ */
+
+export type CostHookPoint =
+  | 'beforeModelCall'
+  | 'afterModelResponse'
+  | 'beforeToolDispatch'
+  | 'afterToolReceipt'
+  | 'degraded'
+
+export interface WorkerCostUsage {
+  input: number
+  output: number
+  total: number
+}
+
+export interface CostHookEvent {
+  point: CostHookPoint
+  at: number
+  ticketId: string
+  stepIndex: number
+  model?: string
+  usage?: WorkerCostUsage
+  latencyMs?: number
+  historyChars?: number
+  toolName?: string
+  argsChars?: number
+  resultChars?: number
+  truncated?: boolean
+  /** 3.3.0 M2 · A1 紧凑化的实测归因（shadow 时 applied=false）。 */
+  compaction?: {
+    module: 'a1-compact'
+    mode: string
+    applicable: boolean
+    applied: boolean
+    originalChars: number
+    compactChars: number
+    savedChars: number
+    estimatedTokens: number
+  }
+  /** 3.3.0 目标 2.1-5：模块异常导致的降级（必须留痕，不得伪装成节省）。 */
+  degraded?: {
+    module: string
+    phase: 'beforeDispatch' | 'afterReceipt' | 'author' | 'guard' | 'substitute' | 'beforeModelCall' | 'afterModelResponse'
+    message: string
+    count: number
+  }
+  /** 3.3.0 §6：工具面常驻成本（模块自报 + 实际 schema），供 prompt 成本报表。 */
+  toolPrompt?: {
+    /** 各 A 模块自报的常驻工具面成本。 */
+    moduleTokens: number
+    moduleSchemas: number
+    /** 本次 Worker 实际注入的工具 schema 成本（chars/4）。 */
+    schemaTokens: number
+    schemaCount: number
+  }
+  /** 3.3.0 §6 A2：渐进式纰漏的加载成本（记 governance，不算节省）。 */
+  disclosure?: {
+    enabled: boolean
+    residentCount: number
+    loaded: string[]
+    loadEvents: number
+    schemaTokens: number
+    schemaCount: number
+  }
+  /** 3.3.0 §5.1：本次 usage 是兜底估算（provider 未返回），报表须与实测分列。 */
+  estimated?: boolean
+}
+
+export interface CostHooks {
+  beforeModelCall(input: { ticketId: string; stepIndex: number; model?: string; historyChars: number }): void
+  afterModelResponse(input: { ticketId: string; stepIndex: number; usage?: WorkerCostUsage; latencyMs: number; estimated?: boolean }): void
+  beforeToolDispatch(input: { ticketId: string; stepIndex: number; toolName: string; argsChars: number }): void
+  afterToolReceipt(input: { ticketId: string; stepIndex: number; toolName: string; resultChars: number; truncated: boolean; compaction?: CostHookEvent['compaction'] }): void
+  /** 模块异常降级：留痕但不中断执行（目标 2.1-5）。 */
+  degraded(input: { ticketId: string; stepIndex: number; module: string; phase: 'beforeDispatch' | 'afterReceipt' | 'author' | 'guard' | 'substitute' | 'beforeModelCall' | 'afterModelResponse'; message: string; count: number }): void
 }
 
 export interface WorkerDeps {
@@ -196,6 +285,34 @@ export interface WorkerDeps {
   model?: string
   /** 需要从日志/步骤中抹掉的具体 secret 值（如 LLM key）；正则脱敏之外的兜底。 */
   redactValues?: string[]
+  /** 取消信号：中止任务（含替换路径）。 */
+  signal?: AbortSignal
+  /** 3.3.0：可注入的成本钩子覆盖（测试/宿主自定义）；默认由 sink.cost 输出。 */
+  costHooks?: Partial<CostHooks>
+  /** 3.3.0 M2：工具输出紧凑化模式（off/shadow/enforce）；默认读 DSH_MASTER_COMPACT_MODE，缺省 shadow。 */
+  compactMode?: string
+  /** 3.3.0 模块层：额外注册的 A/B 类模块（按 SPI；内置 A1 已自动注册）。 */
+  costModules?: import('./cost-spi.ts').CostModule[]
+  /** 3.3.0 §5.2：① 预算闸配置（默认关闭；也可由 DSH_MASTER_BUDGET_* 环境变量启用）。 */
+  budget?: import('./budget-guard.ts').WorkerBudgetOptions
+  /** 3.3.0 §6 A2：渐进式纰漏配置（默认关闭 ⇒ 全量工具面；也可由 DSH_MASTER_DISCLOSURE=on 启用）。 */
+  disclosure?: import('./tool-disclosure.ts').DisclosureOptions
+  /** 3.3.0 §6 A3：批量调用引导（默认启用；PTC 模式未实现 ⇒ 显式 skipped）。 */
+  batch?: import('./tool-batch.ts').BatchOptions
+  /**
+   * 3.3.0 §7 B3：认证回调替换（CCS）。默认不配置 ⇒ 完全不替换，行为与 3.2.x 一致。
+   * 只有同时给出决策图与 `mode:'enforce'`（且白名单放行）才会真的跳过模型回调。
+   */
+  ccs?: {
+    graph: import('./edg.ts').EdgGraph
+    mode?: 'off' | 'shadow' | 'enforce'
+    allowlist?: string[]
+    forkId?: string
+    /** 跳过一次模型回调的预估 token（归因用）。 */
+    reserveTokens?: number
+    /** I3：显式允许破坏性工具进复用池（默认 false）。 */
+    allowDestructive?: boolean
+  }
 }
 
 export interface WorkerFailure {
@@ -222,6 +339,80 @@ export interface WorkerResult {
     draft?: boolean
     files?: Array<{ path: string; content: string }>
   }
+  /** 3.3.0 M2：本次任务的成本归因汇总（A1 紧凑化；shadow 时只记「本可节省」）。 */
+  cost?: {
+    compaction: {
+      mode: string
+      evaluated: number
+      applied: number
+      originalChars: number
+      compactChars: number
+      savedChars: number
+      estimatedTokens: number
+    }
+    /** 3.3.0 目标 2.1-5：本次任务发生过的降级（不伪装成节省）。 */
+    degraded?: {
+      count: number
+      events: Array<{ module: string; phase: string; message: string; count: number }>
+    }
+    /** 3.3.0 §5.1：实测与估算分开上报（provider 未返回 usage 时标记 estimated）。 */
+    tokens?: {
+      measured: number
+      estimated: number
+    }
+    /** 3.3.0 §6：工具面常驻成本（模块自报 + 实际注入 schema）。 */
+    toolPrompt?: {
+      moduleTokens: number
+      moduleSchemas: number
+      schemaTokens: number
+      schemaCount: number
+    }
+    /** 3.3.0 §6 A2：渐进式纰漏的加载成本（记 governance，不算节省）。 */
+    disclosure?: {
+      enabled: boolean
+      residentCount: number
+      loaded: string[]
+      loadEvents: number
+      schemaTokens: number
+      schemaCount: number
+    }
+    /** 3.3.0 §6 A3：批量引导状态（skipped 时显式给出原因）。 */
+    batch?: {
+      state: 'active' | 'skipped'
+      reason: string | null
+      mode: string
+      taught: boolean
+      corrections: number
+    }
+    /** 3.3.0 §7 B3/M3：替换结果、守卫尝试与「本可节省」证据。 */
+    ccs?: {
+      mode: string
+      skippedModelCalls: number
+      /** M3：每次复用尝试（命中率分母）。 */
+      attempts: Array<{ toolName: string; hit: boolean; reason: string | null; stage: string | null; edgeId: string | null; wouldSaveTokens: number; stepIndex: number }>
+      /** M3：shadow 下算出的「本可替换」证书（未派发）。 */
+      shadowCertificates: Array<Record<string, unknown>>
+      substitutions: Array<{
+        edgeId: string
+        toolName: string
+        schemaHash: string
+        guardExpr: string
+        receiptDigest: string
+        replacedCallbackId: string
+        viaNativeDispatcher: true
+        taskId: string
+        step: number
+        dispatched: boolean
+        error?: string
+        resultDigest?: string
+        resultChars?: number
+        savedTokens?: number
+        moduleId?: string
+        at: number
+      }>
+      guard: { matches: number; hits: number; hitRate: number; byReason: Record<string, number> }
+    }
+  }
 }
 
 export interface WorkerSnapshot {