@octopi-agent/engine 0.98.4 → 0.121.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 (493) hide show
  1. package/dist/builtin-model-info.js +28 -7
  2. package/dist/config-admin/agent-presets.d.ts +32 -0
  3. package/dist/config-admin/agent-presets.js +133 -0
  4. package/dist/config-admin/discover.d.ts +33 -4
  5. package/dist/config-admin/discover.js +101 -6
  6. package/dist/config-admin/env.d.ts +11 -0
  7. package/dist/config-admin/env.js +41 -0
  8. package/dist/config-admin/error-copy.d.ts +106 -0
  9. package/dist/config-admin/error-copy.js +287 -0
  10. package/dist/config-admin/i18n.d.ts +21 -0
  11. package/dist/config-admin/i18n.js +19 -0
  12. package/dist/config-admin/index.d.ts +6 -2
  13. package/dist/config-admin/index.js +3 -1
  14. package/dist/config-admin/model-presets.d.ts +14 -0
  15. package/dist/config-admin/model-presets.js +595 -70
  16. package/dist/config-admin/onboarding-apply.d.ts +71 -0
  17. package/dist/config-admin/onboarding-apply.js +235 -0
  18. package/dist/config-admin/onboarding.d.ts +154 -0
  19. package/dist/config-admin/onboarding.js +270 -0
  20. package/dist/config-admin/redact.d.ts +42 -9
  21. package/dist/config-admin/redact.js +69 -5
  22. package/dist/config-schema/agent.d.ts +40 -6
  23. package/dist/config-schema/agent.js +44 -6
  24. package/dist/config-schema/browser.d.ts +62 -0
  25. package/dist/config-schema/browser.js +89 -0
  26. package/dist/config-schema/context.d.ts +12 -37
  27. package/dist/config-schema/context.js +10 -31
  28. package/dist/config-schema/engine.d.ts +140 -164
  29. package/dist/config-schema/engine.js +10 -7
  30. package/dist/config-schema/governance.d.ts +20 -2
  31. package/dist/config-schema/governance.js +18 -3
  32. package/dist/config-schema/models.d.ts +10 -12
  33. package/dist/config-schema/models.js +16 -3
  34. package/dist/config-schema/run.d.ts +6 -2
  35. package/dist/config-schema/run.js +12 -2
  36. package/dist/config-schema/shared.d.ts +1 -3
  37. package/dist/config-schema/shared.js +4 -4
  38. package/dist/config-schema/substrate.d.ts +19 -88
  39. package/dist/config-schema/substrate.js +30 -107
  40. package/dist/config.d.ts +161 -123
  41. package/dist/config.js +109 -7
  42. package/dist/file-mode.d.ts +67 -0
  43. package/dist/file-mode.js +182 -0
  44. package/dist/fork-child.d.ts +82 -0
  45. package/dist/fork-child.js +123 -0
  46. package/dist/harness/activation/delegated-run.d.ts +42 -0
  47. package/dist/harness/activation/delegated-run.js +71 -0
  48. package/dist/harness/activation/dispatcher.js +11 -0
  49. package/dist/harness/activation/inbox.d.ts +3 -3
  50. package/dist/harness/activation/inbox.js +3 -3
  51. package/dist/harness/activation/index.d.ts +1 -0
  52. package/dist/harness/activation/run-backend.d.ts +92 -0
  53. package/dist/harness/activation/run-backend.js +16 -0
  54. package/dist/harness/activation/run-protocol.d.ts +392 -0
  55. package/dist/harness/activation/run-protocol.js +19 -0
  56. package/dist/harness/activation/runtime.d.ts +33 -0
  57. package/dist/harness/activation/runtime.js +130 -31
  58. package/dist/harness/activation/types.d.ts +20 -3
  59. package/dist/harness/agent/builder.d.ts +36 -3
  60. package/dist/harness/agent/builder.js +206 -46
  61. package/dist/harness/agent/config-bridge.d.ts +10 -1
  62. package/dist/harness/agent/config-bridge.js +24 -5
  63. package/dist/harness/agent/config-integrity.js +19 -2
  64. package/dist/harness/agent/registered-tool-adapter.d.ts +27 -0
  65. package/dist/harness/agent/registered-tool-adapter.js +67 -0
  66. package/dist/harness/agent/wire-agent-builder.d.ts +13 -3
  67. package/dist/harness/agent/wire-agent-builder.js +35 -9
  68. package/dist/harness/capabilities/document/backends/plain.js +2 -1
  69. package/dist/harness/capabilities/document/factory.d.ts +5 -0
  70. package/dist/harness/capabilities/document/factory.js +1 -0
  71. package/dist/harness/capabilities/document/legacy/factory.js +3 -2
  72. package/dist/harness/capabilities/document/port.js +6 -3
  73. package/dist/harness/capabilities/document/types.d.ts +5 -0
  74. package/dist/harness/collaboration/autonomous-subsystem/audit/reader.d.ts +17 -0
  75. package/dist/harness/collaboration/autonomous-subsystem/audit/reader.js +66 -36
  76. package/dist/harness/collaboration/autonomous-subsystem/audit/writer.d.ts +6 -2
  77. package/dist/harness/collaboration/autonomous-subsystem/audit/writer.js +27 -7
  78. package/dist/harness/collaboration/autonomous-subsystem/boundary/validator.js +13 -0
  79. package/dist/harness/collaboration/autonomous-subsystem/loader.js +2 -1
  80. package/dist/harness/collaboration/autonomous-subsystem/runtime.d.ts +11 -0
  81. package/dist/harness/collaboration/autonomous-subsystem/runtime.js +17 -0
  82. package/dist/harness/collaboration/autonomous-subsystem/sense/engine.d.ts +14 -4
  83. package/dist/harness/collaboration/autonomous-subsystem/sense/engine.js +50 -41
  84. package/dist/harness/collaboration/autonomous-subsystem/sense/input-builder.js +4 -4
  85. package/dist/harness/collaboration/autonomous-subsystem/sense/metrics.d.ts +2 -2
  86. package/dist/harness/collaboration/autonomous-subsystem/sense/metrics.js +2 -2
  87. package/dist/harness/collaboration/autonomous-subsystem/signal/bus.d.ts +6 -0
  88. package/dist/harness/collaboration/autonomous-subsystem/signal/bus.js +25 -4
  89. package/dist/harness/collaboration/autonomous-subsystem/think/executor.js +4 -1
  90. package/dist/harness/collaboration/autonomous-subsystem/types.d.ts +7 -3
  91. package/dist/harness/collaboration/delegation/child-run.d.ts +10 -1
  92. package/dist/harness/collaboration/delegation/child-run.js +38 -6
  93. package/dist/harness/collaboration/delegation/index.d.ts +1 -1
  94. package/dist/harness/collaboration/delegation/index.js +1 -1
  95. package/dist/harness/collaboration/delegation/notifier.d.ts +6 -1
  96. package/dist/harness/collaboration/delegation/notifier.js +8 -1
  97. package/dist/harness/collaboration/delegation/registry-types.d.ts +2 -0
  98. package/dist/harness/collaboration/delegation/service.d.ts +11 -4
  99. package/dist/harness/collaboration/delegation/service.js +35 -13
  100. package/dist/harness/collaboration/delegation/store.d.ts +4 -0
  101. package/dist/harness/collaboration/delegation/store.js +3 -1
  102. package/dist/harness/collaboration/delegation/types.d.ts +34 -2
  103. package/dist/harness/collaboration/delegation/types.js +22 -0
  104. package/dist/harness/collaboration/delegation/wiring.d.ts +2 -0
  105. package/dist/harness/collaboration/delegation/wiring.js +12 -1
  106. package/dist/harness/context/budget-allocator.d.ts +26 -18
  107. package/dist/harness/context/budget-allocator.js +67 -32
  108. package/dist/harness/context/capabilities/compact/engine.d.ts +44 -11
  109. package/dist/harness/context/capabilities/compact/engine.js +296 -160
  110. package/dist/harness/context/capabilities/compact/handover.d.ts +5 -3
  111. package/dist/harness/context/capabilities/compact/handover.js +7 -5
  112. package/dist/harness/context/capabilities/compact/index.d.ts +7 -2
  113. package/dist/harness/context/capabilities/compact/index.js +5 -1
  114. package/dist/harness/context/capabilities/compact/mechanical.d.ts +130 -0
  115. package/dist/harness/context/capabilities/compact/mechanical.js +268 -0
  116. package/dist/harness/context/capabilities/compact/messages.d.ts +60 -0
  117. package/dist/harness/context/capabilities/compact/messages.js +91 -0
  118. package/dist/harness/context/capabilities/compact/types.d.ts +134 -19
  119. package/dist/harness/context/capabilities/compact/types.js +11 -1
  120. package/dist/harness/context/capabilities/compact/view-split.d.ts +36 -0
  121. package/dist/harness/context/capabilities/compact/view-split.js +72 -0
  122. package/dist/harness/context/capabilities/summary/gate.d.ts +19 -2
  123. package/dist/harness/context/capabilities/summary/gate.js +53 -6
  124. package/dist/harness/context/capabilities/summary/port.js +0 -1
  125. package/dist/harness/context/capabilities/summary/registry.js +20 -0
  126. package/dist/harness/context/capabilities/summary/resolver.d.ts +1 -1
  127. package/dist/harness/context/capabilities/summary/resolver.js +1 -6
  128. package/dist/harness/context/capabilities/summary/tool-binding.d.ts +1 -1
  129. package/dist/harness/context/capabilities/summary/tool-binding.js +16 -12
  130. package/dist/harness/context/capabilities/summary/tool-bindings.d.ts +13 -0
  131. package/dist/harness/context/capabilities/summary/tool-bindings.js +22 -0
  132. package/dist/harness/context/capabilities/summary/types.d.ts +19 -6
  133. package/dist/harness/context/constitution/default-agents.md +85 -0
  134. package/dist/harness/context/context-size-ledger.d.ts +143 -0
  135. package/dist/harness/context/context-size-ledger.js +243 -0
  136. package/dist/harness/context/default-context-engine.d.ts +290 -120
  137. package/dist/harness/context/default-context-engine.js +1555 -764
  138. package/dist/harness/context/index.d.ts +3 -2
  139. package/dist/harness/context/index.js +2 -1
  140. package/dist/harness/context/layer-health.d.ts +4 -0
  141. package/dist/harness/context/layer-health.js +4 -0
  142. package/dist/harness/context/layer-types.d.ts +72 -0
  143. package/dist/harness/context/layer-types.js +87 -2
  144. package/dist/harness/context/layers.d.ts +17 -15
  145. package/dist/harness/context/layers.js +54 -17
  146. package/dist/harness/context/message-selector.d.ts +10 -8
  147. package/dist/harness/context/message-selector.js +49 -27
  148. package/dist/harness/context/prefix-fingerprint.d.ts +46 -0
  149. package/dist/harness/context/prefix-fingerprint.js +52 -0
  150. package/dist/harness/context/summarize.d.ts +2 -2
  151. package/dist/harness/context/summarize.js +27 -2
  152. package/dist/harness/context/system-prompt-assembler.d.ts +4 -0
  153. package/dist/harness/context/system-prompt-assembler.js +7 -3
  154. package/dist/harness/context/token-constants.d.ts +8 -6
  155. package/dist/harness/context/token-constants.js +8 -7
  156. package/dist/harness/context/token-estimate-fns.d.ts +37 -27
  157. package/dist/harness/context/token-estimate-fns.js +85 -66
  158. package/dist/harness/context/token-estimator.d.ts +27 -12
  159. package/dist/harness/context/token-estimator.js +120 -66
  160. package/dist/harness/context/token-segments.d.ts +88 -0
  161. package/dist/harness/context/token-segments.js +103 -0
  162. package/dist/harness/context/tool-result-aging.d.ts +109 -16
  163. package/dist/harness/context/tool-result-aging.js +220 -55
  164. package/dist/harness/context/tool-result-body.js +2 -0
  165. package/dist/harness/context/transform/anchors.d.ts +66 -0
  166. package/dist/harness/context/transform/anchors.js +125 -0
  167. package/dist/harness/context/transform/fold.d.ts +56 -0
  168. package/dist/harness/context/transform/fold.js +135 -0
  169. package/dist/harness/context/transform/migrate.d.ts +41 -0
  170. package/dist/harness/context/transform/migrate.js +69 -0
  171. package/dist/harness/context/transform/types.d.ts +129 -0
  172. package/dist/harness/context/transform/types.js +19 -0
  173. package/dist/harness/context/turn-envelope.d.ts +6 -3
  174. package/dist/harness/context/types.d.ts +196 -119
  175. package/dist/harness/context/types.js +25 -1
  176. package/dist/harness/extension/execution-environment/effect-policy.d.ts +4 -3
  177. package/dist/harness/extension/execution-environment/effect-policy.js +2 -2
  178. package/dist/harness/extension/execution-environment/ops-audit.d.ts +1 -1
  179. package/dist/harness/extension/execution-environment/privileged-exec.js +4 -1
  180. package/dist/harness/extension/execution-environment/resource-limits.d.ts +1 -1
  181. package/dist/harness/extension/execution-environment/resource-limits.js +1 -1
  182. package/dist/harness/extension/execution-environment/workspace.js +1 -1
  183. package/dist/harness/extension/plugin-ecosystem/channel-types.d.ts +28 -2
  184. package/dist/harness/extension/plugin-ecosystem/channel-types.js +11 -2
  185. package/dist/harness/extension/plugin-ecosystem/client-tools/registry.d.ts +12 -0
  186. package/dist/harness/extension/plugin-ecosystem/client-tools/registry.js +25 -0
  187. package/dist/harness/extension/plugin-ecosystem/commands/builtin.js +28 -1
  188. package/dist/harness/extension/plugin-ecosystem/commands/index.d.ts +3 -1
  189. package/dist/harness/extension/plugin-ecosystem/commands/index.js +1 -0
  190. package/dist/harness/extension/plugin-ecosystem/commands/plugin-bridge.d.ts +12 -1
  191. package/dist/harness/extension/plugin-ecosystem/commands/plugin-bridge.js +14 -4
  192. package/dist/harness/extension/plugin-ecosystem/commands/router.d.ts +5 -4
  193. package/dist/harness/extension/plugin-ecosystem/commands/router.js +23 -14
  194. package/dist/harness/extension/plugin-ecosystem/commands/types.d.ts +8 -1
  195. package/dist/harness/extension/plugin-ecosystem/commands/types.js +2 -1
  196. package/dist/harness/extension/plugin-ecosystem/hooks/adapter.d.ts +54 -0
  197. package/dist/harness/extension/plugin-ecosystem/hooks/adapter.js +397 -0
  198. package/dist/harness/extension/plugin-ecosystem/hooks/compaction-integration.d.ts +16 -0
  199. package/dist/harness/extension/plugin-ecosystem/hooks/compaction-integration.js +66 -0
  200. package/dist/harness/extension/plugin-ecosystem/hooks/index.d.ts +4 -0
  201. package/dist/harness/extension/plugin-ecosystem/hooks/index.js +2 -0
  202. package/dist/harness/extension/plugin-ecosystem/hooks/iteration-snapshot.d.ts +11 -0
  203. package/dist/harness/extension/plugin-ecosystem/hooks/iteration-snapshot.js +54 -0
  204. package/dist/harness/extension/plugin-ecosystem/hooks/journal.d.ts +9 -0
  205. package/dist/harness/extension/plugin-ecosystem/hooks/journal.js +22 -0
  206. package/dist/harness/extension/plugin-ecosystem/hooks/policy-error.d.ts +12 -0
  207. package/dist/harness/extension/plugin-ecosystem/hooks/policy-error.js +19 -0
  208. package/dist/harness/extension/plugin-ecosystem/hooks/run-integration.d.ts +36 -0
  209. package/dist/harness/extension/plugin-ecosystem/hooks/run-integration.js +338 -0
  210. package/dist/harness/extension/plugin-ecosystem/hooks/services.d.ts +24 -0
  211. package/dist/harness/extension/plugin-ecosystem/hooks/services.js +139 -0
  212. package/dist/harness/extension/plugin-ecosystem/hooks/types.d.ts +229 -0
  213. package/dist/harness/extension/plugin-ecosystem/hooks/types.js +1 -0
  214. package/dist/harness/extension/plugin-ecosystem/index.d.ts +1 -0
  215. package/dist/harness/extension/plugin-ecosystem/index.js +1 -0
  216. package/dist/harness/extension/plugin-ecosystem/plugins/api.d.ts +223 -222
  217. package/dist/harness/extension/plugin-ecosystem/plugins/api.js +218 -203
  218. package/dist/harness/extension/plugin-ecosystem/plugins/contribution-instances.d.ts +95 -0
  219. package/dist/harness/extension/plugin-ecosystem/plugins/contribution-instances.js +170 -0
  220. package/dist/harness/extension/plugin-ecosystem/plugins/contribution-kinds.d.ts +178 -0
  221. package/dist/harness/extension/plugin-ecosystem/plugins/contribution-kinds.js +314 -0
  222. package/dist/harness/extension/plugin-ecosystem/plugins/contribution-registry.d.ts +78 -0
  223. package/dist/harness/extension/plugin-ecosystem/plugins/contribution-registry.js +80 -0
  224. package/dist/harness/extension/plugin-ecosystem/plugins/engine-compatibility.d.ts +4 -0
  225. package/dist/harness/extension/plugin-ecosystem/plugins/engine-compatibility.js +18 -0
  226. package/dist/harness/extension/plugin-ecosystem/plugins/entry.d.ts +7 -85
  227. package/dist/harness/extension/plugin-ecosystem/plugins/entry.js +8 -50
  228. package/dist/harness/extension/plugin-ecosystem/plugins/index.d.ts +6 -23
  229. package/dist/harness/extension/plugin-ecosystem/plugins/index.js +3 -23
  230. package/dist/harness/extension/plugin-ecosystem/plugins/loader.d.ts +57 -114
  231. package/dist/harness/extension/plugin-ecosystem/plugins/loader.js +279 -282
  232. package/dist/harness/extension/plugin-ecosystem/plugins/manager.d.ts +46 -484
  233. package/dist/harness/extension/plugin-ecosystem/plugins/manager.js +123 -345
  234. package/dist/harness/extension/plugin-ecosystem/plugins/manifest.d.ts +50 -223
  235. package/dist/harness/extension/plugin-ecosystem/plugins/manifest.js +144 -20
  236. package/dist/harness/extension/plugin-ecosystem/plugins/staging.d.ts +17 -0
  237. package/dist/harness/extension/plugin-ecosystem/plugins/staging.js +15 -0
  238. package/dist/harness/extension/plugin-ecosystem/skills/manager.d.ts +6 -1
  239. package/dist/harness/extension/plugin-ecosystem/skills/manager.js +17 -1
  240. package/dist/harness/extension/plugin-ecosystem/tools/ask-user.d.ts +3 -0
  241. package/dist/harness/extension/plugin-ecosystem/tools/ask-user.js +46 -21
  242. package/dist/harness/extension/plugin-ecosystem/tools/browser-types.d.ts +333 -0
  243. package/dist/harness/extension/plugin-ecosystem/tools/browser-types.js +16 -0
  244. package/dist/harness/extension/plugin-ecosystem/tools/browser.d.ts +64 -0
  245. package/dist/harness/extension/plugin-ecosystem/tools/browser.js +692 -0
  246. package/dist/harness/extension/plugin-ecosystem/tools/builtin.d.ts +0 -37
  247. package/dist/harness/extension/plugin-ecosystem/tools/builtin.js +108 -4
  248. package/dist/harness/extension/plugin-ecosystem/tools/delegation.js +36 -8
  249. package/dist/harness/extension/plugin-ecosystem/tools/file-edit.js +34 -0
  250. package/dist/harness/extension/plugin-ecosystem/tools/file-search.d.ts +0 -6
  251. package/dist/harness/extension/plugin-ecosystem/tools/file-search.js +57 -4
  252. package/dist/harness/extension/plugin-ecosystem/tools/git-tools.js +81 -13
  253. package/dist/harness/extension/plugin-ecosystem/tools/http.js +5 -0
  254. package/dist/harness/extension/plugin-ecosystem/tools/knowledge.js +13 -7
  255. package/dist/harness/extension/plugin-ecosystem/tools/package-tools.js +126 -14
  256. package/dist/harness/extension/plugin-ecosystem/tools/platform.d.ts +1 -1
  257. package/dist/harness/extension/plugin-ecosystem/tools/platform.js +44 -5
  258. package/dist/harness/extension/plugin-ecosystem/tools/plugin-tool.d.ts +11 -0
  259. package/dist/harness/extension/plugin-ecosystem/tools/plugin-tool.js +39 -0
  260. package/dist/harness/extension/plugin-ecosystem/tools/tool-bus.d.ts +1 -1
  261. package/dist/harness/extension/plugin-ecosystem/tools/tool-bus.js +19 -24
  262. package/dist/harness/extension/plugin-ecosystem/tools/tool-set.d.ts +7 -0
  263. package/dist/harness/extension/plugin-ecosystem/tools/tool-set.js +4 -0
  264. package/dist/harness/governance/accounting/usage-ledger.d.ts +13 -1
  265. package/dist/harness/governance/accounting/usage-ledger.js +23 -1
  266. package/dist/harness/governance/credentials/db.d.ts +9 -0
  267. package/dist/harness/governance/credentials/db.js +122 -31
  268. package/dist/harness/governance/credentials/store.d.ts +68 -7
  269. package/dist/harness/governance/credentials/store.js +177 -64
  270. package/dist/harness/governance/credentials/types.d.ts +13 -2
  271. package/dist/harness/governance/human-in-the-loop/decision-cache.d.ts +3 -3
  272. package/dist/harness/governance/human-in-the-loop/decision-cache.js +2 -2
  273. package/dist/harness/governance/index.d.ts +1 -0
  274. package/dist/harness/governance/index.js +1 -0
  275. package/dist/harness/governance/registry/db.d.ts +32 -0
  276. package/dist/harness/governance/registry/db.js +142 -0
  277. package/dist/harness/governance/registry/index.d.ts +9 -0
  278. package/dist/harness/governance/registry/index.js +9 -0
  279. package/dist/harness/governance/registry/service.d.ts +381 -0
  280. package/dist/harness/governance/registry/service.js +825 -0
  281. package/dist/harness/governance/registry/types.d.ts +77 -0
  282. package/dist/harness/governance/registry/types.js +7 -0
  283. package/dist/harness/governance/security/capability-enforcer.js +1 -2
  284. package/dist/harness/governance/security/default-security-guard.d.ts +3 -0
  285. package/dist/harness/governance/security/default-security-guard.js +12 -1
  286. package/dist/harness/governance/security/risk-evaluator.d.ts +13 -3
  287. package/dist/harness/governance/security/risk-evaluator.js +307 -21
  288. package/dist/harness/governance/security/shell-parser-treesitter.js +12 -4
  289. package/dist/harness/governance/session-acl/tool-rights.d.ts +1 -0
  290. package/dist/harness/index.d.ts +17 -15
  291. package/dist/harness/index.js +9 -9
  292. package/dist/harness/knowledge/boot-config.d.ts +57 -0
  293. package/dist/harness/knowledge/boot-config.js +52 -0
  294. package/dist/harness/knowledge/catalog-types.d.ts +2 -0
  295. package/dist/harness/knowledge/client.d.ts +77 -9
  296. package/dist/harness/knowledge/client.js +95 -24
  297. package/dist/harness/knowledge/db.d.ts +16 -0
  298. package/dist/harness/knowledge/db.js +112 -41
  299. package/dist/harness/knowledge/describe-sample.d.ts +23 -0
  300. package/dist/harness/knowledge/describe-sample.js +58 -0
  301. package/dist/harness/knowledge/describe.d.ts +8 -0
  302. package/dist/harness/knowledge/describe.js +18 -2
  303. package/dist/harness/knowledge/engine-thread.js +11 -7
  304. package/dist/harness/knowledge/grounding.js +7 -2
  305. package/dist/harness/knowledge/http-app.d.ts +15 -0
  306. package/dist/harness/knowledge/http-app.js +117 -25
  307. package/dist/harness/knowledge/http-bridge.d.ts +15 -0
  308. package/dist/harness/knowledge/http-bridge.js +19 -0
  309. package/dist/harness/knowledge/http-params.d.ts +18 -0
  310. package/dist/harness/knowledge/http-params.js +24 -0
  311. package/dist/harness/knowledge/index.d.ts +2 -0
  312. package/dist/harness/knowledge/index.js +1 -0
  313. package/dist/harness/knowledge/knowledge-serve-child.js +5 -3
  314. package/dist/harness/knowledge/purge.js +5 -2
  315. package/dist/harness/knowledge/query-service.d.ts +25 -4
  316. package/dist/harness/knowledge/query-service.js +79 -43
  317. package/dist/harness/knowledge/query-worker-client.d.ts +14 -2
  318. package/dist/harness/knowledge/query-worker-client.js +8 -3
  319. package/dist/harness/knowledge/query-worker.js +9 -5
  320. package/dist/harness/knowledge/read-http.d.ts +2 -0
  321. package/dist/harness/knowledge/read-http.js +14 -3
  322. package/dist/harness/knowledge/retriever.d.ts +1 -1
  323. package/dist/harness/knowledge/retriever.js +1 -2
  324. package/dist/harness/knowledge/serve.d.ts +14 -8
  325. package/dist/harness/knowledge/serve.js +14 -6
  326. package/dist/harness/knowledge/source-store.d.ts +101 -5
  327. package/dist/harness/knowledge/source-store.js +323 -74
  328. package/dist/harness/knowledge/start-service-process.d.ts +41 -14
  329. package/dist/harness/knowledge/start-service-process.js +67 -96
  330. package/dist/harness/knowledge/tenant-gate.d.ts +81 -0
  331. package/dist/harness/knowledge/tenant-gate.js +167 -0
  332. package/dist/harness/knowledge/types.d.ts +7 -0
  333. package/dist/harness/knowledge/writer-service.d.ts +55 -11
  334. package/dist/harness/knowledge/writer-service.js +200 -30
  335. package/dist/harness/knowledge/writer-worker-client.d.ts +19 -11
  336. package/dist/harness/knowledge/writer-worker-client.js +40 -5
  337. package/dist/harness/knowledge/writer-worker.js +20 -5
  338. package/dist/harness/memory/backfill-trigger.d.ts +10 -3
  339. package/dist/harness/memory/backfill-trigger.js +19 -19
  340. package/dist/harness/memory/cognition-seeds.d.ts +45 -0
  341. package/dist/harness/memory/cognition-seeds.js +67 -0
  342. package/dist/harness/memory/cognition.d.ts +12 -3
  343. package/dist/harness/memory/cognition.js +55 -35
  344. package/dist/harness/memory/conceptualizer.d.ts +11 -1
  345. package/dist/harness/memory/conceptualizer.js +10 -1
  346. package/dist/harness/memory/context-slice.d.ts +42 -0
  347. package/dist/harness/memory/context-slice.js +197 -0
  348. package/dist/harness/memory/health-probe.d.ts +8 -2
  349. package/dist/harness/memory/health-probe.js +10 -13
  350. package/dist/harness/memory/index.d.ts +5 -1
  351. package/dist/harness/memory/index.js +3 -1
  352. package/dist/harness/memory/sqlite/agent-db.d.ts +1 -0
  353. package/dist/harness/memory/sqlite/agent-db.js +9 -8
  354. package/dist/harness/memory/sqlite/cognition-store.d.ts +26 -3
  355. package/dist/harness/memory/sqlite/cognition-store.js +103 -45
  356. package/dist/harness/memory/sqlite/memory-store.js +4 -0
  357. package/dist/harness/memory/sqlite/sqlite-vec.d.ts +24 -1
  358. package/dist/harness/memory/sqlite/sqlite-vec.js +37 -1
  359. package/dist/harness/memory/sqlite/wisdom-store.js +35 -10
  360. package/dist/harness/memory/types.d.ts +24 -6
  361. package/dist/harness/memory/wisdom-formation.d.ts +14 -3
  362. package/dist/harness/memory/wisdom-formation.js +85 -22
  363. package/dist/harness/memory/wisdom-gates.d.ts +14 -0
  364. package/dist/harness/memory/wisdom-gates.js +59 -19
  365. package/dist/harness/memory/wisdom.js +9 -0
  366. package/dist/harness/observability/observer/hub.d.ts +10 -0
  367. package/dist/harness/observability/observer/hub.js +120 -17
  368. package/dist/harness/observability/observer/types.d.ts +10 -6
  369. package/dist/harness/run/agent/agent.d.ts +40 -21
  370. package/dist/harness/run/agent/agent.js +67 -13
  371. package/dist/harness/run/agent/index.d.ts +1 -1
  372. package/dist/harness/run/budget/budget.d.ts +28 -10
  373. package/dist/harness/run/budget/budget.js +38 -15
  374. package/dist/harness/run/concurrency/tool-validator.js +4 -3
  375. package/dist/harness/run/model/index.d.ts +3 -1
  376. package/dist/harness/run/model/index.js +2 -1
  377. package/dist/harness/run/model/resolver.d.ts +4 -1
  378. package/dist/harness/run/model/resolver.js +36 -2
  379. package/dist/harness/run/model/run-scope.d.ts +2 -0
  380. package/dist/harness/run/model/run-scope.js +7 -0
  381. package/dist/harness/run/model/types.d.ts +22 -5
  382. package/dist/harness/run/model/types.js +3 -2
  383. package/dist/harness/run/model/window-truth.d.ts +37 -0
  384. package/dist/harness/run/model/window-truth.js +39 -0
  385. package/dist/harness/run/reliability/context-length-feedback.d.ts +77 -0
  386. package/dist/harness/run/reliability/context-length-feedback.js +128 -0
  387. package/dist/harness/run/reliability/harness-events.d.ts +3 -3
  388. package/dist/harness/run/reliability/model-error-policy.js +4 -0
  389. package/dist/harness/run/reliability/run-agent.d.ts +32 -4
  390. package/dist/harness/run/reliability/run-agent.js +216 -63
  391. package/dist/harness/run/reliability/run-metrics-collector.d.ts +19 -8
  392. package/dist/harness/run/reliability/run-metrics-collector.js +38 -23
  393. package/dist/harness/run/run-guard/default-run-guard.js +8 -8
  394. package/dist/harness/run/run-host.d.ts +302 -0
  395. package/dist/harness/run/run-host.js +978 -0
  396. package/dist/harness/run/run-scope.d.ts +48 -4
  397. package/dist/harness/run/run-scope.js +19 -1
  398. package/dist/harness/run/runner.d.ts +181 -39
  399. package/dist/harness/run/runner.js +654 -119
  400. package/dist/harness/session/attachments/index.d.ts +1 -0
  401. package/dist/harness/session/attachments/index.js +1 -0
  402. package/dist/harness/session/attachments/inject.d.ts +21 -10
  403. package/dist/harness/session/attachments/inject.js +76 -24
  404. package/dist/harness/session/attachments/recall-index.d.ts +70 -0
  405. package/dist/harness/session/attachments/recall-index.js +219 -0
  406. package/dist/harness/session/attachments/service.d.ts +21 -0
  407. package/dist/harness/session/attachments/service.js +258 -139
  408. package/dist/harness/session/attachments/types.d.ts +6 -0
  409. package/dist/harness/session/in-memory-store.js +13 -1
  410. package/dist/harness/session/schedules/service.d.ts +10 -2
  411. package/dist/harness/session/schedules/service.js +13 -2
  412. package/dist/harness/session/tasks/tools.js +12 -0
  413. package/dist/harness/session/transform-store.d.ts +136 -0
  414. package/dist/harness/session/transform-store.js +302 -0
  415. package/dist/harness/session/types.d.ts +11 -15
  416. package/dist/harness/shared/events/agent-event-map.d.ts +75 -13
  417. package/dist/harness/shared/events/agent-event-map.js +3 -2
  418. package/dist/harness/shared/events/scenario-events.d.ts +6 -6
  419. package/dist/harness/shared/types/agent-definition.d.ts +7 -2
  420. package/dist/index.d.ts +16 -18
  421. package/dist/index.js +9 -10
  422. package/dist/integration/agent-runtime/channel-message-source.d.ts +3 -1
  423. package/dist/integration/agent-runtime/channel-message-source.js +4 -3
  424. package/dist/integration/browser/camoufox.d.ts +40 -0
  425. package/dist/integration/browser/camoufox.js +80 -0
  426. package/dist/integration/browser/index.d.ts +91 -0
  427. package/dist/integration/browser/index.js +110 -0
  428. package/dist/integration/browser/install.d.ts +47 -0
  429. package/dist/integration/browser/install.js +214 -0
  430. package/dist/integration/browser/playwright.d.ts +224 -0
  431. package/dist/integration/browser/playwright.js +925 -0
  432. package/dist/integration/browser/service.d.ts +41 -0
  433. package/dist/integration/browser/service.js +181 -0
  434. package/dist/integration/browser/stealth.d.ts +42 -0
  435. package/dist/integration/browser/stealth.js +104 -0
  436. package/dist/integration/observability/metrics.d.ts +6 -6
  437. package/dist/integration/observability/metrics.js +13 -13
  438. package/dist/integration/observability/observer-bridge.js +2 -2
  439. package/dist/integration/observability/trace-collector.d.ts +5 -5
  440. package/dist/integration/observability/trace-collector.js +34 -35
  441. package/dist/integration/observability/trace-events.d.ts +3 -3
  442. package/dist/integration/observability/trace-events.js +3 -3
  443. package/dist/integration/providers/anthropic-message-normalize.d.ts +20 -0
  444. package/dist/integration/providers/anthropic-message-normalize.js +48 -0
  445. package/dist/integration/providers/anthropic.js +41 -3
  446. package/dist/integration/providers/fetch-timeout.d.ts +17 -0
  447. package/dist/integration/providers/fetch-timeout.js +24 -0
  448. package/dist/integration/providers/openai.d.ts +8 -0
  449. package/dist/integration/providers/openai.js +48 -2
  450. package/dist/integration/providers/usage.d.ts +1 -1
  451. package/dist/integration/providers/wire-dump-diff.js +2 -1
  452. package/dist/integration/providers/wire-dump.d.ts +57 -3
  453. package/dist/integration/providers/wire-dump.js +119 -6
  454. package/dist/integration/storage/archive-manager.d.ts +20 -2
  455. package/dist/integration/storage/archive-manager.js +34 -8
  456. package/dist/integration/storage/atomic-tmp.d.ts +12 -0
  457. package/dist/integration/storage/atomic-tmp.js +36 -0
  458. package/dist/integration/storage/jsonl.d.ts +10 -1
  459. package/dist/integration/storage/jsonl.js +155 -54
  460. package/dist/integration/storage/session-index.d.ts +5 -0
  461. package/dist/integration/storage/session-index.js +25 -4
  462. package/dist/integration/tools/assemble.d.ts +50 -0
  463. package/dist/integration/tools/assemble.js +137 -0
  464. package/dist/paths.d.ts +18 -0
  465. package/dist/paths.js +36 -0
  466. package/dist/subsystems/cognition-steward/conceptualize/config.yaml +3 -1
  467. package/dist/subsystems/cognition-steward/conceptualize/handler.js +74 -5
  468. package/dist/subsystems/cognition-steward/consolidate/SUBSYSTEM.md +3 -2
  469. package/dist/subsystems/cognition-steward/consolidate/config.yaml +11 -2
  470. package/dist/subsystems/cognition-steward/consolidate/handler.d.ts +6 -3
  471. package/dist/subsystems/cognition-steward/consolidate/handler.js +266 -28
  472. package/dist/subsystems/memory-steward/backfill/handler.js +3 -2
  473. package/dist/subsystems/memory-steward/govern/config.yaml +6 -1
  474. package/dist/subsystems/wisdom-steward/attribute/config.yaml +5 -1
  475. package/dist/subsystems/wisdom-steward/formation/SUBSYSTEM.md +8 -1
  476. package/dist/subsystems/wisdom-steward/formation/config.yaml +4 -0
  477. package/dist/subsystems/wisdom-steward/formation/handler.js +27 -5
  478. package/dist/subsystems/wisdom-steward/govern/config.yaml +6 -1
  479. package/package.json +14 -15
  480. package/dist/harness/context/hybrid-compressor.d.ts +0 -41
  481. package/dist/harness/context/hybrid-compressor.js +0 -159
  482. package/dist/harness/context/llm-summarizer.d.ts +0 -46
  483. package/dist/harness/context/llm-summarizer.js +0 -249
  484. package/dist/harness/context/smart-router.d.ts +0 -75
  485. package/dist/harness/context/smart-router.js +0 -118
  486. package/dist/harness/context/truncate-compressor.d.ts +0 -28
  487. package/dist/harness/context/truncate-compressor.js +0 -107
  488. package/dist/harness/extension/plugin-ecosystem/plugins/capability.d.ts +0 -97
  489. package/dist/harness/extension/plugin-ecosystem/plugins/capability.js +0 -155
  490. package/dist/harness/extension/plugin-ecosystem/plugins/hooks.d.ts +0 -7
  491. package/dist/harness/extension/plugin-ecosystem/plugins/hooks.js +0 -7
  492. package/dist/harness/extension/plugin-ecosystem/plugins/lifecycle.d.ts +0 -86
  493. package/dist/harness/extension/plugin-ecosystem/plugins/lifecycle.js +0 -139
@@ -2,8 +2,9 @@
2
2
  * 历史工具结果批量冻结老化(F1-B2)— 视图级、零 LLM、write-once
3
3
  *
4
4
  * 语义(arch/long-session-latency.md §5 B2 + arch/b0-cache-stable-context.md §4):
5
- * - **当前 run 永不老化**:最近一条真实 user 消息(排除引擎载体插槽)以来的工具结果全原文;
6
- * - **近 `rawWindow` 条跨轮工具结果**保留原文;
5
+ * - **当前 run 永不老化**:当前 run 起点(`currentRunStartAnchorIndex`——同 run 的
6
+ * 插话 / 接续 turn 不推进边界)以来的工具结果全原文;
7
+ * - **近 `rawWindow` 条跨 run 工具结果**保留原文;
7
8
  * - 更旧的候选按 **`freezeBatch` 批量**降级为结构化指针(工具名 + 参数要点 + 结果轮廓 + re-run 提示);
8
9
  * - **批量冻结(禁渐进老化)**:老化边界只以 `freezeBatch` 为步长成批推进,段间轮次视图
9
10
  * 逐字节稳定——每轮在 recency 边界改写 1 条 = 把边界→尾部整段烧前缀缓存(B0 稿 §4);
@@ -15,21 +16,64 @@
15
16
  * 红线(§4 能力红线):user / assistant **正文**永不降级;**error 结果永不降级**(错误可追溯性优先,
16
17
  * 字段保真);不膨胀守卫——只有指针严格小于原文时才降级。
17
18
  *
18
- * tool_call 参数(`ageToolArgs`,默认开):**只对「结果已被老化」的那条调用**同步降级为键值摘要
19
+ * tool_call 参数(`ageToolArgs`,总开关,默认开;**逐工具 opt-in** `RegisteredTool.ageArgs`):
19
20
  * (长值换成长度标记,键名全保)。原因:参数是上下文中唯一无界增长的成分——结果老化成指针后
20
21
  * 参数仍留原文,实测其总量可达指针本体的 1.1 倍,且随 session 线性增长。
21
22
  * 降级不改变 tool_call ↔ tool_result 配对结构(`id`/`name` 不动,`arguments` 仍是合法 JSON)。
22
23
  *
23
24
  * @module harness/context/tool-result-aging
24
25
  */
25
- import { isTurnAnchor } from './layer-types.js';
26
+ import { AGED_POINTER_PREFIX, TRUNCATED_MARK, elidedValueMarker, isElisionToken } from '@octopi-agent/core/elision.js';
27
+ import { currentRunStartAnchorIndex } from './layer-types.js';
26
28
  import { toolResultBody } from './tool-result-body.js';
27
- /** args / result 轮廓占 maxPointerChars 的比例(合计 ~0.65,加固定骨架 ≈ 目标) */
28
- const ARGS_OUTLINE_RATIO = 0.2;
29
+ /**
30
+ * 从工具面收集「工具名 → 老化函数」表
31
+ *
32
+ * 供装配层把 `AgentTool.ageResult` 传给老化计划。只收有声明的工具——
33
+ * 未声明者不进表 = 走默认规则(长度判据 + 机械指针)。
34
+ *
35
+ * @param tools - 本 run 实际发送的工具面(`RunScope.tools` / `AgentContext.tools`)
36
+ * @returns 名字→函数表;无任何声明时返回 undefined(省去空表分配)
37
+ */
38
+ export function collectToolAgers(tools) {
39
+ if (!tools?.length)
40
+ return undefined;
41
+ let out;
42
+ for (const t of tools) {
43
+ if (!t.ageResult)
44
+ continue;
45
+ out ??= new Map();
46
+ out.set(t.name, t.ageResult);
47
+ }
48
+ return out;
49
+ }
50
+ /**
51
+ * 收集「参数可老化」的工具名(`AgentTool.ageArgs` → 集合)
52
+ *
53
+ * 与 {@link collectToolAgers} 分开:两者语义独立(有结果策略不代表参数可老化,
54
+ * 反之亦然),混成一张表会让「只声明了 ageArgs」的工具误走结果默认规则。
55
+ *
56
+ * @param tools - 本次 run 的工具面
57
+ * @returns 工具名集合;空表返回 undefined(装配侧据此跳过)
58
+ */
59
+ export function collectToolArgAgers(tools) {
60
+ if (!tools?.length)
61
+ return undefined;
62
+ let out;
63
+ for (const t of tools) {
64
+ if (!t.ageArgs)
65
+ continue;
66
+ out ??= new Set();
67
+ out.add(t.name);
68
+ }
69
+ return out;
70
+ }
71
+ /** 结果轮廓占 maxPointerChars 的比例(0.45;固定骨架 ≈ 70 字符) */
29
72
  const RESULT_OUTLINE_RATIO = 0.45;
30
73
  /** 轮廓下限(小旋钮下仍可读) */
31
- const MIN_ARGS_OUTLINE_CHARS = 24;
32
74
  const MIN_RESULT_OUTLINE_CHARS = 48;
75
+ /** 指针在结果正文之后的短提示(旧文案 81 字符 × 每条指针,纯重复噪音) */
76
+ const AGED_POINTER_HINT = ' (re-run to see full output)';
33
77
  /**
34
78
  * 参数摘要中「原样保留」的单个值上限
35
79
  *
@@ -37,7 +81,8 @@ const MIN_RESULT_OUTLINE_CHARS = 48;
37
81
  * 64 足以容纳常见路径,又远小于任何文件内容。
38
82
  */
39
83
  const ARG_VALUE_KEEP_CHARS = 64;
40
- const TRUNCATION_MARK = '…[truncated]';
84
+ /** 已降级值在预算账目里的固定成本(标记是结构噪声,不按字面长度计费) */
85
+ const ELIDED_VALUE_BUDGET_COST = '…';
41
86
  /**
42
87
  * 解析老化配置(缺省 = 拍板参数起点:40 条原文 / 批 20 / 指针 400 字符)
43
88
  *
@@ -45,8 +90,8 @@ const TRUNCATION_MARK = '…[truncated]';
45
90
  * @returns 全字段解析结果(非法值/0 步长回落缺省——0 或负步长等同禁用批量冻结)
46
91
  */
47
92
  export function resolveToolResultAgingOptions(input) {
48
- const rawWindow = Number.isInteger(input?.rawWindow) && (input?.rawWindow ?? -1) >= 0 ? input.rawWindow : 40;
49
- const freezeBatch = Number.isInteger(input?.freezeBatch) && (input?.freezeBatch ?? -1) >= 1 ? input.freezeBatch : 40;
93
+ const rawWindow = Number.isInteger(input?.rawWindow) && (input?.rawWindow ?? -1) >= 0 ? input.rawWindow : 20;
94
+ const freezeBatch = Number.isInteger(input?.freezeBatch) && (input?.freezeBatch ?? -1) >= 1 ? input.freezeBatch : 60;
50
95
  const maxPointerChars = Number.isInteger(input?.maxPointerChars) && (input?.maxPointerChars ?? -1) > 0 ? input.maxPointerChars : 400;
51
96
  const maxAgedArgChars = Number.isInteger(input?.maxAgedArgChars) && (input?.maxAgedArgChars ?? -1) > 0
52
97
  ? input.maxAgedArgChars
@@ -63,25 +108,24 @@ export function resolveToolResultAgingOptions(input) {
63
108
  /**
64
109
  * 计算老化计划:批量冻结边界 + 工具调用参数索引
65
110
  *
66
- * 边界语义:跨轮工具结果(位于最近一条真实 user 消息之前)中,最旧的
67
- * `crossTurn - rawWindow` 条为候选;候选前 `freezeBatch` 整批部分「过冻结线」。
111
+ * 边界语义:跨 run 工具结果(位于当前 run 起点之前)中,最旧的
112
+ * `crossRun - rawWindow` 条为候选;候选前 `freezeBatch` 整批部分「过冻结线」。
68
113
  * 过线条目再过三道守卫才降级:error 永不降级;正文 ≤ 指针目标不降级;
69
114
  * 实际指针不比原文短不降级(不膨胀)。历史只增不减时边界单调推进、
70
115
  * 已降级条目永不回原文——满足 write-once(须以完整历史为输入,见模块头注)。
71
116
  *
72
117
  * @param messages - **完整**历史消息(按时间序;勿传裁剪后的装配视图)
73
118
  * @param opts - 老化配置(已解析)
119
+ * @param override - overflow 收敛阶梯第 0 轮(2026-11-08):ignoreTurnBoundary=true 时
120
+ * 豁免 run 起点限定(不限 crossRun、rawWindow 归 0)——守门兜底语境下「发得出去」
121
+ * 优先于「保护 turn 内工作数据/缓存前缀」;阈值(maxPointerChars/freezeBatch)不动
74
122
  * @returns 老化计划(enabled=false 或无候选时 agedIds 为空)
75
123
  */
76
- export function computeToolResultAgingPlan(messages, opts) {
124
+ export function computeToolResultAgingPlan(messages, opts, override) {
77
125
  const argsById = new Map();
78
126
  const ordered = [];
79
- let lastGenuineUserIdx = -1;
80
127
  for (let i = 0; i < messages.length; i++) {
81
128
  const msg = messages[i];
82
- if (isTurnAnchor(msg)) {
83
- lastGenuineUserIdx = i;
84
- }
85
129
  for (const tc of msg.toolCalls ?? []) {
86
130
  argsById.set(tc.id, tc.arguments);
87
131
  }
@@ -95,17 +139,46 @@ export function computeToolResultAgingPlan(messages, opts) {
95
139
  });
96
140
  }
97
141
  }
142
+ const agesByCallId = new Map();
98
143
  const agedIds = new Set();
99
144
  if (!opts.enabled)
100
- return { agedIds, argsById };
101
- // 边界 = 完整历史最后一个真实 user(两遍判定:旧轮结果在遇到后续 user 前不可下结论)
102
- const crossTurn = ordered.filter((e) => e.msgIndex < lastGenuineUserIdx);
103
- const candidates = crossTurn.slice(0, Math.max(0, crossTurn.length - opts.rawWindow));
104
- const covered = candidates.length - (candidates.length % opts.freezeBatch);
145
+ return { agedIds, argsById, agersByCallId: agesByCallId, argAgedIds: new Set() };
146
+ // 边界 = 当前 run 起点(currentRunStartAnchorIndex,完整历史口径):同 run 的
147
+ // 插话/接续 turn 不推进边界(2026-11-20 拍板)——任务中途的工作数据不因插话
148
+ // 被降级。旧实现取「最近一条真实 user」,插话一落库就把同 run 先前的工具结果
149
+ // 整体划入跨轮候选(插话即触发老化)。
150
+ // overflow 第 0 轮豁免(ignoreTurnBoundary):全历史候选、rawWindow 归 0——
151
+ // run 内工作数据的保护让位于「装得下去」(arch/overflow-redesign.md §3 第 0 轮细则)
152
+ const ignoreTurnBoundary = override?.ignoreTurnBoundary === true;
153
+ const runStartIdx = currentRunStartAnchorIndex(messages);
154
+ const crossRun = ignoreTurnBoundary
155
+ ? ordered
156
+ : ordered.filter((e) => e.msgIndex < runStartIdx);
157
+ const rawWindow = ignoreTurnBoundary ? 0 : opts.rawWindow;
158
+ // freezeBatch(冻结批次防抖)同属 run 内保护——守门语境豁免:发不出去了不等批次
159
+ const freezeBatch = ignoreTurnBoundary ? 1 : opts.freezeBatch;
160
+ const candidates = crossRun.slice(0, Math.max(0, crossRun.length - rawWindow));
161
+ const covered = candidates.length - (candidates.length % freezeBatch);
162
+ const toolAgers = override?.toolAgers;
105
163
  for (let i = 0; i < covered; i++) {
106
164
  const cand = candidates[i];
107
165
  if (cand.isError)
108
166
  continue; // 红线:error 结果永不降级(错误可追溯性优先)
167
+ const ager = cand.tr.name ? toolAgers?.get(cand.tr.name) : undefined;
168
+ if (ager) {
169
+ // 工具自定策略:跳过长度的预筛(作者决定什么是「该丢的」,与结果大小无关——
170
+ // task_list 470 字符也该丢)。仍保留不膨胀守卫:替换文本必须真的更短。
171
+ const replacement = ager({
172
+ args: argsById.get(cand.toolCallId) ?? {},
173
+ result: cand.tr.result,
174
+ chars: cand.bodyLength,
175
+ });
176
+ if (replacement !== undefined && replacement.length < cand.bodyLength) {
177
+ agedIds.add(cand.toolCallId);
178
+ agesByCallId.set(cand.toolCallId, ager);
179
+ }
180
+ continue;
181
+ }
109
182
  if (cand.bodyLength <= opts.maxPointerChars)
110
183
  continue; // 预筛:小于指针目标不值得
111
184
  const pointer = agedToolResultPointer(cand.tr, argsById.get(cand.toolCallId), opts);
@@ -113,11 +186,67 @@ export function computeToolResultAgingPlan(messages, opts) {
113
186
  agedIds.add(cand.toolCallId);
114
187
  }
115
188
  }
116
- return { agedIds, argsById };
189
+ // 参数老化集合:**冻结区内 + 工具 opt-in**,与「结果是否成指针」解耦。
190
+ //
191
+ // 早期实现让它与 agedIds 锁步,被 file_write 证伪:该工具结果只有
192
+ // `{path, bytesWritten, mode}` 约 120 字符,永远小于 maxPointerChars 而不会被
193
+ // 老化,于是它 10k 级的 `content` 参数也就永远不会被裁——恰好放走了唯一需要
194
+ // 参数老化的场景。参数老化本就独立于结果大小:判据是「这条调用已经旧到冻结区」
195
+ // +「该工具声明参数会成为污染源」。
196
+ const toolArgAgers = override?.toolArgAgers;
197
+ const argAgedIds = new Set();
198
+ if (toolArgAgers?.size) {
199
+ for (let i = 0; i < covered; i++) {
200
+ const cand = candidates[i];
201
+ if (cand.isError)
202
+ continue; // 红线同结果侧:错误调用参数保留现场
203
+ if (cand.tr.name && toolArgAgers.has(cand.tr.name))
204
+ argAgedIds.add(cand.toolCallId);
205
+ }
206
+ }
207
+ return { agedIds, argsById, agersByCallId: agesByCallId, argAgedIds };
117
208
  }
118
209
  // 指针 write-once 缓存:同 `tr` 对象 + 同配置指纹 → 同字节(toolResultBody 同款 WeakMap 先例;
119
210
  // 消息内容写入后不可变,对象身份稳定;即便对象重建,纯函数定形也保证字节一致)。
120
211
  const pointerCache = new WeakMap();
212
+ /**
213
+ * 单条工具结果 → 老化后的文本(**唯一裁决点**)
214
+ *
215
+ * 顺序:工具自带 ager → 默认机械指针。两处视图构建(`applyAgingToMessages`
216
+ * 与 `buildLlmMessages`)都必须走这里:历史上它们各写一份内联逻辑,
217
+ * 结果 per-tool ager 只在其中一份生效(2026-11-13 实测发现——wire dump 里
218
+ * file_edit 仍是默认指针,而单测覆盖的却是另一份实现)。
219
+ *
220
+ * @param tr - 工具结果条目
221
+ * @param args - 对应调用参数
222
+ * @param plan - 老化计划(提供 per-tool ager 与参数表)
223
+ * @param opts - 老化配置
224
+ * @returns 供模型读取的文本
225
+ */
226
+ export function ageOneToolResult(tr, args, plan, opts) {
227
+ const ager = plan.agersByCallId.get(tr.toolCallId);
228
+ const viaAger = ager?.({
229
+ args: args ?? {},
230
+ result: tr.result,
231
+ chars: toolResultBody(tr).length,
232
+ });
233
+ return viaAger ?? agedToolResultPointer(tr, args, opts);
234
+ }
235
+ /**
236
+ * 单条工具调用 → 是否应降级其参数(**唯一裁决点**)
237
+ *
238
+ * 只看 `plan.argAgedIds`(冻结区 ∩ 工具 opt-in)。不要再回退到 `agedIds`:
239
+ * 那会让「结果恰好够大」的工具绕过 opt-in 白名单,正是 file_edit 参数在
240
+ * 2026-11-13 仍被全局降级的原因。
241
+ *
242
+ * @param toolCallId - 调用 id
243
+ * @param plan - 老化计划
244
+ * @param opts - 老化配置(含总开关 `ageToolArgs`)
245
+ * @returns 是否降级
246
+ */
247
+ export function shouldAgeArgs(toolCallId, plan, opts) {
248
+ return opts.ageToolArgs && plan.argAgedIds.has(toolCallId);
249
+ }
121
250
  /**
122
251
  * 把老化计划物化为消息视图副本(新建对象,不改原消息)
123
252
  *
@@ -131,15 +260,17 @@ const pointerCache = new WeakMap();
131
260
  * @returns 消息副本(老化条目的正文替换为指针;无老化条目时原样返回同一数组)
132
261
  */
133
262
  export function applyAgingToMessages(messages, plan, opts) {
134
- if (plan.agedIds.size === 0)
263
+ // 提前返回必须同时看两个集合:file_write 这类「结果小、参数大」的调用只会在
264
+ // argAgedIds 里出现(结果永远够不到 maxPointerChars),只看 agedIds 会整段跳过。
265
+ if (plan.agedIds.size === 0 && plan.argAgedIds.size === 0)
135
266
  return messages;
136
267
  return messages.map((msg) => {
137
268
  let next = msg;
138
269
  // 参数与结果同步老化:只动「结果已老化」的那条调用,配对结构不变
139
- if (opts.ageToolArgs && msg.toolCalls?.length) {
270
+ if (opts.ageToolArgs && plan.argAgedIds.size > 0 && msg.toolCalls?.length) {
140
271
  let callsChanged = false;
141
272
  const toolCalls = msg.toolCalls.map((tc) => {
142
- if (!plan.agedIds.has(tc.id))
273
+ if (!shouldAgeArgs(tc.id, plan, opts))
143
274
  return tc;
144
275
  callsChanged = true;
145
276
  return { ...tc, arguments: agedToolArgDigest(tc.name, tc.arguments, opts) };
@@ -154,10 +285,9 @@ export function applyAgingToMessages(messages, plan, opts) {
154
285
  if (!plan.agedIds.has(tr.toolCallId))
155
286
  return tr;
156
287
  changed = true;
157
- return {
158
- ...tr,
159
- result: agedToolResultPointer(tr, plan.argsById.get(tr.toolCallId), opts),
160
- };
288
+ // 统一裁决点(与 buildLlmMessages 同一实现,防两份逻辑漂移)
289
+ const replacement = ageOneToolResult(tr, plan.argsById.get(tr.toolCallId), plan, opts);
290
+ return { ...tr, result: replacement };
161
291
  });
162
292
  return changed ? { ...next, toolResults: results } : next;
163
293
  });
@@ -165,12 +295,17 @@ export function applyAgingToMessages(messages, plan, opts) {
165
295
  /**
166
296
  * 生成结构化摘要指针(机械、零 LLM、确定性)
167
297
  *
168
- * 布局:工具名 + args 轮廓(截断)+ result 轮廓(截断)+ re-run 提示;
169
- * 轮廓预算按 `maxPointerChars` 比例派生(旋钮真实生效)。
298
+ * 布局:工具名 + 结果长度 + 结果轮廓 + 短提示。
299
+ *
300
+ * 不含参数轮廓(2026-11-13 实测):指针里的 args 是**机械截断**产物(130 条指针
301
+ * 全部恰好 98 字符 = 预算 80 + 截断标记),从不承载有效信息;对应的 tool_use 就在
302
+ * 前一条 assistant 消息里,`ageToolArgs` 还额外全保 path/command/id。留着是纯重复。
303
+ * 连同旧尾句(81 字符/条)一并去掉——它把「不要重跑」重复 130 遍,反而在提示重跑。
304
+ *
170
305
  * error 分支为防御性保真(计划永不选中 error 结果)。
171
306
  *
172
307
  * @param tr - 工具结果(error / result 至少其一)
173
- * @param args - 对应工具调用参数(可空)
308
+ * @param args - 对应工具调用参数(保留入参供策略复用;默认指针不再消费)
174
309
  * @param opts - 老化配置(已解析)
175
310
  * @returns 指针文本(write-once:同输入恒同字节)
176
311
  */
@@ -179,17 +314,13 @@ export function agedToolResultPointer(tr, args, opts) {
179
314
  const cached = pointerCache.get(tr);
180
315
  if (cached && cached.fingerprint === fingerprint)
181
316
  return cached.text;
182
- const argsBudget = Math.max(MIN_ARGS_OUTLINE_CHARS, Math.floor(opts.maxPointerChars * ARGS_OUTLINE_RATIO));
183
317
  const resultBudget = Math.max(MIN_RESULT_OUTLINE_CHARS, Math.floor(opts.maxPointerChars * RESULT_OUTLINE_RATIO));
184
- const argsOutline = truncateOutline(safeJson(args ?? {}), argsBudget);
185
318
  // 结果轮廓只保留头部,若不给总量,读方会把「头部那几条」误当成全部(file_search 尤甚)
186
319
  const resultBody = toolResultOutline(tr);
187
320
  const errorOrResult = tr.error !== undefined
188
321
  ? `error: ${tr.error}` // 防御性保真:错误文案不截断、不改写
189
322
  : `result ${resultBody.length} chars: ${truncateOutline(resultBody, resultBudget)}`;
190
- const text = `[aged tool result · pointer] tool: ${tr.name ?? 'unknown'}; ` +
191
- `args: ${argsOutline}; ${errorOrResult}; ` +
192
- 'full output kept in session log — do NOT re-run unless the output is needed again';
323
+ const text = `${AGED_POINTER_PREFIX} ${tr.name ?? 'unknown'}; ${errorOrResult}${AGED_POINTER_HINT}`;
193
324
  pointerCache.set(tr, { fingerprint, text });
194
325
  return text;
195
326
  }
@@ -198,7 +329,7 @@ export function agedToolResultPointer(tr, args, opts) {
198
329
  *
199
330
  * 规则(机械、确定性、无 LLM):
200
331
  * 1. **键名全保**——LLM 需要知道调用了哪个路径/命令才能在必要时重跑;
201
- * 2. 序列化长度超过 {@link ARG_VALUE_KEEP_CHARS} 的值替换为长度标记 `…[N chars]`;
332
+ * 2. 序列化长度超过 {@link ARG_VALUE_KEEP_CHARS} 的值替换为对象形标记 `{"$octopi_elided": {"chars": N}}`(锚点类——定位字段与命令——全保不降级);
202
333
  * 3. 若仍是超预算,按「值从大到小、同大小按键名」顺序继续替换,保证确定性;
203
334
  * 4. 兜底:键名太多装不下时退化为整体轮廓截断。
204
335
  *
@@ -231,7 +362,12 @@ export function agedToolArgDigest(name, args, opts) {
231
362
  // 预算只约束「内容值」,定位字段不计入:
232
363
  // 否则一条绝对路径就能吃掉整个预算,反而先把唯一锚点挤掉(实测 path 均长 79,
233
364
  // 若计入预算,file_edit 这类调用会退化成「看不到改了哪个文件」)。
234
- const contentChars = () => safeJson(Object.fromEntries(Object.entries(out).filter(([k]) => !ANCHOR_FIELDS.has(k)))).length;
365
+ // 已降级值按固定小成本计费:标记串是不可再压的结构噪声,按字面长度计费会让
366
+ // 标记变长把多键调用挤进 _aged 兜底、反而丢键名(OP-TOOL-1 评审 M2:
367
+ // 命名空间标记 +12 字符曾把「键名全保」阈值从 ~17 键压到 10 键)。
368
+ const contentChars = () => safeJson(Object.fromEntries(Object.entries(out)
369
+ .filter(([k]) => !ANCHOR_FIELDS.has(k))
370
+ .map(([k, v]) => [k, isElisionToken(v) ? ELIDED_VALUE_BUDGET_COST : v]))).length;
235
371
  const contentEntries = entries
236
372
  .filter((e) => !ANCHOR_FIELDS.has(e.k))
237
373
  .sort((a, b) => b.size - a.size || (a.k < b.k ? -1 : a.k > b.k ? 1 : 0));
@@ -240,34 +376,60 @@ export function agedToolArgDigest(name, args, opts) {
240
376
  break;
241
377
  out[e.k] = elidedMarker(e.size);
242
378
  }
379
+ // 兜底(键名过多装不下)也必须带上 purpose:它是任务逻辑的可读记录,
380
+ // 整体轮廓截断只保留头部,purpose 很可能不在其中。purpose 不是内容载荷,
381
+ // 不参与预算,因此这里无条件回附。
382
+ const rawPurpose = args[PURPOSE_FIELD];
243
383
  const value = contentChars() > opts.maxAgedArgChars
244
- ? { _aged: `${name} arguments elided`, outline: truncateOutline(safeJson(args), opts.maxAgedArgChars) }
384
+ ? {
385
+ _aged: `${name} arguments elided`,
386
+ outline: truncateOutline(safeJson(args), opts.maxAgedArgChars),
387
+ ...(typeof rawPurpose === 'string' ? { [PURPOSE_FIELD]: rawPurpose } : {}),
388
+ }
245
389
  : out;
246
390
  argDigestCache.set(args, { fingerprint, value });
247
391
  return value;
248
392
  }
249
- /** 值被省略时的长度标记 */
393
+ /** 值被省略时的长度标记(对象形,词汇表单一来源:core/elision)
394
+ *
395
+ * 对象形而非文本形:文本标记与真实内容同形,会被模型当内容回抄进 tool call
396
+ * (OP-TOOL-1 实证污染源);对象形语法类别上就不是内容,抄入 string 参数即
397
+ * schema 违规,执行边界守卫再兜底拒收。
398
+ */
250
399
  function elidedMarker(chars) {
251
- return `…[${chars} chars]`;
400
+ return elidedValueMarker(chars);
252
401
  }
253
402
  /**
254
403
  * 定位字段:它们短、且是「这条调用到底碰了哪里」的唯一锚点,优先全保
255
404
  *
256
- * 实测:`path` 均长 79 字符(全保仅 +1.5% 请求体),而 `command` 均长 414
257
- * (全保 +8.6%)。因此路径类全保、命令类只留头部。
405
+ * 实测:`path` 均长 79 字符(全保仅 +1.5% 请求体),`command` 均长 414
406
+ * (全保 +8.6%)。路径类全保;命令类同样全保不截断(2026-11-12 拍板:截断
407
+ * 收益有限、文本尾标记却是回抄污染源——OP-TOOL-1 sed/grep 案半数案例)。
258
408
  */
259
409
  const LOCATOR_FIELDS = new Set(['path', 'file', 'glob', 'pattern', 'cwd']);
410
+ /**
411
+ * purpose 字段:**永不因内容预算或长度被降级**(2026-11-13 拍板)
412
+ *
413
+ * purpose 是「这次调用做了什么、为什么」的唯一人类可读记录,是后续读方重建
414
+ * 整个任务逻辑的关键信息(arch/tool-call-purpose.md)。它作为普通参数进入
415
+ * `tool_call.arguments`,若按常规阈值处理会被直接替换成
416
+ * `{"$octopi:elided":{"chars":N}}`——实测生产会话 424 条 purpose 里有 14 条
417
+ * (3.3%)如此,长度 66–77,正是「说清一件事」的常见区间。
418
+ *
419
+ * 因此这里**不设长度上限**:老化只做「信息取舍」,不做「长度治理」。长度约束
420
+ * 属于调用入口的职责(schema 声明 + 工具总线校验),在视图侧截断既管不住入口、
421
+ * 又会永久毁掉已发生调用的可读性。
422
+ */
423
+ const PURPOSE_FIELD = 'purpose';
260
424
  /**
261
425
  * 锚点字段:不占用内容预算(否则定位信息会被内容载荷挤出)
262
426
  *
263
- * 定位字段与命令字段都属锚点——`command` 头部回答「跑了什么」,
264
- * 若让它和 `old_text` 之类抢同一个预算,多条命令一累加就会把头部整体省略掉。
427
+ * 定位字段与命令字段都属锚点——`command` 全文回答「跑了什么」,
428
+ * 若让它和 `old_text` 之类抢同一个预算,多条命令一累加就会把命令整体省略掉。
265
429
  */
266
- const ANCHOR_FIELDS = new Set([...LOCATOR_FIELDS, 'command', 'cmd']);
430
+ const ANCHOR_FIELDS = new Set([...LOCATOR_FIELDS, 'command', 'cmd', PURPOSE_FIELD]);
267
431
  /** 定位字段全保上限(超长的罕见路径才会退化为标记) */
268
432
  const LOCATOR_KEEP_CHARS = 200;
269
- /** 命令类字段保留的头部长度(其余用长度标记收尾) */
270
- const COMMAND_HEAD_CHARS = 100;
271
433
  /** 命令类字段名 */
272
434
  const COMMAND_FIELDS = new Set(['command', 'cmd']);
273
435
  function isLocatorField(key) {
@@ -282,15 +444,18 @@ function isLocatorField(key) {
282
444
  * @returns 保留原值、头部摘录或长度标记
283
445
  */
284
446
  function digestArgValue(key, value, size) {
447
+ // purpose 无条件全保:它是任务逻辑的可读记录,不是可牺牲的内容载荷
448
+ if (key === PURPOSE_FIELD)
449
+ return value;
285
450
  if (size <= ARG_VALUE_KEEP_CHARS)
286
451
  return value;
287
452
  if (isLocatorField(key) && size <= LOCATOR_KEEP_CHARS)
288
453
  return value;
289
454
  if (COMMAND_FIELDS.has(key) && typeof value === 'string') {
290
- // 短命令原样保留;长命令保留头部(头部才是「跑了什么」的判据)
291
- if (value.length <= COMMAND_HEAD_CHARS)
292
- return value;
293
- return `${value.slice(0, COMMAND_HEAD_CHARS)}…[+${value.length - COMMAND_HEAD_CHARS} chars]`;
455
+ // 命令不截断、全保(2026-11-12 拍板):截断省的量有限(锚点本就不占内容预算),
456
+ // 文本尾标记却是模型回抄污染源(OP-TOOL-1 sed/grep 案半数案例)。digest
457
+ // 恒 ≤ 原始 args(本字段与原值相同、其余字段只减不增),不引入新的无界增长。
458
+ return value;
294
459
  }
295
460
  return elidedMarker(size);
296
461
  }
@@ -327,5 +492,5 @@ function safeJson(value) {
327
492
  * @returns 轮廓文本
328
493
  */
329
494
  function truncateOutline(text, maxChars) {
330
- return text.length <= maxChars ? text : `${text.slice(0, maxChars)}${TRUNCATION_MARK}`;
495
+ return text.length <= maxChars ? text : `${text.slice(0, maxChars)}${TRUNCATED_MARK}`;
331
496
  }
@@ -4,6 +4,8 @@
4
4
  * 消息内容写入后不可变(全库无对已存在消息 content/toolResults/toolCalls 的
5
5
  * 原地修改;压缩器一律新建对象),同一 `tr` 对象可安全复用序列化结果。
6
6
  * 这消除每轮 context 装配里对同一批 toolResults 反复 `JSON.stringify` 的开销。
7
+ * 注意:摘要投影(capabilities/compact 的会话文本化)也复用本缓存——原地改写
8
+ * toolResult 不只影响 token 计数,还会让摘要吃到陈旧正文;上述不可变性是硬前提。
7
9
  */
8
10
  const cache = new WeakMap();
9
11
  /**
@@ -0,0 +1,66 @@
1
+ /**
2
+ * Message anchors — stable coordinates for transform records.
3
+ *
4
+ * Messages in the session log are append-only and immutable (tool-result
5
+ * aging is view-level), so a content identity hash is a stable coordinate
6
+ * across restarts and session forks. `occurrence` disambiguates byte-identical
7
+ * duplicates in stream order; `indexHint` is only a resolution fast path.
8
+ *
9
+ * Ephemeral messages (never persisted) are never anchorable: a record whose
10
+ * boundary would fall on one is trimmed inward at creation (see
11
+ * {@link anchorRange}), so anchors always resolve against the persisted stream.
12
+ *
13
+ * @module harness/context/transform/anchors
14
+ */
15
+ import type { Message } from '@octopi-agent/core/types.js';
16
+ import type { MessageAnchor, TransformRun } from './types.js';
17
+ /**
18
+ * Canonical identity hash of a message.
19
+ *
20
+ * Covers the persisted identity fields (role / content / toolCalls / toolResults
21
+ * / source / timestamp / agentId / metadata). Only `ephemeral` is excluded —
22
+ * it is in-run only, never persisted, and must not affect identity.
23
+ *
24
+ * @param m - message
25
+ * @returns sha256 hex of the canonical form
26
+ */
27
+ export declare function canonicalMessageHash(m: Message): string;
28
+ /**
29
+ * Build the anchor for messages[index], with occurrence counted in stream order.
30
+ *
31
+ * @param messages - full message stream (may include ephemeral entries)
32
+ * @param index - raw index
33
+ * @returns anchor
34
+ */
35
+ export declare function anchorFor(messages: Message[], index: number): MessageAnchor;
36
+ /**
37
+ * Resolve an anchor to a raw index in the current stream.
38
+ *
39
+ * Fast path: `indexHint` when the hash still matches there (append-only
40
+ * streams keep earlier indices stable). Slow path: the occurrence-th message
41
+ * with the anchor hash. Ephemeral messages are skipped during scanning — they
42
+ * cannot be anchors, and their presence/absence must not shift resolution.
43
+ *
44
+ * @param messages - current message stream
45
+ * @param anchor - anchor to resolve
46
+ * @returns raw index, or undefined when unresolvable (orphan)
47
+ */
48
+ export declare function resolveAnchor(messages: Message[], anchor: MessageAnchor): number | undefined;
49
+ /**
50
+ * Anchor an inclusive index range `[start, end]`, trimming ephemeral
51
+ * boundaries inward so both anchors resolve against the persisted stream.
52
+ *
53
+ * @param messages - full message stream
54
+ * @param start - inclusive raw start index
55
+ * @param end - inclusive raw end index
56
+ * @returns run, or undefined when no non-ephemeral message remains in range
57
+ */
58
+ export declare function anchorRange(messages: Message[], start: number, end: number): TransformRun | undefined;
59
+ /**
60
+ * Resolve a run to an inclusive raw index range.
61
+ *
62
+ * @param messages - current message stream
63
+ * @param run - run to resolve
64
+ * @returns `[start, end]` inclusive, or undefined when either anchor is orphan
65
+ */
66
+ export declare function resolveRun(messages: Message[], run: TransformRun): [number, number] | undefined;
@@ -0,0 +1,125 @@
1
+ /**
2
+ * Message anchors — stable coordinates for transform records.
3
+ *
4
+ * Messages in the session log are append-only and immutable (tool-result
5
+ * aging is view-level), so a content identity hash is a stable coordinate
6
+ * across restarts and session forks. `occurrence` disambiguates byte-identical
7
+ * duplicates in stream order; `indexHint` is only a resolution fast path.
8
+ *
9
+ * Ephemeral messages (never persisted) are never anchorable: a record whose
10
+ * boundary would fall on one is trimmed inward at creation (see
11
+ * {@link anchorRange}), so anchors always resolve against the persisted stream.
12
+ *
13
+ * @module harness/context/transform/anchors
14
+ */
15
+ import { createHash } from 'node:crypto';
16
+ /**
17
+ * Canonical identity hash of a message.
18
+ *
19
+ * Covers the persisted identity fields (role / content / toolCalls / toolResults
20
+ * / source / timestamp / agentId / metadata). Only `ephemeral` is excluded —
21
+ * it is in-run only, never persisted, and must not affect identity.
22
+ *
23
+ * @param m - message
24
+ * @returns sha256 hex of the canonical form
25
+ */
26
+ export function canonicalMessageHash(m) {
27
+ return createHash('sha256')
28
+ .update(canonicalJson({ role: m.role, content: m.content, toolCalls: m.toolCalls, toolResults: m.toolResults, source: m.source, timestamp: m.timestamp, agentId: m.agentId, metadata: m.metadata }), 'utf8')
29
+ .digest('hex');
30
+ }
31
+ /** Deterministic JSON: object keys sorted recursively. */
32
+ function canonicalJson(value) {
33
+ if (value === null || typeof value !== 'object')
34
+ return JSON.stringify(value) ?? 'undefined';
35
+ if (Array.isArray(value))
36
+ return `[${value.map(canonicalJson).join(',')}]`;
37
+ const entries = Object.entries(value)
38
+ .filter(([, v]) => v !== undefined)
39
+ .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
40
+ return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson(v)}`).join(',')}}`;
41
+ }
42
+ /**
43
+ * Build the anchor for messages[index], with occurrence counted in stream order.
44
+ *
45
+ * @param messages - full message stream (may include ephemeral entries)
46
+ * @param index - raw index
47
+ * @returns anchor
48
+ */
49
+ export function anchorFor(messages, index) {
50
+ const hash = canonicalMessageHash(messages[index]);
51
+ let occurrence = 0;
52
+ for (let i = 0; i < index; i++) {
53
+ // 与 resolveAnchor 对称(评审 F8):ephemeral 不参与 occurrence 计数,
54
+ // 否则「创建时含 ephemeral 同形、解析时被跳过」会错位失锚
55
+ if (messages[i]?.ephemeral)
56
+ continue;
57
+ if (canonicalMessageHash(messages[i]) === hash)
58
+ occurrence += 1;
59
+ }
60
+ return { hash, occurrence, indexHint: index };
61
+ }
62
+ /**
63
+ * Resolve an anchor to a raw index in the current stream.
64
+ *
65
+ * Fast path: `indexHint` when the hash still matches there (append-only
66
+ * streams keep earlier indices stable). Slow path: the occurrence-th message
67
+ * with the anchor hash. Ephemeral messages are skipped during scanning — they
68
+ * cannot be anchors, and their presence/absence must not shift resolution.
69
+ *
70
+ * @param messages - current message stream
71
+ * @param anchor - anchor to resolve
72
+ * @returns raw index, or undefined when unresolvable (orphan)
73
+ */
74
+ export function resolveAnchor(messages, anchor) {
75
+ const hinted = messages[anchor.indexHint];
76
+ if (hinted && !hinted.ephemeral && canonicalMessageHash(hinted) === anchor.hash) {
77
+ return anchor.indexHint;
78
+ }
79
+ let seen = 0;
80
+ for (let i = 0; i < messages.length; i++) {
81
+ const m = messages[i];
82
+ if (m.ephemeral)
83
+ continue;
84
+ if (canonicalMessageHash(m) !== anchor.hash)
85
+ continue;
86
+ if (seen === anchor.occurrence)
87
+ return i;
88
+ seen += 1;
89
+ }
90
+ return undefined;
91
+ }
92
+ /**
93
+ * Anchor an inclusive index range `[start, end]`, trimming ephemeral
94
+ * boundaries inward so both anchors resolve against the persisted stream.
95
+ *
96
+ * @param messages - full message stream
97
+ * @param start - inclusive raw start index
98
+ * @param end - inclusive raw end index
99
+ * @returns run, or undefined when no non-ephemeral message remains in range
100
+ */
101
+ export function anchorRange(messages, start, end) {
102
+ let a = start;
103
+ let b = end;
104
+ while (a <= b && messages[a]?.ephemeral)
105
+ a += 1;
106
+ while (b >= a && messages[b]?.ephemeral)
107
+ b -= 1;
108
+ if (a > b)
109
+ return undefined;
110
+ return { from: anchorFor(messages, a), to: anchorFor(messages, b) };
111
+ }
112
+ /**
113
+ * Resolve a run to an inclusive raw index range.
114
+ *
115
+ * @param messages - current message stream
116
+ * @param run - run to resolve
117
+ * @returns `[start, end]` inclusive, or undefined when either anchor is orphan
118
+ */
119
+ export function resolveRun(messages, run) {
120
+ const a = resolveAnchor(messages, run.from);
121
+ const b = resolveAnchor(messages, run.to);
122
+ if (a === undefined || b === undefined || b < a)
123
+ return undefined;
124
+ return [a, b];
125
+ }