@octopi-agent/engine 0.70.7 → 0.86.38

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (362) hide show
  1. package/LICENSE +201 -201
  2. package/NOTICE +7 -7
  3. package/README.md +64 -26
  4. package/dist/config-schema/agent.d.ts +89 -1
  5. package/dist/config-schema/agent.js +69 -0
  6. package/dist/config-schema/context.d.ts +23 -4
  7. package/dist/config-schema/context.js +28 -1
  8. package/dist/config-schema/engine.d.ts +201 -9
  9. package/dist/config-schema/engine.js +31 -2
  10. package/dist/config-schema/governance.d.ts +95 -0
  11. package/dist/config-schema/governance.js +91 -0
  12. package/dist/config-schema/models.d.ts +1 -1
  13. package/dist/config-schema/observability.d.ts +6 -0
  14. package/dist/config-schema/observability.js +16 -0
  15. package/dist/config-schema/run.d.ts +10 -0
  16. package/dist/config-schema/run.js +18 -0
  17. package/dist/config-schema/shared.d.ts +10 -0
  18. package/dist/config-schema/shared.js +10 -0
  19. package/dist/config-schema/substrate.d.ts +1 -1
  20. package/dist/config-schema/subsystems.d.ts +1 -1
  21. package/dist/config-schema/subsystems.js +2 -1
  22. package/dist/config.d.ts +178 -7
  23. package/dist/config.js +113 -3
  24. package/dist/harness/activation/compiler.js +3 -0
  25. package/dist/harness/activation/runtime.d.ts +7 -0
  26. package/dist/harness/activation/runtime.js +60 -2
  27. package/dist/harness/activation/sources/agent-signal.d.ts +11 -0
  28. package/dist/harness/activation/sources/agent-signal.js +33 -0
  29. package/dist/harness/activation/types.d.ts +6 -1
  30. package/dist/harness/agent/builder.d.ts +47 -3
  31. package/dist/harness/agent/builder.js +180 -54
  32. package/dist/harness/agent/config-bridge.d.ts +33 -25
  33. package/dist/harness/agent/config-bridge.js +81 -291
  34. package/dist/harness/agent/index.d.ts +3 -1
  35. package/dist/harness/agent/index.js +2 -1
  36. package/dist/harness/agent/tool-purpose.d.ts +38 -0
  37. package/dist/harness/agent/tool-purpose.js +118 -0
  38. package/dist/harness/agent/wire-agent-builder.d.ts +133 -0
  39. package/dist/harness/agent/wire-agent-builder.js +363 -0
  40. package/dist/harness/collaboration/autonomous-subsystem/runtime.d.ts +4 -1
  41. package/dist/harness/collaboration/autonomous-subsystem/runtime.js +14 -8
  42. package/dist/harness/collaboration/autonomous-subsystem/sense/metrics.d.ts +12 -0
  43. package/dist/harness/collaboration/autonomous-subsystem/sense/metrics.js +19 -0
  44. package/dist/harness/collaboration/autonomous-subsystem/sense/session-lifecycle-bridge.d.ts +6 -0
  45. package/dist/harness/collaboration/autonomous-subsystem/sense/session-lifecycle-bridge.js +24 -7
  46. package/dist/harness/collaboration/autonomous-subsystem/think/executor.d.ts +5 -2
  47. package/dist/harness/collaboration/autonomous-subsystem/think/executor.js +11 -3
  48. package/dist/harness/collaboration/autonomous-subsystem/think/index.d.ts +1 -1
  49. package/dist/harness/collaboration/autonomous-subsystem/think/index.js +1 -1
  50. package/dist/harness/collaboration/autonomous-subsystem/think/llm-port.d.ts +7 -4
  51. package/dist/harness/collaboration/autonomous-subsystem/think/llm-port.js +8 -9
  52. package/dist/harness/collaboration/autonomous-subsystem/think/model-resolver.d.ts +36 -10
  53. package/dist/harness/collaboration/autonomous-subsystem/think/model-resolver.js +60 -7
  54. package/dist/harness/collaboration/delegation/child-run.d.ts +144 -0
  55. package/dist/harness/collaboration/delegation/child-run.js +241 -0
  56. package/dist/harness/collaboration/delegation/index.d.ts +26 -0
  57. package/dist/harness/collaboration/delegation/index.js +25 -0
  58. package/dist/harness/collaboration/delegation/notifier.d.ts +46 -0
  59. package/dist/harness/collaboration/delegation/notifier.js +84 -0
  60. package/dist/harness/collaboration/delegation/registry-types.d.ts +200 -0
  61. package/dist/harness/collaboration/delegation/registry-types.js +61 -0
  62. package/dist/harness/collaboration/delegation/registry.d.ts +110 -0
  63. package/dist/harness/collaboration/delegation/registry.js +220 -0
  64. package/dist/harness/collaboration/delegation/service.d.ts +249 -0
  65. package/dist/harness/collaboration/delegation/service.js +499 -0
  66. package/dist/harness/collaboration/delegation/store.d.ts +155 -0
  67. package/dist/harness/collaboration/delegation/store.js +271 -0
  68. package/dist/harness/collaboration/delegation/transport.d.ts +73 -0
  69. package/dist/harness/collaboration/delegation/transport.js +61 -0
  70. package/dist/harness/collaboration/delegation/types.d.ts +231 -0
  71. package/dist/harness/collaboration/delegation/types.js +70 -0
  72. package/dist/harness/collaboration/delegation/wiring.d.ts +111 -0
  73. package/dist/harness/collaboration/delegation/wiring.js +145 -0
  74. package/dist/harness/collaboration/orchestration/index.d.ts +11 -13
  75. package/dist/harness/collaboration/orchestration/index.js +11 -11
  76. package/dist/harness/context/assembler.d.ts +2 -2
  77. package/dist/harness/context/assembler.js +12 -7
  78. package/dist/harness/context/capabilities/compact/engine.js +80 -38
  79. package/dist/harness/context/capabilities/compact/types.d.ts +12 -1
  80. package/dist/harness/context/capabilities/summary/registry.js +10 -0
  81. package/dist/harness/context/constitution/default-agents.md +230 -228
  82. package/dist/harness/context/default-context-engine.d.ts +101 -23
  83. package/dist/harness/context/default-context-engine.js +483 -172
  84. package/dist/harness/context/hybrid-compressor.d.ts +3 -3
  85. package/dist/harness/context/hybrid-compressor.js +18 -23
  86. package/dist/harness/context/index.d.ts +5 -1
  87. package/dist/harness/context/index.js +2 -0
  88. package/dist/harness/context/layer-snapshot.d.ts +4 -0
  89. package/dist/harness/context/layer-snapshot.js +30 -18
  90. package/dist/harness/context/layer-types.d.ts +49 -1
  91. package/dist/harness/context/layer-types.js +72 -4
  92. package/dist/harness/context/layers.d.ts +5 -2
  93. package/dist/harness/context/layers.js +11 -5
  94. package/dist/harness/context/llm-summarizer.d.ts +15 -1
  95. package/dist/harness/context/llm-summarizer.js +107 -56
  96. package/dist/harness/context/message-selector.js +6 -2
  97. package/dist/harness/context/root-instructions.d.ts +72 -0
  98. package/dist/harness/context/root-instructions.js +227 -0
  99. package/dist/harness/context/runtime-datetime.d.ts +34 -7
  100. package/dist/harness/context/runtime-datetime.js +66 -10
  101. package/dist/harness/context/smart-router.d.ts +1 -1
  102. package/dist/harness/context/smart-router.js +1 -1
  103. package/dist/harness/context/system-prompt-assembler.d.ts +30 -0
  104. package/dist/harness/context/system-prompt-assembler.js +67 -6
  105. package/dist/harness/context/token-constants.d.ts +2 -2
  106. package/dist/harness/context/token-constants.js +2 -2
  107. package/dist/harness/context/token-estimate-fns.d.ts +1 -3
  108. package/dist/harness/context/token-estimate-fns.js +2 -4
  109. package/dist/harness/context/token-estimator.d.ts +1 -1
  110. package/dist/harness/context/token-estimator.js +14 -6
  111. package/dist/harness/context/tool-result-aging.d.ts +140 -0
  112. package/dist/harness/context/tool-result-aging.js +331 -0
  113. package/dist/harness/context/tool-result-body.d.ts +10 -0
  114. package/dist/harness/context/tool-result-body.js +27 -0
  115. package/dist/harness/context/turn-envelope.d.ts +123 -0
  116. package/dist/harness/context/turn-envelope.js +188 -0
  117. package/dist/harness/context/types.d.ts +35 -47
  118. package/dist/harness/extension/execution-environment/effect-policy.d.ts +248 -0
  119. package/dist/harness/extension/execution-environment/effect-policy.js +334 -0
  120. package/dist/harness/extension/execution-environment/index.d.ts +18 -2
  121. package/dist/harness/extension/execution-environment/index.js +11 -2
  122. package/dist/harness/extension/execution-environment/memory-undo.d.ts +101 -0
  123. package/dist/harness/extension/execution-environment/memory-undo.js +192 -0
  124. package/dist/harness/extension/execution-environment/process-isolation.d.ts +84 -0
  125. package/dist/harness/extension/execution-environment/process-isolation.js +315 -0
  126. package/dist/harness/extension/execution-environment/resource-limits.d.ts +36 -0
  127. package/dist/harness/extension/execution-environment/resource-limits.js +84 -0
  128. package/dist/harness/extension/execution-environment/sandbox.d.ts +125 -4
  129. package/dist/harness/extension/execution-environment/sandbox.js +493 -51
  130. package/dist/harness/extension/execution-environment/shell-journal.d.ts +100 -0
  131. package/dist/harness/extension/execution-environment/shell-journal.js +299 -0
  132. package/dist/harness/extension/execution-environment/tool-capabilities.d.ts +45 -0
  133. package/dist/harness/extension/execution-environment/tool-capabilities.js +126 -0
  134. package/dist/harness/extension/execution-environment/types.d.ts +67 -39
  135. package/dist/harness/extension/execution-environment/types.js +2 -2
  136. package/dist/harness/extension/execution-environment/undo-log.d.ts +203 -0
  137. package/dist/harness/extension/execution-environment/undo-log.js +627 -0
  138. package/dist/harness/extension/execution-environment/undo-merge.d.ts +40 -0
  139. package/dist/harness/extension/execution-environment/undo-merge.js +167 -0
  140. package/dist/harness/extension/plugin-ecosystem/client-tools/index.d.ts +1 -1
  141. package/dist/harness/extension/plugin-ecosystem/client-tools/types.d.ts +9 -0
  142. package/dist/harness/extension/plugin-ecosystem/mcp/bridge.js +2 -0
  143. package/dist/harness/extension/plugin-ecosystem/plugins/api.d.ts +1 -6
  144. package/dist/harness/extension/plugin-ecosystem/plugins/api.js +3 -8
  145. package/dist/harness/extension/plugin-ecosystem/plugins/capability.d.ts +0 -3
  146. package/dist/harness/extension/plugin-ecosystem/plugins/capability.js +0 -3
  147. package/dist/harness/extension/plugin-ecosystem/plugins/entry.d.ts +2 -10
  148. package/dist/harness/extension/plugin-ecosystem/plugins/entry.js +2 -9
  149. package/dist/harness/extension/plugin-ecosystem/plugins/index.d.ts +1 -3
  150. package/dist/harness/extension/plugin-ecosystem/plugins/index.js +1 -3
  151. package/dist/harness/extension/plugin-ecosystem/plugins/loader.d.ts +2 -4
  152. package/dist/harness/extension/plugin-ecosystem/plugins/loader.js +4 -21
  153. package/dist/harness/extension/plugin-ecosystem/plugins/manager.d.ts +3 -9
  154. package/dist/harness/extension/plugin-ecosystem/plugins/manager.js +4 -8
  155. package/dist/harness/extension/plugin-ecosystem/plugins/manifest.d.ts +1 -4
  156. package/dist/harness/extension/plugin-ecosystem/plugins/manifest.js +1 -3
  157. package/dist/harness/extension/plugin-ecosystem/skills/manager.d.ts +1 -1
  158. package/dist/harness/extension/plugin-ecosystem/skills/manager.js +1 -1
  159. package/dist/harness/extension/plugin-ecosystem/tools/allowlisted-run.d.ts +45 -0
  160. package/dist/harness/extension/plugin-ecosystem/tools/allowlisted-run.js +136 -0
  161. package/dist/harness/extension/plugin-ecosystem/tools/ask-user.js +1 -0
  162. package/dist/harness/extension/plugin-ecosystem/tools/builtin.d.ts +18 -3
  163. package/dist/harness/extension/plugin-ecosystem/tools/builtin.js +277 -81
  164. package/dist/harness/extension/plugin-ecosystem/tools/delegation.d.ts +31 -0
  165. package/dist/harness/extension/plugin-ecosystem/tools/delegation.js +291 -0
  166. package/dist/harness/extension/plugin-ecosystem/tools/document-tools.js +10 -2
  167. package/dist/harness/extension/plugin-ecosystem/tools/env-info.js +1 -0
  168. package/dist/harness/extension/plugin-ecosystem/tools/eol.d.ts +35 -0
  169. package/dist/harness/extension/plugin-ecosystem/tools/eol.js +43 -0
  170. package/dist/harness/extension/plugin-ecosystem/tools/file-edit.js +40 -9
  171. package/dist/harness/extension/plugin-ecosystem/tools/file-ops.d.ts +33 -0
  172. package/dist/harness/extension/plugin-ecosystem/tools/file-ops.js +376 -0
  173. package/dist/harness/extension/plugin-ecosystem/tools/file-search.d.ts +12 -2
  174. package/dist/harness/extension/plugin-ecosystem/tools/file-search.js +239 -61
  175. package/dist/harness/extension/plugin-ecosystem/tools/git-tools.d.ts +27 -0
  176. package/dist/harness/extension/plugin-ecosystem/tools/git-tools.js +554 -0
  177. package/dist/harness/extension/plugin-ecosystem/tools/http.d.ts +10 -6
  178. package/dist/harness/extension/plugin-ecosystem/tools/http.js +41 -47
  179. package/dist/harness/extension/plugin-ecosystem/tools/index.d.ts +2 -0
  180. package/dist/harness/extension/plugin-ecosystem/tools/index.js +2 -0
  181. package/dist/harness/extension/plugin-ecosystem/tools/knowledge.js +4 -0
  182. package/dist/harness/extension/plugin-ecosystem/tools/memory.js +25 -1
  183. package/dist/harness/extension/plugin-ecosystem/tools/package-tools.d.ts +13 -0
  184. package/dist/harness/extension/plugin-ecosystem/tools/package-tools.js +391 -0
  185. package/dist/harness/extension/plugin-ecosystem/tools/platform.d.ts +51 -2
  186. package/dist/harness/extension/plugin-ecosystem/tools/platform.js +151 -12
  187. package/dist/harness/extension/plugin-ecosystem/tools/session-history.js +2 -0
  188. package/dist/harness/extension/plugin-ecosystem/tools/tool-bus.d.ts +10 -1
  189. package/dist/harness/extension/plugin-ecosystem/tools/tool-bus.js +35 -19
  190. package/dist/harness/extension/plugin-ecosystem/tools/tool-set.d.ts +8 -0
  191. package/dist/harness/extension/plugin-ecosystem/tools/tool-set.js +5 -0
  192. package/dist/harness/extension/plugin-ecosystem/tools/web-search.js +1 -0
  193. package/dist/harness/governance/credentials/index.d.ts +1 -1
  194. package/dist/harness/governance/credentials/store.d.ts +16 -4
  195. package/dist/harness/governance/credentials/store.js +33 -6
  196. package/dist/harness/governance/credentials/types.d.ts +11 -0
  197. package/dist/harness/governance/human-in-the-loop/decision-cache.d.ts +105 -0
  198. package/dist/harness/governance/human-in-the-loop/decision-cache.js +184 -0
  199. package/dist/harness/governance/human-in-the-loop/index.d.ts +5 -5
  200. package/dist/harness/governance/human-in-the-loop/index.js +3 -3
  201. package/dist/harness/governance/human-in-the-loop/types.d.ts +7 -62
  202. package/dist/harness/governance/human-in-the-loop/types.js +6 -2
  203. package/dist/harness/governance/security/capability-enforcer.d.ts +9 -1
  204. package/dist/harness/governance/security/capability-enforcer.js +31 -8
  205. package/dist/harness/governance/security/degradation.js +5 -7
  206. package/dist/harness/governance/security/risk-evaluator.d.ts +1 -1
  207. package/dist/harness/governance/security/risk-evaluator.js +4 -82
  208. package/dist/harness/governance/security/temp-path.d.ts +41 -0
  209. package/dist/harness/governance/security/temp-path.js +117 -0
  210. package/dist/harness/governance/session-acl/index.d.ts +1 -0
  211. package/dist/harness/governance/session-acl/index.js +1 -0
  212. package/dist/harness/governance/session-acl/rights.d.ts +12 -0
  213. package/dist/harness/governance/session-acl/rights.js +89 -7
  214. package/dist/harness/governance/session-acl/seed-roles.js +9 -1
  215. package/dist/harness/governance/session-acl/service.js +21 -29
  216. package/dist/harness/governance/session-acl/tool-rights.d.ts +81 -0
  217. package/dist/harness/governance/session-acl/tool-rights.js +238 -0
  218. package/dist/harness/governance/session-acl/types.d.ts +22 -0
  219. package/dist/harness/index.d.ts +14 -12
  220. package/dist/harness/index.js +9 -6
  221. package/dist/harness/knowledge/file-index-store.js +11 -11
  222. package/dist/harness/knowledge/grounding.d.ts +2 -1
  223. package/dist/harness/knowledge/grounding.js +6 -3
  224. package/dist/harness/knowledge/index.d.ts +2 -2
  225. package/dist/harness/knowledge/index.js +1 -1
  226. package/dist/harness/knowledge/ingest.js +4 -1
  227. package/dist/harness/knowledge/job-control-state.js +4 -4
  228. package/dist/harness/knowledge/job-control.js +11 -11
  229. package/dist/harness/knowledge/membership-store.js +11 -11
  230. package/dist/harness/knowledge/network-guard.d.ts +61 -4
  231. package/dist/harness/knowledge/network-guard.js +390 -113
  232. package/dist/harness/knowledge/query-service.js +3 -3
  233. package/dist/harness/knowledge/writer-service.d.ts +2 -0
  234. package/dist/harness/knowledge/writer-service.js +14 -13
  235. package/dist/harness/memory/backfill-trigger.d.ts +2 -2
  236. package/dist/harness/memory/backfill-trigger.js +4 -4
  237. package/dist/harness/memory/index.d.ts +1 -0
  238. package/dist/harness/memory/index.js +1 -0
  239. package/dist/harness/memory/sqlite/agent-db.js +2 -0
  240. package/dist/harness/memory/sqlite/memory-store.d.ts +1 -0
  241. package/dist/harness/memory/sqlite/memory-store.js +14 -4
  242. package/dist/harness/memory/sqlite/wisdom-store.js +9 -9
  243. package/dist/harness/memory/store.d.ts +1 -0
  244. package/dist/harness/memory/store.js +3 -0
  245. package/dist/harness/memory/time-format.d.ts +28 -0
  246. package/dist/harness/memory/time-format.js +52 -0
  247. package/dist/harness/memory/types.d.ts +12 -0
  248. package/dist/harness/observability/observer/hub.js +23 -1
  249. package/dist/harness/observability/observer/index.d.ts +2 -2
  250. package/dist/harness/observability/observer/index.js +1 -1
  251. package/dist/harness/observability/observer/types.d.ts +57 -0
  252. package/dist/harness/observability/observer/types.js +118 -9
  253. package/dist/harness/run/agent/agent.d.ts +18 -0
  254. package/dist/harness/run/agent/agent.js +26 -0
  255. package/dist/harness/run/concurrency/tool-loop-detection-core.d.ts +1 -1
  256. package/dist/harness/run/concurrency/tool-loop-detection-core.js +1 -1
  257. package/dist/harness/run/reliability/harness-events.d.ts +4 -0
  258. package/dist/harness/run/reliability/run-agent.js +110 -18
  259. package/dist/harness/run/reliability/run-metrics-collector.d.ts +28 -2
  260. package/dist/harness/run/reliability/run-metrics-collector.js +92 -2
  261. package/dist/harness/run/run-guard/default-run-guard.d.ts +0 -5
  262. package/dist/harness/run/run-guard/default-run-guard.js +104 -44
  263. package/dist/harness/run/run-scope.d.ts +52 -0
  264. package/dist/harness/run/runner.d.ts +101 -16
  265. package/dist/harness/run/runner.js +556 -158
  266. package/dist/harness/session/attachments/llm-intent.js +17 -17
  267. package/dist/harness/session/history/port.js +1 -0
  268. package/dist/harness/session/in-memory-store.d.ts +1 -0
  269. package/dist/harness/session/in-memory-store.js +22 -1
  270. package/dist/harness/session/schedules/index.d.ts +10 -0
  271. package/dist/harness/session/schedules/index.js +10 -0
  272. package/dist/harness/session/schedules/render.d.ts +13 -0
  273. package/dist/harness/session/schedules/render.js +63 -0
  274. package/dist/harness/session/schedules/service.d.ts +179 -0
  275. package/dist/harness/session/schedules/service.js +695 -0
  276. package/dist/harness/session/schedules/store.d.ts +119 -0
  277. package/dist/harness/session/schedules/store.js +323 -0
  278. package/dist/harness/session/schedules/tools.d.ts +39 -0
  279. package/dist/harness/session/schedules/tools.js +442 -0
  280. package/dist/harness/session/schedules/types.d.ts +104 -0
  281. package/dist/harness/session/schedules/types.js +97 -0
  282. package/dist/harness/session/tasks/tools.js +22 -0
  283. package/dist/harness/session/types.d.ts +35 -0
  284. package/dist/harness/shared/events/agent-event-map.d.ts +13 -0
  285. package/dist/harness/shared/types/agent-definition.d.ts +23 -0
  286. package/dist/index.d.ts +23 -9
  287. package/dist/index.js +10 -2
  288. package/dist/integration/providers/anthropic.d.ts +10 -0
  289. package/dist/integration/providers/anthropic.js +44 -1
  290. package/dist/integration/providers/openai.d.ts +10 -0
  291. package/dist/integration/providers/openai.js +58 -2
  292. package/dist/integration/providers/wire-dump-diff.d.ts +191 -0
  293. package/dist/integration/providers/wire-dump-diff.js +351 -0
  294. package/dist/integration/providers/wire-dump.d.ts +178 -0
  295. package/dist/integration/providers/wire-dump.js +396 -0
  296. package/dist/integration/storage/jsonl.d.ts +11 -0
  297. package/dist/integration/storage/jsonl.js +148 -39
  298. package/dist/integration/storage/session-index.js +63 -8
  299. package/dist/subsystems/cognition-steward/conceptualize/SUBSYSTEM.md +43 -43
  300. package/dist/subsystems/cognition-steward/conceptualize/config.yaml +50 -50
  301. package/dist/subsystems/cognition-steward/consolidate/SUBSYSTEM.md +6 -6
  302. package/dist/subsystems/cognition-steward/consolidate/config.yaml +54 -54
  303. package/dist/subsystems/memory-steward/backfill/handler.js +9 -0
  304. package/dist/subsystems/wisdom-steward/evaluate/config.yaml +50 -50
  305. package/dist/subsystems/wisdom-steward/formation/SUBSYSTEM.md +42 -42
  306. package/dist/subsystems/wisdom-steward/formation/config.yaml +54 -54
  307. package/dist/subsystems/wisdom-steward/govern/config.yaml +55 -55
  308. package/package.json +115 -115
  309. package/dist/harness/collaboration/multi-agent/agent-registry-types.d.ts +0 -144
  310. package/dist/harness/collaboration/multi-agent/agent-registry-types.js +0 -25
  311. package/dist/harness/collaboration/multi-agent/index.d.ts +0 -17
  312. package/dist/harness/collaboration/multi-agent/index.js +0 -15
  313. package/dist/harness/collaboration/multi-agent/process.d.ts +0 -167
  314. package/dist/harness/collaboration/multi-agent/process.js +0 -256
  315. package/dist/harness/collaboration/multi-agent/registry.d.ts +0 -36
  316. package/dist/harness/collaboration/multi-agent/registry.js +0 -137
  317. package/dist/harness/collaboration/multi-agent/swarm.d.ts +0 -135
  318. package/dist/harness/collaboration/multi-agent/swarm.js +0 -317
  319. package/dist/harness/collaboration/multi-agent/types.d.ts +0 -66
  320. package/dist/harness/collaboration/multi-agent/types.js +0 -15
  321. package/dist/harness/collaboration/orchestration/async-task-store.d.ts +0 -107
  322. package/dist/harness/collaboration/orchestration/async-task-store.js +0 -12
  323. package/dist/harness/collaboration/orchestration/async-task.d.ts +0 -156
  324. package/dist/harness/collaboration/orchestration/async-task.js +0 -359
  325. package/dist/harness/collaboration/orchestration/planner/hybrid-planner.d.ts +0 -47
  326. package/dist/harness/collaboration/orchestration/planner/hybrid-planner.js +0 -61
  327. package/dist/harness/collaboration/orchestration/planner/index.d.ts +0 -9
  328. package/dist/harness/collaboration/orchestration/planner/index.js +0 -6
  329. package/dist/harness/collaboration/orchestration/planner/llm-planner.d.ts +0 -54
  330. package/dist/harness/collaboration/orchestration/planner/llm-planner.js +0 -167
  331. package/dist/harness/collaboration/orchestration/planner/rule-planner.d.ts +0 -85
  332. package/dist/harness/collaboration/orchestration/planner/rule-planner.js +0 -175
  333. package/dist/harness/collaboration/orchestration/quality/classifier.d.ts +0 -21
  334. package/dist/harness/collaboration/orchestration/quality/classifier.js +0 -235
  335. package/dist/harness/collaboration/orchestration/quality/gate.d.ts +0 -29
  336. package/dist/harness/collaboration/orchestration/quality/gate.js +0 -409
  337. package/dist/harness/collaboration/orchestration/quality/index.d.ts +0 -9
  338. package/dist/harness/collaboration/orchestration/quality/index.js +0 -8
  339. package/dist/harness/collaboration/orchestration/quality/types.d.ts +0 -159
  340. package/dist/harness/collaboration/orchestration/quality/types.js +0 -33
  341. package/dist/harness/collaboration/orchestration/scheduler/index.d.ts +0 -5
  342. package/dist/harness/collaboration/orchestration/scheduler/index.js +0 -4
  343. package/dist/harness/collaboration/orchestration/scheduler/task-scheduler.d.ts +0 -143
  344. package/dist/harness/collaboration/orchestration/scheduler/task-scheduler.js +0 -297
  345. package/dist/harness/collaboration/orchestration/strategy/classifier.d.ts +0 -12
  346. package/dist/harness/collaboration/orchestration/strategy/classifier.js +0 -81
  347. package/dist/harness/collaboration/orchestration/strategy/index.d.ts +0 -3
  348. package/dist/harness/collaboration/orchestration/strategy/index.js +0 -2
  349. package/dist/harness/collaboration/orchestration/strategy/router.d.ts +0 -28
  350. package/dist/harness/collaboration/orchestration/strategy/router.js +0 -105
  351. package/dist/harness/collaboration/orchestration/strategy/types.d.ts +0 -49
  352. package/dist/harness/collaboration/orchestration/strategy/types.js +0 -4
  353. package/dist/harness/collaboration/orchestration/workflow/engine.d.ts +0 -86
  354. package/dist/harness/collaboration/orchestration/workflow/engine.js +0 -298
  355. package/dist/harness/collaboration/orchestration/workflow/index.d.ts +0 -9
  356. package/dist/harness/collaboration/orchestration/workflow/index.js +0 -7
  357. package/dist/harness/collaboration/orchestration/workflow/types.d.ts +0 -143
  358. package/dist/harness/collaboration/orchestration/workflow/types.js +0 -7
  359. package/dist/harness/governance/human-in-the-loop/approval-manager.d.ts +0 -32
  360. package/dist/harness/governance/human-in-the-loop/approval-manager.js +0 -93
  361. /package/dist/harness/collaboration/{multi-agent → delegation}/message-channel-types.d.ts +0 -0
  362. /package/dist/harness/collaboration/{multi-agent → delegation}/message-channel-types.js +0 -0
@@ -0,0 +1,191 @@
1
+ /**
2
+ * LLM Wire Dump — 前缀比对分析
3
+ *
4
+ * 读 `<dir>/<session>/index.jsonl`,按时间顺序把相邻两次调用逐条比对,
5
+ * 回答「前缀在哪一条消息、哪个字符断开」。
6
+ *
7
+ * 判据:前缀缓存只认最长公共前缀,因此相邻调用的 `messages` 序列逐单元 hash 比对
8
+ * 即是 provider 的缓存判据(tools 变化单独标记)。
9
+ *
10
+ * @module integration/providers/wire-dump-diff
11
+ */
12
+ import { type WireDumpRequestRecord, type WireDumpResultRecord } from './wire-dump.js';
13
+ /** 一次调用的合并视图(request 行 + 可选 result 行) */
14
+ export interface WireCallSummary {
15
+ request: WireDumpRequestRecord;
16
+ result?: WireDumpResultRecord;
17
+ /** body 文件是否仍存在(环形裁剪/oversize 后可能缺失) */
18
+ hasBody: boolean;
19
+ }
20
+ /** 相邻两次调用的前缀比对结果 */
21
+ export interface WirePrefixDiff {
22
+ /** identical:完全一致;append-only:纯追加;truncated:尾部被删;diverged:中部改写 */
23
+ stability: 'identical' | 'append-only' | 'truncated' | 'diverged';
24
+ /** 逐单元 hash 相同的单元数 */
25
+ commonPrefix: number;
26
+ appended: number;
27
+ removed: number;
28
+ /** 公共前缀在 next 侧的字符数(≈ 可命中缓存的输入量) */
29
+ stableChars: number;
30
+ /**
31
+ * 实际可复用缓存的前缀字符数
32
+ *
33
+ * tools / model 变化会让整段前缀缓存失效,此时为 0:Anthropic 文档明确缓存层级为
34
+ * tools → system → messages,OpenAI 的完整渲染上下文同样把工具定义排在消息之前。
35
+ * 仅消息前缀稳定不足以命中缓存。`mode` 变化不影响缓存,不参与此判定。
36
+ */
37
+ cacheableChars: number;
38
+ divergence?: {
39
+ index: number;
40
+ prevRole?: string;
41
+ nextRole?: string;
42
+ prevLen?: number;
43
+ nextLen?: number;
44
+ };
45
+ /**
46
+ * 断点之后仍有内容变化的单元数
47
+ *
48
+ * 单点改写(如上一轮 assistant 文本被用户编辑)为 0;历史批量老化(多条原文被替换为
49
+ * 指针)会远大于 0——这类批量改写即使断点靠前,实际失效范围也覆盖到尾部。
50
+ */
51
+ changedAfter: number;
52
+ toolsChanged: boolean;
53
+ modelChanged: boolean;
54
+ modeChanged: boolean;
55
+ }
56
+ /** 单条消息内部的字符级差异 */
57
+ export interface WireUnitDiffDetail {
58
+ index: number;
59
+ /** 单元内首个不同字符的偏移(0 = 单元开头即不同) */
60
+ offset: number;
61
+ prevSnippet: string;
62
+ nextSnippet: string;
63
+ }
64
+ /**
65
+ * 读取 session 目录里第一条 request 记录(用于按真实 sessionId 匹配被 sanitize 过的目录名)
66
+ *
67
+ * @param dirPath - session 目录
68
+ * @returns 首条 request 行;不存在时 null
69
+ */
70
+ export declare function readFirstWireDumpRequest(dirPath: string): WireDumpRequestRecord | null;
71
+ /**
72
+ * 读取单个 session 目录的 index.jsonl(request 与 result 按 id 合并、按时间排序)
73
+ *
74
+ * @param dirPath - session 目录(含 index.jsonl)
75
+ * @returns 调用摘要列表;无索引时返回空数组
76
+ */
77
+ export declare function readWireDumpIndex(dirPath: string): WireCallSummary[];
78
+ /**
79
+ * 列出 dump 根目录下的 session 目录(按 index.jsonl 更新时间倒序)
80
+ *
81
+ * @param rootDir - dump 根目录
82
+ * @returns session 目录列表
83
+ */
84
+ export declare function listWireDumpSessions(rootDir: string): Array<{
85
+ dir: string;
86
+ sessionId: string;
87
+ mtimeMs: number;
88
+ }>;
89
+ /**
90
+ * 读取一次调用的完整请求体
91
+ *
92
+ * @param dirPath - session 目录
93
+ * @param request - 索引中的 request 行
94
+ * @returns 请求体;缺失/损坏时 null
95
+ */
96
+ export declare function loadWireDumpBody(dirPath: string, request: WireDumpRequestRecord): Record<string, unknown> | null;
97
+ /**
98
+ * 比对相邻两次调用的前缀
99
+ *
100
+ * @param prev - 上一次调用
101
+ * @param next - 本次调用
102
+ * @returns 前缀比对结果
103
+ */
104
+ export declare function compareWireCalls(prev: WireCallSummary, next: WireCallSummary): WirePrefixDiff;
105
+ /** 老化扫描结果 */
106
+ export interface WireAgingReport {
107
+ /** prev 侧指针条数 */
108
+ prevPointers: number;
109
+ /** next 侧指针条数 */
110
+ nextPointers: number;
111
+ /**
112
+ * 本次新增的老化替换条数
113
+ *
114
+ * 统计「prev 侧该位置是原文、next 侧同一位置变成指针」的单元数——这正是前缀断裂
115
+ * 的真实来源,也是判断一次分歧是单点改写还是批量老化的依据。
116
+ */
117
+ agedInPlace: number;
118
+ /** 首个被老化的单元下标;无老化时 -1 */
119
+ firstAgedIndex: number;
120
+ /**
121
+ * 本次老化净减掉的字符数(原文长度 − 指针长度 + 参数收缩量)
122
+ *
123
+ * 这是老化带来的**持续收益**:此后每次调用都不必再发送这些字符。
124
+ */
125
+ agedCharsSaved: number;
126
+ /**
127
+ * 其中来自「工具调用参数摘要」的部分
128
+ *
129
+ * 参数老化发生在 assistant 单元内,不在「原文→指针」判定里,必须单独计息。
130
+ */
131
+ agedArgCharsSaved: number;
132
+ }
133
+ /** 老化回本判定输入 */
134
+ export interface WireAgingPaybackInput {
135
+ /** 老化净减掉的字符数 */
136
+ agedCharsSaved: number;
137
+ /** 本次因断点失效而必须重算的字符数(请求尾部) */
138
+ burnedChars: number;
139
+ /** 该调用的 tokens/char(由真实 usage 推算;缺省 1/3 粗估) */
140
+ tokensPerChar: number;
141
+ /** 缓存命中价格相对全价的比例(0.1 = 一折);0 表示无缓存 */
142
+ cacheDiscount: number;
143
+ /** 该次老化之后实际发生的调用次数(收益的真实摊薄面) */
144
+ callsAfter: number;
145
+ }
146
+ /** 老化回本判定结果 */
147
+ export interface WireAgingPayback {
148
+ savedTokens: number;
149
+ burnedTokens: number;
150
+ /** 回本所需调用次数(Infinity = 收益为零或无缓存,永远回不来) */
151
+ paybackCalls: number;
152
+ /**
153
+ * 是否已由后续调用回本
154
+ *
155
+ * 老化收益是**持续性**的(此后每次调用都少读),因此以「之后实际发生了多少次调用」
156
+ * 对比回本点。未回本不代表亏——只要 session 还会继续,差额最终会被摊掉。
157
+ */
158
+ repaid: boolean;
159
+ }
160
+ /**
161
+ * 统计两次调用之间的历史老化(原文 → 指针)情况
162
+ *
163
+ * @param prevBody - 上次调用的请求体
164
+ * @param nextBody - 本次调用的请求体
165
+ * @returns 老化统计;任一侧 body 缺失时 null
166
+ */
167
+ export declare function reportWireAging(prevBody: Record<string, unknown> | null, nextBody: Record<string, unknown> | null): WireAgingReport | null;
168
+ /**
169
+ * 估算一次老化的回本点
170
+ *
171
+ * 成本模型(把「老化」与「不老化」两条路径对比):
172
+ * - 老化路径:本次调用要把失效尾部按**全价**重算一次 → 额外成本 `burned × (1 − discount)`
173
+ * - 不老化路径:被老化的原文此后每次调用都要重新发送,且作为热前缀按 `discount` 计价
174
+ * → 每次调用节省 `saved × discount`
175
+ *
176
+ * 因此 `paybackCalls = burned × (1 − discount) / (saved × discount)`。
177
+ * discount=0.1(一折)时即 `9 × burned / saved`。
178
+ *
179
+ * @param input - 老化量 / 燃烧量 / 价格折扣 / 本轮调用次数
180
+ * @returns 回本判定;`paybackCalls` 为 Infinity 表示收益为零或无缓存
181
+ */
182
+ export declare function estimateAgingPayback(input: WireAgingPaybackInput): WireAgingPayback;
183
+ /**
184
+ * 定位单个前缀单元内部的字符级差异
185
+ *
186
+ * @param prevBody - 上次调用的请求体
187
+ * @param nextBody - 本次调用的请求体
188
+ * @param index - 分歧单元下标(来自 {@link compareWireCalls} 的 divergence.index)
189
+ * @returns 字符偏移与上下文片段;单元缺失时 null
190
+ */
191
+ export declare function explainWireDivergence(prevBody: Record<string, unknown>, nextBody: Record<string, unknown>, index: number): WireUnitDiffDetail | null;
@@ -0,0 +1,351 @@
1
+ /**
2
+ * LLM Wire Dump — 前缀比对分析
3
+ *
4
+ * 读 `<dir>/<session>/index.jsonl`,按时间顺序把相邻两次调用逐条比对,
5
+ * 回答「前缀在哪一条消息、哪个字符断开」。
6
+ *
7
+ * 判据:前缀缓存只认最长公共前缀,因此相邻调用的 `messages` 序列逐单元 hash 比对
8
+ * 即是 provider 的缓存判据(tools 变化单独标记)。
9
+ *
10
+ * @module integration/providers/wire-dump-diff
11
+ */
12
+ import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
13
+ import { join } from 'node:path';
14
+ import { wireUnitPayloads, } from './wire-dump.js';
15
+ /**
16
+ * 读取 session 目录里第一条 request 记录(用于按真实 sessionId 匹配被 sanitize 过的目录名)
17
+ *
18
+ * @param dirPath - session 目录
19
+ * @returns 首条 request 行;不存在时 null
20
+ */
21
+ export function readFirstWireDumpRequest(dirPath) {
22
+ const indexPath = join(dirPath, 'index.jsonl');
23
+ if (!existsSync(indexPath))
24
+ return null;
25
+ let head;
26
+ try {
27
+ // 只需靠前的行:截取前 64KB 足够覆盖若干条索引行
28
+ head = readFileSync(indexPath, 'utf8').slice(0, 65_536);
29
+ }
30
+ catch {
31
+ return null;
32
+ }
33
+ // 首行可能是 result 行、半行或损坏行:逐行找第一条能解析的 request
34
+ for (const line of head.split('\n')) {
35
+ if (!line.trim())
36
+ continue;
37
+ try {
38
+ const rec = JSON.parse(line);
39
+ if (rec.type === 'request')
40
+ return rec;
41
+ }
42
+ catch {
43
+ // 截断/损坏行(多半是 64KB 边界或进程被杀):跳过,继续找下一行
44
+ continue;
45
+ }
46
+ }
47
+ return null;
48
+ }
49
+ /**
50
+ * 读取单个 session 目录的 index.jsonl(request 与 result 按 id 合并、按时间排序)
51
+ *
52
+ * @param dirPath - session 目录(含 index.jsonl)
53
+ * @returns 调用摘要列表;无索引时返回空数组
54
+ */
55
+ export function readWireDumpIndex(dirPath) {
56
+ const indexPath = join(dirPath, 'index.jsonl');
57
+ if (!existsSync(indexPath))
58
+ return [];
59
+ const requests = [];
60
+ const results = new Map();
61
+ for (const line of readFileSync(indexPath, 'utf8').split('\n')) {
62
+ if (!line.trim())
63
+ continue;
64
+ let rec;
65
+ try {
66
+ rec = JSON.parse(line);
67
+ }
68
+ catch {
69
+ // 半行(进程被杀)无法解析:跳过,后续行仍可读
70
+ continue;
71
+ }
72
+ if (rec.type === 'request')
73
+ requests.push(rec);
74
+ else if (rec.type === 'result')
75
+ results.set(rec.id, rec);
76
+ }
77
+ requests.sort((a, b) => (a.at === b.at ? a.n - b.n : a.at - b.at));
78
+ return requests.map((request) => ({
79
+ request,
80
+ result: results.get(request.id),
81
+ hasBody: request.file != null && existsSync(join(dirPath, request.file)),
82
+ }));
83
+ }
84
+ /**
85
+ * 列出 dump 根目录下的 session 目录(按 index.jsonl 更新时间倒序)
86
+ *
87
+ * @param rootDir - dump 根目录
88
+ * @returns session 目录列表
89
+ */
90
+ export function listWireDumpSessions(rootDir) {
91
+ if (!existsSync(rootDir))
92
+ return [];
93
+ const out = [];
94
+ for (const name of readdirSync(rootDir)) {
95
+ const dir = join(rootDir, name);
96
+ try {
97
+ if (!statSync(dir).isDirectory())
98
+ continue;
99
+ }
100
+ catch {
101
+ continue;
102
+ }
103
+ const indexPath = join(dir, 'index.jsonl');
104
+ const mtimeMs = existsSync(indexPath) ? statSync(indexPath).mtimeMs : 0;
105
+ if (mtimeMs === 0)
106
+ continue;
107
+ out.push({ dir, sessionId: name, mtimeMs });
108
+ }
109
+ return out.sort((a, b) => b.mtimeMs - a.mtimeMs);
110
+ }
111
+ /**
112
+ * 读取一次调用的完整请求体
113
+ *
114
+ * @param dirPath - session 目录
115
+ * @param request - 索引中的 request 行
116
+ * @returns 请求体;缺失/损坏时 null
117
+ */
118
+ export function loadWireDumpBody(dirPath, request) {
119
+ if (!request.file)
120
+ return null;
121
+ try {
122
+ return JSON.parse(readFileSync(join(dirPath, request.file), 'utf8'));
123
+ }
124
+ catch {
125
+ return null;
126
+ }
127
+ }
128
+ /**
129
+ * 比对相邻两次调用的前缀
130
+ *
131
+ * @param prev - 上一次调用
132
+ * @param next - 本次调用
133
+ * @returns 前缀比对结果
134
+ */
135
+ export function compareWireCalls(prev, next) {
136
+ const a = prev.request;
137
+ const b = next.request;
138
+ const limit = Math.min(a.hashes.length, b.hashes.length);
139
+ let common = 0;
140
+ while (common < limit &&
141
+ a.hashes[common] === b.hashes[common] &&
142
+ a.roles[common] === b.roles[common]) {
143
+ common += 1;
144
+ }
145
+ const appended = b.hashes.length - common;
146
+ const removed = a.hashes.length - common;
147
+ const diverged = common < limit;
148
+ const stability = diverged
149
+ ? 'diverged'
150
+ : appended === 0 && removed === 0
151
+ ? 'identical'
152
+ : removed === 0
153
+ ? 'append-only'
154
+ : 'truncated';
155
+ let stableChars = 0;
156
+ for (let i = 0; i < common; i++)
157
+ stableChars += b.lens[i] ?? 0;
158
+ let changedAfter = 0;
159
+ for (let i = common; i < limit; i++) {
160
+ if (a.hashes[i] !== b.hashes[i])
161
+ changedAfter += 1;
162
+ }
163
+ const toolsChanged = a.toolsHash !== b.toolsHash;
164
+ const modelChanged = a.model !== b.model;
165
+ return {
166
+ stability,
167
+ commonPrefix: common,
168
+ appended,
169
+ removed,
170
+ stableChars,
171
+ // tools/model 在请求最前,一变就整段缓存失效——此时消息前缀再稳也命中不了
172
+ cacheableChars: toolsChanged || modelChanged ? 0 : stableChars,
173
+ divergence: diverged
174
+ ? {
175
+ index: common,
176
+ prevRole: a.roles[common],
177
+ nextRole: b.roles[common],
178
+ prevLen: a.lens[common],
179
+ nextLen: b.lens[common],
180
+ }
181
+ : undefined,
182
+ changedAfter,
183
+ toolsChanged,
184
+ modelChanged,
185
+ modeChanged: a.mode !== b.mode,
186
+ };
187
+ }
188
+ /** 历史老化指针的固定前缀(见 harness/context 的 aging 输出) */
189
+ const AGED_POINTER_MARKER = '[aged tool result · pointer]';
190
+ /**
191
+ * 统计两次调用之间的历史老化(原文 → 指针)情况
192
+ *
193
+ * @param prevBody - 上次调用的请求体
194
+ * @param nextBody - 本次调用的请求体
195
+ * @returns 老化统计;任一侧 body 缺失时 null
196
+ */
197
+ export function reportWireAging(prevBody, nextBody) {
198
+ if (!prevBody || !nextBody)
199
+ return null;
200
+ const prevUnits = wireUnitPayloads(prevBody);
201
+ const nextUnits = wireUnitPayloads(nextBody);
202
+ const isPointer = (text) => text.includes(AGED_POINTER_MARKER);
203
+ const prevPointers = prevUnits.filter((u) => isPointer(u.text)).length;
204
+ const nextPointers = nextUnits.filter((u) => isPointer(u.text)).length;
205
+ let agedInPlace = 0;
206
+ let firstAgedIndex = -1;
207
+ let agedCharsSaved = 0;
208
+ const limit = Math.min(prevUnits.length, nextUnits.length);
209
+ for (let i = 0; i < limit; i++) {
210
+ if (!isPointer(prevUnits[i].text) && isPointer(nextUnits[i].text)) {
211
+ agedInPlace += 1;
212
+ agedCharsSaved += prevUnits[i].text.length - nextUnits[i].text.length;
213
+ if (firstAgedIndex < 0)
214
+ firstAgedIndex = i;
215
+ }
216
+ }
217
+ // 参数老化(与结果同步降级):assistant 单元的 tool_call 参数也会缩短,
218
+ // 但这部分不在 tool 单元的「原文→指针」判定里,必须单独计息——否则回本点被高估。
219
+ const agedArgCharsSaved = measureArgShrink(prevBody, nextBody);
220
+ return {
221
+ prevPointers,
222
+ nextPointers,
223
+ agedInPlace,
224
+ firstAgedIndex,
225
+ agedCharsSaved: agedCharsSaved + agedArgCharsSaved,
226
+ agedArgCharsSaved,
227
+ };
228
+ }
229
+ /**
230
+ * 统计两次请求之间 assistant 工具调用参数的缩短量
231
+ *
232
+ * 按「同一 assistant 消息内同一位置的 tool_call」逐对比对;只累计变短的部分
233
+ * (参数被摘要替换)。新增调用的参数不计入。
234
+ *
235
+ * @param prevBody - 上次请求体
236
+ * @param nextBody - 本次请求体
237
+ * @returns 参数缩短的总字符数
238
+ */
239
+ function measureArgShrink(prevBody, nextBody) {
240
+ const prevMessages = Array.isArray(prevBody.messages) ? prevBody.messages : [];
241
+ const nextMessages = Array.isArray(nextBody.messages) ? nextBody.messages : [];
242
+ const limit = Math.min(prevMessages.length, nextMessages.length);
243
+ let saved = 0;
244
+ for (let i = 0; i < limit; i++) {
245
+ const prevCalls = toolCallsOf(prevMessages[i]);
246
+ const nextCalls = toolCallsOf(nextMessages[i]);
247
+ if (!prevCalls.length || prevCalls.length !== nextCalls.length)
248
+ continue;
249
+ for (let c = 0; c < prevCalls.length; c++) {
250
+ const before = prevCalls[c];
251
+ const after = nextCalls[c];
252
+ if (before.id !== after.id)
253
+ continue;
254
+ const delta = before.chars - after.chars;
255
+ if (delta > 0)
256
+ saved += delta;
257
+ }
258
+ }
259
+ return saved;
260
+ }
261
+ /**
262
+ * 提取消息内每个 tool_call 的 id 与参数序列化长度
263
+ *
264
+ * @param msg - wire 消息
265
+ * @returns 调用元组(非 assistant / 无 tool_calls 时为空)
266
+ */
267
+ function toolCallsOf(msg) {
268
+ if (msg == null || typeof msg !== 'object')
269
+ return [];
270
+ const calls = msg.tool_calls;
271
+ if (!Array.isArray(calls))
272
+ return [];
273
+ const out = [];
274
+ for (const call of calls) {
275
+ const args = call?.function?.arguments;
276
+ out.push({
277
+ id: typeof call?.id === 'string' ? call.id : '',
278
+ chars: typeof args === 'string' ? args.length : JSON.stringify(args ?? null).length,
279
+ });
280
+ }
281
+ return out;
282
+ }
283
+ /**
284
+ * 估算一次老化的回本点
285
+ *
286
+ * 成本模型(把「老化」与「不老化」两条路径对比):
287
+ * - 老化路径:本次调用要把失效尾部按**全价**重算一次 → 额外成本 `burned × (1 − discount)`
288
+ * - 不老化路径:被老化的原文此后每次调用都要重新发送,且作为热前缀按 `discount` 计价
289
+ * → 每次调用节省 `saved × discount`
290
+ *
291
+ * 因此 `paybackCalls = burned × (1 − discount) / (saved × discount)`。
292
+ * discount=0.1(一折)时即 `9 × burned / saved`。
293
+ *
294
+ * @param input - 老化量 / 燃烧量 / 价格折扣 / 本轮调用次数
295
+ * @returns 回本判定;`paybackCalls` 为 Infinity 表示收益为零或无缓存
296
+ */
297
+ export function estimateAgingPayback(input) {
298
+ const { agedCharsSaved, burnedChars, tokensPerChar, cacheDiscount, callsAfter } = input;
299
+ const savedTokens = agedCharsSaved * tokensPerChar;
300
+ const burnedTokens = burnedChars * tokensPerChar;
301
+ const discount = Math.min(Math.max(cacheDiscount, 0), 0.95);
302
+ const paybackCalls = savedTokens > 0 && discount > 0
303
+ ? (burnedTokens * (1 - discount)) / (savedTokens * discount)
304
+ : Number.POSITIVE_INFINITY;
305
+ return {
306
+ savedTokens,
307
+ burnedTokens,
308
+ paybackCalls,
309
+ repaid: callsAfter >= paybackCalls,
310
+ };
311
+ }
312
+ /**
313
+ * 定位单个前缀单元内部的字符级差异
314
+ *
315
+ * @param prevBody - 上次调用的请求体
316
+ * @param nextBody - 本次调用的请求体
317
+ * @param index - 分歧单元下标(来自 {@link compareWireCalls} 的 divergence.index)
318
+ * @returns 字符偏移与上下文片段;单元缺失时 null
319
+ */
320
+ export function explainWireDivergence(prevBody, nextBody, index) {
321
+ const prevPayloads = wireUnitPayloads(prevBody);
322
+ const nextPayloads = wireUnitPayloads(nextBody);
323
+ const prevText = prevPayloads[index]?.text;
324
+ const nextText = nextPayloads[index]?.text;
325
+ if (prevText == null || nextText == null)
326
+ return null;
327
+ const limit = Math.min(prevText.length, nextText.length);
328
+ let offset = 0;
329
+ while (offset < limit && prevText[offset] === nextText[offset])
330
+ offset += 1;
331
+ return {
332
+ index,
333
+ offset,
334
+ prevSnippet: snippetAround(prevText, offset),
335
+ nextSnippet: snippetAround(nextText, offset),
336
+ };
337
+ }
338
+ /**
339
+ * 取偏移附近的片段:前 80 字符 + 断点标记 + 后 80 字符
340
+ *
341
+ * `<|>` 是断点标记(对应返回的 `offset`),不是原文内容——原文在断点处是连续的。
342
+ *
343
+ * @param text - 单元 JSON 文本
344
+ * @param offset - 首个不同字符的偏移
345
+ * @returns 带断点标记的片段
346
+ */
347
+ function snippetAround(text, offset) {
348
+ const start = Math.max(0, offset - 80);
349
+ const end = Math.min(text.length, offset + 80);
350
+ return `${start > 0 ? '…' : ''}${text.slice(start, offset)}<|>${text.slice(offset, end)}${end < text.length ? '…' : ''}`;
351
+ }