@octopi-agent/engine 0.98.4 → 0.102.10

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 (301) hide show
  1. package/dist/config-schema/agent.d.ts +35 -5
  2. package/dist/config-schema/agent.js +24 -4
  3. package/dist/config-schema/context.d.ts +6 -36
  4. package/dist/config-schema/context.js +4 -28
  5. package/dist/config-schema/engine.d.ts +57 -160
  6. package/dist/config-schema/engine.js +1 -5
  7. package/dist/config-schema/governance.d.ts +8 -1
  8. package/dist/config-schema/governance.js +8 -1
  9. package/dist/config-schema/models.d.ts +2 -8
  10. package/dist/config-schema/models.js +0 -2
  11. package/dist/config-schema/run.d.ts +2 -2
  12. package/dist/config-schema/run.js +2 -2
  13. package/dist/config-schema/shared.d.ts +0 -3
  14. package/dist/config-schema/shared.js +0 -2
  15. package/dist/config-schema/substrate.d.ts +14 -88
  16. package/dist/config-schema/substrate.js +22 -107
  17. package/dist/config.d.ts +45 -113
  18. package/dist/config.js +8 -2
  19. package/dist/harness/activation/dispatcher.js +7 -0
  20. package/dist/harness/activation/inbox.d.ts +3 -3
  21. package/dist/harness/activation/inbox.js +3 -3
  22. package/dist/harness/activation/runtime.js +13 -5
  23. package/dist/harness/activation/types.d.ts +2 -2
  24. package/dist/harness/agent/builder.d.ts +24 -3
  25. package/dist/harness/agent/builder.js +131 -27
  26. package/dist/harness/agent/config-bridge.js +9 -2
  27. package/dist/harness/agent/config-integrity.js +19 -2
  28. package/dist/harness/agent/wire-agent-builder.d.ts +11 -3
  29. package/dist/harness/agent/wire-agent-builder.js +26 -7
  30. package/dist/harness/capabilities/document/factory.d.ts +5 -0
  31. package/dist/harness/capabilities/document/factory.js +1 -0
  32. package/dist/harness/capabilities/document/port.js +6 -3
  33. package/dist/harness/capabilities/document/types.d.ts +5 -0
  34. package/dist/harness/collaboration/autonomous-subsystem/loader.js +1 -1
  35. package/dist/harness/collaboration/autonomous-subsystem/sense/engine.d.ts +1 -1
  36. package/dist/harness/collaboration/autonomous-subsystem/sense/engine.js +2 -2
  37. package/dist/harness/collaboration/autonomous-subsystem/sense/input-builder.js +4 -4
  38. package/dist/harness/collaboration/autonomous-subsystem/sense/metrics.d.ts +2 -2
  39. package/dist/harness/collaboration/autonomous-subsystem/sense/metrics.js +2 -2
  40. package/dist/harness/collaboration/autonomous-subsystem/signal/bus.d.ts +6 -0
  41. package/dist/harness/collaboration/autonomous-subsystem/signal/bus.js +25 -4
  42. package/dist/harness/collaboration/autonomous-subsystem/think/executor.js +1 -1
  43. package/dist/harness/collaboration/autonomous-subsystem/types.d.ts +3 -3
  44. package/dist/harness/collaboration/delegation/child-run.d.ts +1 -1
  45. package/dist/harness/collaboration/delegation/child-run.js +4 -4
  46. package/dist/harness/collaboration/delegation/index.d.ts +1 -1
  47. package/dist/harness/collaboration/delegation/index.js +1 -1
  48. package/dist/harness/collaboration/delegation/notifier.d.ts +6 -1
  49. package/dist/harness/collaboration/delegation/notifier.js +8 -1
  50. package/dist/harness/collaboration/delegation/service.d.ts +2 -0
  51. package/dist/harness/collaboration/delegation/service.js +2 -1
  52. package/dist/harness/collaboration/delegation/store.d.ts +2 -0
  53. package/dist/harness/collaboration/delegation/store.js +2 -1
  54. package/dist/harness/collaboration/delegation/types.d.ts +23 -2
  55. package/dist/harness/collaboration/delegation/types.js +22 -0
  56. package/dist/harness/collaboration/delegation/wiring.js +11 -1
  57. package/dist/harness/context/budget-allocator.d.ts +26 -18
  58. package/dist/harness/context/budget-allocator.js +67 -32
  59. package/dist/harness/context/capabilities/compact/engine.d.ts +0 -6
  60. package/dist/harness/context/capabilities/compact/engine.js +169 -121
  61. package/dist/harness/context/capabilities/compact/handover.d.ts +5 -3
  62. package/dist/harness/context/capabilities/compact/handover.js +7 -5
  63. package/dist/harness/context/capabilities/compact/index.d.ts +5 -1
  64. package/dist/harness/context/capabilities/compact/index.js +4 -0
  65. package/dist/harness/context/capabilities/compact/mechanical.d.ts +130 -0
  66. package/dist/harness/context/capabilities/compact/mechanical.js +268 -0
  67. package/dist/harness/context/capabilities/compact/messages.d.ts +60 -0
  68. package/dist/harness/context/capabilities/compact/messages.js +91 -0
  69. package/dist/harness/context/capabilities/compact/types.d.ts +76 -11
  70. package/dist/harness/context/capabilities/compact/types.js +11 -1
  71. package/dist/harness/context/capabilities/compact/view-split.d.ts +36 -0
  72. package/dist/harness/context/capabilities/compact/view-split.js +72 -0
  73. package/dist/harness/context/capabilities/summary/port.js +0 -1
  74. package/dist/harness/context/capabilities/summary/resolver.d.ts +1 -1
  75. package/dist/harness/context/capabilities/summary/resolver.js +1 -6
  76. package/dist/harness/context/capabilities/summary/tool-binding.d.ts +1 -1
  77. package/dist/harness/context/capabilities/summary/types.d.ts +3 -6
  78. package/dist/harness/context/context-size-ledger.d.ts +143 -0
  79. package/dist/harness/context/context-size-ledger.js +236 -0
  80. package/dist/harness/context/default-context-engine.d.ts +195 -119
  81. package/dist/harness/context/default-context-engine.js +1241 -743
  82. package/dist/harness/context/index.d.ts +2 -2
  83. package/dist/harness/context/index.js +1 -1
  84. package/dist/harness/context/layer-types.d.ts +15 -0
  85. package/dist/harness/context/layer-types.js +14 -1
  86. package/dist/harness/context/layers.d.ts +14 -15
  87. package/dist/harness/context/layers.js +41 -11
  88. package/dist/harness/context/message-selector.d.ts +10 -8
  89. package/dist/harness/context/message-selector.js +49 -27
  90. package/dist/harness/context/summarize.d.ts +2 -2
  91. package/dist/harness/context/summarize.js +9 -2
  92. package/dist/harness/context/system-prompt-assembler.d.ts +2 -0
  93. package/dist/harness/context/system-prompt-assembler.js +2 -1
  94. package/dist/harness/context/token-constants.d.ts +8 -6
  95. package/dist/harness/context/token-constants.js +8 -7
  96. package/dist/harness/context/token-estimate-fns.d.ts +37 -27
  97. package/dist/harness/context/token-estimate-fns.js +85 -66
  98. package/dist/harness/context/token-estimator.d.ts +27 -12
  99. package/dist/harness/context/token-estimator.js +120 -66
  100. package/dist/harness/context/token-segments.d.ts +88 -0
  101. package/dist/harness/context/token-segments.js +103 -0
  102. package/dist/harness/context/tool-result-aging.d.ts +6 -1
  103. package/dist/harness/context/tool-result-aging.js +16 -5
  104. package/dist/harness/context/tool-result-body.js +2 -0
  105. package/dist/harness/context/transform/anchors.d.ts +66 -0
  106. package/dist/harness/context/transform/anchors.js +125 -0
  107. package/dist/harness/context/transform/fold.d.ts +56 -0
  108. package/dist/harness/context/transform/fold.js +135 -0
  109. package/dist/harness/context/transform/migrate.d.ts +41 -0
  110. package/dist/harness/context/transform/migrate.js +69 -0
  111. package/dist/harness/context/transform/types.d.ts +129 -0
  112. package/dist/harness/context/transform/types.js +19 -0
  113. package/dist/harness/context/turn-envelope.d.ts +6 -3
  114. package/dist/harness/context/types.d.ts +127 -117
  115. package/dist/harness/extension/execution-environment/ops-audit.d.ts +1 -1
  116. package/dist/harness/extension/execution-environment/resource-limits.d.ts +1 -1
  117. package/dist/harness/extension/execution-environment/resource-limits.js +1 -1
  118. package/dist/harness/extension/plugin-ecosystem/channel-types.d.ts +1 -1
  119. package/dist/harness/extension/plugin-ecosystem/commands/index.d.ts +3 -1
  120. package/dist/harness/extension/plugin-ecosystem/commands/index.js +1 -0
  121. package/dist/harness/extension/plugin-ecosystem/commands/plugin-bridge.d.ts +12 -1
  122. package/dist/harness/extension/plugin-ecosystem/commands/plugin-bridge.js +14 -4
  123. package/dist/harness/extension/plugin-ecosystem/commands/router.d.ts +5 -4
  124. package/dist/harness/extension/plugin-ecosystem/commands/router.js +23 -14
  125. package/dist/harness/extension/plugin-ecosystem/commands/types.d.ts +8 -1
  126. package/dist/harness/extension/plugin-ecosystem/commands/types.js +2 -1
  127. package/dist/harness/extension/plugin-ecosystem/hooks/adapter.d.ts +54 -0
  128. package/dist/harness/extension/plugin-ecosystem/hooks/adapter.js +397 -0
  129. package/dist/harness/extension/plugin-ecosystem/hooks/compaction-integration.d.ts +16 -0
  130. package/dist/harness/extension/plugin-ecosystem/hooks/compaction-integration.js +66 -0
  131. package/dist/harness/extension/plugin-ecosystem/hooks/index.d.ts +4 -0
  132. package/dist/harness/extension/plugin-ecosystem/hooks/index.js +2 -0
  133. package/dist/harness/extension/plugin-ecosystem/hooks/iteration-snapshot.d.ts +11 -0
  134. package/dist/harness/extension/plugin-ecosystem/hooks/iteration-snapshot.js +54 -0
  135. package/dist/harness/extension/plugin-ecosystem/hooks/journal.d.ts +9 -0
  136. package/dist/harness/extension/plugin-ecosystem/hooks/journal.js +22 -0
  137. package/dist/harness/extension/plugin-ecosystem/hooks/policy-error.d.ts +12 -0
  138. package/dist/harness/extension/plugin-ecosystem/hooks/policy-error.js +19 -0
  139. package/dist/harness/extension/plugin-ecosystem/hooks/run-integration.d.ts +36 -0
  140. package/dist/harness/extension/plugin-ecosystem/hooks/run-integration.js +338 -0
  141. package/dist/harness/extension/plugin-ecosystem/hooks/services.d.ts +24 -0
  142. package/dist/harness/extension/plugin-ecosystem/hooks/services.js +139 -0
  143. package/dist/harness/extension/plugin-ecosystem/hooks/types.d.ts +229 -0
  144. package/dist/harness/extension/plugin-ecosystem/hooks/types.js +1 -0
  145. package/dist/harness/extension/plugin-ecosystem/plugins/api.d.ts +83 -249
  146. package/dist/harness/extension/plugin-ecosystem/plugins/api.js +88 -214
  147. package/dist/harness/extension/plugin-ecosystem/plugins/contribution-registry.d.ts +43 -0
  148. package/dist/harness/extension/plugin-ecosystem/plugins/contribution-registry.js +61 -0
  149. package/dist/harness/extension/plugin-ecosystem/plugins/engine-compatibility.d.ts +4 -0
  150. package/dist/harness/extension/plugin-ecosystem/plugins/engine-compatibility.js +18 -0
  151. package/dist/harness/extension/plugin-ecosystem/plugins/entry.d.ts +7 -85
  152. package/dist/harness/extension/plugin-ecosystem/plugins/entry.js +8 -50
  153. package/dist/harness/extension/plugin-ecosystem/plugins/index.d.ts +6 -23
  154. package/dist/harness/extension/plugin-ecosystem/plugins/index.js +3 -23
  155. package/dist/harness/extension/plugin-ecosystem/plugins/loader.d.ts +50 -117
  156. package/dist/harness/extension/plugin-ecosystem/plugins/loader.js +316 -285
  157. package/dist/harness/extension/plugin-ecosystem/plugins/manager.d.ts +23 -490
  158. package/dist/harness/extension/plugin-ecosystem/plugins/manager.js +85 -353
  159. package/dist/harness/extension/plugin-ecosystem/plugins/manifest.d.ts +41 -223
  160. package/dist/harness/extension/plugin-ecosystem/plugins/manifest.js +138 -19
  161. package/dist/harness/extension/plugin-ecosystem/plugins/staging.d.ts +15 -0
  162. package/dist/harness/extension/plugin-ecosystem/plugins/staging.js +15 -0
  163. package/dist/harness/extension/plugin-ecosystem/skills/manager.d.ts +6 -1
  164. package/dist/harness/extension/plugin-ecosystem/skills/manager.js +17 -1
  165. package/dist/harness/extension/plugin-ecosystem/tools/ask-user.d.ts +3 -0
  166. package/dist/harness/extension/plugin-ecosystem/tools/ask-user.js +46 -21
  167. package/dist/harness/extension/plugin-ecosystem/tools/delegation.js +18 -8
  168. package/dist/harness/extension/plugin-ecosystem/tools/plugin-tool.d.ts +11 -0
  169. package/dist/harness/extension/plugin-ecosystem/tools/plugin-tool.js +39 -0
  170. package/dist/harness/extension/plugin-ecosystem/tools/tool-bus.d.ts +1 -1
  171. package/dist/harness/extension/plugin-ecosystem/tools/tool-bus.js +11 -2
  172. package/dist/harness/governance/accounting/usage-ledger.d.ts +13 -1
  173. package/dist/harness/governance/accounting/usage-ledger.js +23 -1
  174. package/dist/harness/governance/human-in-the-loop/decision-cache.d.ts +3 -3
  175. package/dist/harness/governance/human-in-the-loop/decision-cache.js +2 -2
  176. package/dist/harness/governance/security/capability-enforcer.js +1 -2
  177. package/dist/harness/index.d.ts +12 -12
  178. package/dist/harness/index.js +7 -7
  179. package/dist/harness/knowledge/boot-config.d.ts +55 -0
  180. package/dist/harness/knowledge/boot-config.js +50 -0
  181. package/dist/harness/knowledge/catalog-types.d.ts +2 -0
  182. package/dist/harness/knowledge/client.d.ts +24 -2
  183. package/dist/harness/knowledge/client.js +19 -5
  184. package/dist/harness/knowledge/db.js +5 -0
  185. package/dist/harness/knowledge/describe-sample.d.ts +23 -0
  186. package/dist/harness/knowledge/describe-sample.js +58 -0
  187. package/dist/harness/knowledge/describe.d.ts +8 -0
  188. package/dist/harness/knowledge/describe.js +18 -2
  189. package/dist/harness/knowledge/engine-thread.js +6 -0
  190. package/dist/harness/knowledge/grounding.js +3 -1
  191. package/dist/harness/knowledge/http-app.js +35 -4
  192. package/dist/harness/knowledge/http-params.d.ts +18 -0
  193. package/dist/harness/knowledge/http-params.js +24 -0
  194. package/dist/harness/knowledge/index.d.ts +2 -0
  195. package/dist/harness/knowledge/index.js +1 -0
  196. package/dist/harness/knowledge/knowledge-serve-child.js +3 -0
  197. package/dist/harness/knowledge/purge.js +5 -2
  198. package/dist/harness/knowledge/query-service.d.ts +13 -2
  199. package/dist/harness/knowledge/query-service.js +4 -2
  200. package/dist/harness/knowledge/query-worker-client.d.ts +9 -1
  201. package/dist/harness/knowledge/query-worker-client.js +4 -2
  202. package/dist/harness/knowledge/query-worker.js +4 -2
  203. package/dist/harness/knowledge/read-http.js +5 -1
  204. package/dist/harness/knowledge/serve.d.ts +8 -7
  205. package/dist/harness/knowledge/serve.js +9 -0
  206. package/dist/harness/knowledge/source-store.js +26 -3
  207. package/dist/harness/knowledge/start-service-process.d.ts +15 -7
  208. package/dist/harness/knowledge/start-service-process.js +21 -9
  209. package/dist/harness/knowledge/types.d.ts +7 -0
  210. package/dist/harness/knowledge/writer-service.d.ts +37 -9
  211. package/dist/harness/knowledge/writer-service.js +120 -14
  212. package/dist/harness/knowledge/writer-worker-client.d.ts +10 -9
  213. package/dist/harness/knowledge/writer-worker-client.js +20 -2
  214. package/dist/harness/knowledge/writer-worker.js +9 -1
  215. package/dist/harness/memory/sqlite/wisdom-store.js +35 -10
  216. package/dist/harness/memory/types.d.ts +6 -4
  217. package/dist/harness/memory/wisdom-formation.d.ts +14 -3
  218. package/dist/harness/memory/wisdom-formation.js +85 -22
  219. package/dist/harness/memory/wisdom-gates.d.ts +14 -0
  220. package/dist/harness/memory/wisdom-gates.js +59 -19
  221. package/dist/harness/memory/wisdom.js +9 -0
  222. package/dist/harness/observability/observer/hub.js +25 -15
  223. package/dist/harness/observability/observer/types.d.ts +10 -6
  224. package/dist/harness/run/agent/agent.d.ts +40 -21
  225. package/dist/harness/run/agent/agent.js +66 -13
  226. package/dist/harness/run/agent/index.d.ts +1 -1
  227. package/dist/harness/run/budget/budget.d.ts +28 -10
  228. package/dist/harness/run/budget/budget.js +38 -15
  229. package/dist/harness/run/model/index.d.ts +3 -1
  230. package/dist/harness/run/model/index.js +2 -1
  231. package/dist/harness/run/model/resolver.d.ts +4 -1
  232. package/dist/harness/run/model/resolver.js +36 -2
  233. package/dist/harness/run/model/run-scope.d.ts +2 -0
  234. package/dist/harness/run/model/run-scope.js +7 -0
  235. package/dist/harness/run/model/types.d.ts +22 -5
  236. package/dist/harness/run/model/types.js +3 -2
  237. package/dist/harness/run/model/window-truth.d.ts +37 -0
  238. package/dist/harness/run/model/window-truth.js +39 -0
  239. package/dist/harness/run/reliability/context-length-feedback.d.ts +77 -0
  240. package/dist/harness/run/reliability/context-length-feedback.js +128 -0
  241. package/dist/harness/run/reliability/harness-events.d.ts +3 -3
  242. package/dist/harness/run/reliability/model-error-policy.js +4 -0
  243. package/dist/harness/run/reliability/run-agent.d.ts +10 -4
  244. package/dist/harness/run/reliability/run-agent.js +137 -53
  245. package/dist/harness/run/reliability/run-metrics-collector.d.ts +19 -8
  246. package/dist/harness/run/reliability/run-metrics-collector.js +38 -23
  247. package/dist/harness/run/run-guard/default-run-guard.js +8 -8
  248. package/dist/harness/run/run-scope.d.ts +37 -4
  249. package/dist/harness/run/runner.d.ts +44 -29
  250. package/dist/harness/run/runner.js +320 -102
  251. package/dist/harness/session/attachments/index.d.ts +1 -0
  252. package/dist/harness/session/attachments/index.js +1 -0
  253. package/dist/harness/session/attachments/inject.d.ts +21 -10
  254. package/dist/harness/session/attachments/inject.js +76 -24
  255. package/dist/harness/session/attachments/recall-index.d.ts +70 -0
  256. package/dist/harness/session/attachments/recall-index.js +219 -0
  257. package/dist/harness/session/attachments/service.d.ts +21 -0
  258. package/dist/harness/session/attachments/service.js +258 -139
  259. package/dist/harness/session/attachments/types.d.ts +6 -0
  260. package/dist/harness/session/transform-store.d.ts +136 -0
  261. package/dist/harness/session/transform-store.js +302 -0
  262. package/dist/harness/session/types.d.ts +2 -2
  263. package/dist/harness/shared/events/agent-event-map.d.ts +46 -13
  264. package/dist/harness/shared/events/agent-event-map.js +3 -2
  265. package/dist/harness/shared/events/scenario-events.d.ts +6 -6
  266. package/dist/harness/shared/types/agent-definition.d.ts +1 -2
  267. package/dist/index.d.ts +14 -17
  268. package/dist/index.js +7 -9
  269. package/dist/integration/observability/metrics.d.ts +6 -6
  270. package/dist/integration/observability/metrics.js +13 -13
  271. package/dist/integration/observability/observer-bridge.js +2 -2
  272. package/dist/integration/observability/trace-collector.d.ts +5 -5
  273. package/dist/integration/observability/trace-collector.js +34 -35
  274. package/dist/integration/observability/trace-events.d.ts +3 -3
  275. package/dist/integration/observability/trace-events.js +3 -3
  276. package/dist/integration/providers/anthropic.js +14 -1
  277. package/dist/integration/providers/openai.js +7 -1
  278. package/dist/integration/providers/usage.d.ts +1 -1
  279. package/dist/integration/providers/wire-dump.d.ts +1 -1
  280. package/dist/integration/storage/archive-manager.d.ts +6 -0
  281. package/dist/integration/storage/archive-manager.js +10 -0
  282. package/dist/integration/storage/jsonl.d.ts +1 -1
  283. package/dist/integration/storage/jsonl.js +18 -16
  284. package/dist/subsystems/wisdom-steward/formation/SUBSYSTEM.md +8 -1
  285. package/dist/subsystems/wisdom-steward/formation/config.yaml +1 -0
  286. package/dist/subsystems/wisdom-steward/formation/handler.js +27 -5
  287. package/package.json +11 -14
  288. package/dist/harness/context/hybrid-compressor.d.ts +0 -41
  289. package/dist/harness/context/hybrid-compressor.js +0 -159
  290. package/dist/harness/context/llm-summarizer.d.ts +0 -46
  291. package/dist/harness/context/llm-summarizer.js +0 -249
  292. package/dist/harness/context/smart-router.d.ts +0 -75
  293. package/dist/harness/context/smart-router.js +0 -118
  294. package/dist/harness/context/truncate-compressor.d.ts +0 -28
  295. package/dist/harness/context/truncate-compressor.js +0 -107
  296. package/dist/harness/extension/plugin-ecosystem/plugins/capability.d.ts +0 -97
  297. package/dist/harness/extension/plugin-ecosystem/plugins/capability.js +0 -155
  298. package/dist/harness/extension/plugin-ecosystem/plugins/hooks.d.ts +0 -7
  299. package/dist/harness/extension/plugin-ecosystem/plugins/hooks.js +0 -7
  300. package/dist/harness/extension/plugin-ecosystem/plugins/lifecycle.d.ts +0 -86
  301. package/dist/harness/extension/plugin-ecosystem/plugins/lifecycle.js +0 -139
@@ -0,0 +1,130 @@
1
+ /**
2
+ * 机械降级 — 零 LLM 的压缩执行(purpose 账本,单级)
3
+ *
4
+ * 定位(2026-11-04 拍板):**应急通道**,只在摘要无法产出时接手——
5
+ * provider 报错/超时、输出闸门二次判污染、摘要请求放不进窗口。它不是常态压缩
6
+ * (常态走交接式摘要),因此不需要渐进、不需要分级,一次做到最大化压缩。
7
+ *
8
+ * 形态:整段 middle/messages 替换为 **一条 purpose 账本消息**——保留「调用过什么、
9
+ * 为什么调用、哪条失败」,丢弃结果正文与参数载荷。依据:
10
+ * - purpose 是工具调用的必填契约(`≤120 字符`,动词+宾语+目标),本身就是
11
+ * 「任务执行情况」的最小可读摘要,实测 510/510 调用齐备;
12
+ * - 生产实测压缩比 ~16x(475k → 29k 字符),远优于结果打码的 ~3.7x 地板
13
+ * (aging 指针约 557 字符/调用,账本约 58 字符/调用);
14
+ * - 省下的正是最不值钱的部分(长结果正文),留下的正是最值钱的(意图与失败)。
15
+ *
16
+ * **超预算不静默丢条目**:账本已是最小形态,若仍超预算说明该会话不宜继续——
17
+ * 如实上报 `overBudget`,由上层决定告知用户开新会话。丢条目等于静默失忆。
18
+ *
19
+ * 单源:占位文案与判别见 ./messages.ts;错别话术禁止在本模块手写第二份。
20
+ *
21
+ * @module harness/context/capabilities/compact/mechanical
22
+ */
23
+ import type { Message } from '@octopi-agent/core/types.js';
24
+ /**
25
+ * 工具调用账本(`name + purpose` 逐行)——降级时的「做过什么」无损索引。
26
+ *
27
+ * 输出形态:
28
+ * ```
29
+ * - file_edit: Add event-vocabulary disposition to P5 row
30
+ * - shell: Stage explicit paths, commit, and tag v0.98.17
31
+ * ! project_run: test failed (exit 1)
32
+ * ```
33
+ * error 结果附在对应调用行下方(错误可追溯性优先,永不省略)。
34
+ *
35
+ * @param messages - 被降级丢弃的消息
36
+ * @returns 账本文本(可为空串)
37
+ */
38
+ export declare function buildToolCallLedger(messages: Message[]): string;
39
+ /**
40
+ * 账本消息构造(user 角色——中段 system 会被部分网关拒绝)。
41
+ *
42
+ * @param ledger - 账本文本(可为空)
43
+ * @param removedCount - 被替换的消息条数
44
+ * @returns 账本视图消息
45
+ */
46
+ export declare function asLedgerMessage(ledger: string, removedCount: number): Message;
47
+ /**
48
+ * 账本截断(保留近尾 + 头部替换为账本)——**物理溢出兜底专用**。
49
+ *
50
+ * 与 `mechanicalDegrade` 的分工:本函数服务「消息必须放回窗口否则请求 400」的场景
51
+ * (overflow 路径),所以在丢头部的同时**保住近尾原文**(最近的现场最值钱);
52
+ * `mechanicalDegrade` 服务「摘要失败」的场景,一次全量转账本。
53
+ *
54
+ * 形态(middle 替换体,外层 head/tail 由调用方拼接):`[账本说明 + 近尾]`。
55
+ * - 保留近尾:预算驱动从头丢弃,但**保底**不破(禁止只留 4 条);
56
+ * - 边界对齐:tool_call/tool_result 对同进同出,保留尾不得起于孤儿结果
57
+ * (孤儿时**回退**切点把调用一并纳入 kept——宁可胖不可拆对;向前跳会把连续
58
+ * tool 结果一路丢光、整段 middle 被吞);
59
+ * - 无可丢弃时原样返回(禁止「0 removed」假通知膨胀)。
60
+ *
61
+ * @param messages - 待降级消息
62
+ * @param opts - targetTokens 预算、估算器、minKeep 保底
63
+ * - targetTokens 缺省不是「不压缩」,而是**只丢到保底**(最大压缩);
64
+ * - minKeep 为**纯保底**(拍板常量,非可调参数):显式传入即用该值(「压到目标」的
65
+ * 机械压缩传 2 = 旧 TruncateCompressor「至少留 2」口径,不叠 15%——叠加会把保 2
66
+ * 架空成 15%、粘滞增量撑胖后在复用轮挤出 overflow 补摘要);缺省 = max(6, 15%)
67
+ * (旧 fallbackTruncate / conservativeTruncate 失败兜底口径)。
68
+ * @returns 截断结果(result 含账本说明或原样 + droppedCount + ledgerKept)
69
+ */
70
+ export declare function ledgerTruncate(messages: Message[], opts?: {
71
+ targetTokens?: number;
72
+ estimator?: {
73
+ estimateMessages(ms: Message[]): number;
74
+ };
75
+ minKeep?: number;
76
+ }): {
77
+ result: Message[];
78
+ droppedCount: number;
79
+ ledgerKept: boolean;
80
+ };
81
+ /**
82
+ * 机械降级:整段替换为 purpose 账本(零 LLM,单级,无可再降)。
83
+ *
84
+ * @param messages - 待降级消息
85
+ * @param opts - targetTokens(用于判定是否仍需上报超预算)与估算器
86
+ * @returns 降级结果
87
+ * - `result`:单条账本消息(入参为空时为空数组)
88
+ * - `tokensAfter`:账本 token 估算
89
+ * - `overBudget`:账本仍超 targetTokens —— 已无可降空间,调用方须如实上报,
90
+ * 不得再丢条目(丢条目 = 静默失忆)
91
+ * - `droppedSummary`:产物描述
92
+ */
93
+ export declare function mechanicalDegrade(messages: Message[], opts?: {
94
+ targetTokens?: number;
95
+ estimator?: {
96
+ estimateMessages(ms: Message[]): number;
97
+ };
98
+ }): {
99
+ result: Message[];
100
+ tokensAfter: number;
101
+ overBudget: boolean;
102
+ droppedSummary?: string;
103
+ };
104
+ /**
105
+ * 工具执行账本化(收敛阶梯第 1–3 轮专用,arch/overflow-redesign.md §3)。
106
+ *
107
+ * 语义(丢弃次序原则:数据细节 → 执行记录 → 工作窗口 → 放弃,从最可再生到最不可再生):
108
+ * - **账本化对象 = 工具执行段**(assistant(toolCalls) + tool(result) 对,同进同出)——
109
+ * 执行记录可再生(可重执行/磁盘找回),先于工作窗口丢弃;
110
+ * - **跳过保留**:真 user 消息(最不可再生)、assistant 文本(非执行记录)、
111
+ * 合成消息(contextLedger/contextSummary 占位——已是索引/交接形态,不可再降);
112
+ * - **tailKeep 近尾保护**(工作窗口):近尾 tailKeep 条内的工具执行不账本化。
113
+ *
114
+ * 形态:被账本化 run 的原位移除,**第一个**被砍 run 的下标处放一个合并 notice
115
+ * (buildToolCallLedger 汇总全部被砍执行的 name+purpose+errors)——与 fold 同构:
116
+ * foldTransformView 对多 covers runs 渲染**一个**占位(firstIndex 处、区间内保护类原样),
117
+ * 本函数的产物即 fold 后视图,守门量的与发送的是同一个产物。
118
+ *
119
+ * 每档独立调用(幂等):无候选时原样返回——天然支持「每档对原视图重算」,不累积吞账本。
120
+ *
121
+ * @param messages - 原始视图(收敛循环对同一 view 每档独立调用)
122
+ * @param opts - tailKeep 近尾保护档、估算器、targetTokens(缺省=砍掉全部候选)
123
+ * @returns 产物视图 + 被账本化条数(0=砍不动/无候选)
124
+ */
125
+ export declare function toolExecutionLedgerTrim(messages: Message[], opts: {
126
+ tailKeep: number;
127
+ }): {
128
+ result: Message[];
129
+ droppedCount: number;
130
+ };
@@ -0,0 +1,268 @@
1
+ /**
2
+ * 机械降级 — 零 LLM 的压缩执行(purpose 账本,单级)
3
+ *
4
+ * 定位(2026-11-04 拍板):**应急通道**,只在摘要无法产出时接手——
5
+ * provider 报错/超时、输出闸门二次判污染、摘要请求放不进窗口。它不是常态压缩
6
+ * (常态走交接式摘要),因此不需要渐进、不需要分级,一次做到最大化压缩。
7
+ *
8
+ * 形态:整段 middle/messages 替换为 **一条 purpose 账本消息**——保留「调用过什么、
9
+ * 为什么调用、哪条失败」,丢弃结果正文与参数载荷。依据:
10
+ * - purpose 是工具调用的必填契约(`≤120 字符`,动词+宾语+目标),本身就是
11
+ * 「任务执行情况」的最小可读摘要,实测 510/510 调用齐备;
12
+ * - 生产实测压缩比 ~16x(475k → 29k 字符),远优于结果打码的 ~3.7x 地板
13
+ * (aging 指针约 557 字符/调用,账本约 58 字符/调用);
14
+ * - 省下的正是最不值钱的部分(长结果正文),留下的正是最值钱的(意图与失败)。
15
+ *
16
+ * **超预算不静默丢条目**:账本已是最小形态,若仍超预算说明该会话不宜继续——
17
+ * 如实上报 `overBudget`,由上层决定告知用户开新会话。丢条目等于静默失忆。
18
+ *
19
+ * 单源:占位文案与判别见 ./messages.ts;错别话术禁止在本模块手写第二份。
20
+ *
21
+ * @module harness/context/capabilities/compact/mechanical
22
+ */
23
+ import { HeuristicTokenEstimator } from '../../token-estimator.js';
24
+ import { MECHANICAL_NOTICE_TRUNCATED, hasToolCall, isToolResultMessage } from './messages.js';
25
+ /**
26
+ * 账本单条 purpose 的防御上限(字符)。
27
+ * purpose 契约本身 ≤120;超长只可能来自历史数据或非本契约客户端,截断防单条撑爆账本。
28
+ */
29
+ const LEDGER_PURPOSE_MAX = 160;
30
+ /** 账本单条 error 上限(字符):错误文案优先保真,仅在异常长时截断 */
31
+ const LEDGER_ERROR_MAX = 200;
32
+ /** purpose 缺失时的诚实占位(正常不出现:purpose 是必填参数,缺失会在调用期直接报错) */
33
+ const MISSING_PURPOSE = '(purpose not recorded)';
34
+ /**
35
+ * 工具调用账本(`name + purpose` 逐行)——降级时的「做过什么」无损索引。
36
+ *
37
+ * 输出形态:
38
+ * ```
39
+ * - file_edit: Add event-vocabulary disposition to P5 row
40
+ * - shell: Stage explicit paths, commit, and tag v0.98.17
41
+ * ! project_run: test failed (exit 1)
42
+ * ```
43
+ * error 结果附在对应调用行下方(错误可追溯性优先,永不省略)。
44
+ *
45
+ * @param messages - 被降级丢弃的消息
46
+ * @returns 账本文本(可为空串)
47
+ */
48
+ export function buildToolCallLedger(messages) {
49
+ const lines = [];
50
+ // 调用行只从 toolCalls 产出(时间序);错误行从 toolResults 追加到最近一次产出之后,
51
+ // 保证「哪条调用失败」可定位——跨消息配对时以 toolCallId 归位。
52
+ const lineIndexByCallId = new Map();
53
+ for (const msg of messages) {
54
+ for (const tc of msg.toolCalls ?? []) {
55
+ const raw = tc.arguments?.purpose;
56
+ const purpose = typeof raw === 'string' && raw.trim()
57
+ ? raw.trim().slice(0, LEDGER_PURPOSE_MAX)
58
+ : MISSING_PURPOSE;
59
+ lines.push(`- ${tc.name}: ${purpose}`);
60
+ lineIndexByCallId.set(tc.id, lines.length - 1);
61
+ }
62
+ for (const tr of msg.toolResults ?? []) {
63
+ if (lineIndexByCallId.get(tr.toolCallId) === undefined && tr.error === undefined) {
64
+ // 孤儿 result(调用方消息不在本账本范围/未被砍):结果被账本化也必须留痕——
65
+ // name 不可失忆,否则「做过什么」无从追溯(只留 error 行不够)
66
+ lines.push(`- ${tr.name ?? tr.toolCallId}: ${MISSING_PURPOSE}`);
67
+ lineIndexByCallId.set(tr.toolCallId, lines.length - 1);
68
+ }
69
+ if (tr.error === undefined)
70
+ continue;
71
+ const err = tr.error.length > LEDGER_ERROR_MAX ? `${tr.error.slice(0, LEDGER_ERROR_MAX)}…` : tr.error;
72
+ const errorLine = ` ! ${tr.name ?? tr.toolCallId}: ${err}`;
73
+ const at = lineIndexByCallId.get(tr.toolCallId);
74
+ if (at === undefined) {
75
+ // 调用方消息已被丢弃(跨切片降级):错误仍须保留,独立成行——宁可错位,不可丢失
76
+ lines.push(errorLine);
77
+ continue;
78
+ }
79
+ // 紧贴其调用行插入(倒序插入时下标不失效:同一条目只插一次)
80
+ lines.splice(at + 1, 0, errorLine);
81
+ for (const [id, idx] of lineIndexByCallId) {
82
+ if (idx > at)
83
+ lineIndexByCallId.set(id, idx + 1);
84
+ }
85
+ }
86
+ }
87
+ return lines.join('\n');
88
+ }
89
+ /**
90
+ * 账本消息构造(user 角色——中段 system 会被部分网关拒绝)。
91
+ *
92
+ * @param ledger - 账本文本(可为空)
93
+ * @param removedCount - 被替换的消息条数
94
+ * @returns 账本视图消息
95
+ */
96
+ export function asLedgerMessage(ledger, removedCount) {
97
+ const head = `${MECHANICAL_NOTICE_TRUNCATED} ${removedCount} earlier entries replaced by a tool-call ledger to fit context window]`;
98
+ const body = ledger
99
+ ? `[Tool call ledger — do NOT redo these unless explicitly asked]\n${ledger}\n[Tool results and arguments were dropped; re-read files/sources if you need their content. Check session task list via task_* before continuing]`
100
+ : '[No tool calls in the dropped range. Check session task list via task_* before continuing]';
101
+ return {
102
+ role: 'user',
103
+ content: `${head}\n${body}`,
104
+ timestamp: Date.now(),
105
+ // 语义诚实:账本是机械降级产物,**不是**摘要——不得复用 contextSummary 标记,
106
+ // 否则下游(持久化/回放/审计)会把它当交接摘要处理。
107
+ metadata: { source: 'contextLedger' },
108
+ };
109
+ }
110
+ /**
111
+ * 账本截断(保留近尾 + 头部替换为账本)——**物理溢出兜底专用**。
112
+ *
113
+ * 与 `mechanicalDegrade` 的分工:本函数服务「消息必须放回窗口否则请求 400」的场景
114
+ * (overflow 路径),所以在丢头部的同时**保住近尾原文**(最近的现场最值钱);
115
+ * `mechanicalDegrade` 服务「摘要失败」的场景,一次全量转账本。
116
+ *
117
+ * 形态(middle 替换体,外层 head/tail 由调用方拼接):`[账本说明 + 近尾]`。
118
+ * - 保留近尾:预算驱动从头丢弃,但**保底**不破(禁止只留 4 条);
119
+ * - 边界对齐:tool_call/tool_result 对同进同出,保留尾不得起于孤儿结果
120
+ * (孤儿时**回退**切点把调用一并纳入 kept——宁可胖不可拆对;向前跳会把连续
121
+ * tool 结果一路丢光、整段 middle 被吞);
122
+ * - 无可丢弃时原样返回(禁止「0 removed」假通知膨胀)。
123
+ *
124
+ * @param messages - 待降级消息
125
+ * @param opts - targetTokens 预算、估算器、minKeep 保底
126
+ * - targetTokens 缺省不是「不压缩」,而是**只丢到保底**(最大压缩);
127
+ * - minKeep 为**纯保底**(拍板常量,非可调参数):显式传入即用该值(「压到目标」的
128
+ * 机械压缩传 2 = 旧 TruncateCompressor「至少留 2」口径,不叠 15%——叠加会把保 2
129
+ * 架空成 15%、粘滞增量撑胖后在复用轮挤出 overflow 补摘要);缺省 = max(6, 15%)
130
+ * (旧 fallbackTruncate / conservativeTruncate 失败兜底口径)。
131
+ * @returns 截断结果(result 含账本说明或原样 + droppedCount + ledgerKept)
132
+ */
133
+ export function ledgerTruncate(messages, opts) {
134
+ if (messages.length === 0)
135
+ return { result: [], droppedCount: 0, ledgerKept: false };
136
+ // 尺子内建兜底:给了 targetTokens 却无 estimator 时不得静默不截断
137
+ const estimator = opts?.estimator ?? new HeuristicTokenEstimator();
138
+ const floorKeep = opts?.minKeep != null
139
+ ? Math.min(opts.minKeep, messages.length)
140
+ : Math.min(Math.max(6, Math.ceil(messages.length * 0.15)), messages.length);
141
+ // 切片求和逐轮 O(n²) 叠加:内置估算器对单条消息有 WeakMap 缓存(求和=缓存查找,
142
+ // 实测可接受);改为前缀和会改变自定义估算器的预算语义,不值得
143
+ const tokensOf = (ms) => estimator.estimateMessages(ms);
144
+ let cut = 0;
145
+ while (messages.length - cut > floorKeep &&
146
+ (opts?.targetTokens == null || tokensOf(messages.slice(cut)) > opts.targetTokens)) {
147
+ // 对齐:tool_call+tool_result 对同进同出
148
+ const next = messages[cut + 1];
149
+ cut += hasToolCall(messages[cut]) && next !== undefined && isToolResultMessage(next) ? 2 : 1;
150
+ }
151
+ // 保留尾不得起于孤儿结果(其调用已被丢弃):回退切点把调用一并纳入 kept(宁可胖,
152
+ // 不可拆对、不可吞光——向前跳过会在「连续 tool 结果收尾」时把 kept 清空)
153
+ while (cut > 0 && isToolResultMessage(messages[cut])) {
154
+ cut -= 1;
155
+ }
156
+ const dropped = messages.slice(0, cut);
157
+ const kept = messages.slice(cut);
158
+ if (dropped.length === 0) {
159
+ return { result: [...messages], droppedCount: 0, ledgerKept: false };
160
+ }
161
+ const ledger = buildToolCallLedger(dropped);
162
+ const notice = asLedgerMessage(ledger, dropped.length);
163
+ return { result: [notice, ...kept], droppedCount: dropped.length, ledgerKept: ledger.length > 0 };
164
+ }
165
+ /**
166
+ * 机械降级:整段替换为 purpose 账本(零 LLM,单级,无可再降)。
167
+ *
168
+ * @param messages - 待降级消息
169
+ * @param opts - targetTokens(用于判定是否仍需上报超预算)与估算器
170
+ * @returns 降级结果
171
+ * - `result`:单条账本消息(入参为空时为空数组)
172
+ * - `tokensAfter`:账本 token 估算
173
+ * - `overBudget`:账本仍超 targetTokens —— 已无可降空间,调用方须如实上报,
174
+ * 不得再丢条目(丢条目 = 静默失忆)
175
+ * - `droppedSummary`:产物描述
176
+ */
177
+ export function mechanicalDegrade(messages, opts) {
178
+ if (messages.length === 0) {
179
+ return { result: [], tokensAfter: 0, overBudget: false };
180
+ }
181
+ const estimator = opts?.estimator ?? new HeuristicTokenEstimator();
182
+ const ledger = buildToolCallLedger(messages);
183
+ const ledgerMsg = asLedgerMessage(ledger, messages.length);
184
+ const result = [ledgerMsg];
185
+ const tokensAfter = estimator.estimateMessages(result);
186
+ const overBudget = opts?.targetTokens != null && tokensAfter > opts.targetTokens;
187
+ const callCount = messages.reduce((n, m) => n + (m.toolCalls?.length ?? 0), 0);
188
+ return {
189
+ result,
190
+ tokensAfter,
191
+ overBudget,
192
+ droppedSummary: `Replaced ${messages.length} messages (${callCount} tool calls) with a purpose ledger`,
193
+ };
194
+ }
195
+ /**
196
+ * 工具执行账本化(收敛阶梯第 1–3 轮专用,arch/overflow-redesign.md §3)。
197
+ *
198
+ * 语义(丢弃次序原则:数据细节 → 执行记录 → 工作窗口 → 放弃,从最可再生到最不可再生):
199
+ * - **账本化对象 = 工具执行段**(assistant(toolCalls) + tool(result) 对,同进同出)——
200
+ * 执行记录可再生(可重执行/磁盘找回),先于工作窗口丢弃;
201
+ * - **跳过保留**:真 user 消息(最不可再生)、assistant 文本(非执行记录)、
202
+ * 合成消息(contextLedger/contextSummary 占位——已是索引/交接形态,不可再降);
203
+ * - **tailKeep 近尾保护**(工作窗口):近尾 tailKeep 条内的工具执行不账本化。
204
+ *
205
+ * 形态:被账本化 run 的原位移除,**第一个**被砍 run 的下标处放一个合并 notice
206
+ * (buildToolCallLedger 汇总全部被砍执行的 name+purpose+errors)——与 fold 同构:
207
+ * foldTransformView 对多 covers runs 渲染**一个**占位(firstIndex 处、区间内保护类原样),
208
+ * 本函数的产物即 fold 后视图,守门量的与发送的是同一个产物。
209
+ *
210
+ * 每档独立调用(幂等):无候选时原样返回——天然支持「每档对原视图重算」,不累积吞账本。
211
+ *
212
+ * @param messages - 原始视图(收敛循环对同一 view 每档独立调用)
213
+ * @param opts - tailKeep 近尾保护档、估算器、targetTokens(缺省=砍掉全部候选)
214
+ * @returns 产物视图 + 被账本化条数(0=砍不动/无候选)
215
+ */
216
+ export function toolExecutionLedgerTrim(messages, opts) {
217
+ if (messages.length === 0)
218
+ return { result: [], droppedCount: 0 };
219
+ const isSynthetic = (m) => m.metadata?.source === 'contextLedger' || m.metadata?.source === 'contextSummary';
220
+ const isToolExec = (m) => !isSynthetic(m) && (hasToolCall(m) || isToolResultMessage(m));
221
+ // 档位即语义(B2 拍板 2026-11-08):tailKeep 保护窗内的消息原样保留,
222
+ // **窗外工具执行全部账本化**(砍满候选窗)——砍量由档位定义,不在档内提前停;
223
+ // 「装得下吗」由外层 fits 判(校准+aging 同一把尺),砍量尺与验收尺不混。
224
+ const tailFloor = Math.max(0, messages.length - Math.max(0, opts.tailKeep));
225
+ const runs = [];
226
+ let i = 0;
227
+ while (i < tailFloor) {
228
+ if (!isToolExec(messages[i])) {
229
+ i += 1;
230
+ continue;
231
+ }
232
+ const start = i;
233
+ while (i < tailFloor && isToolExec(messages[i]))
234
+ i += 1;
235
+ let end = i - 1;
236
+ // 边界对齐(评审 B1):run 尾是 tool_call 而其 result 在 tail 窗内/窗后时整对不砍——
237
+ // end 允许降到 start-1(单条 run 的 call 与 result 拆对正是孤儿 result 400 的来源)
238
+ while (end >= start && hasToolCall(messages[end]) && end + 1 < messages.length && isToolResultMessage(messages[end + 1])) {
239
+ end -= 1;
240
+ }
241
+ if (end < start)
242
+ continue; // 整对落在 tail 窗内 → 本 run 不砍(宁可少砍,不可拆对)
243
+ runs.push({ start, end });
244
+ }
245
+ if (runs.length === 0)
246
+ return { result: [...messages], droppedCount: 0 };
247
+ // 砍满:全部候选 run 一次账本化(每档对原视图独立、幂等——累积截断会吞前轮账本)
248
+ const droppedIdx = new Set();
249
+ for (const r of runs)
250
+ for (let k = r.start; k <= r.end; k++)
251
+ droppedIdx.add(k);
252
+ const droppedMsgs = runs.flatMap((r) => messages.slice(r.start, r.end + 1));
253
+ const ledger = buildToolCallLedger(droppedMsgs);
254
+ const notice = asLedgerMessage(ledger, droppedMsgs.length);
255
+ const result = [];
256
+ let noticePlaced = false;
257
+ for (let idx = 0; idx < messages.length; idx++) {
258
+ if (droppedIdx.has(idx)) {
259
+ if (!noticePlaced) {
260
+ result.push(notice);
261
+ noticePlaced = true;
262
+ }
263
+ continue;
264
+ }
265
+ result.push(messages[idx]);
266
+ }
267
+ return { result, droppedCount: droppedMsgs.length };
268
+ }
@@ -0,0 +1,60 @@
1
+ /**
2
+ * 视图消息构造 — 摘要包装与机械占位的唯一实现
3
+ *
4
+ * 摘要包装(`[Conversation Summary]`)与机械占位说明(`[Context truncated:` 等)
5
+ * 此前散落在 llm-summarizer / truncate-compressor / default-context-engine 等 ~6 处
6
+ * (债务 #4)。收敛后:文案、包装、识别全部单源于本模块——**生产者与识别串同源**,
7
+ * 新增占位类型时不得绕过这里手写字面量。
8
+ *
9
+ * @module harness/context/capabilities/compact/messages
10
+ */
11
+ import type { Message } from '@octopi-agent/core/types.js';
12
+ /**
13
+ * 是否工具结果消息(role=tool 或携带 toolResults)。
14
+ *
15
+ * @param msg - 候选消息
16
+ * @returns 是否工具结果消息
17
+ */
18
+ export declare function isToolResultMessage(msg: Message): boolean;
19
+ /**
20
+ * 是否携带工具调用的 assistant 消息(机械阶梯/消息选择器的对齐判别用;
21
+ * 切片对齐 alignViewSplit 沿用旧引擎的无角色判别以保持逐字节行为)。
22
+ *
23
+ * @param msg - 候选消息
24
+ * @returns 是否携带 toolCalls
25
+ */
26
+ export declare function hasToolCall(msg: Message): boolean;
27
+ /** 摘要标记(extract / 调试 / 幂等包装判别共用) */
28
+ export declare const SUMMARY_MARKER = "[Conversation Summary]";
29
+ /**
30
+ * 摘要正文包装:确保带 `[Conversation Summary]` 标记(幂等)。
31
+ *
32
+ * @param text - 摘要正文
33
+ * @returns 带标记的摘要正文
34
+ */
35
+ export declare function wrapSummaryText(text: string): string;
36
+ /**
37
+ * 摘要消息构造(user 角色——中段 system 会被部分网关拒绝)。
38
+ *
39
+ * 覆盖边界行(评审 F11)按覆盖点动态渲染,**不写进摘要正文**:
40
+ * 写进正文会把过期数字烘死、随失败累积、还会被当 Previous summary 回喂模型。
41
+ *
42
+ * @param summary - 摘要正文
43
+ * @param coveredEnd - 摘要覆盖终点(下标,不含);>0 时附 [Coverage] 行
44
+ * @returns 摘要视图消息
45
+ */
46
+ export declare function asSummaryMessage(summary: string, coveredEnd?: number): Message;
47
+ /** 账本降级占位(生产者:mechanical.ts ledgerTruncate / mechanicalDegrade) */
48
+ export declare const MECHANICAL_NOTICE_TRUNCATED = "[Context truncated:";
49
+ /** 头切截断占位(生产者已随 TruncateCompressor 退休;识别保留兜旧持久化状态) */
50
+ export declare const MECHANICAL_NOTICE_COMPRESSED = "[Context compressed:";
51
+ /** 结构压缩占位(生产者:compact 引擎 head_tail_only / 文本结构路径) */
52
+ export declare const MECHANICAL_NOTICE_STRUCTURAL = "[Structural compact]";
53
+ /**
54
+ * 机械降级占位说明判别(非语义摘要):首条实质行以占位标记开头即认定。
55
+ * 只看首行而非全文 includes——真实摘要引用这些字符串(如记录「曾发生截断」)不得被误杀。
56
+ *
57
+ * @param text - 候选摘要正文
58
+ * @returns 是否为机械占位说明
59
+ */
60
+ export declare function isMechanicalNotice(text: string): boolean;
@@ -0,0 +1,91 @@
1
+ /**
2
+ * 视图消息构造 — 摘要包装与机械占位的唯一实现
3
+ *
4
+ * 摘要包装(`[Conversation Summary]`)与机械占位说明(`[Context truncated:` 等)
5
+ * 此前散落在 llm-summarizer / truncate-compressor / default-context-engine 等 ~6 处
6
+ * (债务 #4)。收敛后:文案、包装、识别全部单源于本模块——**生产者与识别串同源**,
7
+ * 新增占位类型时不得绕过这里手写字面量。
8
+ *
9
+ * @module harness/context/capabilities/compact/messages
10
+ */
11
+ // ── 消息形状谓词(切片手术与机械阶梯共用) ──
12
+ /**
13
+ * 是否工具结果消息(role=tool 或携带 toolResults)。
14
+ *
15
+ * @param msg - 候选消息
16
+ * @returns 是否工具结果消息
17
+ */
18
+ export function isToolResultMessage(msg) {
19
+ return msg.role === 'tool' || (msg.toolResults?.length ?? 0) > 0;
20
+ }
21
+ /**
22
+ * 是否携带工具调用的 assistant 消息(机械阶梯/消息选择器的对齐判别用;
23
+ * 切片对齐 alignViewSplit 沿用旧引擎的无角色判别以保持逐字节行为)。
24
+ *
25
+ * @param msg - 候选消息
26
+ * @returns 是否携带 toolCalls
27
+ */
28
+ export function hasToolCall(msg) {
29
+ return msg.role === 'assistant' && (msg.toolCalls?.length ?? 0) > 0;
30
+ }
31
+ // ── 摘要包装(族 A 交接摘要的视图载体) ──
32
+ /** 摘要标记(extract / 调试 / 幂等包装判别共用) */
33
+ export const SUMMARY_MARKER = '[Conversation Summary]';
34
+ /**
35
+ * 摘要正文包装:确保带 `[Conversation Summary]` 标记(幂等)。
36
+ *
37
+ * @param text - 摘要正文
38
+ * @returns 带标记的摘要正文
39
+ */
40
+ export function wrapSummaryText(text) {
41
+ const trimmed = text.trim();
42
+ if (trimmed.includes(SUMMARY_MARKER))
43
+ return trimmed;
44
+ return `${SUMMARY_MARKER}\n\n${trimmed}`;
45
+ }
46
+ /**
47
+ * 摘要消息构造(user 角色——中段 system 会被部分网关拒绝)。
48
+ *
49
+ * 覆盖边界行(评审 F11)按覆盖点动态渲染,**不写进摘要正文**:
50
+ * 写进正文会把过期数字烘死、随失败累积、还会被当 Previous summary 回喂模型。
51
+ *
52
+ * @param summary - 摘要正文
53
+ * @param coveredEnd - 摘要覆盖终点(下标,不含);>0 时附 [Coverage] 行
54
+ * @returns 摘要视图消息
55
+ */
56
+ export function asSummaryMessage(summary, coveredEnd) {
57
+ const coverage = coveredEnd && coveredEnd > 0
58
+ ? `\n\n[Coverage] This handoff covers the conversation up to message ${coveredEnd}; later messages appear verbatim and take precedence.`
59
+ : '';
60
+ return {
61
+ role: 'user',
62
+ content: wrapSummaryText(`${summary}${coverage}`),
63
+ timestamp: Date.now(),
64
+ metadata: { source: 'contextSummary' },
65
+ };
66
+ }
67
+ // ── 机械占位(非摘要,永不进 previousSummary) ──
68
+ /** 账本降级占位(生产者:mechanical.ts ledgerTruncate / mechanicalDegrade) */
69
+ export const MECHANICAL_NOTICE_TRUNCATED = '[Context truncated:';
70
+ /** 头切截断占位(生产者已随 TruncateCompressor 退休;识别保留兜旧持久化状态) */
71
+ export const MECHANICAL_NOTICE_COMPRESSED = '[Context compressed:';
72
+ /** 结构压缩占位(生产者:compact 引擎 head_tail_only / 文本结构路径) */
73
+ export const MECHANICAL_NOTICE_STRUCTURAL = '[Structural compact]';
74
+ /**
75
+ * 机械降级占位说明判别(非语义摘要):首条实质行以占位标记开头即认定。
76
+ * 只看首行而非全文 includes——真实摘要引用这些字符串(如记录「曾发生截断」)不得被误杀。
77
+ *
78
+ * @param text - 候选摘要正文
79
+ * @returns 是否为机械占位说明
80
+ */
81
+ export function isMechanicalNotice(text) {
82
+ for (const raw of text.split('\n')) {
83
+ const line = raw.trim();
84
+ if (!line || line === SUMMARY_MARKER)
85
+ continue;
86
+ return (line.startsWith(MECHANICAL_NOTICE_TRUNCATED) ||
87
+ line.startsWith(MECHANICAL_NOTICE_COMPRESSED) ||
88
+ line.startsWith(MECHANICAL_NOTICE_STRUCTURAL));
89
+ }
90
+ return false;
91
+ }