@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
@@ -3,37 +3,38 @@
3
3
  *
4
4
  * Harness 层的默认实现,整合所有组件:
5
5
  * - MessageSelector:消息选择
6
- * - Compressor:压缩(截断 + LLM 摘要)
6
+ * - capabilities/compact:压缩执行(交接摘要 + 机械降级阶梯;本引擎只做触发/状态)
7
7
  * - BudgetAllocator:预算分配
8
8
  * - TokenEstimator:Token 估算
9
9
  *
10
10
  * 特性:
11
- * - 四区域划分(头部保护 + 中间可压缩 + 尾部保护)
12
- * - 边界对齐(不拆分 tool_call/tool_result 对)
13
- * - 工具结果预处理(清除旧工具输出)
11
+ * - **持久转换记录**(arch/context-size-accounting.md §10.18):压缩产物是事实,
12
+ * 不是临时视图。装配 = 原文 + 有效记录的确定性 fold(transform/fold)——没有
13
+ * 游标、没有增量抢救;没被记录覆盖的消息逐字在视图里。回填只在显式撤销时。
14
+ * - fresh 门控只决定**新记录的类型**(summary / degrade),不再决定旧记录是否生效。
15
+ * - 四区域划分(头部保护 + 中间可压缩 + 尾部保护)退为压缩时刻的选段策略:
16
+ * 保护窗决定记录覆盖哪些消息(写进锚点),装配不再看它们。
17
+ * - 边界对齐(不拆分 tool_call/tool_result 对)——同上,压缩时刻生效。
14
18
  * - 迭代式摘要(传入上次摘要,更新而非重建)
15
19
  * - 实际 token 数回写
16
20
  */
17
21
  import type { Message } from '@octopi-agent/core/types.js';
18
22
  import type { LLMMessage, LLMToolDefinition } from '@octopi-agent/core/interfaces/model-provider.js';
19
- import type { ContextEngine, ContextEngineInfo, AssembleParams, AssembleResult, IngestParams, CompactResult, AfterTurnParams, TokenEstimator, SummarizeFunction, MessageSelector, Compressor, BudgetAllocator, ContextEmitFn } from './types.js';
23
+ import type { ContextEngine, ContextEngineInfo, AssembleParams, AssembleResult, IngestParams, AfterStepParams, TokenEstimator, SummarizeFunction, MessageSelector, BudgetAllocator, ContextEmitFn, ContextCompactSnapshot } from './types.js';
20
24
  import { type ToolResultAgingConfig } from './tool-result-aging.js';
21
- import type { SmartRouterConfig } from './smart-router.js';
22
- import type { CompactEngine } from './capabilities/compact/index.js';
25
+ import type { CompactEngine, CompactOutcome } from './capabilities/compact/index.js';
26
+ import type { TransformStore } from './transform/types.js';
23
27
  export interface DefaultContextEngineConfig {
24
28
  /** 消息选择策略 */
25
29
  messageSelector?: MessageSelector;
26
- /** 压缩策略 */
27
- compressor?: Compressor;
28
30
  /** 预算分配策略 */
29
31
  budgetAllocator?: BudgetAllocator;
30
32
  /** Token 估算器 */
31
33
  tokenEstimator?: TokenEstimator;
32
34
  /** 智能路由器配置 */
33
- router?: SmartRouterConfig;
34
- /** 头部保护消息数(默认 5:交接快照的「任务前因」) */
35
+ /** 头部保护消息数(默认 5:交接快照的「任务前因」)。压缩时刻的选段策略。 */
35
36
  protectFirstN?: number;
36
- /** 尾部保护消息数(默认 20:进度锚,明确任务截止到哪) */
37
+ /** 尾部保护消息数(默认 20:进度锚,明确任务截止到哪)。压缩时刻的选段策略。 */
37
38
  protectLastN?: number;
38
39
  /** 摘要软目标预算(P1c 缺省 clamp(2%, 2k, 8k)):可配置 ratioPct/minTokens/maxTokens */
39
40
  summaryBudget?: {
@@ -44,155 +45,178 @@ export interface DefaultContextEngineConfig {
44
45
  /**
45
46
  * 窗口比例线:消息 token / messagesBudget 超过该比例时,
46
47
  * 在窗口硬溢出之前先做主动压缩(缓解长会话失忆 / 窗口到顶未触发)。
47
- * 默认 0.6;`0` = 禁止**发起新的**路径 A 压缩(不只禁 LLM),**不**丢已有粘滞压缩视图。
48
+ * 默认 0.6;`0` = 禁止**发起新的**路径 A 压缩(不只禁 LLM),不丢已有转换记录。
48
49
  */
49
50
  proactiveCompactRatio?: number;
51
+ /** 主动 LLM 摘要冷却(ms)。冷却期内零 LLM 复用(fold),避免单 turn 双摘要。默认 30_000。 */
52
+ proactiveCooldownMs?: number;
50
53
  /**
51
- * 主动 LLM 摘要冷却(ms)。冷却期内优先缓存重建,避免单 turn 双摘要。
52
- * 默认 30_000;0 表示不冷却。
54
+ * 单次摘要 LLM 调用预算(ms)。0 = 不设预算(只受 provider 超时约束)。
55
+ * 默认 300_000:摘要请求体量与视图同阶(P2 后约 100–200KB),正常远低于此值;
56
+ * 留足慢 provider / 大请求的余量,同时给「provider 挂死」一个确定上界——超时即中止,
57
+ * 按 onSummarizeFail 降级(2026-11-07 事故)。中断不续做:下一轮重新发起即可。
53
58
  */
54
- proactiveCooldownMs?: number;
59
+ summarizeTimeoutMs?: number;
55
60
  /**
56
61
  * 历史工具结果批量冻结老化(F1-B2):当前 run 永不老化、近 rawWindow 条跨轮原文、
57
62
  * 更旧按 freezeBatch 成批降级为结构化指针(视图级、write-once、禁渐进)。
58
63
  * 缺省启用(40 条 / 批 20 / 指针 400 字符)。
59
64
  */
60
65
  historyAging?: ToolResultAgingConfig;
61
- /**
62
- * 工作目标 token(与窗口解耦,F1-B3)。>0 时主动压缩目标线 = targetTokens ×
63
- * compactFallbackRatio,并与窗口比例线取 min。
64
- * 默认 200000;0 = 只挂窗口比例线(proactiveCompactRatio)。
65
- */
66
+ /** 工作目标 token(与窗口解耦,F1-B3)。>0 时主动压缩目标线 = targetTokens × compactFallbackRatio。默认 200000。 */
66
67
  targetTokens?: number;
68
+ /** 目标线倍数(默认 3)。触发线 = targetTokens × compactFallbackRatio;窗口比例线始终并存。 */
69
+ compactFallbackRatio?: number;
67
70
  /**
68
- * 目标线倍数(默认 3)。触发线 = targetTokens × compactFallbackRatio;
69
- * 须 > B2 老化稳态,否则双机制打架(每 turn 触发压缩)。1.5 时刚过目标就压、
70
- * 压完只回到约目标附近,压缩收益太小;3 让压缩成为有意义的收缩。
71
- * ⚠️ 窗口比例线(messagesBudget × proactiveCompactRatio)始终并存,防小窗口到顶未触发。
71
+ * turn 内(工具活动进行中)主动压缩的保护尾条数(2026-11-07 方案 E 修订)。
72
+ * turn 内进行中的工作记录(最近的工具步骤/证据/推理链)不进压缩选段,由活跃窗口保护;
73
+ * 窗口外的执行痕迹可正常语义压缩(长任务 turn 内上下文持续增长时目标线才真正生效)。
74
+ * turn 边界仍用 protectLastN。默认 50;取 max(protectLastN, midTurnProtectLastN)。
72
75
  */
73
- compactFallbackRatio?: number;
74
- /** 公用能力 CompactEngine(缺省自动创建;算法委托,E4 状态仍在本引擎) */
76
+ midTurnProtectLastN?: number;
77
+ /** 公用能力 CompactEngine(缺省自动创建;算法委托,记录/状态仍在本引擎) */
75
78
  compactEngine?: CompactEngine;
79
+ /**
80
+ * 转换记录存储(持久化拍板:记录跨装配永久生效)。缺省 InMemory(进程内永久);
81
+ * 组合层注入 JsonlTransformStore 获得 `sessions/<sid>/transform/` 持久化。
82
+ */
83
+ transformStore?: TransformStore;
84
+ /** Host extension boundary; absent preserves the existing engine exactly. */
85
+ extensionHooks?: import('../extension/plugin-ecosystem/hooks/types.js').ExtensionHookPort;
86
+ extensionIdentity?: {
87
+ sessionId: string;
88
+ agentId?: string;
89
+ };
76
90
  }
77
- /** 摘要正文包装:确保带 [Conversation Summary] 标记,便于 extract / 调试 */
78
- declare function wrapContextSummary(text: string): string;
79
- /** 供调用方/测试引用 */
80
- export { wrapContextSummary };
81
91
  export declare class DefaultContextEngine implements ContextEngine {
82
92
  readonly info: ContextEngineInfo;
83
93
  private config;
84
- private router;
85
94
  private states;
95
+ /** 转换记录账本缓存(每 (sessionId, agentId) 加载一次;append 同步进缓存) */
96
+ private ledgers;
97
+ /** 孤儿记录告警去重(键:session|agent|seq[|partial]) */
98
+ private orphanWarned;
99
+ /** P1-a 校准台账:ratio 按 model 分键,observe/calibrate 唯一出入口 */
100
+ private sizeLedger;
86
101
  constructor(config?: DefaultContextEngineConfig);
87
102
  /**
88
103
  * 组装上下文
89
104
  *
90
- * 核心方法。根据 token 预算,选择最有价值的信息组装成 LLM 上下文。
105
+ * 核心方法。装配 = 原文 + 有效转换记录的确定性 fold;需要收缩时由
106
+ * proactive/overflow 路径产出新记录(记录先落盘、后发视图)。
91
107
  *
92
- * 使用 SmartRouter 进行智能路由决策:
108
+ * 路由(Q2 B′ 后两路由):
93
109
  * - fits: 不需要压缩
94
- * - truncate_tool_results_only: 只截断工具输出
95
- * - compact_only: 只做 LLM 摘要
96
- * - compact_then_truncate: 先 LLM 摘要,再截断
110
+ * - compact: 走 compact 能力(有 summarize 出真摘要;无 summarize / 失败走机械降级阶梯)
97
111
  */
98
112
  assemble(params: AssembleParams): Promise<AssembleResult>;
99
- /** 从引擎内存态导出可持久化快照 */
100
- private buildCompactSnapshot;
101
113
  /**
102
- * 主动压缩(路径 A):消息 token 超过触发线时,在硬溢出前收缩
114
+ * 加载(并缓存)(sessionId, agentId) 的转换记录账本;账本为空且有旧压缩快照时
115
+ * 一次性迁移(幂等:账本非空即跳过)。
103
116
  *
104
- * 触发线取两条线的 min(都保留,缺一不可):
105
- * - **目标线** targetTokens × compactFallbackRatio——与窗口解耦,防长会话失忆
106
- * - **窗口比例线** messagesBudget × proactiveCompactRatio——防小窗口/已知窗口到顶仍未触发
107
- *
108
- * 语义(粘滞 + ratio=0 禁新压缩):
109
- * - **压缩视图粘滞**:一旦建立过压缩态(previousSummary 或 lastProactiveMessageCount),
110
- * 后续装配优先复用 head+摘要/机械中间+tail,不因估算回落或 ratio=0 而打回全量
111
- * (全量请求会 bust 前缀缓存,且等于撤销已完成的压缩)。
112
- * - **proactiveCompactRatio=0**:禁止**发起新的**路径 A 压缩(不只禁 LLM);
113
- * **不**丢弃已有压缩视图。
114
- * - 策略:
115
- * - ratio=0:无压缩态原样返回;有压缩态仅粘滞重建
116
- * - 未超线且无压缩态:原样返回
117
- * - 超线且需要新一轮压缩(上次压缩后新增消息够多):LLM 压缩中间段并产出语义摘要
118
- * - 已有压缩态且增量小或冷却中或禁新 LLM:零 LLM 重建视图
117
+ * @param sessionId - 会话 id
118
+ * @param agentId - agent id
119
+ * @param messages - 全量原始消息(迁移锚点需要)
120
+ * @param loadLegacy - 旧 ContextCompactSnapshot 读口(迁移输入;缺省不迁移)
121
+ * @returns 账本
119
122
  */
120
- private applyProactiveCompact;
123
+ private loadLedger;
121
124
  /**
122
- * 保守降级(overflow **middle 替换体**):工具账本说明 + 近尾
123
- * 外层 head/tail 由 assemble 重组拼接,此处不得重复携带。
125
+ * 摘要调用预算(P3):外部 abort 与单次摘要超时合并成一个 signal。
124
126
  *
125
- * @param messages - 待降级消息(overflow 段)
126
- * @param _estimator - token 估算器(保留签名对称)
127
- * @returns 降级后的消息列表
128
- */
129
- private conservativeTruncate;
130
- /**
131
- * 从压缩结果中提取语义摘要正文(contextSummary 标记或 [Conversation Summary] 前缀)。
132
- * 机械降级的占位说明([Context truncated / [Context compressed / [Structural compact])
133
- * 不算语义摘要:把它们当摘要存入 previousSummary 会污染增量合并输入,
134
- * 并让复用分支拿到假摘要、掩盖「从未真正摘要」的事实。
135
- */
136
- private extractSummaryText;
137
- /**
138
- * 机械降级占位说明判别(非语义摘要):首条实质行以占位标记开头即认定。
139
- * 只看首行而非全文 includes——真实摘要引用这些字符串(如记录「曾发生截断」)不得被误杀。
127
+ * 为什么必须合并:run 中止只到 convertToLlm 边界,摘要调用在 `provider.chat` 内部
128
+ * 等待 HTTP;没有 signal 时 abort 只能等 provider 自己超时(实测 900s,UI 全程假死)。
140
129
  *
141
- * @param text - 候选摘要正文
142
- * @returns 是否为机械占位说明
130
+ * @param external - 上游(run)abort 信号
131
+ * @returns 合并信号与「是否超时」判定(超时归失败降级,外部中止归取消不写记录)
143
132
  */
144
- private isMechanicalNotice;
133
+ private createSummarizeSignal;
145
134
  /**
146
- * 判断是否工具结果消息(视图边界对齐用)
135
+ * 请求口径读数:**fold 视图 + 老化** = 实际发给 LLM 的 messages 部分。
147
136
  *
148
- * @param msg - 待判定消息
149
- * @returns 是否为工具结果消息
137
+ * 压缩决策(触发线、增长门、记录 meta)只许用这个口径:量原文会让「已压缩但视图很小」
138
+ * 的会话被反复判超线(2026-11-07 事故:视图 118k、原文 621k → 每次增长 25% 必然重压)。
139
+ *
140
+ * @param folded - 当前 fold 结果
141
+ * @param agingPlan - 老化计划(基于完整历史,按消息身份匹配)
142
+ * @param estimator - 校准后的估算器
143
+ * @returns messages 口径 token 估算
150
144
  */
151
- private isToolResultMessage;
145
+ private measureRequestViewTokens;
152
146
  /**
153
- * 视图切分边界对齐(不拆 tool_call/tool_result 对)
147
+ * 摘要请求的回声比对源(P2):前缀去掉既有压缩占位。
154
148
  *
155
- * head 不得停在带 toolCalls 的 assistant 上(其结果落入中间段,视图里会成悬空调用);
156
- * tail 不得起于 tool 结果(其调用在中间段,会成孤儿结果)——两种形状都会被严格网关 400。
149
+ * 前缀已是 fold 视图时,占位正文就是「上一份交接书」——模型续写/复用它是正常迭代,
150
+ * 不是复读原文;若把占位计入比对源,只要新增内容不多就会误判 verbatim_echo 并降级。
157
151
  *
158
- * @param messages - 全量消息
159
- * @param headCount - 期望头部条数
160
- * @param tailCount - 期望尾部条数
161
- * @returns 对齐后的 head 终点(不含)与 tail 起点(含)
152
+ * @param view - 摘要前缀所用的消息(fold 视图)
153
+ * @param systemPrompt - 同形 system
154
+ * @param agingPlan - 老化计划(与真实请求同式)
155
+ * @returns 换行拼接的文本投影
162
156
  */
163
- private alignViewSplit;
157
+ private buildEchoSource;
158
+ /** 重 fold(append 后调用);孤儿告警去重键 = session|agent|seq(F9:跨会话不串键) */
159
+ private foldView;
164
160
  /**
165
- * 压缩/摘要的语义输入:丢掉托管 system 与 turn 信封元数据
166
- * (turn_context picks 不进 previousSummary——防陈旧择取固化进摘要);
167
- * turn_start 只保留 <user_message> 正文。
161
+ * 显式撤销一条转换记录(回填的唯一通道;记录模型拍板:「回填只在显式撤销时」)。
162
+ *
163
+ * 撤销是 append-only 附加行,永久生效面翻转为 revoked;被覆盖的原文在下一次
164
+ * 装配回到视图。宿主(UI/工具)据此实现「撤销压缩」。
165
+ *
166
+ * @param sessionId - 会话 id
167
+ * @param agentId - agent id
168
+ * @param seq - 记录 seq(账本 load 可得)
169
+ * @returns void
168
170
  */
169
- private semanticHistory;
171
+ revokeTransformRecord(sessionId: string, agentId: string | undefined, seq: number): Promise<void>;
172
+ /** 当前有效语义摘要正文(最新 summary 型记录的文本;机械占位永不冒充) */
173
+ private deriveSummary;
170
174
  /**
171
- * 摘要消息构造(装配/度量共用)——禁止在别处手抄此形状,防口径漂移
175
+ * previousSummary 的覆盖终点(下标,不含)——与 deriveSummary 同一选择口径(最新、
176
+ * type==='summary'、有正文)的记录,返回其**解析后**覆盖端(M-4/C1,评审 del-e1ee43ef)。
177
+ *
178
+ * 摘要素材起点必须与 previousSummary 同源:derivedCoverEnd 含 degrade 多 run 的最大覆盖
179
+ * 端 E(E > S 是常态),以 E 为起点会把 [S, E)「既不在旧摘要、也不在新素材」的原文排除,
180
+ * 而新记录 covers 吞掉 [headEnd, tailStart) 全区间 → 静默丢数据。返回 undefined = 覆盖端
181
+ * 解析不出(如零覆盖 legacy 记录)→ 素材回退全区间(宁可胖不丢,方向安全)。
172
182
  */
173
- private contextSummaryMessage;
183
+ private deriveSummaryCoverEnd;
184
+ /** 有效记录覆盖终点(下标,不含)——传输口径 coveredMessageCount 用 */
185
+ private derivedCoverEnd;
186
+ /** 重启恢复:增长门/冷却基数从账本 meta 初始化(仅内存态缺失时;F2 对称) */
187
+ private restoreGatesFromLedger;
174
188
  /**
175
- * 粘性视图布局 = head + 摘要 + tail(压缩后请求视图的唯一实现,装配与度量共用)
189
+ * 压缩产物 → 持久转换记录(三条压缩路径的唯一翻译口)。
190
+ *
191
+ * 翻译 = 对照压缩输入与产物视图做身份差分:产物里消失的原文/占位所代表的原始
192
+ * 区间即记录覆盖区间(contiguous 合并)。fresh 且为真摘要 → summary 型;否则
193
+ * degrade 型(机械占位如实分类,伪摘要永不冒充 summary)。
176
194
  *
177
- * @param messages - 全量原始消息
178
- * @param protectFirstN - 头部保护条数
179
- * @param protectLastN - 尾部保护条数
180
- * @param summary - 语义摘要正文
181
- * @returns 视图消息列表;总长 ≤ 头尾保护无需压缩时返回 null
195
+ * @param params - 输入集合、产物视图、fresh 判定等
196
+ * @returns 生成的记录(无丢弃时为 undefined,不产记录)
182
197
  */
183
- private stickyViewMessages;
198
+ private appendRecordFromProduct;
184
199
  /**
185
- * 结构视图:有 previousSummary 时 head + summary + tail;否则原样
186
- * 用于 contextWindow 未知时的 assemble / 手动压缩后的回放
200
+ * 主动压缩(路径 A):消息 token 超过触发线时,在硬溢出前收缩
201
+ *
202
+ * 触发线取两条线的 min:
203
+ * - **目标线** targetTokens × compactFallbackRatio——与窗口解耦,防长会话失忆
204
+ * - **窗口比例线** messagesBudget × proactiveCompactRatio——防小窗口到顶未触发
205
+ *
206
+ * 语义(记录模型):
207
+ * - 装配 = fold(原文 + 有效记录);已有压缩态天然粘滞,不因估算回落打回全量
208
+ * - proactiveCompactRatio=0:禁止发起**新的**压缩;已有记录照常生效
209
+ * - 超线且需要新一轮压缩(增长门 + 冷却):LLM 压缩中间段 → 产出 summary 记录
210
+ * - 其余情形:零 LLM,直接返回 fold 视图
187
211
  */
188
- private buildStructuralView;
212
+ private applyProactiveCompact;
189
213
  /**
190
214
  * 结构压缩:头尾保护 + 中间段摘要(不依赖 contextWindow)
191
- * 算法委托 capabilities/compact;本引擎只维护 E4 状态。
215
+ * 算法委托 capabilities/compact;本引擎把产物翻译成转换记录。
192
216
  */
193
217
  private structuralCompact;
194
218
  /**
195
- * 结构压缩入口(手动 / overflow)— 可无 contextWindow
219
+ * 结构压缩入口(手动)— 可无 contextWindow
196
220
  *
197
221
  * @param input - sessionId + 全量 messages + 可选 summarize
198
222
  * @returns 压缩结果
@@ -215,35 +239,77 @@ export declare class DefaultContextEngine implements ContextEngine {
215
239
  maxOutputTokens?: number;
216
240
  /** F22:cache-miss 旁路事件出口(manual 路可观测性,与 proactive/overflow 对称) */
217
241
  emit?: ContextEmitFn;
218
- }): Promise<CompactResult>;
242
+ /** 旧压缩快照读口(迁移输入;缺省不迁移) */
243
+ loadCompactState?: (sessionId: string) => Promise<ContextCompactSnapshot | undefined> | ContextCompactSnapshot | undefined;
244
+ }): Promise<CompactOutcome>;
245
+ /**
246
+ * 冻结请求级配对槽(callId 同源配对的唯一写入口,2026-11-08)。
247
+ *
248
+ * 每次冻结携带单调 seq(pairSeq)作请求身份;覆盖未消费的旧槽即作废并告警——
249
+ * 「上一请求 usage 未到就再次装配」正是错位对(0.085/0.258 家族)的嫌疑通道,
250
+ * 静默覆盖会让旧估算去配陌生 usage。覆盖语义=只认最新发送(串行下与先到先得等价,
251
+ * 非串行下更安全:旧请求可能已被重试/替代)。
252
+ *
253
+ * @param stateKey 会话状态键
254
+ * @param rawEstimatedTokens 本请求「system+tools+视图」口径未校准估算
255
+ * @param modelKey 校准分键
256
+ */
257
+ /**
258
+ * 校准分键(取舍③落地 2026-11-08):ratio/锚按 (session, modelKey) 复合键隔离——
259
+ * 同 modelKey 的多 session 内容形态各异,混学 EMA 互相毒化(生产实证:跨形态比率
260
+ * 0.185 vs 1.263 共存)。stateKey 即 session 维度(E4 compact key component)。
261
+ */
262
+ private calKey;
263
+ private freezeUsagePair;
219
264
  /**
220
265
  * 每轮结束后更新状态
221
266
  *
222
- * 使用 LLM 返回的真实 usage 校准 token 估算:
223
- * 1. 存储真实 reported prompt tokens
224
- * 2. 记录当前消息数量快照(用于增量估算)
225
- * 3. 计算校准比率 = actual / estimated
267
+ * 使用 LLM 返回的真实 usage 校准 token 估算:把(实测 prompt, 请求口径估算)样本
268
+ * 送入 ContextSizeLedger(P1-a,ratio 按 model 分键)。
269
+ *
270
+ * 配对纪律(2026-11-07):分母只能是**本请求** assemble 冻结的 pendingUsagePair,
271
+ * 消费即清;缺对丢样,绝不拿旧估算/旧实测凑对(错位对是毒 ratio 样本与毒锚的源头)。
226
272
  */
227
- afterTurn(params: AfterTurnParams): Promise<void>;
273
+ afterStep(params: AfterStepParams): Promise<void>;
228
274
  /**
229
275
  * 存储消息(可选)
230
276
  *
231
277
  * DefaultContextEngine 不需要单独存储消息,
232
278
  * 因为消息历史由调用方管理。
233
279
  */
280
+ /**
281
+ * 校准状态快照(持久化用):per-key 样本计数 + 锚(含 stateKey 归属)。
282
+ * 与 importCalibration 配对——重启后恢复,消除校准冷启动过渡(跑几轮才准)。
283
+ */
284
+ exportCalibration(): {
285
+ samples: Record<string, {
286
+ samples: number;
287
+ }>;
288
+ anchors: Record<string, {
289
+ actual: number;
290
+ raw: number;
291
+ modelKey: string;
292
+ }>;
293
+ };
294
+ /**
295
+ * 校准状态恢复(restore 用):锚/样本计数回填——restore 后第一轮即 anchored/calibrated。
296
+ */
297
+ importCalibration(data: {
298
+ samples?: Record<string, {
299
+ samples: number;
300
+ }>;
301
+ anchors?: Record<string, {
302
+ actual: number;
303
+ raw: number;
304
+ modelKey: string;
305
+ }>;
306
+ }): void;
234
307
  ingest(_params: IngestParams): Promise<void>;
235
308
  /**
236
309
  * 构建 LLM 消息格式
237
310
  *
238
311
  * 将内部 Message 格式转换为 LLM Message 格式。
239
312
  */
240
- /**
241
- * 使用校准比率修正 token 估算
242
- *
243
- * 当有真实 usage 数据时,用 calibrationRatio 修正启发式估算值。
244
- * 优先用真实值,估算只做兜底,校准比率平滑修正偏差。
245
- */
246
- private calibrateTokens;
247
313
  private buildLlmMessages;
248
314
  /**
249
315
  * 转换单条消息为 LLM 格式
@@ -277,3 +343,13 @@ export declare class DefaultContextEngine implements ContextEngine {
277
343
  * @returns 是否 turn 内
278
344
  */
279
345
  export declare function isMidTurn(messages: Message[]): boolean;
346
+ /**
347
+ * 最后一条「真实 user 消息」的下标(turn 起点标识)。
348
+ *
349
+ * 「真实 user」= 无 agentId 归因,且非引擎载体(含 `engineHint` reliability 注入)。
350
+ * 历史 append-only,该下标在同 turn 内稳定,可作 turn key(overflow 每 turn 限一次用)。
351
+ *
352
+ * @param messages - 全量消息
353
+ * @returns 下标;无真实 user 时返回 -1
354
+ */
355
+ export declare function lastGenuineUserIndex(messages: Message[]): number;