pi-braid 0.0.0-stage → 0.40.0

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 (1011) hide show
  1. package/AGENTS.md +195 -0
  2. package/CONTRIBUTING.md +302 -0
  3. package/LICENSE +21 -0
  4. package/README.md +260 -2
  5. package/TOOLS.md +147 -0
  6. package/dist/extensions/cognitive/mars-reflector/index.d.ts +82 -0
  7. package/dist/extensions/cognitive/mars-reflector/index.js +327 -0
  8. package/dist/extensions/cognitive/metacognition/handlers/claim-verification.d.ts +23 -0
  9. package/dist/extensions/cognitive/metacognition/handlers/claim-verification.js +233 -0
  10. package/dist/extensions/cognitive/metacognition/handlers/finalize.d.ts +27 -0
  11. package/dist/extensions/cognitive/metacognition/handlers/finalize.js +557 -0
  12. package/dist/extensions/cognitive/metacognition/handlers/hypothesize.d.ts +19 -0
  13. package/dist/extensions/cognitive/metacognition/handlers/hypothesize.js +291 -0
  14. package/dist/extensions/cognitive/metacognition/handlers/scoring.d.ts +28 -0
  15. package/dist/extensions/cognitive/metacognition/handlers/scoring.js +173 -0
  16. package/dist/extensions/cognitive/metacognition/handlers/think-budget.d.ts +85 -0
  17. package/dist/extensions/cognitive/metacognition/handlers/think-budget.js +164 -0
  18. package/dist/extensions/cognitive/metacognition/handlers/think.d.ts +27 -0
  19. package/dist/extensions/cognitive/metacognition/handlers/think.js +374 -0
  20. package/dist/extensions/cognitive/metacognition/handlers/verify.d.ts +53 -0
  21. package/dist/extensions/cognitive/metacognition/handlers/verify.js +321 -0
  22. package/dist/extensions/cognitive/metacognition/index.d.ts +10 -0
  23. package/dist/extensions/cognitive/metacognition/index.js +90 -0
  24. package/dist/extensions/cognitive/reasoning/index.d.ts +43 -0
  25. package/dist/extensions/cognitive/reasoning/index.js +99 -0
  26. package/dist/extensions/cognitive/sycophancy-detector/index.d.ts +16 -0
  27. package/dist/extensions/cognitive/sycophancy-detector/index.js +203 -0
  28. package/dist/extensions/cognitive/topic-drift/index.d.ts +51 -0
  29. package/dist/extensions/cognitive/topic-drift/index.js +346 -0
  30. package/dist/extensions/cognitive/turn-outcome/index.d.ts +35 -0
  31. package/dist/extensions/cognitive/turn-outcome/index.js +163 -0
  32. package/dist/extensions/context-management/index.d.ts +77 -0
  33. package/dist/extensions/context-management/index.js +339 -0
  34. package/dist/extensions/core/agent-environment/index.d.ts +30 -0
  35. package/dist/extensions/core/agent-environment/index.js +89 -0
  36. package/dist/extensions/core/polyfill/index.d.ts +28 -0
  37. package/dist/extensions/core/polyfill/index.js +474 -0
  38. package/dist/extensions/core/prompt-builder/awareness-whisper.d.ts +74 -0
  39. package/dist/extensions/core/prompt-builder/awareness-whisper.js +116 -0
  40. package/dist/extensions/core/prompt-builder/context-section.d.ts +41 -0
  41. package/dist/extensions/core/prompt-builder/context-section.js +101 -0
  42. package/dist/extensions/core/prompt-builder/custom-sections.d.ts +21 -0
  43. package/dist/extensions/core/prompt-builder/custom-sections.js +11 -0
  44. package/dist/extensions/core/prompt-builder/external-tool-guidelines.d.ts +23 -0
  45. package/dist/extensions/core/prompt-builder/external-tool-guidelines.js +37 -0
  46. package/dist/extensions/core/prompt-builder/identity.d.ts +33 -0
  47. package/dist/extensions/core/prompt-builder/identity.js +77 -0
  48. package/dist/extensions/core/prompt-builder/index.d.ts +33 -0
  49. package/dist/extensions/core/prompt-builder/index.js +496 -0
  50. package/dist/extensions/core/prompt-builder/inspect.d.ts +58 -0
  51. package/dist/extensions/core/prompt-builder/inspect.js +182 -0
  52. package/dist/extensions/core/prompt-builder/instance-composition.d.ts +101 -0
  53. package/dist/extensions/core/prompt-builder/instance-composition.js +416 -0
  54. package/dist/extensions/core/prompt-builder/memory-section.d.ts +20 -0
  55. package/dist/extensions/core/prompt-builder/memory-section.js +60 -0
  56. package/dist/extensions/core/prompt-builder/pi-reference-section.d.ts +17 -0
  57. package/dist/extensions/core/prompt-builder/pi-reference-section.js +11 -0
  58. package/dist/extensions/core/prompt-builder/project-docs-section.d.ts +42 -0
  59. package/dist/extensions/core/prompt-builder/project-docs-section.js +72 -0
  60. package/dist/extensions/core/prompt-builder/section-parity.d.ts +36 -0
  61. package/dist/extensions/core/prompt-builder/section-parity.js +66 -0
  62. package/dist/extensions/core/prompt-builder/section-publish.d.ts +30 -0
  63. package/dist/extensions/core/prompt-builder/section-publish.js +16 -0
  64. package/dist/extensions/core/prompt-builder/section.d.ts +75 -0
  65. package/dist/extensions/core/prompt-builder/section.js +127 -0
  66. package/dist/extensions/core/prompt-builder/surface-discipline-section.d.ts +18 -0
  67. package/dist/extensions/core/prompt-builder/surface-discipline-section.js +20 -0
  68. package/dist/extensions/core/prompt-builder/system-info-tool.d.ts +27 -0
  69. package/dist/extensions/core/prompt-builder/system-info-tool.js +67 -0
  70. package/dist/extensions/core/prompt-builder/tool-description-trim.d.ts +56 -0
  71. package/dist/extensions/core/prompt-builder/tool-description-trim.js +129 -0
  72. package/dist/extensions/core/prompt-builder/tool-guidelines.d.ts +80 -0
  73. package/dist/extensions/core/prompt-builder/tool-guidelines.js +179 -0
  74. package/dist/extensions/core/prompt-builder/tool-pipelines.d.ts +50 -0
  75. package/dist/extensions/core/prompt-builder/tool-pipelines.js +69 -0
  76. package/dist/extensions/core/prompt-builder/top-level-extensions.d.ts +44 -0
  77. package/dist/extensions/core/prompt-builder/top-level-extensions.js +300 -0
  78. package/dist/extensions/core/skills-tool/auto-inject.d.ts +333 -0
  79. package/dist/extensions/core/skills-tool/auto-inject.js +817 -0
  80. package/dist/extensions/core/skills-tool/index.d.ts +56 -0
  81. package/dist/extensions/core/skills-tool/index.js +200 -0
  82. package/dist/extensions/core/skills-tool/loading-guidance.d.ts +50 -0
  83. package/dist/extensions/core/skills-tool/loading-guidance.js +87 -0
  84. package/dist/extensions/core/skills-tool/session-records.d.ts +114 -0
  85. package/dist/extensions/core/skills-tool/session-records.js +268 -0
  86. package/dist/extensions/core/skills-tool/skill-triggers.d.ts +48 -0
  87. package/dist/extensions/core/skills-tool/skill-triggers.js +113 -0
  88. package/dist/extensions/enforcement/detection/malformed.d.ts +9 -0
  89. package/dist/extensions/enforcement/detection/malformed.js +30 -0
  90. package/dist/extensions/enforcement/detection/verification.d.ts +10 -0
  91. package/dist/extensions/enforcement/detection/verification.js +34 -0
  92. package/dist/extensions/enforcement/enforcement-types.d.ts +33 -0
  93. package/dist/extensions/enforcement/enforcement-types.js +24 -0
  94. package/dist/extensions/enforcement/handler-registry.d.ts +12 -0
  95. package/dist/extensions/enforcement/handler-registry.js +196 -0
  96. package/dist/extensions/enforcement/handlers/analysis/bpe-handler.d.ts +10 -0
  97. package/dist/extensions/enforcement/handlers/analysis/bpe-handler.js +37 -0
  98. package/dist/extensions/enforcement/handlers/analysis/dreamer-handler.d.ts +6 -0
  99. package/dist/extensions/enforcement/handlers/analysis/dreamer-handler.js +60 -0
  100. package/dist/extensions/enforcement/handlers/analysis/drift-handler.d.ts +6 -0
  101. package/dist/extensions/enforcement/handlers/analysis/drift-handler.js +75 -0
  102. package/dist/extensions/enforcement/handlers/analysis/feedback-handler.d.ts +6 -0
  103. package/dist/extensions/enforcement/handlers/analysis/feedback-handler.js +19 -0
  104. package/dist/extensions/enforcement/handlers/analysis/mars-handler.d.ts +14 -0
  105. package/dist/extensions/enforcement/handlers/analysis/mars-handler.js +99 -0
  106. package/dist/extensions/enforcement/handlers/analysis/reflection-handler.d.ts +6 -0
  107. package/dist/extensions/enforcement/handlers/analysis/reflection-handler.js +16 -0
  108. package/dist/extensions/enforcement/handlers/blocking.d.ts +16 -0
  109. package/dist/extensions/enforcement/handlers/blocking.js +33 -0
  110. package/dist/extensions/enforcement/handlers/message-analysis.d.ts +25 -0
  111. package/dist/extensions/enforcement/handlers/message-analysis.js +70 -0
  112. package/dist/extensions/enforcement/handlers/orphan-chains.d.ts +14 -0
  113. package/dist/extensions/enforcement/handlers/orphan-chains.js +44 -0
  114. package/dist/extensions/enforcement/handlers/over-correction-gate.d.ts +73 -0
  115. package/dist/extensions/enforcement/handlers/over-correction-gate.js +565 -0
  116. package/dist/extensions/enforcement/handlers/probe-handler.d.ts +31 -0
  117. package/dist/extensions/enforcement/handlers/probe-handler.js +111 -0
  118. package/dist/extensions/enforcement/handlers/register-adherence-meter.d.ts +52 -0
  119. package/dist/extensions/enforcement/handlers/register-adherence-meter.js +158 -0
  120. package/dist/extensions/enforcement/handlers/register-agent-end-api-error.d.ts +3 -0
  121. package/dist/extensions/enforcement/handlers/register-agent-end-api-error.js +69 -0
  122. package/dist/extensions/enforcement/handlers/register-input-handler.d.ts +10 -0
  123. package/dist/extensions/enforcement/handlers/register-input-handler.js +35 -0
  124. package/dist/extensions/enforcement/handlers/register-message-end.d.ts +6 -0
  125. package/dist/extensions/enforcement/handlers/register-message-end.js +388 -0
  126. package/dist/extensions/enforcement/handlers/register-post-cycle-hygiene.d.ts +25 -0
  127. package/dist/extensions/enforcement/handlers/register-post-cycle-hygiene.js +143 -0
  128. package/dist/extensions/enforcement/handlers/register-session-compact.d.ts +50 -0
  129. package/dist/extensions/enforcement/handlers/register-session-compact.js +207 -0
  130. package/dist/extensions/enforcement/handlers/register-session-shutdown-resumption.d.ts +21 -0
  131. package/dist/extensions/enforcement/handlers/register-session-shutdown-resumption.js +116 -0
  132. package/dist/extensions/enforcement/handlers/register-session-shutdown.d.ts +6 -0
  133. package/dist/extensions/enforcement/handlers/register-session-shutdown.js +38 -0
  134. package/dist/extensions/enforcement/handlers/register-session-start-discoverability.d.ts +34 -0
  135. package/dist/extensions/enforcement/handlers/register-session-start-discoverability.js +240 -0
  136. package/dist/extensions/enforcement/handlers/register-session-start.d.ts +16 -0
  137. package/dist/extensions/enforcement/handlers/register-session-start.js +198 -0
  138. package/dist/extensions/enforcement/handlers/register-tool-call.d.ts +6 -0
  139. package/dist/extensions/enforcement/handlers/register-tool-call.js +132 -0
  140. package/dist/extensions/enforcement/handlers/register-tool-result-formatting.d.ts +18 -0
  141. package/dist/extensions/enforcement/handlers/register-tool-result-formatting.js +56 -0
  142. package/dist/extensions/enforcement/handlers/register-tool-result.d.ts +6 -0
  143. package/dist/extensions/enforcement/handlers/register-tool-result.js +91 -0
  144. package/dist/extensions/enforcement/handlers/register-turn-end-hygiene.d.ts +35 -0
  145. package/dist/extensions/enforcement/handlers/register-turn-end-hygiene.js +385 -0
  146. package/dist/extensions/enforcement/handlers/routing-handler.d.ts +42 -0
  147. package/dist/extensions/enforcement/handlers/routing-handler.js +135 -0
  148. package/dist/extensions/enforcement/handlers/tool-tracker.d.ts +9 -0
  149. package/dist/extensions/enforcement/handlers/tool-tracker.js +122 -0
  150. package/dist/extensions/enforcement/handlers/turn-analysis.d.ts +41 -0
  151. package/dist/extensions/enforcement/handlers/turn-analysis.js +109 -0
  152. package/dist/extensions/enforcement/handlers/turn-end-handler.d.ts +9 -0
  153. package/dist/extensions/enforcement/handlers/turn-end-handler.js +451 -0
  154. package/dist/extensions/enforcement/index.d.ts +15 -0
  155. package/dist/extensions/enforcement/index.js +22 -0
  156. package/dist/extensions/enforcement/judge-utils.d.ts +73 -0
  157. package/dist/extensions/enforcement/judge-utils.js +83 -0
  158. package/dist/extensions/enforcement/nudge-manager.d.ts +106 -0
  159. package/dist/extensions/enforcement/nudge-manager.js +203 -0
  160. package/dist/extensions/enforcement/self-state-claims.d.ts +79 -0
  161. package/dist/extensions/enforcement/self-state-claims.js +167 -0
  162. package/dist/extensions/enforcement/session-health.d.ts +107 -0
  163. package/dist/extensions/enforcement/session-health.js +251 -0
  164. package/dist/extensions/enforcement/signals.d.ts +54 -0
  165. package/dist/extensions/enforcement/signals.js +47 -0
  166. package/dist/extensions/enforcement/similarity.d.ts +16 -0
  167. package/dist/extensions/enforcement/similarity.js +64 -0
  168. package/dist/extensions/enforcement/state.d.ts +40 -0
  169. package/dist/extensions/enforcement/state.js +74 -0
  170. package/dist/extensions/enforcement/substate/context-hygiene-state.d.ts +88 -0
  171. package/dist/extensions/enforcement/substate/context-hygiene-state.js +119 -0
  172. package/dist/extensions/enforcement/substate/error-tracking-state.d.ts +20 -0
  173. package/dist/extensions/enforcement/substate/error-tracking-state.js +37 -0
  174. package/dist/extensions/enforcement/substate/memory-hygiene-state.d.ts +24 -0
  175. package/dist/extensions/enforcement/substate/memory-hygiene-state.js +37 -0
  176. package/dist/extensions/enforcement/substate/session-state.d.ts +34 -0
  177. package/dist/extensions/enforcement/substate/session-state.js +45 -0
  178. package/dist/extensions/enforcement/substate/thought-chain-state.d.ts +23 -0
  179. package/dist/extensions/enforcement/substate/thought-chain-state.js +43 -0
  180. package/dist/extensions/enforcement/substate/tool-tracking-state.d.ts +71 -0
  181. package/dist/extensions/enforcement/substate/tool-tracking-state.js +99 -0
  182. package/dist/extensions/enforcement/substate/verification-judge-state.d.ts +17 -0
  183. package/dist/extensions/enforcement/substate/verification-judge-state.js +39 -0
  184. package/dist/extensions/enforcement/task-evidence.d.ts +108 -0
  185. package/dist/extensions/enforcement/task-evidence.js +335 -0
  186. package/dist/extensions/enforcement/types.d.ts +35 -0
  187. package/dist/extensions/enforcement/types.js +5 -0
  188. package/dist/extensions/enforcement/validation.d.ts +12 -0
  189. package/dist/extensions/enforcement/validation.js +151 -0
  190. package/dist/extensions/enforcement/verification-judge.d.ts +110 -0
  191. package/dist/extensions/enforcement/verification-judge.js +214 -0
  192. package/dist/extensions/enforcement/whisper.d.ts +46 -0
  193. package/dist/extensions/enforcement/whisper.js +104 -0
  194. package/dist/extensions/heartbeat/analytics/ab-variant.d.ts +19 -0
  195. package/dist/extensions/heartbeat/analytics/ab-variant.js +86 -0
  196. package/dist/extensions/heartbeat/analytics/core.d.ts +12 -0
  197. package/dist/extensions/heartbeat/analytics/core.js +201 -0
  198. package/dist/extensions/heartbeat/analytics/format.d.ts +7 -0
  199. package/dist/extensions/heartbeat/analytics/format.js +111 -0
  200. package/dist/extensions/heartbeat/analytics/index.d.ts +14 -0
  201. package/dist/extensions/heartbeat/analytics/index.js +352 -0
  202. package/dist/extensions/heartbeat/analytics/shared.d.ts +85 -0
  203. package/dist/extensions/heartbeat/analytics/shared.js +69 -0
  204. package/dist/extensions/heartbeat/heartbeat-scheduler/index.d.ts +31 -0
  205. package/dist/extensions/heartbeat/heartbeat-scheduler/index.js +881 -0
  206. package/dist/extensions/heartbeat/heartbeat-scheduler/meta-learning.d.ts +10 -0
  207. package/dist/extensions/heartbeat/heartbeat-scheduler/meta-learning.js +49 -0
  208. package/dist/extensions/heartbeat/heartbeat-scheduler/modules/behavioral-drift.d.ts +17 -0
  209. package/dist/extensions/heartbeat/heartbeat-scheduler/modules/behavioral-drift.js +161 -0
  210. package/dist/extensions/heartbeat/heartbeat-scheduler/modules/budget.d.ts +13 -0
  211. package/dist/extensions/heartbeat/heartbeat-scheduler/modules/budget.js +101 -0
  212. package/dist/extensions/heartbeat/heartbeat-scheduler/modules/context-hygiene.d.ts +10 -0
  213. package/dist/extensions/heartbeat/heartbeat-scheduler/modules/context-hygiene.js +221 -0
  214. package/dist/extensions/heartbeat/heartbeat-scheduler/modules/evolver.d.ts +9 -0
  215. package/dist/extensions/heartbeat/heartbeat-scheduler/modules/evolver.js +65 -0
  216. package/dist/extensions/heartbeat/heartbeat-scheduler/modules/measurement.d.ts +8 -0
  217. package/dist/extensions/heartbeat/heartbeat-scheduler/modules/measurement.js +32 -0
  218. package/dist/extensions/heartbeat/heartbeat-scheduler/modules/recaller.d.ts +9 -0
  219. package/dist/extensions/heartbeat/heartbeat-scheduler/modules/recaller.js +75 -0
  220. package/dist/extensions/heartbeat/heartbeat-scheduler/modules/reflection-consolidator.d.ts +9 -0
  221. package/dist/extensions/heartbeat/heartbeat-scheduler/modules/reflection-consolidator.js +98 -0
  222. package/dist/extensions/heartbeat/heartbeat-scheduler/policies.d.ts +14 -0
  223. package/dist/extensions/heartbeat/heartbeat-scheduler/policies.js +149 -0
  224. package/dist/extensions/heartbeat/heartbeat-scheduler/state.d.ts +22 -0
  225. package/dist/extensions/heartbeat/heartbeat-scheduler/state.js +82 -0
  226. package/dist/extensions/heartbeat/heartbeat-scheduler/types.d.ts +124 -0
  227. package/dist/extensions/heartbeat/heartbeat-scheduler/types.js +7 -0
  228. package/dist/extensions/heartbeat/heartbeat-scheduler/whisper-batcher.d.ts +52 -0
  229. package/dist/extensions/heartbeat/heartbeat-scheduler/whisper-batcher.js +83 -0
  230. package/dist/extensions/manifest.d.ts +32 -0
  231. package/dist/extensions/manifest.js +251 -0
  232. package/dist/extensions/memory/context-lifecycle/helpers.d.ts +55 -0
  233. package/dist/extensions/memory/context-lifecycle/helpers.js +142 -0
  234. package/dist/extensions/memory/context-lifecycle/index.d.ts +17 -0
  235. package/dist/extensions/memory/context-lifecycle/index.js +977 -0
  236. package/dist/extensions/memory/context-lifecycle/policy-engine.d.ts +50 -0
  237. package/dist/extensions/memory/context-lifecycle/policy-engine.js +196 -0
  238. package/dist/extensions/memory/context-lifecycle/signal-detector.d.ts +28 -0
  239. package/dist/extensions/memory/context-lifecycle/signal-detector.js +224 -0
  240. package/dist/extensions/memory/context-lifecycle/state.d.ts +98 -0
  241. package/dist/extensions/memory/context-lifecycle/state.js +90 -0
  242. package/dist/extensions/memory/context-lifecycle/types.d.ts +132 -0
  243. package/dist/extensions/memory/context-lifecycle/types.js +273 -0
  244. package/dist/extensions/memory/context-manager/analysis.d.ts +47 -0
  245. package/dist/extensions/memory/context-manager/analysis.js +264 -0
  246. package/dist/extensions/memory/context-manager/handlers/compaction-chunked.d.ts +159 -0
  247. package/dist/extensions/memory/context-manager/handlers/compaction-chunked.js +658 -0
  248. package/dist/extensions/memory/context-manager/handlers/compaction-retry.d.ts +29 -0
  249. package/dist/extensions/memory/context-manager/handlers/compaction-retry.js +410 -0
  250. package/dist/extensions/memory/context-manager/handlers/compaction-trace.d.ts +74 -0
  251. package/dist/extensions/memory/context-manager/handlers/compaction-trace.js +180 -0
  252. package/dist/extensions/memory/context-manager/handlers/compaction-watchdog.d.ts +69 -0
  253. package/dist/extensions/memory/context-manager/handlers/compaction-watchdog.js +297 -0
  254. package/dist/extensions/memory/context-manager/handlers/compaction.d.ts +37 -0
  255. package/dist/extensions/memory/context-manager/handlers/compaction.js +2150 -0
  256. package/dist/extensions/memory/context-manager/handlers/context-emergency.d.ts +124 -0
  257. package/dist/extensions/memory/context-manager/handlers/context-emergency.js +364 -0
  258. package/dist/extensions/memory/context-manager/handlers/events.d.ts +5 -0
  259. package/dist/extensions/memory/context-manager/handlers/events.js +314 -0
  260. package/dist/extensions/memory/context-manager/handlers/navigation.d.ts +5 -0
  261. package/dist/extensions/memory/context-manager/handlers/navigation.js +86 -0
  262. package/dist/extensions/memory/context-manager/handlers/offload.d.ts +94 -0
  263. package/dist/extensions/memory/context-manager/handlers/offload.js +248 -0
  264. package/dist/extensions/memory/context-manager/handlers/rotation.d.ts +6 -0
  265. package/dist/extensions/memory/context-manager/handlers/rotation.js +304 -0
  266. package/dist/extensions/memory/context-manager/handlers/shared.d.ts +410 -0
  267. package/dist/extensions/memory/context-manager/handlers/shared.js +579 -0
  268. package/dist/extensions/memory/context-manager/handlers/tool-batch-boundary.d.ts +55 -0
  269. package/dist/extensions/memory/context-manager/handlers/tool-batch-boundary.js +190 -0
  270. package/dist/extensions/memory/context-manager/handlers/toolresult-capture-cap.d.ts +21 -0
  271. package/dist/extensions/memory/context-manager/handlers/toolresult-capture-cap.js +155 -0
  272. package/dist/extensions/memory/context-manager/handlers/tools/context-compress.d.ts +90 -0
  273. package/dist/extensions/memory/context-manager/handlers/tools/context-compress.js +1156 -0
  274. package/dist/extensions/memory/context-manager/handlers/tools/context-inspect.d.ts +16 -0
  275. package/dist/extensions/memory/context-manager/handlers/tools/context-inspect.js +276 -0
  276. package/dist/extensions/memory/context-manager/handlers/tools/context-navigate.d.ts +19 -0
  277. package/dist/extensions/memory/context-manager/handlers/tools/context-navigate.js +378 -0
  278. package/dist/extensions/memory/context-manager/handlers/tools/offload-recover.d.ts +13 -0
  279. package/dist/extensions/memory/context-manager/handlers/tools/offload-recover.js +181 -0
  280. package/dist/extensions/memory/context-manager/index.d.ts +3 -0
  281. package/dist/extensions/memory/context-manager/index.js +88 -0
  282. package/dist/extensions/memory/context-manager/pruning.d.ts +47 -0
  283. package/dist/extensions/memory/context-manager/pruning.js +406 -0
  284. package/dist/extensions/memory/context-manager/semantic-compress.d.ts +71 -0
  285. package/dist/extensions/memory/context-manager/semantic-compress.js +279 -0
  286. package/dist/extensions/memory/memory-agent-bridge/conflict-qa-tool.d.ts +20 -0
  287. package/dist/extensions/memory/memory-agent-bridge/conflict-qa-tool.js +71 -0
  288. package/dist/extensions/memory/memory-agent-bridge/explore-paths.d.ts +30 -0
  289. package/dist/extensions/memory/memory-agent-bridge/explore-paths.js +231 -0
  290. package/dist/extensions/memory/memory-agent-bridge/index.d.ts +28 -0
  291. package/dist/extensions/memory/memory-agent-bridge/index.js +124 -0
  292. package/dist/extensions/memory/memory-agent-bridge/memory-store-tool.d.ts +21 -0
  293. package/dist/extensions/memory/memory-agent-bridge/memory-store-tool.js +194 -0
  294. package/dist/extensions/memory/memory-agent-bridge/memory-tool.d.ts +22 -0
  295. package/dist/extensions/memory/memory-agent-bridge/memory-tool.js +548 -0
  296. package/dist/extensions/memory/scratchpad/format.d.ts +19 -0
  297. package/dist/extensions/memory/scratchpad/format.js +135 -0
  298. package/dist/extensions/memory/scratchpad/handlers.d.ts +53 -0
  299. package/dist/extensions/memory/scratchpad/handlers.js +469 -0
  300. package/dist/extensions/memory/scratchpad/index.d.ts +17 -0
  301. package/dist/extensions/memory/scratchpad/index.js +168 -0
  302. package/dist/extensions/memory/scratchpad/persistence.d.ts +46 -0
  303. package/dist/extensions/memory/scratchpad/persistence.js +343 -0
  304. package/dist/extensions/memory/scratchpad/types.d.ts +124 -0
  305. package/dist/extensions/memory/scratchpad/types.js +8 -0
  306. package/dist/extensions/memory/scratchpad/utils.d.ts +76 -0
  307. package/dist/extensions/memory/scratchpad/utils.js +236 -0
  308. package/dist/extensions/memory/session-recall/analyze.d.ts +58 -0
  309. package/dist/extensions/memory/session-recall/analyze.js +478 -0
  310. package/dist/extensions/memory/session-recall/context-aggregate.d.ts +117 -0
  311. package/dist/extensions/memory/session-recall/context-aggregate.js +315 -0
  312. package/dist/extensions/memory/session-recall/index.d.ts +29 -0
  313. package/dist/extensions/memory/session-recall/index.js +820 -0
  314. package/dist/extensions/memory/session-recall/query.d.ts +15 -0
  315. package/dist/extensions/memory/session-recall/query.js +38 -0
  316. package/dist/extensions/memory/session-recall/rank.d.ts +71 -0
  317. package/dist/extensions/memory/session-recall/rank.js +85 -0
  318. package/dist/extensions/memory/session-recall/search.d.ts +159 -0
  319. package/dist/extensions/memory/session-recall/search.js +682 -0
  320. package/dist/extensions/memory/session-recall/stats.d.ts +34 -0
  321. package/dist/extensions/memory/session-recall/stats.js +67 -0
  322. package/dist/extensions/memory/session-recall/text-utils.d.ts +82 -0
  323. package/dist/extensions/memory/session-recall/text-utils.js +184 -0
  324. package/dist/extensions/memory/three-memory-stores/episodes-disk.d.ts +43 -0
  325. package/dist/extensions/memory/three-memory-stores/episodes-disk.js +125 -0
  326. package/dist/extensions/memory/three-memory-stores/episodes.d.ts +46 -0
  327. package/dist/extensions/memory/three-memory-stores/episodes.js +299 -0
  328. package/dist/extensions/memory/three-memory-stores/handlers/whisper-recall.d.ts +25 -0
  329. package/dist/extensions/memory/three-memory-stores/handlers/whisper-recall.js +112 -0
  330. package/dist/extensions/memory/three-memory-stores/heuristics.d.ts +19 -0
  331. package/dist/extensions/memory/three-memory-stores/heuristics.js +89 -0
  332. package/dist/extensions/memory/three-memory-stores/index.d.ts +34 -0
  333. package/dist/extensions/memory/three-memory-stores/index.js +436 -0
  334. package/dist/extensions/memory/three-memory-stores/tool-reliability.d.ts +11 -0
  335. package/dist/extensions/memory/three-memory-stores/tool-reliability.js +38 -0
  336. package/dist/extensions/memory/three-memory-stores/types.d.ts +69 -0
  337. package/dist/extensions/memory/three-memory-stores/types.js +2 -0
  338. package/dist/extensions/memory/workspace-snapshot/index.d.ts +19 -0
  339. package/dist/extensions/memory/workspace-snapshot/index.js +363 -0
  340. package/dist/extensions/orchestrator/index.d.ts +19 -0
  341. package/dist/extensions/orchestrator/index.js +796 -0
  342. package/dist/extensions/scheduling/timer/fire-timing.d.ts +25 -0
  343. package/dist/extensions/scheduling/timer/fire-timing.js +28 -0
  344. package/dist/extensions/scheduling/timer/index.d.ts +102 -0
  345. package/dist/extensions/scheduling/timer/index.js +1143 -0
  346. package/dist/extensions/scheduling/timer/poller.d.ts +52 -0
  347. package/dist/extensions/scheduling/timer/poller.js +135 -0
  348. package/dist/extensions/scheduling/timer/recovery.d.ts +145 -0
  349. package/dist/extensions/scheduling/timer/recovery.js +445 -0
  350. package/dist/extensions/scheduling/timer/store-file.d.ts +38 -0
  351. package/dist/extensions/scheduling/timer/store-file.js +59 -0
  352. package/dist/extensions/scheduling/timer/timer-manager.d.ts +21 -0
  353. package/dist/extensions/scheduling/timer/timer-manager.js +143 -0
  354. package/dist/extensions/scheduling/timer/wake-retry.d.ts +455 -0
  355. package/dist/extensions/scheduling/timer/wake-retry.js +872 -0
  356. package/dist/extensions/self/auto-recovery/index.d.ts +20 -0
  357. package/dist/extensions/self/auto-recovery/index.js +89 -0
  358. package/dist/extensions/self/error-tracking/index.d.ts +3 -0
  359. package/dist/extensions/self/error-tracking/index.js +244 -0
  360. package/dist/extensions/self/health-maintenance/format.d.ts +3 -0
  361. package/dist/extensions/self/health-maintenance/format.js +60 -0
  362. package/dist/extensions/self/health-maintenance/handlers/session-health-tool.d.ts +23 -0
  363. package/dist/extensions/self/health-maintenance/handlers/session-health-tool.js +158 -0
  364. package/dist/extensions/self/health-maintenance/helpers.d.ts +25 -0
  365. package/dist/extensions/self/health-maintenance/helpers.js +67 -0
  366. package/dist/extensions/self/health-maintenance/index.d.ts +6 -0
  367. package/dist/extensions/self/health-maintenance/index.js +238 -0
  368. package/dist/extensions/self/health-maintenance/types.d.ts +14 -0
  369. package/dist/extensions/self/health-maintenance/types.js +2 -0
  370. package/dist/extensions/self/latent-activator/index.d.ts +12 -0
  371. package/dist/extensions/self/latent-activator/index.js +173 -0
  372. package/dist/extensions/self/latent-activator/mixes.d.ts +9 -0
  373. package/dist/extensions/self/latent-activator/mixes.js +20 -0
  374. package/dist/extensions/self/latent-activator/signals.d.ts +17 -0
  375. package/dist/extensions/self/latent-activator/signals.js +228 -0
  376. package/dist/extensions/self/latent-activator/state.d.ts +43 -0
  377. package/dist/extensions/self/latent-activator/state.js +59 -0
  378. package/dist/extensions/self/latent-activator/types.d.ts +8 -0
  379. package/dist/extensions/self/latent-activator/types.js +8 -0
  380. package/dist/extensions/self/watchdog/config.d.ts +4 -0
  381. package/dist/extensions/self/watchdog/config.js +79 -0
  382. package/dist/extensions/self/watchdog/engine.d.ts +256 -0
  383. package/dist/extensions/self/watchdog/engine.js +935 -0
  384. package/dist/extensions/self/watchdog/index.d.ts +23 -0
  385. package/dist/extensions/self/watchdog/index.js +485 -0
  386. package/dist/index.d.ts +25 -0
  387. package/dist/index.js +81 -0
  388. package/dist/lib/ai/consolidated-claim-critic.d.ts +84 -0
  389. package/dist/lib/ai/consolidated-claim-critic.js +191 -0
  390. package/dist/lib/ai/cost-report.d.ts +83 -0
  391. package/dist/lib/ai/cost-report.js +116 -0
  392. package/dist/lib/ai/critic-cache.d.ts +57 -0
  393. package/dist/lib/ai/critic-cache.js +100 -0
  394. package/dist/lib/ai/critic-fallbacks.d.ts +37 -0
  395. package/dist/lib/ai/critic-fallbacks.js +75 -0
  396. package/dist/lib/ai/critic-gate.d.ts +75 -0
  397. package/dist/lib/ai/critic-gate.js +81 -0
  398. package/dist/lib/ai/critic-helpers.d.ts +26 -0
  399. package/dist/lib/ai/critic-helpers.js +131 -0
  400. package/dist/lib/ai/critic-registry.d.ts +417 -0
  401. package/dist/lib/ai/critic-registry.js +639 -0
  402. package/dist/lib/ai/critic-stats.d.ts +78 -0
  403. package/dist/lib/ai/critic-stats.js +90 -0
  404. package/dist/lib/ai/judge-budget.d.ts +138 -0
  405. package/dist/lib/ai/judge-budget.js +143 -0
  406. package/dist/lib/ai/language-hint.d.ts +21 -0
  407. package/dist/lib/ai/language-hint.js +58 -0
  408. package/dist/lib/ai/llm-call.d.ts +141 -0
  409. package/dist/lib/ai/llm-call.js +745 -0
  410. package/dist/lib/ai/model-resolver.d.ts +90 -0
  411. package/dist/lib/ai/model-resolver.js +185 -0
  412. package/dist/lib/ai/models-init.d.ts +46 -0
  413. package/dist/lib/ai/models-init.js +65 -0
  414. package/dist/lib/ai/payload-hygiene.d.ts +74 -0
  415. package/dist/lib/ai/payload-hygiene.js +240 -0
  416. package/dist/lib/ai/post-loop-classify.d.ts +128 -0
  417. package/dist/lib/ai/post-loop-classify.js +87 -0
  418. package/dist/lib/ai/text-classifier.d.ts +142 -0
  419. package/dist/lib/ai/text-classifier.js +548 -0
  420. package/dist/lib/cognitive/hints.d.ts +33 -0
  421. package/dist/lib/cognitive/hints.js +223 -0
  422. package/dist/lib/cognitive/openspec.d.ts +29 -0
  423. package/dist/lib/cognitive/openspec.js +108 -0
  424. package/dist/lib/config/braid-paths.d.ts +188 -0
  425. package/dist/lib/config/braid-paths.js +340 -0
  426. package/dist/lib/config/braid-settings.d.ts +489 -0
  427. package/dist/lib/config/braid-settings.js +938 -0
  428. package/dist/lib/config/per-tool-settings.d.ts +95 -0
  429. package/dist/lib/config/per-tool-settings.js +161 -0
  430. package/dist/lib/config/session-profiles.d.ts +68 -0
  431. package/dist/lib/config/session-profiles.js +143 -0
  432. package/dist/lib/constants/injection-details.d.ts +30 -0
  433. package/dist/lib/constants/injection-details.js +30 -0
  434. package/dist/lib/constants/session-thresholds.d.ts +42 -0
  435. package/dist/lib/constants/session-thresholds.js +54 -0
  436. package/dist/lib/constants/tool-constants.d.ts +11 -0
  437. package/dist/lib/constants/tool-constants.js +12 -0
  438. package/dist/lib/core/event-names.d.ts +23 -0
  439. package/dist/lib/core/event-names.js +26 -0
  440. package/dist/lib/core/logger.d.ts +102 -0
  441. package/dist/lib/core/logger.js +274 -0
  442. package/dist/lib/detection/compression-strategy.d.ts +38 -0
  443. package/dist/lib/detection/compression-strategy.js +147 -0
  444. package/dist/lib/detection/consolidated-topic-critic.d.ts +51 -0
  445. package/dist/lib/detection/consolidated-topic-critic.js +132 -0
  446. package/dist/lib/detection/context-density.d.ts +70 -0
  447. package/dist/lib/detection/context-density.js +193 -0
  448. package/dist/lib/detection/context-thresholds.d.ts +88 -0
  449. package/dist/lib/detection/context-thresholds.js +107 -0
  450. package/dist/lib/detection/context-tiers.d.ts +80 -0
  451. package/dist/lib/detection/context-tiers.js +144 -0
  452. package/dist/lib/detection/context-usage.d.ts +75 -0
  453. package/dist/lib/detection/context-usage.js +209 -0
  454. package/dist/lib/detection/degradation-detector.d.ts +74 -0
  455. package/dist/lib/detection/degradation-detector.js +454 -0
  456. package/dist/lib/detection/test-burst.d.ts +77 -0
  457. package/dist/lib/detection/test-burst.js +126 -0
  458. package/dist/lib/detection/tool-loop-detector.d.ts +125 -0
  459. package/dist/lib/detection/tool-loop-detector.js +302 -0
  460. package/dist/lib/detection/topic-drift-detector.d.ts +80 -0
  461. package/dist/lib/detection/topic-drift-detector.js +252 -0
  462. package/dist/lib/enforcement/adherence-meter.d.ts +240 -0
  463. package/dist/lib/enforcement/adherence-meter.js +420 -0
  464. package/dist/lib/enforcement/turn-dedup.d.ts +106 -0
  465. package/dist/lib/enforcement/turn-dedup.js +195 -0
  466. package/dist/lib/errors/llm-error.d.ts +79 -0
  467. package/dist/lib/errors/llm-error.js +241 -0
  468. package/dist/lib/events/consolidation-channel.d.ts +109 -0
  469. package/dist/lib/events/consolidation-channel.js +374 -0
  470. package/dist/lib/events/consolidation-scoring.d.ts +59 -0
  471. package/dist/lib/events/consolidation-scoring.js +95 -0
  472. package/dist/lib/events/event-bus.d.ts +123 -0
  473. package/dist/lib/events/event-bus.js +108 -0
  474. package/dist/lib/events/event-types.d.ts +39 -0
  475. package/dist/lib/events/event-types.js +30 -0
  476. package/dist/lib/events/timer-bus.d.ts +21 -0
  477. package/dist/lib/events/timer-bus.js +41 -0
  478. package/dist/lib/events/timer-types.d.ts +64 -0
  479. package/dist/lib/events/timer-types.js +8 -0
  480. package/dist/lib/events/turn-end-coordinator.d.ts +52 -0
  481. package/dist/lib/events/turn-end-coordinator.js +89 -0
  482. package/dist/lib/harness/failure-trace-collector.d.ts +31 -0
  483. package/dist/lib/harness/failure-trace-collector.js +114 -0
  484. package/dist/lib/harness/index.d.ts +20 -0
  485. package/dist/lib/harness/index.js +21 -0
  486. package/dist/lib/harness/types.d.ts +85 -0
  487. package/dist/lib/harness/types.js +20 -0
  488. package/dist/lib/harness/weakness-miner.d.ts +29 -0
  489. package/dist/lib/harness/weakness-miner.js +165 -0
  490. package/dist/lib/memory/constants.d.ts +11 -0
  491. package/dist/lib/memory/constants.js +29 -0
  492. package/dist/lib/memory/index.d.ts +147 -0
  493. package/dist/lib/memory/index.js +564 -0
  494. package/dist/lib/memory/lifecycle.d.ts +50 -0
  495. package/dist/lib/memory/lifecycle.js +139 -0
  496. package/dist/lib/memory/past-insights.d.ts +35 -0
  497. package/dist/lib/memory/past-insights.js +189 -0
  498. package/dist/lib/memory/storage.d.ts +38 -0
  499. package/dist/lib/memory/storage.js +167 -0
  500. package/dist/lib/memory/store-lock.d.ts +23 -0
  501. package/dist/lib/memory/store-lock.js +69 -0
  502. package/dist/lib/memory/store-merge.d.ts +38 -0
  503. package/dist/lib/memory/store-merge.js +73 -0
  504. package/dist/lib/memory/types.d.ts +65 -0
  505. package/dist/lib/memory/types.js +5 -0
  506. package/dist/lib/memory/utils.d.ts +35 -0
  507. package/dist/lib/memory/utils.js +156 -0
  508. package/dist/lib/memory/write-log.d.ts +85 -0
  509. package/dist/lib/memory/write-log.js +124 -0
  510. package/dist/lib/memory/write-quality.d.ts +197 -0
  511. package/dist/lib/memory/write-quality.js +314 -0
  512. package/dist/lib/orchestrator/branch.d.ts +63 -0
  513. package/dist/lib/orchestrator/branch.js +192 -0
  514. package/dist/lib/orchestrator/index.d.ts +14 -0
  515. package/dist/lib/orchestrator/index.js +11 -0
  516. package/dist/lib/orchestrator/locks.d.ts +46 -0
  517. package/dist/lib/orchestrator/locks.js +122 -0
  518. package/dist/lib/orchestrator/slop-scanner.d.ts +31 -0
  519. package/dist/lib/orchestrator/slop-scanner.js +207 -0
  520. package/dist/lib/orchestrator/workers.d.ts +453 -0
  521. package/dist/lib/orchestrator/workers.js +1001 -0
  522. package/dist/lib/public.d.ts +18 -0
  523. package/dist/lib/public.js +23 -0
  524. package/dist/lib/reasoning/advice-tracker.d.ts +51 -0
  525. package/dist/lib/reasoning/advice-tracker.js +177 -0
  526. package/dist/lib/reasoning/belief-policy-engine.d.ts +48 -0
  527. package/dist/lib/reasoning/belief-policy-engine.js +268 -0
  528. package/dist/lib/reasoning/belief-types.d.ts +32 -0
  529. package/dist/lib/reasoning/belief-types.js +8 -0
  530. package/dist/lib/reasoning/classifier-offline.d.ts +72 -0
  531. package/dist/lib/reasoning/classifier-offline.js +75 -0
  532. package/dist/lib/reasoning/dreamer.d.ts +37 -0
  533. package/dist/lib/reasoning/dreamer.js +169 -0
  534. package/dist/lib/reasoning/nudge-analytics.d.ts +18 -0
  535. package/dist/lib/reasoning/nudge-analytics.js +62 -0
  536. package/dist/lib/reasoning/policy-rules.d.ts +18 -0
  537. package/dist/lib/reasoning/policy-rules.js +153 -0
  538. package/dist/lib/reasoning/reasoning-metrics.d.ts +42 -0
  539. package/dist/lib/reasoning/reasoning-metrics.js +174 -0
  540. package/dist/lib/reasoning/reasoning-summary.d.ts +34 -0
  541. package/dist/lib/reasoning/reasoning-summary.js +122 -0
  542. package/dist/lib/reasoning/tool-usage-analyzer.d.ts +50 -0
  543. package/dist/lib/reasoning/tool-usage-analyzer.js +188 -0
  544. package/dist/lib/state/async-storage.d.ts +52 -0
  545. package/dist/lib/state/async-storage.js +171 -0
  546. package/dist/lib/state/extension-state.d.ts +184 -0
  547. package/dist/lib/state/extension-state.js +373 -0
  548. package/dist/lib/state/global-state.d.ts +358 -0
  549. package/dist/lib/state/global-state.js +741 -0
  550. package/dist/lib/state/metacognitive-state.d.ts +21 -0
  551. package/dist/lib/state/metacognitive-state.js +50 -0
  552. package/dist/lib/state/session-manager.d.ts +32 -0
  553. package/dist/lib/state/session-manager.js +11 -0
  554. package/dist/lib/state/session-start-queue.d.ts +42 -0
  555. package/dist/lib/state/session-start-queue.js +105 -0
  556. package/dist/lib/state/state-checkpoint.d.ts +72 -0
  557. package/dist/lib/state/state-checkpoint.js +252 -0
  558. package/dist/lib/state/telegram-poller-liveness.d.ts +54 -0
  559. package/dist/lib/state/telegram-poller-liveness.js +67 -0
  560. package/dist/lib/state/tool-provenance.d.ts +22 -0
  561. package/dist/lib/state/tool-provenance.js +25 -0
  562. package/dist/lib/state/workspace-snapshot.d.ts +111 -0
  563. package/dist/lib/state/workspace-snapshot.js +372 -0
  564. package/dist/lib/store/belief-store.d.ts +112 -0
  565. package/dist/lib/store/belief-store.js +252 -0
  566. package/dist/lib/store/bidirectional-verifier.d.ts +87 -0
  567. package/dist/lib/store/bidirectional-verifier.js +242 -0
  568. package/dist/lib/store/claim-tracker.d.ts +66 -0
  569. package/dist/lib/store/claim-tracker.js +276 -0
  570. package/dist/lib/store/conflict-qa.d.ts +96 -0
  571. package/dist/lib/store/conflict-qa.js +283 -0
  572. package/dist/lib/store/evidence-pool.d.ts +185 -0
  573. package/dist/lib/store/evidence-pool.js +598 -0
  574. package/dist/lib/telemetry/context-heartbeat.d.ts +122 -0
  575. package/dist/lib/telemetry/context-heartbeat.js +449 -0
  576. package/dist/lib/telemetry/drift-signals.d.ts +46 -0
  577. package/dist/lib/telemetry/drift-signals.js +75 -0
  578. package/dist/lib/telemetry/rss-telemetry.d.ts +41 -0
  579. package/dist/lib/telemetry/rss-telemetry.js +53 -0
  580. package/dist/lib/types/episode-types.d.ts +31 -0
  581. package/dist/lib/types/episode-types.js +9 -0
  582. package/dist/lib/types/standard-result.d.ts +32 -0
  583. package/dist/lib/types/standard-result.js +22 -0
  584. package/dist/lib/utils/async-fs.d.ts +17 -0
  585. package/dist/lib/utils/async-fs.js +22 -0
  586. package/dist/lib/utils/bounded.d.ts +38 -0
  587. package/dist/lib/utils/bounded.js +59 -0
  588. package/dist/lib/utils/dedup.d.ts +40 -0
  589. package/dist/lib/utils/dedup.js +43 -0
  590. package/dist/lib/utils/error-guard.d.ts +15 -0
  591. package/dist/lib/utils/error-guard.js +22 -0
  592. package/dist/lib/utils/extension-utils.d.ts +36 -0
  593. package/dist/lib/utils/extension-utils.js +65 -0
  594. package/dist/lib/utils/extract-json.d.ts +23 -0
  595. package/dist/lib/utils/extract-json.js +90 -0
  596. package/dist/lib/utils/file-mutation-queue.d.ts +33 -0
  597. package/dist/lib/utils/file-mutation-queue.js +150 -0
  598. package/dist/lib/utils/filter-safe-to-remove.d.ts +26 -0
  599. package/dist/lib/utils/filter-safe-to-remove.js +256 -0
  600. package/dist/lib/utils/format-tool-result.d.ts +47 -0
  601. package/dist/lib/utils/format-tool-result.js +88 -0
  602. package/dist/lib/utils/id.d.ts +44 -0
  603. package/dist/lib/utils/id.js +59 -0
  604. package/dist/lib/utils/injection-tracker.d.ts +317 -0
  605. package/dist/lib/utils/injection-tracker.js +840 -0
  606. package/dist/lib/utils/local-time.d.ts +57 -0
  607. package/dist/lib/utils/local-time.js +181 -0
  608. package/dist/lib/utils/memory-fence.d.ts +55 -0
  609. package/dist/lib/utils/memory-fence.js +66 -0
  610. package/dist/lib/utils/sop-extractor.d.ts +75 -0
  611. package/dist/lib/utils/sop-extractor.js +259 -0
  612. package/dist/lib/utils/sop-suggestion.d.ts +34 -0
  613. package/dist/lib/utils/sop-suggestion.js +336 -0
  614. package/dist/lib/utils/wake-gate.d.ts +151 -0
  615. package/dist/lib/utils/wake-gate.js +265 -0
  616. package/dist/lib/utils/whisper-format.d.ts +95 -0
  617. package/dist/lib/utils/whisper-format.js +115 -0
  618. package/dist/lib/verification/coordination-checker.d.ts +72 -0
  619. package/dist/lib/verification/coordination-checker.js +126 -0
  620. package/dist/loader/api.d.ts +19 -0
  621. package/dist/loader/api.js +114 -0
  622. package/dist/loader/loader.d.ts +85 -0
  623. package/dist/loader/loader.js +534 -0
  624. package/docs/BEGINNERS.md +144 -0
  625. package/docs/COMPACTION-LOSS-INVESTIGATION.md +179 -0
  626. package/docs/CONTEXT-MAP.md +220 -0
  627. package/docs/CONTEXT-POLICY.md +86 -0
  628. package/docs/HISTORY.md +110 -0
  629. package/docs/LOCAL_DEV.md +246 -0
  630. package/docs/ROADMAP.md +107 -0
  631. package/docs/SETUP.md +459 -0
  632. package/package.json +97 -4
  633. package/skills/agent-testing/SKILL.md +214 -0
  634. package/skills/braid-reference/SKILL.md +88 -0
  635. package/skills/code-refactoring/SKILL.md +211 -0
  636. package/skills/code-search/SKILL.md +14 -0
  637. package/skills/documentation/SKILL.md +89 -0
  638. package/skills/dox/AGENTS.md.template +83 -0
  639. package/skills/dox/SKILL.md +86 -0
  640. package/skills/healthcheck/SKILL.md +65 -0
  641. package/skills/herdr-topology/SKILL.md +269 -0
  642. package/skills/meta-cognition/SKILL.md +24 -0
  643. package/skills/meta-improvement/SKILL.md +180 -0
  644. package/skills/misdirection-audit/SKILL.md +66 -0
  645. package/skills/pi-reference/SKILL.md +104 -0
  646. package/skills/placement-discipline/SKILL.md +69 -0
  647. package/skills/probe-evaluation/SKILL.md +85 -0
  648. package/skills/release-pipeline/SKILL.md +191 -0
  649. package/skills/research/SKILL.md +166 -0
  650. package/skills/skill-usage/SKILL.md +81 -0
  651. package/skills/software-engineer/SKILL.md +83 -0
  652. package/skills/subagent-orchestration/SKILL.md +454 -0
  653. package/skills/subagent-orchestration/scripts/workers.mjs +283 -0
  654. package/skills/subagent-verification/SKILL.md +127 -0
  655. package/skills/tone-quality/SKILL.md +176 -0
  656. package/skills/voice-replies/SKILL.md +125 -0
  657. package/src/AGENTS.md +111 -0
  658. package/src/extensions/cognitive/AGENTS.md +29 -0
  659. package/src/extensions/cognitive/mars-reflector/index.ts +415 -0
  660. package/src/extensions/cognitive/metacognition/handlers/AGENTS.md +30 -0
  661. package/src/extensions/cognitive/metacognition/handlers/claim-verification.ts +295 -0
  662. package/src/extensions/cognitive/metacognition/handlers/finalize.ts +648 -0
  663. package/src/extensions/cognitive/metacognition/handlers/hypothesize.ts +368 -0
  664. package/src/extensions/cognitive/metacognition/handlers/scoring.ts +242 -0
  665. package/src/extensions/cognitive/metacognition/handlers/think-budget.ts +199 -0
  666. package/src/extensions/cognitive/metacognition/handlers/think.ts +489 -0
  667. package/src/extensions/cognitive/metacognition/handlers/verify.ts +440 -0
  668. package/src/extensions/cognitive/metacognition/index.ts +109 -0
  669. package/src/extensions/cognitive/reasoning/index.ts +168 -0
  670. package/src/extensions/cognitive/sycophancy-detector/index.ts +286 -0
  671. package/src/extensions/cognitive/topic-drift/index.ts +429 -0
  672. package/src/extensions/cognitive/turn-outcome/index.ts +209 -0
  673. package/src/extensions/context-management/README.md +102 -0
  674. package/src/extensions/context-management/index.ts +383 -0
  675. package/src/extensions/core/AGENTS.md +34 -0
  676. package/src/extensions/core/agent-environment/index.ts +135 -0
  677. package/src/extensions/core/polyfill/index.ts +617 -0
  678. package/src/extensions/core/prompt-builder/AGENTS.md +151 -0
  679. package/src/extensions/core/prompt-builder/awareness-whisper.ts +162 -0
  680. package/src/extensions/core/prompt-builder/context-section.ts +120 -0
  681. package/src/extensions/core/prompt-builder/custom-sections.ts +27 -0
  682. package/src/extensions/core/prompt-builder/external-tool-guidelines.ts +41 -0
  683. package/src/extensions/core/prompt-builder/identity.ts +98 -0
  684. package/src/extensions/core/prompt-builder/index.ts +602 -0
  685. package/src/extensions/core/prompt-builder/inspect.ts +227 -0
  686. package/src/extensions/core/prompt-builder/instance-composition.ts +515 -0
  687. package/src/extensions/core/prompt-builder/memory-section.ts +76 -0
  688. package/src/extensions/core/prompt-builder/pi-reference-section.ts +26 -0
  689. package/src/extensions/core/prompt-builder/project-docs-section.ts +105 -0
  690. package/src/extensions/core/prompt-builder/section-parity.ts +108 -0
  691. package/src/extensions/core/prompt-builder/section-publish.ts +43 -0
  692. package/src/extensions/core/prompt-builder/section.ts +150 -0
  693. package/src/extensions/core/prompt-builder/surface-discipline-section.ts +21 -0
  694. package/src/extensions/core/prompt-builder/system-info-tool.ts +87 -0
  695. package/src/extensions/core/prompt-builder/tool-description-trim.ts +127 -0
  696. package/src/extensions/core/prompt-builder/tool-guidelines.ts +226 -0
  697. package/src/extensions/core/prompt-builder/tool-pipelines.ts +78 -0
  698. package/src/extensions/core/prompt-builder/top-level-extensions.ts +338 -0
  699. package/src/extensions/core/skills-tool/auto-inject.ts +1004 -0
  700. package/src/extensions/core/skills-tool/index.ts +240 -0
  701. package/src/extensions/core/skills-tool/loading-guidance.ts +89 -0
  702. package/src/extensions/core/skills-tool/session-records.ts +328 -0
  703. package/src/extensions/core/skills-tool/skill-triggers.ts +119 -0
  704. package/src/extensions/enforcement/AGENTS.md +69 -0
  705. package/src/extensions/enforcement/detection/malformed.ts +42 -0
  706. package/src/extensions/enforcement/detection/verification.ts +52 -0
  707. package/src/extensions/enforcement/enforcement-types.ts +42 -0
  708. package/src/extensions/enforcement/handler-registry.ts +225 -0
  709. package/src/extensions/enforcement/handlers/AGENTS.md +68 -0
  710. package/src/extensions/enforcement/handlers/analysis/AGENTS.md +40 -0
  711. package/src/extensions/enforcement/handlers/analysis/bpe-handler.ts +53 -0
  712. package/src/extensions/enforcement/handlers/analysis/dreamer-handler.ts +73 -0
  713. package/src/extensions/enforcement/handlers/analysis/drift-handler.ts +100 -0
  714. package/src/extensions/enforcement/handlers/analysis/feedback-handler.ts +22 -0
  715. package/src/extensions/enforcement/handlers/analysis/mars-handler.ts +121 -0
  716. package/src/extensions/enforcement/handlers/analysis/reflection-handler.ts +22 -0
  717. package/src/extensions/enforcement/handlers/blocking.ts +50 -0
  718. package/src/extensions/enforcement/handlers/message-analysis.ts +95 -0
  719. package/src/extensions/enforcement/handlers/orphan-chains.ts +53 -0
  720. package/src/extensions/enforcement/handlers/over-correction-gate.ts +634 -0
  721. package/src/extensions/enforcement/handlers/probe-handler.ts +133 -0
  722. package/src/extensions/enforcement/handlers/register-adherence-meter.ts +216 -0
  723. package/src/extensions/enforcement/handlers/register-agent-end-api-error.ts +82 -0
  724. package/src/extensions/enforcement/handlers/register-input-handler.ts +36 -0
  725. package/src/extensions/enforcement/handlers/register-message-end.ts +477 -0
  726. package/src/extensions/enforcement/handlers/register-post-cycle-hygiene.ts +166 -0
  727. package/src/extensions/enforcement/handlers/register-session-compact.ts +248 -0
  728. package/src/extensions/enforcement/handlers/register-session-shutdown-resumption.ts +138 -0
  729. package/src/extensions/enforcement/handlers/register-session-shutdown.ts +46 -0
  730. package/src/extensions/enforcement/handlers/register-session-start-discoverability.ts +270 -0
  731. package/src/extensions/enforcement/handlers/register-session-start.ts +240 -0
  732. package/src/extensions/enforcement/handlers/register-tool-call.ts +160 -0
  733. package/src/extensions/enforcement/handlers/register-tool-result-formatting.ts +73 -0
  734. package/src/extensions/enforcement/handlers/register-tool-result.ts +108 -0
  735. package/src/extensions/enforcement/handlers/register-turn-end-hygiene.ts +456 -0
  736. package/src/extensions/enforcement/handlers/routing-handler.ts +191 -0
  737. package/src/extensions/enforcement/handlers/tool-tracker.ts +145 -0
  738. package/src/extensions/enforcement/handlers/turn-analysis.ts +156 -0
  739. package/src/extensions/enforcement/handlers/turn-end-handler.ts +538 -0
  740. package/src/extensions/enforcement/index.ts +28 -0
  741. package/src/extensions/enforcement/judge-utils.ts +106 -0
  742. package/src/extensions/enforcement/nudge-manager.ts +298 -0
  743. package/src/extensions/enforcement/self-state-claims.ts +204 -0
  744. package/src/extensions/enforcement/session-health.ts +317 -0
  745. package/src/extensions/enforcement/signals.ts +88 -0
  746. package/src/extensions/enforcement/similarity.ts +76 -0
  747. package/src/extensions/enforcement/state.ts +115 -0
  748. package/src/extensions/enforcement/substate/context-hygiene-state.ts +212 -0
  749. package/src/extensions/enforcement/substate/error-tracking-state.ts +50 -0
  750. package/src/extensions/enforcement/substate/memory-hygiene-state.ts +54 -0
  751. package/src/extensions/enforcement/substate/session-state.ts +79 -0
  752. package/src/extensions/enforcement/substate/thought-chain-state.ts +62 -0
  753. package/src/extensions/enforcement/substate/tool-tracking-state.ts +166 -0
  754. package/src/extensions/enforcement/substate/verification-judge-state.ts +52 -0
  755. package/src/extensions/enforcement/task-evidence.ts +436 -0
  756. package/src/extensions/enforcement/types.ts +38 -0
  757. package/src/extensions/enforcement/validation.ts +194 -0
  758. package/src/extensions/enforcement/verification-judge.ts +317 -0
  759. package/src/extensions/enforcement/whisper.ts +120 -0
  760. package/src/extensions/heartbeat/AGENTS.md +47 -0
  761. package/src/extensions/heartbeat/analytics/AGENTS.md +57 -0
  762. package/src/extensions/heartbeat/analytics/ab-variant.ts +106 -0
  763. package/src/extensions/heartbeat/analytics/core.ts +222 -0
  764. package/src/extensions/heartbeat/analytics/format.ts +144 -0
  765. package/src/extensions/heartbeat/analytics/index.ts +373 -0
  766. package/src/extensions/heartbeat/analytics/shared.ts +149 -0
  767. package/src/extensions/heartbeat/heartbeat-scheduler/AGENTS.md +84 -0
  768. package/src/extensions/heartbeat/heartbeat-scheduler/index.ts +1095 -0
  769. package/src/extensions/heartbeat/heartbeat-scheduler/meta-learning.ts +75 -0
  770. package/src/extensions/heartbeat/heartbeat-scheduler/modules/behavioral-drift.ts +200 -0
  771. package/src/extensions/heartbeat/heartbeat-scheduler/modules/budget.ts +113 -0
  772. package/src/extensions/heartbeat/heartbeat-scheduler/modules/context-hygiene.ts +288 -0
  773. package/src/extensions/heartbeat/heartbeat-scheduler/modules/evolver.ts +88 -0
  774. package/src/extensions/heartbeat/heartbeat-scheduler/modules/measurement.ts +47 -0
  775. package/src/extensions/heartbeat/heartbeat-scheduler/modules/recaller.ts +99 -0
  776. package/src/extensions/heartbeat/heartbeat-scheduler/modules/reflection-consolidator.ts +114 -0
  777. package/src/extensions/heartbeat/heartbeat-scheduler/policies.ts +193 -0
  778. package/src/extensions/heartbeat/heartbeat-scheduler/state.ts +88 -0
  779. package/src/extensions/heartbeat/heartbeat-scheduler/types.ts +128 -0
  780. package/src/extensions/heartbeat/heartbeat-scheduler/whisper-batcher.ts +98 -0
  781. package/src/extensions/manifest.ts +293 -0
  782. package/src/extensions/memory/AGENTS.md +93 -0
  783. package/src/extensions/memory/context-lifecycle/AGENTS.md +62 -0
  784. package/src/extensions/memory/context-lifecycle/helpers.ts +167 -0
  785. package/src/extensions/memory/context-lifecycle/index.ts +1232 -0
  786. package/src/extensions/memory/context-lifecycle/policy-engine.ts +287 -0
  787. package/src/extensions/memory/context-lifecycle/signal-detector.ts +293 -0
  788. package/src/extensions/memory/context-lifecycle/state.ts +165 -0
  789. package/src/extensions/memory/context-lifecycle/types.ts +441 -0
  790. package/src/extensions/memory/context-manager/analysis.ts +344 -0
  791. package/src/extensions/memory/context-manager/handlers/AGENTS.md +37 -0
  792. package/src/extensions/memory/context-manager/handlers/compaction-chunked.ts +800 -0
  793. package/src/extensions/memory/context-manager/handlers/compaction-retry.ts +556 -0
  794. package/src/extensions/memory/context-manager/handlers/compaction-trace.ts +243 -0
  795. package/src/extensions/memory/context-manager/handlers/compaction-watchdog.ts +366 -0
  796. package/src/extensions/memory/context-manager/handlers/compaction.ts +2552 -0
  797. package/src/extensions/memory/context-manager/handlers/context-emergency.ts +470 -0
  798. package/src/extensions/memory/context-manager/handlers/events.ts +430 -0
  799. package/src/extensions/memory/context-manager/handlers/navigation.ts +94 -0
  800. package/src/extensions/memory/context-manager/handlers/offload.ts +330 -0
  801. package/src/extensions/memory/context-manager/handlers/rotation.ts +363 -0
  802. package/src/extensions/memory/context-manager/handlers/shared.ts +961 -0
  803. package/src/extensions/memory/context-manager/handlers/tool-batch-boundary.ts +219 -0
  804. package/src/extensions/memory/context-manager/handlers/toolresult-capture-cap.ts +176 -0
  805. package/src/extensions/memory/context-manager/handlers/tools/context-compress.ts +1333 -0
  806. package/src/extensions/memory/context-manager/handlers/tools/context-inspect.ts +343 -0
  807. package/src/extensions/memory/context-manager/handlers/tools/context-navigate.ts +423 -0
  808. package/src/extensions/memory/context-manager/handlers/tools/offload-recover.ts +234 -0
  809. package/src/extensions/memory/context-manager/index.ts +111 -0
  810. package/src/extensions/memory/context-manager/pruning.ts +479 -0
  811. package/src/extensions/memory/context-manager/semantic-compress.ts +321 -0
  812. package/src/extensions/memory/memory-agent-bridge/AGENTS.md +62 -0
  813. package/src/extensions/memory/memory-agent-bridge/conflict-qa-tool.ts +106 -0
  814. package/src/extensions/memory/memory-agent-bridge/explore-paths.ts +283 -0
  815. package/src/extensions/memory/memory-agent-bridge/index.ts +163 -0
  816. package/src/extensions/memory/memory-agent-bridge/memory-store-tool.ts +284 -0
  817. package/src/extensions/memory/memory-agent-bridge/memory-tool.ts +746 -0
  818. package/src/extensions/memory/scratchpad/AGENTS.md +148 -0
  819. package/src/extensions/memory/scratchpad/format.ts +161 -0
  820. package/src/extensions/memory/scratchpad/handlers.ts +601 -0
  821. package/src/extensions/memory/scratchpad/index.ts +230 -0
  822. package/src/extensions/memory/scratchpad/persistence.ts +374 -0
  823. package/src/extensions/memory/scratchpad/types.ts +149 -0
  824. package/src/extensions/memory/scratchpad/utils.ts +268 -0
  825. package/src/extensions/memory/session-recall/AGENTS.md +104 -0
  826. package/src/extensions/memory/session-recall/analyze.ts +605 -0
  827. package/src/extensions/memory/session-recall/context-aggregate.ts +381 -0
  828. package/src/extensions/memory/session-recall/index.ts +956 -0
  829. package/src/extensions/memory/session-recall/query.ts +44 -0
  830. package/src/extensions/memory/session-recall/rank.ts +121 -0
  831. package/src/extensions/memory/session-recall/search.ts +801 -0
  832. package/src/extensions/memory/session-recall/stats.ts +93 -0
  833. package/src/extensions/memory/session-recall/text-utils.ts +209 -0
  834. package/src/extensions/memory/three-memory-stores/AGENTS.md +66 -0
  835. package/src/extensions/memory/three-memory-stores/episodes-disk.ts +138 -0
  836. package/src/extensions/memory/three-memory-stores/episodes.ts +371 -0
  837. package/src/extensions/memory/three-memory-stores/handlers/whisper-recall.ts +132 -0
  838. package/src/extensions/memory/three-memory-stores/heuristics.ts +109 -0
  839. package/src/extensions/memory/three-memory-stores/index.ts +549 -0
  840. package/src/extensions/memory/three-memory-stores/tool-reliability.ts +58 -0
  841. package/src/extensions/memory/three-memory-stores/types.ts +74 -0
  842. package/src/extensions/memory/workspace-snapshot/AGENTS.md +19 -0
  843. package/src/extensions/memory/workspace-snapshot/index.ts +455 -0
  844. package/src/extensions/orchestrator/index.ts +1141 -0
  845. package/src/extensions/scheduling/AGENTS.md +26 -0
  846. package/src/extensions/scheduling/timer/AGENTS.md +259 -0
  847. package/src/extensions/scheduling/timer/fire-timing.ts +46 -0
  848. package/src/extensions/scheduling/timer/index.ts +1331 -0
  849. package/src/extensions/scheduling/timer/poller.ts +138 -0
  850. package/src/extensions/scheduling/timer/recovery.ts +462 -0
  851. package/src/extensions/scheduling/timer/store-file.ts +59 -0
  852. package/src/extensions/scheduling/timer/timer-manager.ts +161 -0
  853. package/src/extensions/scheduling/timer/wake-retry.ts +1057 -0
  854. package/src/extensions/self/AGENTS.md +30 -0
  855. package/src/extensions/self/auto-recovery/index.ts +112 -0
  856. package/src/extensions/self/error-tracking/AGENTS.md +38 -0
  857. package/src/extensions/self/error-tracking/index.ts +299 -0
  858. package/src/extensions/self/health-maintenance/AGENTS.md +42 -0
  859. package/src/extensions/self/health-maintenance/format.ts +87 -0
  860. package/src/extensions/self/health-maintenance/handlers/session-health-tool.ts +182 -0
  861. package/src/extensions/self/health-maintenance/helpers.ts +78 -0
  862. package/src/extensions/self/health-maintenance/index.ts +308 -0
  863. package/src/extensions/self/health-maintenance/types.ts +14 -0
  864. package/src/extensions/self/latent-activator/AGENTS.md +64 -0
  865. package/src/extensions/self/latent-activator/index.ts +206 -0
  866. package/src/extensions/self/latent-activator/mixes.ts +22 -0
  867. package/src/extensions/self/latent-activator/signals.ts +237 -0
  868. package/src/extensions/self/latent-activator/state.ts +79 -0
  869. package/src/extensions/self/latent-activator/types.ts +47 -0
  870. package/src/extensions/self/watchdog/AGENTS.md +27 -0
  871. package/src/extensions/self/watchdog/config.ts +73 -0
  872. package/src/extensions/self/watchdog/engine.ts +1246 -0
  873. package/src/extensions/self/watchdog/index.ts +577 -0
  874. package/src/index.ts +93 -0
  875. package/src/lib/AGENTS.md +39 -0
  876. package/src/lib/ai/AGENTS.md +37 -0
  877. package/src/lib/ai/consolidated-claim-critic.ts +287 -0
  878. package/src/lib/ai/cost-report.ts +206 -0
  879. package/src/lib/ai/critic-cache.ts +122 -0
  880. package/src/lib/ai/critic-fallbacks.ts +74 -0
  881. package/src/lib/ai/critic-gate.ts +135 -0
  882. package/src/lib/ai/critic-helpers.ts +135 -0
  883. package/src/lib/ai/critic-registry.ts +754 -0
  884. package/src/lib/ai/critic-stats.ts +158 -0
  885. package/src/lib/ai/judge-budget.ts +241 -0
  886. package/src/lib/ai/language-hint.ts +70 -0
  887. package/src/lib/ai/llm-call.ts +975 -0
  888. package/src/lib/ai/model-resolver.ts +224 -0
  889. package/src/lib/ai/models-init.ts +68 -0
  890. package/src/lib/ai/payload-hygiene.ts +265 -0
  891. package/src/lib/ai/post-loop-classify.ts +185 -0
  892. package/src/lib/ai/text-classifier.ts +746 -0
  893. package/src/lib/cognitive/AGENTS.md +40 -0
  894. package/src/lib/cognitive/hints.ts +254 -0
  895. package/src/lib/cognitive/openspec.ts +124 -0
  896. package/src/lib/config/AGENTS.md +17 -0
  897. package/src/lib/config/braid-paths.ts +401 -0
  898. package/src/lib/config/braid-settings.ts +1442 -0
  899. package/src/lib/config/per-tool-settings.ts +197 -0
  900. package/src/lib/config/session-profiles.ts +165 -0
  901. package/src/lib/constants/AGENTS.md +15 -0
  902. package/src/lib/constants/injection-details.ts +32 -0
  903. package/src/lib/constants/session-thresholds.ts +64 -0
  904. package/src/lib/constants/tool-constants.ts +16 -0
  905. package/src/lib/core/AGENTS.md +23 -0
  906. package/src/lib/core/event-names.ts +31 -0
  907. package/src/lib/core/logger.ts +334 -0
  908. package/src/lib/detection/AGENTS.md +21 -0
  909. package/src/lib/detection/compression-strategy.ts +183 -0
  910. package/src/lib/detection/consolidated-topic-critic.ts +188 -0
  911. package/src/lib/detection/context-density.ts +237 -0
  912. package/src/lib/detection/context-thresholds.ts +132 -0
  913. package/src/lib/detection/context-tiers.ts +201 -0
  914. package/src/lib/detection/context-usage.ts +270 -0
  915. package/src/lib/detection/degradation-detector.ts +583 -0
  916. package/src/lib/detection/test-burst.ts +170 -0
  917. package/src/lib/detection/tool-loop-detector.ts +364 -0
  918. package/src/lib/detection/topic-drift-detector.ts +323 -0
  919. package/src/lib/enforcement/AGENTS.md +20 -0
  920. package/src/lib/enforcement/adherence-meter.ts +578 -0
  921. package/src/lib/enforcement/turn-dedup.ts +246 -0
  922. package/src/lib/errors/llm-error.ts +288 -0
  923. package/src/lib/events/AGENTS.md +23 -0
  924. package/src/lib/events/consolidation-channel.ts +493 -0
  925. package/src/lib/events/consolidation-scoring.ts +112 -0
  926. package/src/lib/events/event-bus.ts +213 -0
  927. package/src/lib/events/event-types.ts +53 -0
  928. package/src/lib/events/timer-bus.ts +53 -0
  929. package/src/lib/events/timer-types.ts +64 -0
  930. package/src/lib/events/turn-end-coordinator.ts +108 -0
  931. package/src/lib/harness/AGENTS.md +20 -0
  932. package/src/lib/harness/failure-trace-collector.ts +157 -0
  933. package/src/lib/harness/index.ts +41 -0
  934. package/src/lib/harness/types.ts +122 -0
  935. package/src/lib/harness/weakness-miner.ts +209 -0
  936. package/src/lib/memory/AGENTS.md +36 -0
  937. package/src/lib/memory/constants.ts +34 -0
  938. package/src/lib/memory/index.ts +705 -0
  939. package/src/lib/memory/lifecycle.ts +159 -0
  940. package/src/lib/memory/past-insights.ts +221 -0
  941. package/src/lib/memory/storage.ts +187 -0
  942. package/src/lib/memory/store-lock.ts +70 -0
  943. package/src/lib/memory/store-merge.ts +100 -0
  944. package/src/lib/memory/types.ts +82 -0
  945. package/src/lib/memory/utils.ts +173 -0
  946. package/src/lib/memory/write-log.ts +174 -0
  947. package/src/lib/memory/write-quality.ts +383 -0
  948. package/src/lib/orchestrator/branch.ts +193 -0
  949. package/src/lib/orchestrator/index.ts +78 -0
  950. package/src/lib/orchestrator/locks.ts +160 -0
  951. package/src/lib/orchestrator/slop-scanner.ts +258 -0
  952. package/src/lib/orchestrator/workers.ts +1382 -0
  953. package/src/lib/public.ts +43 -0
  954. package/src/lib/reasoning/AGENTS.md +25 -0
  955. package/src/lib/reasoning/advice-tracker.ts +244 -0
  956. package/src/lib/reasoning/belief-policy-engine.ts +342 -0
  957. package/src/lib/reasoning/belief-types.ts +45 -0
  958. package/src/lib/reasoning/classifier-offline.ts +111 -0
  959. package/src/lib/reasoning/dreamer.ts +215 -0
  960. package/src/lib/reasoning/nudge-analytics.ts +85 -0
  961. package/src/lib/reasoning/policy-rules.ts +172 -0
  962. package/src/lib/reasoning/reasoning-metrics.ts +202 -0
  963. package/src/lib/reasoning/reasoning-summary.ts +154 -0
  964. package/src/lib/reasoning/tool-usage-analyzer.ts +248 -0
  965. package/src/lib/state/AGENTS.md +192 -0
  966. package/src/lib/state/async-storage.ts +189 -0
  967. package/src/lib/state/extension-state.ts +419 -0
  968. package/src/lib/state/global-state.ts +1046 -0
  969. package/src/lib/state/metacognitive-state.ts +65 -0
  970. package/src/lib/state/session-manager.ts +43 -0
  971. package/src/lib/state/session-start-queue.ts +135 -0
  972. package/src/lib/state/state-checkpoint.ts +352 -0
  973. package/src/lib/state/telegram-poller-liveness.ts +75 -0
  974. package/src/lib/state/tool-provenance.ts +26 -0
  975. package/src/lib/state/workspace-snapshot.ts +466 -0
  976. package/src/lib/store/AGENTS.md +24 -0
  977. package/src/lib/store/belief-store.ts +325 -0
  978. package/src/lib/store/bidirectional-verifier.ts +316 -0
  979. package/src/lib/store/claim-tracker.ts +382 -0
  980. package/src/lib/store/conflict-qa.ts +385 -0
  981. package/src/lib/store/evidence-pool.ts +779 -0
  982. package/src/lib/telemetry/AGENTS.md +28 -0
  983. package/src/lib/telemetry/context-heartbeat.ts +555 -0
  984. package/src/lib/telemetry/drift-signals.ts +105 -0
  985. package/src/lib/telemetry/rss-telemetry.ts +57 -0
  986. package/src/lib/types/AGENTS.md +21 -0
  987. package/src/lib/types/episode-types.ts +31 -0
  988. package/src/lib/types/standard-result.ts +40 -0
  989. package/src/lib/utils/AGENTS.md +30 -0
  990. package/src/lib/utils/async-fs.ts +23 -0
  991. package/src/lib/utils/bounded.ts +58 -0
  992. package/src/lib/utils/dedup.ts +44 -0
  993. package/src/lib/utils/error-guard.ts +27 -0
  994. package/src/lib/utils/extension-utils.ts +72 -0
  995. package/src/lib/utils/extract-json.ts +89 -0
  996. package/src/lib/utils/file-mutation-queue.ts +172 -0
  997. package/src/lib/utils/filter-safe-to-remove.ts +301 -0
  998. package/src/lib/utils/format-tool-result.ts +109 -0
  999. package/src/lib/utils/id.ts +64 -0
  1000. package/src/lib/utils/injection-tracker.ts +1014 -0
  1001. package/src/lib/utils/local-time.ts +196 -0
  1002. package/src/lib/utils/memory-fence.ts +70 -0
  1003. package/src/lib/utils/sop-extractor.ts +329 -0
  1004. package/src/lib/utils/sop-suggestion.ts +426 -0
  1005. package/src/lib/utils/wake-gate.ts +318 -0
  1006. package/src/lib/utils/whisper-format.ts +120 -0
  1007. package/src/lib/verification/coordination-checker.ts +183 -0
  1008. package/src/loader/AGENTS.md +32 -0
  1009. package/src/loader/api.ts +138 -0
  1010. package/src/loader/loader.ts +600 -0
  1011. package/src/types/extension-context.d.ts +85 -0
@@ -0,0 +1,2552 @@
1
+ // Compaction handler: session_before_compact, session_compact (parking +
2
+ // outcome stages), session_compact_failed, and retry logic. pi-core 0.85.1
3
+ // has no `compaction_end` extension event - the cycle's outcome stages are
4
+ // wired to the events pi-core actually fires. This is the core of context
5
+ // management - compaction quality directly affects agent performance on long
6
+ // sessions.
7
+
8
+ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
9
+ import type { SessionManager } from "../../../../lib/state/session-manager.js";
10
+
11
+ // Minimal typed interface for pi APIs that lack type declarations
12
+ interface FullSessionManager extends SessionManager {
13
+ appendMessage(msg: unknown): string;
14
+ getSessionId(): string;
15
+ /** Flush tracking for compaction dedup */
16
+ flushed?: boolean;
17
+ /** File entries from session for diagnostics */
18
+ fileEntries?: unknown[];
19
+ }
20
+ interface Preparation {
21
+ messagesToSummarize?: unknown[];
22
+ }
23
+ import { addEvidence } from "../../../../lib/store/evidence-pool.js";
24
+ import { eventBus } from "../../../../lib/events/event-bus.js";
25
+ import { recordAdvice } from "../../../../lib/reasoning/advice-tracker.js";
26
+ import { appendFileSync, mkdirSync } from "node:fs";
27
+ import { dirname, join } from "node:path";
28
+ import { createHash } from "node:crypto";
29
+ import { analyzeSession } from "../analysis.js";
30
+ import {
31
+ getSessionIdSafe,
32
+ getLeafIdSafe,
33
+ getExtensionState,
34
+ getFullSessionManager,
35
+ } from "../../../../lib/state/extension-state.js";
36
+ import {
37
+ log,
38
+ getCmState,
39
+ isTransientCompactionError,
40
+ isContextWindowError,
41
+ isCompactionActive,
42
+ setCompactionActive,
43
+ recordCompactionOutcome,
44
+ recordCompactionHealth,
45
+ compactionRetryState,
46
+ overflowRetryState,
47
+ noteCompactionNoProgress,
48
+ clearCompactionFailsafe,
49
+ armCompactionFailsafeCut,
50
+ consumeCompactionFailsafeCut,
51
+ settleCompactionRetry,
52
+ settleOverflowRetry,
53
+ resetCompactionRetry,
54
+ resetOverflowRetry,
55
+ COMPACTION_NO_PROGRESS_LIMIT,
56
+ } from "./shared.js";
57
+ import { snapBoundaryOutsideToolBatch } from "./tool-batch-boundary.js";
58
+ import type { AgentMessage as CoreAgentMessage } from "@earendil-works/pi-agent-core";
59
+ import type { ThinkingLevel } from "@earendil-works/pi-ai";
60
+ import type { AgentMessage as FilterMessage } from "../../../../lib/utils/filter-safe-to-remove.js";
61
+ import { filterSafeToRemove } from "../../../../lib/utils/filter-safe-to-remove.js";
62
+ import { determineCompressionLevel } from "../../../../lib/detection/compression-strategy.js";
63
+ import {
64
+ CONTEXT_COMPACT_REFUSE_PERCENT,
65
+ USAGE_WHISPER_CRITICAL,
66
+ } from "../../../../lib/detection/context-thresholds.js";
67
+ import { estimateMessagesTokens, resolveWindow } from "../../../../lib/detection/context-usage.js";
68
+ import { semanticCompress } from "../semantic-compress.js";
69
+ import { onEvent } from "../../../../lib/events/event-types.js";
70
+ import {
71
+ SESSION_SHUTDOWN,
72
+ SESSION_COMPACT,
73
+ SESSION_COMPACT_FAILED,
74
+ SESSION_BEFORE_COMPACT,
75
+ MESSAGE_END,
76
+ AGENT_SETTLED,
77
+ INPUT,
78
+ } from "../../../../lib/core/event-names.js";
79
+ import {
80
+ handleOverflowFailure,
81
+ handleTransientError,
82
+ handleContextWindowError,
83
+ handleThresholdFailure,
84
+ handleSummaryCapFailure,
85
+ triggerFailsafeCompaction,
86
+ } from "./compaction-retry.js";
87
+ import {
88
+ COMPACTION_STALL_THRESHOLD_MS,
89
+ armCompactionWatchdog,
90
+ clearCompactionWatchdog,
91
+ getCompactionWatchdogArmedAt,
92
+ handleSummaryCapAbort,
93
+ } from "./compaction-watchdog.js";
94
+ import {
95
+ classifyCompactionFailure,
96
+ countSpanMessages,
97
+ writeCompactionTrace,
98
+ } from "./compaction-trace.js";
99
+ import { summarizeSpanInChunks } from "./compaction-chunked.js";
100
+ import { trackInjection } from "../../../../lib/utils/injection-tracker.js";
101
+
102
+ // Deduplication Guard
103
+ // NOTE: registerTurnEndRetryReset is registered in compaction-retry.ts and
104
+ // wired from index.ts. Test checks it's mentioned here.
105
+ // session_before_compact fires from TWO call sites in pi core:
106
+ // (1) compact() - manual /pi compact command
107
+ // (2) _runAutoCompaction() - auto-compaction triggered by context pressure
108
+ // Without a guard, our handler fires twice per compaction cycle.
109
+ const MAX_PROCESSED_COMPACTS = 200;
110
+ const _processedCompacts = new Map<string, number>();
111
+
112
+ /**
113
+ * Cooldown window for the dedup guard. A later compaction cycle on the same
114
+ * session+leaf that begins AFTER this window — or once compaction is no longer
115
+ * in-flight — is NOT a duplicate; it must run. The guard only ever blocks the
116
+ * in-cycle double-fire from pi-core's two call sites (compact() + _runAutoCompaction()).
117
+ */
118
+ const COMPACT_COOLDOWN_MS = 20000;
119
+
120
+ // Summarizer thinking-off switch: pi-core forwards the session thinking level
121
+ // into its own summarization call
122
+ // (agent-session.js:1844 -> compaction.js createSummarizationOptions), and
123
+ // effort-based providers bill reasoning inside max_tokens — the same budget
124
+ // the summary needs; xhigh reasoning on a large span length-stops the summary.
125
+ // When a cycle is about to hand its span to pi-core's summarizer, switch the
126
+ // level off for the call and restore it at the cycle outcome (both outcome
127
+ // events fire on every cycle that armed the switch; shutdown is the
128
+ // backstop). Summaries are mechanical merges; xhigh is actively harmful
129
+ // there. Extension-owned chunked calls (range branch, recovery branch) pass
130
+ // reasoning "off" per call and never arm this.
131
+ function armSummarizerThinkingOff(pi: ExtensionAPI, ctx: ExtensionContext): void {
132
+ try {
133
+ const cmState = getCmState(ctx);
134
+ if (cmState.pendingSummarizerThinkingLevel !== undefined) return; // already armed
135
+ const model = ctx.model as { reasoning?: boolean } | undefined;
136
+ if (!model?.reasoning) return; // nothing to strip
137
+ const previous = pi.getThinkingLevel();
138
+ if (previous === "off") return; // no change, no session entry
139
+ cmState.pendingSummarizerThinkingLevel = previous;
140
+ // "off" is accepted at runtime by pi-ai's clampThinkingLevel (it maps to
141
+ // the model's lowest level or disables thinking), but the public union
142
+ // doesn't list it yet — same boundary cast callLlm centralizes for its
143
+ // reasoning option.
144
+ pi.setThinkingLevel("off" as unknown as ThinkingLevel);
145
+ log.info(
146
+ `[context-manager] Summarizer thinking off: level ${previous} -> off for the ` +
147
+ `summarization call (restored at cycle outcome)`,
148
+ );
149
+ } catch (e) {
150
+ log.warn(
151
+ "[context-manager] thinking switch unavailable - summarizer runs at the session level:",
152
+ e,
153
+ );
154
+ }
155
+ }
156
+
157
+ function restoreSummarizerThinkingLevel(pi: ExtensionAPI, ctx: ExtensionContext): void {
158
+ try {
159
+ const cmState = getCmState(ctx);
160
+ const previous = cmState.pendingSummarizerThinkingLevel;
161
+ if (previous === undefined) return;
162
+ cmState.pendingSummarizerThinkingLevel = undefined;
163
+ pi.setThinkingLevel(previous as ThinkingLevel);
164
+ log.info(`[context-manager] Summarizer thinking restored: level ${previous}`);
165
+ } catch (e) {
166
+ log.warn("[context-manager] thinking restore failed - level may stay switched:", e);
167
+ }
168
+ }
169
+
170
+ /**
171
+ * Concurrency-scoped dedup guard. Returns true when the compaction should
172
+ * proceed, false when it is a duplicate of a compaction already in-flight for
173
+ * this leaf (same cycle).
174
+ *
175
+ * The dedupe covers only the in-cycle double-fire — when a compaction was
176
+ * already in-flight as this firing began (captured before the handler marks
177
+ * this cycle active) AND it was already seen within the cooldown window. A
178
+ * persistent whole-session key would starve legitimate later compactions on
179
+ * the same leaf ("duplicate - skipping"); once the cycle completes
180
+ * (active=false) or the cooldown lapses, a fresh cycle on the same leaf runs.
181
+ */
182
+ function markCompactProcessed(
183
+ sessionId: string,
184
+ leafId: string,
185
+ ctx: ExtensionContext,
186
+ inFlightBefore: boolean,
187
+ ): boolean {
188
+ const key = `${sessionId}::${leafId}`;
189
+ const now = Date.now();
190
+ const last = _processedCompacts.get(key);
191
+ const fresh = last !== undefined && now - last < COMPACT_COOLDOWN_MS;
192
+ // Dedupe only if a compaction was ALREADY in-flight when this firing began
193
+ // (the in-cycle double-fire from pi-core's compact() + _runAutoCompaction())
194
+ // AND we already saw this leaf within the cooldown window. A new cycle that
195
+ // begins after completion — or after the cooldown lapses — must run.
196
+ if (inFlightBefore && fresh) {
197
+ return false;
198
+ }
199
+ // LRU: remove oldest half when over limit
200
+ if (_processedCompacts.size >= MAX_PROCESSED_COMPACTS) {
201
+ const oldest = [..._processedCompacts.entries()]
202
+ .sort((a, b) => a[1] - b[1])
203
+ .slice(0, Math.floor(MAX_PROCESSED_COMPACTS / 2));
204
+ for (const [k] of oldest) _processedCompacts.delete(k);
205
+ }
206
+ _processedCompacts.set(key, now);
207
+ return true;
208
+ }
209
+
210
+ function clearProcessedCompacts(sessionId: string, leafId: string): void {
211
+ _processedCompacts.delete(`${sessionId}::${leafId}`);
212
+ }
213
+
214
+ /**
215
+ * Extract the messages in a declared archive span [startIndex..endIndex] from
216
+ * the session branch, mirroring pi-core's compaction message extraction.
217
+ */
218
+ function collectRangeMessages(
219
+ branch: Array<{ id: string; type?: string; message?: any }>,
220
+ startIndex: number,
221
+ endIndex: number,
222
+ ): any[] {
223
+ const messages: any[] = [];
224
+ const lo = Math.max(0, startIndex);
225
+ const hi = Math.min(branch.length - 1, endIndex);
226
+ for (let i = lo; i <= hi; i++) {
227
+ const entry = branch[i];
228
+ if (entry?.type === "message" && entry.message) {
229
+ messages.push(entry.message);
230
+ }
231
+ }
232
+ return messages;
233
+ }
234
+
235
+ /**
236
+ * Count of messages in this cycle's RAW summarization input —
237
+ * the captured originals JSON (what the compaction summary replaced). Returns
238
+ * undefined when the capture is absent/unparseable — telemetry degrades to
239
+ * absent, never wrong.
240
+ */
241
+ function countSummarizedMessages(originals: string | undefined): number | undefined {
242
+ if (!originals) return undefined;
243
+ try {
244
+ const parsed = JSON.parse(originals);
245
+ return Array.isArray(parsed) ? parsed.length : undefined;
246
+ } catch {
247
+ return undefined;
248
+ }
249
+ }
250
+
251
+ /**
252
+ * Count the messages that remain LIVE in context after a compaction with the
253
+ * given firstKeptEntryId anchor: message entries from the anchor (inclusive)
254
+ * to the branch end, minus any the recovery path omitted. A `context_edit`
255
+ * with `replacement === null` removes the TARGET from model context without
256
+ * removing it from the branch, so counting branch messages alone overcounts by
257
+ * the omitted attempts (exactly the entries overflow recovery appends after
258
+ * the anchor). Returns undefined when the anchor is missing from the branch
259
+ * (degrade - telemetry is never wrong, at worst absent).
260
+ */
261
+ function countKeptMessages(
262
+ branch: Array<{
263
+ id: string;
264
+ type?: string;
265
+ message?: any;
266
+ targetId?: string;
267
+ replacement?: unknown;
268
+ }>,
269
+ firstKeptEntryId: string | undefined,
270
+ ): number | undefined {
271
+ if (!firstKeptEntryId) return undefined;
272
+ const anchorIndex = branch.findIndex((entry) => entry.id === firstKeptEntryId);
273
+ if (anchorIndex < 0) return undefined;
274
+ // Effective omissions, last edit per target wins (pi keeps a Map keyed by
275
+ // targetId): a later non-null replacement re-includes the target.
276
+ const omitted = new Set<string>();
277
+ for (const entry of branch) {
278
+ if (entry?.type !== "context_edit" || !entry.targetId) continue;
279
+ if (entry.replacement === null) omitted.add(entry.targetId);
280
+ else omitted.delete(entry.targetId);
281
+ }
282
+ let kept = 0;
283
+ for (let i = anchorIndex; i < branch.length; i++) {
284
+ const entry = branch[i];
285
+ if (entry?.type === "message" && entry.message && !omitted.has(entry.id)) kept++;
286
+ }
287
+ return kept;
288
+ }
289
+
290
+ /**
291
+ * Stable fingerprint over the compaction INPUT (Pattern 8 delta-only borrow):
292
+ * sha256(branchLength + "|" + entryIds(messagesToSummarize).join(",") + "|" +
293
+ * firstKeptEntryId). Entry ids are stable across turns; timestamps and token
294
+ * counts are excluded because they drift and would defeat the skip.
295
+ *
296
+ * Messages in messagesToSummarize are the same object references as
297
+ * branch[i].message (pi-core's prepareCompaction pushes entry.message), so
298
+ * entry ids are recovered by identity, in branch order.
299
+ */
300
+ function computeCompactionFingerprint(
301
+ branch: Array<{ id: string; type?: string; message?: any }>,
302
+ messagesToSummarize: unknown[],
303
+ firstKeptEntryId: string | undefined,
304
+ ): string {
305
+ const summarizeSet = new Set(messagesToSummarize);
306
+ const ids: string[] = [];
307
+ for (const entry of branch) {
308
+ if (entry?.type === "message" && entry.message && summarizeSet.has(entry.message)) {
309
+ ids.push(entry.id);
310
+ }
311
+ }
312
+ return createHash("sha256")
313
+ .update(`${branch.length}|${ids.join(",")}|${firstKeptEntryId ?? ""}`)
314
+ .digest("hex");
315
+ }
316
+
317
+ // Verify / rollback stage (light path).
318
+ // A compaction that "succeeds" can still destroy context silently: an
319
+ // empty/boilerplate summary (the STEP 0.75 defect class), a summary larger than
320
+ // the dropped span (budget not recovered), or a branch left incoherent (missing
321
+ // first-kept anchor). Recording "success" on any truthy result with no
322
+ // coherence or budget validation is exactly that silent destruction.
323
+ //
324
+ // Light path: validation + honest failure feedback. NO destructive rollback —
325
+ // pi-core 0.84.2 has no snapshot mechanism; the branch file is append-only and
326
+ // originals are recoverable via context_navigate/archive (the append-only
327
+ // archive preserves every compaction's originals batch).
328
+
329
+ /**
330
+ * Verify a completed compaction BEFORE recording success.
331
+ *
332
+ * - Coherence: compactionEntry must exist with a non-empty summary (trim
333
+ * length > 0) and firstKeptEntryId must be present. An empty summary is the
334
+ * STEP 0.75 defect class — caught here even though prevents it at the
335
+ * source.
336
+ * - Budget: post-compaction usage (recomputed via analyzeSession) must be
337
+ * strictly below the pre-compaction usage captured at session_before_compact
338
+ * (<= 1pp slack: a drop of 1pp or less is a no-op treadmill). Only enforced
339
+ * when a pre-compaction value was captured; analysis failure degrades to
340
+ * coherence-only and never fails a compaction on missing telemetry.
341
+ *
342
+ * Returns { ok: true } when verification passes, or { ok: false, reason } with a
343
+ * specific reason ("coherence..." vs "budget...").
344
+ */
345
+ function verifyCompactionResult(
346
+ event: {
347
+ compactionEntry?: { id?: string; summary?: string };
348
+ firstKeptEntryId?: string;
349
+ },
350
+ ctx: ExtensionContext,
351
+ preCompactionUsagePercent: number | undefined,
352
+ ): { ok: boolean; reason?: string } {
353
+ // Coherence: non-empty summary + first-kept anchor present.
354
+ const summary = event.compactionEntry?.summary?.trim() ?? "";
355
+ if (summary.length === 0) {
356
+ return {
357
+ ok: false,
358
+ reason: "coherence: compaction summary is empty (STEP 0.75 defect class)",
359
+ };
360
+ }
361
+ if (!event.firstKeptEntryId) {
362
+ return {
363
+ ok: false,
364
+ reason: "coherence: firstKeptEntryId missing — branch anchor lost",
365
+ };
366
+ }
367
+ // Budget: post-compaction usage must be strictly below the pre-compaction
368
+ // usage captured at session_before_compact (<= 1pp slack).
369
+ if (preCompactionUsagePercent !== undefined) {
370
+ let postUsagePercent = 0;
371
+ try {
372
+ postUsagePercent = analyzeSession(ctx).usage.percent;
373
+ } catch {
374
+ /* analysis unavailable - cannot verify budget; do not fail the compaction */
375
+ }
376
+ if (postUsagePercent >= preCompactionUsagePercent - 1) {
377
+ return {
378
+ ok: false,
379
+ reason:
380
+ `budget: post-compaction usage ${postUsagePercent.toFixed(1)}% did not drop ` +
381
+ `below pre-compaction ${preCompactionUsagePercent.toFixed(1)}% (<=1pp slack)`,
382
+ };
383
+ }
384
+ }
385
+ return { ok: true };
386
+ }
387
+
388
+ // Append-only originals archive.
389
+ // A compaction that "succeeded" but destroyed context needs recovery, not
390
+ // just detection: the dropped originals stay buried in the append-only session
391
+ // file in a way the live branch can't navigate to. EVERY compaction that
392
+ // proceeded writes its raw originals (captured at session_before_compact,
393
+ // pre-compression) into an explicit on-disk archive (pi-condense's post-hoc
394
+ // recovery-archive pattern; no new dependency), so originals are never
395
+ // silently discarded from the live branch just because verification happened
396
+ // to pass.
397
+
398
+ /**
399
+ * Write the append-only originals archive. Called from BOTH the
400
+ * session_compact outcome stage's success path (reason "compact") and the
401
+ * verify-failure path (reason = verify.reason). Always-on per (lossless
402
+ * default): whenever
403
+ * originals were captured (a compaction actually proceeded), the exact
404
+ * pre-compression originals are appended as one JSON line to
405
+ * <sessionDir>/archives/<sessionId>-<leafId>-<epoch>.jsonl (mkdir -p
406
+ * archives) and the recovery path is logged. VerifyFailed +
407
+ * pendingCompactionOriginals are ALWAYS cleared in finally here (the archive
408
+ * write owns the flag lifecycle) so no stale flag or capture lingers on
409
+ * success or failure.
410
+ *
411
+ * Each line also carries the compacted-vs-kept message counter
412
+ * (compactedMessages = this cycle's raw summarization input, keptMessages =
413
+ * messages still live from the firstKeptEntryId anchor), so post-hoc loss
414
+ * questions are answerable from the durable per-compaction record. Counts are
415
+ * omitted (undefined) when their source degraded — absent, never wrong.
416
+ *
417
+ * Session file access is READ-ONLY (rotation.ts statSync pattern): the session
418
+ * file path is read from ctx.sessionManager (getSessionFile(), backed by the
419
+ * private sessionFile field) and never written.
420
+ */
421
+ function writeOriginalsArchive(
422
+ ctx: ExtensionContext,
423
+ reason: string | undefined,
424
+ originals: string | undefined,
425
+ counts?: { compactedMessages?: number; keptMessages?: number },
426
+ ): void {
427
+ try {
428
+ // Always-on / lossless default: the archive is written whenever originals
429
+ // were captured (a compaction actually proceeded), on BOTH the healthy and
430
+ // verify-failed path (the !originals no-op below covers abort /
431
+ // fingerprint-skip). Future opt-out extension point: a config toggle keyed
432
+ // on getCmState(ctx) would re-introduce a gate here (e.g.
433
+ // archiveOriginals === false).
434
+ if (!originals) return; // nothing captured — nothing to archive
435
+
436
+ const sm = ctx.sessionManager as {
437
+ sessionFile?: string;
438
+ getSessionFile?(): string | undefined;
439
+ };
440
+ const sessionFilePath = sm.sessionFile ?? sm.getSessionFile?.();
441
+ if (!sessionFilePath) {
442
+ log.warn("[context-manager] No session file path — originals archive skipped");
443
+ return;
444
+ }
445
+
446
+ const sessionDir = dirname(sessionFilePath);
447
+ const archivesDir = join(sessionDir, "archives");
448
+ mkdirSync(archivesDir, { recursive: true });
449
+ const sessionId = getSessionIdSafe(ctx);
450
+ const leafId = getLeafIdSafe(ctx);
451
+ const epoch = Date.now();
452
+ const archivePath = join(archivesDir, `${sessionId}-${leafId}-${epoch}.jsonl`);
453
+ const line = JSON.stringify({
454
+ sessionId,
455
+ leafId,
456
+ reason,
457
+ timestamp: new Date().toISOString(),
458
+ compactedMessages: counts?.compactedMessages,
459
+ keptMessages: counts?.keptMessages,
460
+ originals,
461
+ });
462
+ appendFileSync(archivePath, `${line}\n`);
463
+ // A: count coverage on a successful append only — an
464
+ // archive write that threw must not inflate the coverage counter.
465
+ recordCompactionHealth("totalArchivesWritten");
466
+ log.info(
467
+ `[context-manager] Originals archived to ${archivePath} (verify: ${reason}) — ` +
468
+ `recover via context_navigate/read`,
469
+ );
470
+ } catch (e) {
471
+ log.error("[context-manager] Originals archive write failed:", e);
472
+ } finally {
473
+ // Owns the flag lifecycle: verifyFailed must never linger after the
474
+ // write attempt (success or failure), and the capture is consumed.
475
+ try {
476
+ const cmState = getCmState(ctx);
477
+ cmState.verifyFailed = false;
478
+ cmState.pendingCompactionOriginals = undefined;
479
+ } catch {
480
+ /* state unavailable */
481
+ }
482
+ }
483
+ }
484
+
485
+ // Pre-append queued message handling.
486
+ // When a user sends a message during compaction, it is queued in the TUI's
487
+ // compactionQueuedMessages (not in sessionManager yet).
488
+ //
489
+ // On compaction_end, the TUI calls rebuildChatFromMessages() BEFORE
490
+ // flushCompactionQueue delivers the user's message. This means the user's
491
+ // message is NOT in the rebuilt chat snapshot.
492
+ //
493
+ // Fix:
494
+ // 1. input event -> capture user's message text (TUI queues it after)
495
+ // 2. session_compact -> pre-append to sessionManager + intercept appendMessage
496
+ // 3. compaction_end -> rebuildChatFromMessages() sees user's message in session [ok]
497
+ // 4. flushCompactionQueue -> session.prompt() -> appendMessage intercept SKIPS duplicate
498
+ // 5. Auto (threshold/overflow): agent turn fires [ok] - the flush replay is
499
+ // the resume. Manual: the replay is swallowed by the input-hook hold
500
+ // (one-shot, armed here on reason=manual) - a manual compaction is a full
501
+ // stop; the parked message waits for the operator's next input or a wake.
502
+ //
503
+ // The intercept works by wrapping sessionManager.appendMessage to detect when
504
+ // flushCompactionQueue's session.prompt() fires (it calls appendMessage via the
505
+ // message_end handler). We skip the duplicate by returning the pre-appended
506
+ // entry ID instead of creating a new one.
507
+
508
+ // Session-scoped compaction intercept state.
509
+ // The fields below are all part of the same lifecycle: capture a user
510
+ // message during compaction, pre-append it, intercept the duplicate, then
511
+ // restore; plus the manual-compaction hold (arm/swallow/disarm). One
512
+ // per-session state object — separate module-level `let` variables would
513
+ // leak across sessions in multi-session pi-core deployments.
514
+
515
+ interface CompactionInterceptState {
516
+ /** Text of the user's message queued during compaction. */
517
+ queuedDuringCompaction: string | undefined;
518
+ /** Entry ID of the message pre-appended to sessionManager. */
519
+ preAppendedEntryId: string | undefined;
520
+ /** Original sessionManager.appendMessage - restored after intercept window. */
521
+ origAppendMessage: ((msg: any) => string) | undefined;
522
+ /** Whether the intercept is currently active. */
523
+ interceptActive: boolean;
524
+ /** SessionManager reference at time of intercept setup. */
525
+ interceptedSmRef: any;
526
+ /**
527
+ * Manual-compaction hold, armed by session_compact when a manual compaction
528
+ * succeeded with a parked message. One-shot: the first post-compaction input
529
+ * event spends it (swallowing the TUI flush's replay of the held text, or
530
+ * disarming for any other input). A manual compaction is a full stop: its
531
+ * parked message must not start a turn via the flush replay.
532
+ */
533
+ holdQueuedPrompt: boolean;
534
+ /** Text snapshot held by the armed hold (isolated from later captures). */
535
+ heldQueuedText: string | undefined;
536
+ /**
537
+ * Owner inputs seated durably at receipt and not yet confirmed delivered.
538
+ * Unlike the fields above, this list is NOT part of the intercept window:
539
+ * it survives clearInterceptState so a failure cannot wipe the only
540
+ * in-memory pointer to text the durable seat still holds.
541
+ */
542
+ pendingOwnerInputs: PendingOwnerInput[];
543
+ /**
544
+ * Recently delivered owner texts (bounded ring). A replay of a text this
545
+ * extension already parked (the TUI flush replay after an auto compaction)
546
+ * must not be re-seated as if it were a fresh receipt.
547
+ */
548
+ deliveredOwnerInputs: string[];
549
+ }
550
+
551
+ interface PendingOwnerInput {
552
+ text: string;
553
+ /** Which queue the text entered: the compaction capture, or a steer into a run. */
554
+ kind: "compaction" | "steer";
555
+ seatedAt: number;
556
+ }
557
+
558
+ /**
559
+ * Source stamped on the durable seat record. A reader that has to recover
560
+ * owner input after a crash looks for this value in the branch's
561
+ * `braid_injection` entries.
562
+ */
563
+ export const OWNER_INPUT_SEAT_SOURCE = "context-manager/owner-input-seat";
564
+
565
+ /** Bounded ring so a long session's delivery confirmations stay small. */
566
+ const MAX_DELIVERED_OWNER_INPUTS = 32;
567
+
568
+ const EMPTY_INTERCEPT_STATE: CompactionInterceptState = {
569
+ queuedDuringCompaction: undefined,
570
+ preAppendedEntryId: undefined,
571
+ origAppendMessage: undefined,
572
+ interceptActive: false,
573
+ interceptedSmRef: undefined,
574
+ holdQueuedPrompt: false,
575
+ heldQueuedText: undefined,
576
+ pendingOwnerInputs: [],
577
+ deliveredOwnerInputs: [],
578
+ };
579
+
580
+ function getInterceptState(ctx: ExtensionContext): CompactionInterceptState {
581
+ return getExtensionState(ctx, "context-manager/compaction-intercept", () => ({
582
+ ...EMPTY_INTERCEPT_STATE,
583
+ // Fresh arrays: the spread above copies the const's references, and a
584
+ // push into a shared array would leak one session's seats into the next.
585
+ pendingOwnerInputs: [],
586
+ deliveredOwnerInputs: [],
587
+ }));
588
+ }
589
+
590
+ /**
591
+ * Create a wrapper for sessionManager.appendMessage that skips the duplicate
592
+ * when flushCompactionQueue's session.prompt() fires after our pre-append.
593
+ *
594
+ * SAFETY: Captures the original appendMessage in the closure at creation time.
595
+ * This prevents self-recursion (max call stack) if intercept state is cleared
596
+ * while the wrapper is still in place — the fallback still delegates to the
597
+ * original function rather than calling sessionManager.appendMessage (which
598
+ * IS the wrapper itself).
599
+ *
600
+ * Returns the pre-appended entry ID to avoid creating a duplicate entry.
601
+ */
602
+ function createSkipDuplicateWrapper(
603
+ sessionManager: any,
604
+ ctx: ExtensionContext,
605
+ originalAppendMessage: (msg: any) => string,
606
+ ): (msg: any) => string {
607
+ return (msg: any) => {
608
+ const st = getInterceptState(ctx);
609
+
610
+ // Safety: if intercept was deactivated (e.g., the outcome stage closing a
611
+ // cycle with no queued messages), pass through to the original without any
612
+ // duplicate detection.
613
+ if (!st.interceptActive) {
614
+ return originalAppendMessage.call(sessionManager, msg);
615
+ }
616
+
617
+ // Only messages with content[] can be the duplicate user message.
618
+ // BashExecutionMessage has NO `content` field - must pass through.
619
+ const content = msg?.content;
620
+ if (Array.isArray(content)) {
621
+ const text = content[0]?.text;
622
+ if (typeof text === "string" && text === st.queuedDuringCompaction) {
623
+ // Skip - this is the duplicate from session.prompt()'s message_end handler.
624
+ // The original from session_compact is already in sessionManager.
625
+ // Return the pre-appended entry ID so the caller gets a valid ID.
626
+ return st.preAppendedEntryId ?? "";
627
+ }
628
+ }
629
+
630
+ // Not a duplicate — delegate to original (captured in closure).
631
+ return originalAppendMessage.call(sessionManager, msg);
632
+ };
633
+ }
634
+
635
+ /**
636
+ * Attempt to restore sessionManager.appendMessage from the intercept.
637
+ * Called wherever the intercept window can close without the flush replay:
638
+ * the input hook that spends the manual-compaction hold, the message_end
639
+ * backup, session_compact_failed, and session shutdown.
640
+ */
641
+ export function tryRestoreAppendMessage(ctx: ExtensionContext): void {
642
+ const st = getInterceptState(ctx);
643
+ if (!st.interceptActive || !st.origAppendMessage) return;
644
+ // The install side wraps the manager ctx exposes (getFullSessionManager),
645
+ // so the restore must read the same handle for the same-instance guard
646
+ // below to mean anything. pi's ExtensionAPI carries no sessionManager.
647
+ const sm = getFullSessionManager(ctx);
648
+ if (!sm) {
649
+ // No sessionManager available - clear intercept state.
650
+ st.interceptActive = false;
651
+ st.origAppendMessage = undefined;
652
+ st.interceptedSmRef = undefined;
653
+ return;
654
+ }
655
+ // Only restore if the sessionManager is the same one we intercepted.
656
+ // After session replacement (reload/newSession), sm is a new instance
657
+ // and the old st.origAppendMessage is stale - DO NOT restore.
658
+ if (sm !== st.interceptedSmRef) {
659
+ log.debug("[context-manager] Skipped intercept restore - sessionManager replaced");
660
+ st.interceptActive = false;
661
+ st.origAppendMessage = undefined;
662
+ st.interceptedSmRef = undefined;
663
+ return;
664
+ }
665
+ // Verify appendMessage is still our wrapper (not further mutated).
666
+ // If it's no longer the wrapper, someone else already restored it.
667
+ if (typeof sm.appendMessage !== "function" || sm.appendMessage === st.origAppendMessage) {
668
+ // Not wrapped or already restored - nothing to do.
669
+ st.interceptActive = false;
670
+ st.origAppendMessage = undefined;
671
+ st.interceptedSmRef = undefined;
672
+ return;
673
+ }
674
+ sm.appendMessage = st.origAppendMessage;
675
+ st.origAppendMessage = undefined;
676
+ st.interceptActive = false;
677
+ st.interceptedSmRef = undefined;
678
+ log.debug("[context-manager] AppendMessage intercept restored");
679
+ }
680
+
681
+ export function clearInterceptState(ctx: ExtensionContext): void {
682
+ // Unwrap before clearing: the bookkeeping below is what the restore path
683
+ // reads, so clearing first would strand the wrapper on the session manager.
684
+ tryRestoreAppendMessage(ctx);
685
+ const st = getInterceptState(ctx);
686
+ st.queuedDuringCompaction = undefined;
687
+ st.preAppendedEntryId = undefined;
688
+ st.origAppendMessage = undefined;
689
+ st.interceptActive = false;
690
+ st.interceptedSmRef = undefined;
691
+ st.holdQueuedPrompt = false;
692
+ st.heldQueuedText = undefined;
693
+ setCompactionActive(false, ctx);
694
+ }
695
+
696
+ /**
697
+ * Force-persist the session to disk.
698
+ * This is needed because sessionManager._persist() has a no-assistant guard that
699
+ * returns early without writing if there's no assistant message yet.
700
+ * When we pre-append a user message during compaction (before any assistant response),
701
+ * _persist() silently ignores it, causing the message to be lost on session reload.
702
+ *
703
+ * This function manually writes all pending entries to disk, bypassing the guard.
704
+ */
705
+ function forcePersistSession(sm: any): void {
706
+ try {
707
+ if (!sm?.sessionFile || !sm?.persist) return;
708
+ const flushed = (sm as FullSessionManager).flushed;
709
+ const fileEntries = (sm as FullSessionManager).fileEntries;
710
+ // The force-write reaches pi-core's private buffer by design (its own
711
+ // _persist() guards on a landed user/assistant message). A rename of
712
+ // either private field would otherwise silently turn this loss-prevention
713
+ // write into a no-op, or re-append entries that were already persisted.
714
+ // Verify the private shape before writing.
715
+ if (typeof flushed !== "boolean" || !Array.isArray(fileEntries)) {
716
+ log.warn(
717
+ "[context-manager] Force-persist skipped: sessionManager private layout changed " +
718
+ "(expected flushed:boolean, fileEntries:array)",
719
+ );
720
+ return;
721
+ }
722
+ if (!flushed && fileEntries.length > 0) {
723
+ // Write all entries to establish the session file with all content
724
+ for (const entry of fileEntries) {
725
+ appendFileSync(sm.sessionFile, `${JSON.stringify(entry)}\n`);
726
+ }
727
+ (sm as FullSessionManager).flushed = true;
728
+ log.debug(
729
+ `[context-manager] Force-persisted ${fileEntries.length} entries to ${sm.sessionFile}`,
730
+ );
731
+ }
732
+ } catch (e) {
733
+ log.error("[context-manager] Force-persist failed:", e);
734
+ }
735
+ }
736
+
737
+ // Durable owner-input seat.
738
+ // The intercept state above is an in-memory seat, and a failed compaction
739
+ // wipes it (clearInterceptState) while the text exists nowhere else: the
740
+ // TUI's compaction queue lives in the TUI process, non-TUI callers have none,
741
+ // and a steer parked in pi's in-memory steering queue is invisible to the
742
+ // session tree. Owner text therefore gets a durable copy at receipt, written
743
+ // through the same store every tracked injection uses (`braid_injection`
744
+ // session entries; injection-tracker owns that write path), and delivery is
745
+ // confirmed by the session's own message events.
746
+ //
747
+ // The seat is a COPY, never a second queue: text pi still holds in its own
748
+ // queue is not re-delivered (a settled run's unconsumed steer is drained by
749
+ // the next run's start), and a text confirmed delivered is never delivered
750
+ // again.
751
+
752
+ /** Record owner text in the durable seat, once per undelivered text. */
753
+ function seatOwnerInput(
754
+ ctx: ExtensionContext,
755
+ text: string,
756
+ kind: PendingOwnerInput["kind"],
757
+ ): void {
758
+ try {
759
+ const st = getInterceptState(ctx);
760
+ if (st.deliveredOwnerInputs.includes(text)) return;
761
+ if (st.pendingOwnerInputs.some((item) => item.text === text)) return;
762
+ st.pendingOwnerInputs.push({ text, kind, seatedAt: Date.now() });
763
+ trackInjection({
764
+ type: "context",
765
+ source: OWNER_INPUT_SEAT_SOURCE,
766
+ content: text,
767
+ display: true,
768
+ steer: kind === "steer",
769
+ fullContent: true,
770
+ });
771
+ } catch (e) {
772
+ log.warn("[context-manager] owner-input seat write failed:", e);
773
+ }
774
+ }
775
+
776
+ /**
777
+ * Confirm delivery and drop the pending seat. `remember` also suppresses
778
+ * re-seating a replay of this text: a park is followed by the TUI flush
779
+ * replay, which is a second receipt of text already in the session.
780
+ */
781
+ function markOwnerInputDelivered(ctx: ExtensionContext, text: string, remember = false): void {
782
+ const st = getInterceptState(ctx);
783
+ const index = st.pendingOwnerInputs.findIndex((item) => item.text === text);
784
+ if (index >= 0) st.pendingOwnerInputs.splice(index, 1);
785
+ if (index < 0 && !remember) return;
786
+ st.deliveredOwnerInputs.push(text);
787
+ while (st.deliveredOwnerInputs.length > MAX_DELIVERED_OWNER_INPUTS) {
788
+ st.deliveredOwnerInputs.shift();
789
+ }
790
+ }
791
+
792
+ /**
793
+ * Write one owner text into the session as a user message and force-persist
794
+ * it - the delivery the successful compaction path pre-appends, reused by the
795
+ * failure and settle paths. Returns false when no session manager is
796
+ * reachable; the durable seat still holds the text.
797
+ */
798
+ function parkOwnerTextInSession(ctx: ExtensionContext, text: string): boolean {
799
+ const sm = getFullSessionManager(ctx);
800
+ if (!sm || typeof sm.appendMessage !== "function") return false;
801
+ try {
802
+ const st = getInterceptState(ctx);
803
+ const messageObj = {
804
+ role: "user" as const,
805
+ content: [{ type: "text" as const, text }],
806
+ timestamp: Date.now(),
807
+ };
808
+ // Append through the original when the intercept wrapper is already
809
+ // installed for THIS session manager, so the wrapper's duplicate skip
810
+ // cannot swallow this write. A replaced manager (session reload) must
811
+ // never receive the write through the stale binding.
812
+ const reuseWrapper = Boolean(
813
+ st.interceptActive && st.origAppendMessage && st.interceptedSmRef === sm,
814
+ );
815
+ const append =
816
+ reuseWrapper && st.origAppendMessage ? st.origAppendMessage : sm.appendMessage.bind(sm);
817
+ st.preAppendedEntryId = append(messageObj);
818
+ if (!reuseWrapper) {
819
+ // Fresh intercept window: wrap appendMessage so the flush replay of this
820
+ // text is skipped instead of creating a duplicate entry.
821
+ st.origAppendMessage = sm.appendMessage.bind(sm);
822
+ sm.appendMessage = createSkipDuplicateWrapper(sm, ctx, st.origAppendMessage);
823
+ st.interceptedSmRef = sm;
824
+ st.interceptActive = true;
825
+ }
826
+ forcePersistSession(sm);
827
+ markOwnerInputDelivered(ctx, text, true);
828
+ log.info(
829
+ `[context-manager] Owner input parked in the session (entry: ${st.preAppendedEntryId})`,
830
+ );
831
+ return true;
832
+ } catch (e) {
833
+ log.error("[context-manager] Failed to park owner input in the session:", e);
834
+ return false;
835
+ }
836
+ }
837
+
838
+ /**
839
+ * Re-deliver owner inputs still pending at a lifecycle boundary.
840
+ *
841
+ * - "failure": the compaction cycle landed no entry. Deliver now only when the
842
+ * session is idle; a live run must not receive a raw session write mid-run
843
+ * (message order), so the text waits for the settle boundary.
844
+ * - "settle": the run has settled. Texts pi still holds in its own queue are
845
+ * skipped - the next run's start drains them (the agent loop polls the
846
+ * steering queue at run start), and delivering here would duplicate that.
847
+ * - "shutdown": last chance to persist; deliver everything still pending.
848
+ */
849
+ export function flushPendingOwnerInputs(
850
+ ctx: ExtensionContext,
851
+ phase: "failure" | "settle" | "shutdown",
852
+ ): void {
853
+ let pending: PendingOwnerInput[];
854
+ try {
855
+ pending = [...getInterceptState(ctx).pendingOwnerInputs];
856
+ } catch {
857
+ return;
858
+ }
859
+ if (pending.length === 0) return;
860
+ if (phase === "failure" && !readIdle(ctx)) return;
861
+ if (phase === "settle" && readHasPendingMessages(ctx)) return;
862
+ for (const item of pending) {
863
+ parkOwnerTextInSession(ctx, item.text);
864
+ }
865
+ }
866
+
867
+ /** Live idle read, fail-open to delivery (a missed delivery loses owner text). */
868
+ function readIdle(ctx: ExtensionContext): boolean {
869
+ try {
870
+ return typeof ctx.isIdle === "function" ? ctx.isIdle() : true;
871
+ } catch {
872
+ return true;
873
+ }
874
+ }
875
+
876
+ /**
877
+ * Live queued-messages read. Fail-closed: an unreadable queue must not make
878
+ * the settle flush re-deliver text pi may still be holding.
879
+ */
880
+ function readHasPendingMessages(ctx: ExtensionContext): boolean {
881
+ try {
882
+ return typeof ctx.hasPendingMessages === "function" ? ctx.hasPendingMessages() : false;
883
+ } catch {
884
+ return false;
885
+ }
886
+ }
887
+
888
+ /**
889
+ * Drop the seat bookkeeping. For shutdown (after the flush above) and for
890
+ * fixtures; the durable entries stay in the session either way.
891
+ */
892
+ export function clearOwnerInputSeats(ctx: ExtensionContext): void {
893
+ const st = getInterceptState(ctx);
894
+ st.pendingOwnerInputs.length = 0;
895
+ st.deliveredOwnerInputs.length = 0;
896
+ }
897
+
898
+ // Compaction Instructions Builder
899
+ // Generates smarter instructions for the summarization model.
900
+ // The key insight: tell the model WHAT to preserve, not just "summarize".
901
+
902
+ function buildCompactionInstructions(audit: any): string[] {
903
+ const instructions: string[] = [];
904
+
905
+ // 1. Task state preservation
906
+ if (audit.tagCount > 0) {
907
+ instructions.push(
908
+ `Session has ${audit.tagCount} checkpoint(s): preserve tag labels for navigation.`,
909
+ );
910
+ }
911
+
912
+ // 2. Prune candidates - tell model what to cut
913
+ const highPriorityPrune = audit.candidates?.filter((c: any) => c.score >= 0.6) ?? [];
914
+ if (highPriorityPrune.length > 3) {
915
+ instructions.push(
916
+ `${highPriorityPrune.length} entries are prune candidates with low semantic value - summarize briefly.`,
917
+ );
918
+ }
919
+
920
+ // 3. Context pressure - tell model how aggressive to be
921
+ if (audit.usage.percent > 85) {
922
+ instructions.push(
923
+ `CRITICAL: Context at ${audit.usage.percent.toFixed(0)}% - aggressively summarize. ` +
924
+ `Preserve: (1) active task/goals, (2) key file paths and edits, (3) error states. ` +
925
+ `Discard: verbose tool outputs, repeated reads, exploration logs.`,
926
+ );
927
+ } else if (audit.usage.percent > CONTEXT_COMPACT_REFUSE_PERCENT) {
928
+ instructions.push(
929
+ `Context at ${audit.usage.percent.toFixed(0)}% - moderate summarization. ` +
930
+ `Keep: task context, recent decisions, pending work. Summarize: older tool outputs.`,
931
+ );
932
+ }
933
+
934
+ // 4. Semantic preservation rules
935
+ instructions.push(
936
+ "Preserve tool-call/result pairs together - never split a tool call from its result. " +
937
+ "If a tool call produced an error, keep both the call and the error.",
938
+ );
939
+
940
+ // 5. Memory hint
941
+ instructions.push(
942
+ "After compaction: consider storing key learnings in memory for cross-session continuity.",
943
+ );
944
+
945
+ return instructions;
946
+ }
947
+
948
+ // Session before compact: custom instructions before compaction for
949
+ // smarter LLM summarization.
950
+ //
951
+ // The path always uses LLM summarization - it's fast (a few seconds) and
952
+ // produces better summaries than hard truncation; pi-core handles its own
953
+ // last-resort safety net.
954
+ //
955
+ // Flow:
956
+ // 1. Deduplicate - prevent two compaction entries from manual+auto call sites
957
+ // 2. Pre-filter - remove 100%-safe-to-remove items (STEP 1)
958
+ // 3. Instruct - inject smart summarization instructions (STEP 2)
959
+ // pi core then calls LLM summarization with our instructions
960
+
961
+ /**
962
+ * Capture the messages a deterministic cut drops as this cycle's originals
963
+ * capture, so the trace's span size and the originals archive describe the cut
964
+ * that actually landed rather than pi-core's default token-cut span. Degrades
965
+ * to the existing capture, never to a wrong one.
966
+ */
967
+ function captureDroppedSpanBefore(ctx: ExtensionContext, cutEntryId: string): void {
968
+ try {
969
+ const sm = ctx.sessionManager;
970
+ const branch =
971
+ typeof (sm as { getBranch?: () => unknown[] }).getBranch === "function"
972
+ ? ((sm as { getBranch: () => unknown[] }).getBranch() ?? [])
973
+ : [];
974
+ const cutIndex = branch.findIndex((entry) => (entry as { id?: string })?.id === cutEntryId);
975
+ if (cutIndex < 0) return;
976
+ const droppedMessages: unknown[] = [];
977
+ for (const entry of branch.slice(0, cutIndex)) {
978
+ const message = (entry as { type?: string; message?: unknown }).message;
979
+ if ((entry as { type?: string }).type === "message" && message) droppedMessages.push(message);
980
+ }
981
+ getCmState(ctx).pendingCompactionOriginals = JSON.stringify(droppedMessages);
982
+ } catch {
983
+ /* capture replacement unavailable - telemetry degrades to the default snapshot */
984
+ }
985
+ }
986
+
987
+ /**
988
+ * Deterministic no-LLM cut point: the last rung of the summary-cap ladder.
989
+ * Persists an extension compaction result that drops the oldest entries and
990
+ * keeps the recent tail live - the same cut shape the high-context guard
991
+ * persists, reused here so a bounded summarizer failure can never leave a
992
+ * session unable to compact. Returns null when no cut point resolves (the
993
+ * caller then cancels as before).
994
+ *
995
+ * `reason` and `detail` are the landed summary's own account of why the cut was
996
+ * taken; the defaults describe the bounded-summarizer failure this rung was
997
+ * first built for, and the fail-safe rung passes its own.
998
+ */
999
+ function buildDeterministicCut(
1000
+ ctx: ExtensionContext,
1001
+ prep: { tokensBefore?: number } | undefined,
1002
+ account: {
1003
+ reason?: string;
1004
+ detail?: string;
1005
+ } = {},
1006
+ ): {
1007
+ compaction: {
1008
+ summary: string;
1009
+ firstKeptEntryId: string;
1010
+ tokensBefore: number;
1011
+ details: { readFiles: string[]; modifiedFiles: string[] };
1012
+ };
1013
+ } | null {
1014
+ const reason = account.reason ?? "after a bounded summarizer failure";
1015
+ const detail =
1016
+ account.detail ?? "(the chunked summarizer exhausted its bounded budget on this span)";
1017
+ try {
1018
+ const sm = ctx.sessionManager;
1019
+ const branch =
1020
+ typeof (sm as { getBranch?: () => unknown[] }).getBranch === "function"
1021
+ ? ((sm as { getBranch: () => unknown[] }).getBranch() ?? [])
1022
+ : [];
1023
+ const keepCount = Math.min(50, Math.max(10, Math.floor(branch.length * 0.3)));
1024
+ // The deterministic cut is a supplied boundary: snap it out of any tool
1025
+ // batch it lands in (HTTP 400: a kept slice that opens with a tool result
1026
+ // has no preceding tool_calls).
1027
+ const cutIndex = snapBoundaryOutsideToolBatch(branch, Math.max(0, branch.length - keepCount));
1028
+ const cutEntryId = (branch[cutIndex] as { id?: string } | undefined)?.id;
1029
+ if (!cutEntryId || cutIndex <= 0) return null;
1030
+ const keptCount = branch.length - cutIndex;
1031
+ const cmState = getCmState(ctx);
1032
+ cmState.slideMode = {
1033
+ active: true,
1034
+ cutEntryId,
1035
+ keepCount: keptCount,
1036
+ droppedCount: cutIndex,
1037
+ timestamp: Date.now(),
1038
+ };
1039
+ captureDroppedSpanBefore(ctx, cutEntryId);
1040
+ return {
1041
+ compaction: {
1042
+ summary:
1043
+ `Deterministic cut ${reason}: dropped the ${cutIndex} entries ` +
1044
+ `before the cut without LLM summarization ${detail}. The last ${keptCount} entries ` +
1045
+ `remain live; dropped content stays in the append-only session file and the originals archive.`,
1046
+ firstKeptEntryId: cutEntryId,
1047
+ tokensBefore: typeof prep?.tokensBefore === "number" ? prep.tokensBefore : 0,
1048
+ details: { readFiles: [], modifiedFiles: [] },
1049
+ },
1050
+ };
1051
+ } catch (err) {
1052
+ log.error("[context-manager] deterministic cut failed:", err);
1053
+ return null;
1054
+ }
1055
+ }
1056
+
1057
+ export function registerBeforeCompactHandler(pi: ExtensionAPI): void {
1058
+ // Input hook: capture user's queued message during compaction
1059
+ // When the user sends a message while compaction is running, it is queued in
1060
+ // TUI's compactionQueuedMessages (not persisted to sessionManager yet).
1061
+ // We capture the text here so we can pre-append it to sessionManager in
1062
+ // session_compact (before TUI's rebuildChatFromMessages runs).
1063
+ pi.on(INPUT, (event: any, ctx: ExtensionContext) => {
1064
+ if (!event?.text) return;
1065
+ // Durable seat at receipt: text entering a queue this extension cannot
1066
+ // verify drains (the compaction capture window, or a steer/follow-up into
1067
+ // a run) gets its durable copy before any cycle can consume the capture.
1068
+ // An idle prompt is delivered by definition and is not seated.
1069
+ // Per-session active read: the ctx-less fallback is a single-session
1070
+ // shortcut, and this hook's ctx is the session the text belongs to.
1071
+ const compactionActive = isCompactionActive(ctx);
1072
+ if (compactionActive || event.streamingBehavior !== undefined) {
1073
+ seatOwnerInput(ctx, event.text, compactionActive ? "compaction" : "steer");
1074
+ }
1075
+ // Guard: only capture messages typed DURING active compaction.
1076
+ // Messages typed before compaction starts are already in sessionManager
1077
+ // and should NOT be pre-appended (would create a duplicate).
1078
+ if (compactionActive) {
1079
+ const st = getInterceptState(ctx);
1080
+ if (st.queuedDuringCompaction === undefined) {
1081
+ st.queuedDuringCompaction = event.text;
1082
+ }
1083
+ }
1084
+ // Manual-compaction hold (armed in session_compact): a manual compaction is
1085
+ // a full stop: the TUI's post-compaction flush replays the parked message
1086
+ // via session.prompt(text, {streamingBehavior}), which would start a fresh
1087
+ // assistant turn from pre-compaction input. The hold is one-shot: the first
1088
+ // post-compaction input event spends it. Swallow only the exact replay:
1089
+ // held text arriving as a queued prompt (streamingBehavior set, the flush's
1090
+ // call shape; a genuinely new idle submit carries no streamingBehavior).
1091
+ // Any other input disarms without swallowing. Either way the parked text
1092
+ // stays in the session (pre-appended at session_compact) and the intercept
1093
+ // wrapper is restored, since the flush it guarded can no longer duplicate.
1094
+ const st = getInterceptState(ctx);
1095
+ if (st.holdQueuedPrompt) {
1096
+ const isFlushReplay =
1097
+ event.text === st.heldQueuedText && event.streamingBehavior !== undefined;
1098
+ st.holdQueuedPrompt = false;
1099
+ st.heldQueuedText = undefined;
1100
+ st.queuedDuringCompaction = undefined;
1101
+ tryRestoreAppendMessage(ctx);
1102
+ if (isFlushReplay) {
1103
+ log.info(
1104
+ "[context-manager] Manual compaction: flush replay of parked message swallowed - no turn from pre-compaction input",
1105
+ );
1106
+ return { action: "handled" };
1107
+ }
1108
+ }
1109
+ });
1110
+
1111
+ pi.on(SESSION_BEFORE_COMPACT, async (event: any, ctx: ExtensionContext) => {
1112
+ try {
1113
+ const sessionId = getSessionIdSafe(ctx);
1114
+ const leafId = getLeafIdSafe(ctx);
1115
+ // Capture whether a compaction is ALREADY in-flight when this firing
1116
+ // begins (a same-cycle double-fire), BEFORE we mark this cycle active.
1117
+ const wasCompactionInFlight = isCompactionActive(ctx);
1118
+ // P2a: carry the in-flight capture to the outcome stage so an abort of
1119
+ // this cycle can be tagged with whether another compaction was
1120
+ // in-flight. Store before the dedup early-return so even a second
1121
+ // (deduped) firing leaves
1122
+ // the tag for the abort path.
1123
+ try {
1124
+ getCmState(ctx).inFlightBeforeCapture = wasCompactionInFlight;
1125
+ } catch {
1126
+ /* state unavailable - abort tagging degrades to untagged */
1127
+ }
1128
+ setCompactionActive(true, ctx);
1129
+ // Arm the stall watchdog: an in-flight cycle that never reaches an
1130
+ // outcome (a summarization stream stalled mid-flight) must not freeze
1131
+ // the agent. Re-firings of the same cycle just refresh the deadline.
1132
+ armCompactionWatchdog(pi, ctx, { reason: event.reason });
1133
+ // Cycle identity for post-hoc pairing: one monotonic counter per
1134
+ // session_before_compact firing, written into every trace as `cycleId`
1135
+ // so an outcome names the attempt it belongs to rather than being
1136
+ // reconstructable only by entry ordering. Mirrors the watchdog's
1137
+ // per-arm counter.
1138
+ try {
1139
+ const cmc = getCmState(ctx);
1140
+ cmc.compactionCycleId = (cmc.compactionCycleId ?? 0) + 1;
1141
+ } catch {
1142
+ /* state unavailable - cycle id degrades to absent in the trace */
1143
+ }
1144
+ if (!markCompactProcessed(sessionId, leafId, ctx, wasCompactionInFlight)) {
1145
+ log.info("[context-manager] session_before_compact duplicate - skipping");
1146
+ return;
1147
+ }
1148
+ // Fresh cycle: the previous cycle's capture and manual-compaction hold
1149
+ // are spent. Clearing here keeps the capture keyed to THIS cycle (a stale
1150
+ // text would be pre-appended as a duplicate at this cycle's session_compact
1151
+ // and would arm the hold against the wrong message), and disarms a hold
1152
+ // that survived its flush window unspent (e.g. a queue replayed entirely
1153
+ // as commands/steers produced no input event). The new cycle re-arms at
1154
+ // session_compact if it parks a message. The stale cancel source is
1155
+ // cleared too: an unattributed abort of THIS cycle must not inherit the
1156
+ // previous cycle's attribution.
1157
+ try {
1158
+ const ist = getInterceptState(ctx);
1159
+ ist.queuedDuringCompaction = undefined;
1160
+ ist.holdQueuedPrompt = false;
1161
+ ist.heldQueuedText = undefined;
1162
+ // The replay suppression is cycle-scoped: a text parked by the cycle
1163
+ // that just closed must not suppress a seat for the same text typed
1164
+ // into a later cycle.
1165
+ ist.deliveredOwnerInputs = [];
1166
+ } catch {
1167
+ /* intercept state unavailable - fresh-cycle hygiene degrades to no-op */
1168
+ }
1169
+ try {
1170
+ getCmState(ctx).cancelSource = undefined;
1171
+ getCmState(ctx).summaryCapCancelError = undefined;
1172
+ } catch {
1173
+ /* state unavailable - abort attribution degrades to untagged */
1174
+ }
1175
+ // Reset the pre-compaction usage capture so a stale
1176
+ // value from a previous cycle can never trigger a false budget failure at
1177
+ // the outcome stage. A fresh value is stashed below wherever an existing
1178
+ // analyzeSession runs (fingerprint block + STEP 0.75 guard).
1179
+ try {
1180
+ getCmState(ctx).preCompactionUsagePercent = undefined;
1181
+ } catch {
1182
+ /* state unavailable - budget verify degrades to coherence-only */
1183
+ }
1184
+ const prep = event.preparation;
1185
+ // Read once, before any branch that may rewrite event.customInstructions:
1186
+ // the SLIDE_MODE marker decides whether this cycle is the operator's own
1187
+ // deterministic cut (below).
1188
+ const customInstructions: string | undefined = event.customInstructions;
1189
+ const isOperatorSlide =
1190
+ typeof customInstructions === "string" && customInstructions.includes("SLIDE_MODE");
1191
+
1192
+ // Fail-safe rung: the previous cycles each ended with no landed entry
1193
+ // while this session sat above the critical usage band, and the failure
1194
+ // routing armed a deterministic cut rather than trying the summarizer
1195
+ // again. Land it here, BEFORE the blocks below can cancel or hand a span
1196
+ // to a summarizer: pi-core consumes an extension compaction result
1197
+ // verbatim and skips its own call, so this cycle compacts with no LLM
1198
+ // request at all. An operator's own slide keeps precedence and leaves the
1199
+ // cut armed for the next cycle.
1200
+ if (prep && !isOperatorSlide) {
1201
+ const armed = consumeCompactionFailsafeCut(ctx);
1202
+ if (armed) {
1203
+ const cut = buildDeterministicCut(ctx, prep as { tokensBefore?: number }, {
1204
+ reason: armed.reason,
1205
+ detail: "(no summarizer call was attempted for this cut)",
1206
+ });
1207
+ if (cut) {
1208
+ log.error(
1209
+ `[context-manager] Fail-safe cut landing: ${armed.reason} - persisting the ` +
1210
+ `deterministic cut (no LLM summarization)`,
1211
+ );
1212
+ return cut;
1213
+ }
1214
+ // No cut point resolves (branch too short to drop anything). Reset the
1215
+ // ladder instead of re-dispatching per failure, so the next arm needs
1216
+ // a fresh sequence of no-progress cycles.
1217
+ log.error(
1218
+ `[context-manager] Fail-safe cut armed but no cut point resolves ` +
1219
+ `(branch has nothing to drop) - continuing with the normal path`,
1220
+ );
1221
+ clearCompactionFailsafe(ctx);
1222
+ }
1223
+ }
1224
+
1225
+ // If the compaction INPUT is identical to the last SUCCESSFUL compaction
1226
+ // on this leaf, re-summarizing it is pure waste ("silent re-prime
1227
+ // starvation"): the agent keeps receiving the same summary and the
1228
+ // redundant steering (pre-filter, semantic compression, summarization)
1229
+ // burns tokens for zero new value.
1230
+ //
1231
+ // pi-core 0.83.0 (installed) cancel contract — verified:
1232
+ // runner.js:570/586-588 — a session-before handler returning an object
1233
+ // with a truthy `.cancel` short-circuits the event emit.
1234
+ // agent-session.js:1396/1400-1402 (manual compact()) — event.reason ===
1235
+ // "manual"; result?.cancel throws "Compaction cancelled".
1236
+ // agent-session.js:1615-1629 (_runAutoCompaction) — event.reason is the
1237
+ // auto reason ("threshold"|"overflow"); extensionResult?.cancel emits
1238
+ // the internal compaction_end(aborted) plus the extension-visible
1239
+ // session_compact_failed, and returns false (clean no-op, no branch
1240
+ // mutation). So auto vs manual IS distinguishable and the cancel path
1241
+ // is safe for auto.
1242
+ //
1243
+ // Decision rule: cancel ONLY the auto path (reason !== "manual"), and
1244
+ // ONLY when usage < 85 — critical pressure must still compact to avoid
1245
+ // overflow, and manual/agent-initiated compaction is explicit intent that
1246
+ // is never skipped.
1247
+ if (prep?.messagesToSummarize?.length) {
1248
+ const cmState = getCmState(ctx);
1249
+ const leafKey = `${sessionId}::${leafId}`;
1250
+ const branch =
1251
+ typeof ctx.sessionManager?.getBranch === "function"
1252
+ ? (ctx.sessionManager.getBranch() ?? [])
1253
+ : [];
1254
+ const currentFp = computeCompactionFingerprint(
1255
+ branch,
1256
+ prep.messagesToSummarize,
1257
+ (prep as any).firstKeptEntryId,
1258
+ );
1259
+ if (cmState.lastCompactionFingerprints?.[leafKey] === currentFp) {
1260
+ let usagePercent = 0;
1261
+ try {
1262
+ usagePercent = analyzeSession(ctx).usage.percent;
1263
+ // Capture pre-compaction usage for the
1264
+ // outcome-stage budget verify — reuses this analyzeSession (
1265
+ // code path). The STEP 0.75 guard below re-stashes the same value
1266
+ // for the standard path.
1267
+ cmState.preCompactionUsagePercent = usagePercent;
1268
+ } catch {
1269
+ /* non-fatal - analysis unavailable */
1270
+ }
1271
+ const isManual = event.reason === "manual";
1272
+ if (!isManual && usagePercent < 85) {
1273
+ log.info(
1274
+ `[context-manager] Input unchanged since last compaction — skipping ` +
1275
+ `(leaf ${leafKey}, usage ${usagePercent.toFixed(1)}%)`,
1276
+ );
1277
+ // Cancel the auto-compaction: pi-core emits the internal
1278
+ // compaction_end(aborted) plus the extension-visible
1279
+ // session_compact_failed, and returns false — a clean no-op that
1280
+ // leaves the branch untouched. Attribute the cancel so the failed
1281
+ // handler records a deliberate skip, not an unexplained abort.
1282
+ try {
1283
+ getCmState(ctx).cancelSource = "extension";
1284
+ } catch {
1285
+ /* state unavailable - cancel attribution degrades to untagged */
1286
+ }
1287
+ return { cancel: true, reason: "input unchanged since last compaction" };
1288
+ }
1289
+ log.info(
1290
+ `[context-manager] Input unchanged since last compaction but NOT skipping: ` +
1291
+ `${isManual ? "manual intent" : `critical usage ${usagePercent.toFixed(1)}%`}`,
1292
+ );
1293
+ }
1294
+ // Stash the current input fingerprint so session_compact can record it
1295
+ // on success — the branch is mutated by then, so it can't be recomputed.
1296
+ cmState.pendingCompactionFingerprint = currentFp;
1297
+ }
1298
+
1299
+ // Capture the RAW originals for the recovery
1300
+ // archive. Placed AFTER the fingerprint block (which may cancel) and
1301
+ // BEFORE the semantic-compression block (STEP 1.5 replaces
1302
+ // prep.messagesToSummarize in place — capture must see the RAW originals,
1303
+ // byte-exact, independent of later in-place mutation). Serialized to JSON
1304
+ // so the snapshot is immutable; serialization failure degrades the
1305
+ // archive to off and never breaks the compaction path.
1306
+ if (prep?.messagesToSummarize?.length) {
1307
+ try {
1308
+ getCmState(ctx).pendingCompactionOriginals = JSON.stringify(prep.messagesToSummarize);
1309
+ } catch {
1310
+ log.warn("[context-manager] Failed to capture compaction originals for recovery archive");
1311
+ }
1312
+ }
1313
+
1314
+ // Slide mode arrives via customInstructions, set by context_compress action="slide".
1315
+ // When slide mode is active, respond with pi-core's extension-compaction
1316
+ // result: compact() skips the default LLM summarization entirely and
1317
+ // appends this result verbatim (fromExtension=true). Steering
1318
+ // prep.messagesToSummarize=[] alone would still route the stale summary
1319
+ // through the UPDATE prompt — an LLM call re-rendering old content from
1320
+ // an empty conversation, costing output tokens and minutes for zero new
1321
+ // value.
1322
+ if (isOperatorSlide && prep) {
1323
+ const cmState = getCmState(ctx);
1324
+ const slide = cmState.slideMode;
1325
+ if (slide?.active && slide.cutEntryId) {
1326
+ // The stored cut is a supplied boundary: re-snap it against the
1327
+ // branch as it stands at consumption (the armer may have read the
1328
+ // branch before the batch's later results landed). HTTP 400: a kept
1329
+ // slice that opens with a tool result has no preceding tool_calls.
1330
+ const slideBranch =
1331
+ typeof ctx.sessionManager?.getBranch === "function"
1332
+ ? (ctx.sessionManager.getBranch() ?? [])
1333
+ : [];
1334
+ const storedIndex = slideBranch.findIndex(
1335
+ (entry) => (entry as { id?: string })?.id === slide.cutEntryId,
1336
+ );
1337
+ const cutIndex =
1338
+ storedIndex >= 0 ? snapBoundaryOutsideToolBatch(slideBranch, storedIndex) : -1;
1339
+ const cutEntryId =
1340
+ cutIndex >= 0
1341
+ ? ((slideBranch[cutIndex] as { id?: string })?.id ?? slide.cutEntryId)
1342
+ : slide.cutEntryId;
1343
+ const droppedCount = cutIndex >= 0 ? cutIndex : slide.droppedCount;
1344
+ const keptCount = cutIndex >= 0 ? slideBranch.length - cutIndex : slide.keepCount;
1345
+ log.info(
1346
+ `[context-manager] Slide mode: keeping last ${keptCount} entries, ` +
1347
+ `dropping ${droppedCount}`,
1348
+ );
1349
+
1350
+ // Telemetry honesty: the originals capture above snapshotted
1351
+ // pi-core's DEFAULT token-cut summarize set, not the deterministic
1352
+ // span this cycle actually drops. Replace it with the dropped span
1353
+ // so the compacted/kept counters and the originals archive describe
1354
+ // THIS cut, not the token-budget cut pi-core would have made.
1355
+ captureDroppedSpanBefore(ctx, cutEntryId);
1356
+
1357
+ // One-shot consumption so a later normal compaction is unaffected.
1358
+ cmState.slideMode = null;
1359
+
1360
+ return {
1361
+ compaction: {
1362
+ summary:
1363
+ `Sliding window compaction: dropped the ${droppedCount} entries before the ` +
1364
+ `cut; the last ${keptCount} entries remain live. Deterministic entry cut — ` +
1365
+ `dropped content is preserved in the append-only session file and the originals archive.`,
1366
+ firstKeptEntryId: cutEntryId,
1367
+ tokensBefore: typeof prep.tokensBefore === "number" ? prep.tokensBefore : 0,
1368
+ details: { readFiles: [], modifiedFiles: [] },
1369
+ },
1370
+ };
1371
+ } else {
1372
+ log.warn(
1373
+ "[context-manager] SLIDE_MODE marker found but slide state is missing or inactive",
1374
+ );
1375
+ }
1376
+ }
1377
+
1378
+ // Set by context_compress(action="archive"): the user declared a range
1379
+ // [startIndex..endIndex] plus a summary that must anchor the compaction.
1380
+ // Apply firstKeptEntryId = <entry after endIndex> so the declared range is
1381
+ // the real compaction boundary, keep messagesToSummarize = the declared
1382
+ // span (it SHOULD be summarized), and render the user summary as an anchor
1383
+ // in the compaction instructions so the LLM carries intent, changes,
1384
+ // decisions, and next steps forward (the research-grounded anchor model).
1385
+ const rangeMode = getCmState(ctx).rangeMode;
1386
+ if (prep && rangeMode?.active) {
1387
+ const branch: Array<{ id: string; type?: string; message?: any }> =
1388
+ typeof ctx.sessionManager?.getBranch === "function"
1389
+ ? (ctx.sessionManager.getBranch() ?? [])
1390
+ : [];
1391
+ const spanMessages = collectRangeMessages(branch, rangeMode.startIndex, rangeMode.endIndex);
1392
+
1393
+ // The declared boundary is a supplied one: snap it out of any tool
1394
+ // batch it lands in (HTTP 400: a kept slice that opens with a tool
1395
+ // result has no preceding tool_calls), against the branch as it
1396
+ // stands at consumption.
1397
+ let boundaryId = rangeMode.firstKeptEntryId;
1398
+ if (boundaryId) {
1399
+ const storedIndex = branch.findIndex((entry) => entry.id === boundaryId);
1400
+ if (storedIndex >= 0) {
1401
+ const snappedIndex = snapBoundaryOutsideToolBatch(branch, storedIndex);
1402
+ boundaryId = branch[snappedIndex]?.id ?? boundaryId;
1403
+ }
1404
+ (prep as any).firstKeptEntryId = boundaryId;
1405
+ }
1406
+ (prep as any).messagesToSummarize = spanMessages;
1407
+ // No split-turn prefix summary — the declared span IS the summarize set.
1408
+ (prep as any).turnPrefixMessages = [];
1409
+ (prep as any).isSplitTurn = false;
1410
+
1411
+ // Telemetry honesty (same convention as the slide branch): the capture
1412
+ // above snapshotted pi-core's default token-cut span, not the declared
1413
+ // range this cycle actually summarizes. Replace it with the span.
1414
+ try {
1415
+ getCmState(ctx).pendingCompactionOriginals = JSON.stringify(spanMessages);
1416
+ } catch {
1417
+ /* capture replacement unavailable - telemetry degrades to the default snapshot */
1418
+ }
1419
+
1420
+ // Anchor the user summary into the compaction instructions. pi-core
1421
+ // does not read this channel back (see the dead-code gap note below);
1422
+ // the chunked takeover below folds the anchor into its own prompts.
1423
+ event.customInstructions = [
1424
+ `Declared archive range for this compaction: entries [${rangeMode.startIndex}..${rangeMode.endIndex}] (topic: "${rangeMode.topic}").`,
1425
+ `The user supplied the following anchor summary — fold its intent, changes made, decisions, and next steps into the new compaction summary; keep this substance intact:`,
1426
+ `---ANCHOR---`,
1427
+ rangeMode.summary,
1428
+ `---END ANCHOR---`,
1429
+ ].join("\n");
1430
+
1431
+ // Stash the declaration so a failed cycle can re-arm it on its
1432
+ // summary-cap retry (retry cycles recompute pi-core's default span,
1433
+ // which would silently drop the declared range).
1434
+ getCmState(ctx).pendingRangeArchive = { ...rangeMode };
1435
+ // Reset range mode so subsequent compactions are unaffected.
1436
+ getCmState(ctx).rangeMode = null;
1437
+
1438
+ log.info(
1439
+ `[context-manager] Range mode: archiving entries [${rangeMode.startIndex}..${rangeMode.endIndex}], ` +
1440
+ `${spanMessages.length} messages to summarize, boundary ${boundaryId ?? "branch-end"}`,
1441
+ );
1442
+
1443
+ // Bounded takeover: summarize the declared span in chunked calls
1444
+ // (reasoning off, fixed per-call output budget, previous summary and
1445
+ // anchor merged) and hand pi-core the finished summary as an extension
1446
+ // compaction result. The declared range never reaches a summarizer as
1447
+ // one giant call — that is the range-archive shape: a single
1448
+ // 185-message call length-stops and the archive lands
1449
+ // with no summary at all.
1450
+ const chunked = await summarizeSpanInChunks({
1451
+ ctx,
1452
+ span: spanMessages,
1453
+ anchor: { topic: rangeMode.topic, summary: rangeMode.summary },
1454
+ previousSummary: (prep as any).previousSummary,
1455
+ signal: (event as { signal?: AbortSignal }).signal,
1456
+ logPrefix: "Range archive summary",
1457
+ });
1458
+ if (!("error" in chunked)) {
1459
+ // Landed: the stash is consumed (the success handler also clears it,
1460
+ // this just avoids a window where a stale stash outlives the cycle).
1461
+ getCmState(ctx).pendingRangeArchive = undefined;
1462
+ return {
1463
+ compaction: {
1464
+ summary: chunked.summary,
1465
+ firstKeptEntryId: (prep as any).firstKeptEntryId,
1466
+ tokensBefore: typeof prep.tokensBefore === "number" ? prep.tokensBefore : 0,
1467
+ details: { readFiles: [], modifiedFiles: [] },
1468
+ ...(chunked.usage ? { usage: chunked.usage } : {}),
1469
+ },
1470
+ };
1471
+ }
1472
+ // Summary-cap class: a bounded failure must stay bounded. Handing the
1473
+ // span to pi-core's default summarizer is the one recovery that cannot
1474
+ // work for the class that made the bounded path necessary — an
1475
+ // observed failure (a 750-message span) shows the shape: chunk
1476
+ // capped -> fall-through -> pi-core's single unbounded call capped too
1477
+ // -> retry ladder burned on calls that could never complete. Cancel
1478
+ // the cycle instead; the failed routing attributes the cancel
1479
+ // (cancelSource "summary-cap") and re-arms the bounded recovery, with
1480
+ // the stash surviving to re-arm the declared range.
1481
+ if (chunked.failureClass === "summary-cap") {
1482
+ log.error(
1483
+ `[context-manager] Range archive chunked summary failed (${chunked.error}) — ` +
1484
+ `bounded failure, cancelling the cycle (no fall-through to pi-core's unbounded summarizer)`,
1485
+ );
1486
+ const cmState = getCmState(ctx);
1487
+ cmState.cancelSource = "summary-cap";
1488
+ cmState.summaryCapCancelError = chunked.error;
1489
+ // A cancelled cycle never fires session_compact, so the retry guard
1490
+ // it set stays true and the ladder then answers "already active" for
1491
+ // every later retry — the armed bounded recovery starves. This
1492
+ // cycle is over; release the guard.
1493
+ const wasRetryCycle = cmState.compactionRetryActive === true;
1494
+ cmState.compactionRetryActive = false;
1495
+ if (wasRetryCycle) {
1496
+ // Never block: the bounded summarizer already had its retry cycle,
1497
+ // so the next move is deterministic instead of a third cancel that
1498
+ // leaves the session unable to compact at all.
1499
+ const cut = buildDeterministicCut(ctx, prep as { tokensBefore?: number });
1500
+ if (cut) {
1501
+ log.error(
1502
+ `[context-manager] Range archive chunked summary failed twice - persisting the ` +
1503
+ `deterministic cut (no LLM summarization)`,
1504
+ );
1505
+ return cut;
1506
+ }
1507
+ }
1508
+ return { cancel: true };
1509
+ }
1510
+ log.error(
1511
+ `[context-manager] Range archive chunked summary failed (${chunked.error}) — ` +
1512
+ `falling through to pi-core's default summarization`,
1513
+ );
1514
+ // Fall through: the span stays replaced; pi-core summarizes it. That
1515
+ // call is pi-core's own, so arm the thinking-off switch for it. The
1516
+ // stash STAYS: if pi-core's call dies with a summary-cap failure, the
1517
+ // failed routing re-arms the declared range on the retry cycle.
1518
+ armSummarizerThinkingOff(pi, ctx);
1519
+ return;
1520
+ }
1521
+
1522
+ // When context exceeds CONTEXT_COMPACT_REFUSE_PERCENT (owner:
1523
+ // lib/detection/context-thresholds.ts), ANY compaction path (manual context_compress or
1524
+ // pi-core auto-compaction) can cause "max call stack" crashes that corrupt
1525
+ // session state and lead to 403 provider errors. We auto-redirect to a
1526
+ // deterministic entry-based CUT POINT (slide-mode behavior). The cut is
1527
+ // applied to pi-core's boundary-aware preparation: the guard never widens
1528
+ // messagesToSummarize back to the raw branch head, and it never hands the
1529
+ // summarizer a span that pi-ai's request clamp would strangle (that span is
1530
+ // persisted as a deterministic cut instead). The normal summarization
1531
+ // machinery below (STEP 1/1.5/2) still produces a substantive summary
1532
+ // whenever the prepared span fits the window.
1533
+ //
1534
+ // This covers both compaction paths because both fire session_before_compact.
1535
+ // The existing guard in context_compress(action="compact") only covers the
1536
+ // manual tool path. Auto-compaction bypasses that guard entirely.
1537
+ if (prep?.messagesToSummarize?.length) {
1538
+ try {
1539
+ let usagePercent = 0;
1540
+ try {
1541
+ const audit = analyzeSession(ctx);
1542
+ usagePercent = audit.usage.percent;
1543
+ // Capture pre-compaction usage for the
1544
+ // outcome-stage budget verify — reuses this analyzeSession (the
1545
+ // first unconditional one in the handler).
1546
+ try {
1547
+ getCmState(ctx).preCompactionUsagePercent = usagePercent;
1548
+ } catch {
1549
+ /* state unavailable - budget verify degrades to coherence-only */
1550
+ }
1551
+ } catch {
1552
+ // Non-fatal - analysis unavailable
1553
+ }
1554
+
1555
+ if (
1556
+ usagePercent > CONTEXT_COMPACT_REFUSE_PERCENT &&
1557
+ !event.customInstructions?.includes("SLIDE_MODE")
1558
+ ) {
1559
+ const sm = ctx.sessionManager;
1560
+ const branch = typeof sm.getBranch === "function" ? sm.getBranch() : [];
1561
+ const keepCount = Math.min(50, Math.max(10, Math.floor(branch.length * 0.3)));
1562
+ // The guard arms a supplied boundary: snap it out of any tool batch
1563
+ // it lands in (HTTP 400: a kept slice that opens with a tool result
1564
+ // has no preceding tool_calls).
1565
+ const cutIndex = snapBoundaryOutsideToolBatch(
1566
+ branch,
1567
+ Math.max(0, branch.length - keepCount),
1568
+ );
1569
+ const cutEntryId = branch[cutIndex]?.id;
1570
+ const keptCount = branch.length - cutIndex;
1571
+
1572
+ if (cutEntryId && cutIndex > 0) {
1573
+ // Store slide state for audit trail (session_compact handler reads it).
1574
+ const cmState = getCmState(ctx);
1575
+ cmState.slideMode = {
1576
+ active: true,
1577
+ cutEntryId,
1578
+ keepCount: keptCount,
1579
+ droppedCount: cutIndex,
1580
+ timestamp: Date.now(),
1581
+ };
1582
+
1583
+ // pi-core's preparation is boundary-aware: messagesToSummarize starts
1584
+ // after the last persisted compaction boundary and ends at pi-core's own
1585
+ // cut point. Replacing it with the raw branch head re-summarizes content
1586
+ // the persisted summaries already cover and can push the span past the
1587
+ // window (the strangle class this guard exists for). Keep the prepared
1588
+ // span; shrink it only when it overlaps the entries this deterministic
1589
+ // cut keeps live, shrinking in place so the boundary-aware start survives.
1590
+ // A span lying entirely inside the kept region is left alone: trimming it
1591
+ // to the cut would empty the summarize set (the defect class this guard
1592
+ // exists for).
1593
+ // The messages are the same object references as branch[i].message
1594
+ // (pi-core's prepareCompaction pushes entry.message), so the span's
1595
+ // branch indices are recoverable by identity.
1596
+ const spanMessages = prep.messagesToSummarize as unknown[];
1597
+ const spanRefs = new Set(spanMessages);
1598
+ let spanStart = -1;
1599
+ let spanLast = -1;
1600
+ for (let i = 0; i < branch.length; i++) {
1601
+ const entry = branch[i];
1602
+ if (entry?.type === "message" && entry.message && spanRefs.has(entry.message)) {
1603
+ if (spanStart < 0) spanStart = i;
1604
+ spanLast = i;
1605
+ }
1606
+ }
1607
+ // Exclusive end of the prepared span: pi-core's kept-region anchor when
1608
+ // it resolves in the branch (it can sit past the span on split turns),
1609
+ // else the entry after the span's last message.
1610
+ const preparedKeepEntryId = (prep as any).firstKeptEntryId;
1611
+ const preparedKeepIndex =
1612
+ typeof preparedKeepEntryId === "string"
1613
+ ? branch.findIndex((entry) => entry.id === preparedKeepEntryId)
1614
+ : -1;
1615
+ const spanEnd = preparedKeepIndex >= 0 ? preparedKeepIndex : spanLast + 1;
1616
+ const spanResolved = spanStart >= 0;
1617
+ const shrinksSpan = spanResolved && spanStart <= cutIndex - 1 && spanEnd > cutIndex;
1618
+ const summarySpan = shrinksSpan
1619
+ ? collectRangeMessages(branch, spanStart, cutIndex - 1)
1620
+ : spanMessages;
1621
+
1622
+ // Mirror pi-ai's request-side clamp (simple-options.js:6-12:
1623
+ // available = window - estimate(prompt) - 4096). A span whose estimate
1624
+ // no longer fits leaves max_tokens at its 1-token floor, the provider
1625
+ // returns an empty length-stopped summary, and pi-core refuses to
1626
+ // persist it - the compaction aborts and re-fires every turn. Never
1627
+ // hand the summarizer such a span: persist the deterministic cut
1628
+ // instead (pi-core consumes an extension compaction result verbatim
1629
+ // and skips its summarization call).
1630
+ const window = resolveWindow(ctx?.model?.contextWindow).contextWindow;
1631
+ const spanEstimate = estimateMessagesTokens(summarySpan);
1632
+ if (spanEstimate + 4096 >= window) {
1633
+ // Telemetry honesty, same convention as the slide branch: the
1634
+ // originals capture above snapshotted pi-core's default span, not
1635
+ // the deterministic cut this cycle persists.
1636
+ captureDroppedSpanBefore(ctx, cutEntryId);
1637
+ log.warn(
1638
+ `[context-manager] High-context guard: dropped-span estimate ${spanEstimate} ` +
1639
+ `+ 4096 safety >= window ${window} - deterministic cut without LLM ` +
1640
+ `summarization (keep ${keptCount}/${branch.length}, dropped ${cutIndex} ` +
1641
+ `entries before ${cutEntryId}).`,
1642
+ );
1643
+ return {
1644
+ compaction: {
1645
+ summary:
1646
+ `High-context deterministic cut: dropped the ${cutIndex} entries before the cut ` +
1647
+ `without LLM summarization (the summary span would not fit the configured ` +
1648
+ `context window: estimated ${spanEstimate} tokens plus 4096 safety >= ${window}). ` +
1649
+ `The last ${keptCount} entries remain live; dropped content stays in the ` +
1650
+ `append-only session file and the originals archive.`,
1651
+ firstKeptEntryId: cutEntryId,
1652
+ tokensBefore: typeof prep.tokensBefore === "number" ? prep.tokensBefore : 0,
1653
+ details: { readFiles: [], modifiedFiles: [] },
1654
+ },
1655
+ };
1656
+ }
1657
+
1658
+ if (shrinksSpan) {
1659
+ (prep as any).messagesToSummarize = summarySpan;
1660
+ (prep as any).turnPrefixMessages = [];
1661
+ (prep as any).isSplitTurn = false;
1662
+ (prep as any).firstKeptEntryId = cutEntryId;
1663
+ log.warn(
1664
+ `[context-manager] High-context compact guard triggered: ` +
1665
+ `${usagePercent.toFixed(1)}% > ${CONTEXT_COMPACT_REFUSE_PERCENT}%. ` +
1666
+ `Deterministic cut: keep ${keptCount}/${branch.length} entries; prepared ` +
1667
+ `span trimmed to [${spanStart}..${cutIndex - 1}].`,
1668
+ );
1669
+ } else {
1670
+ log.warn(
1671
+ `[context-manager] High-context compact guard triggered: ` +
1672
+ `${usagePercent.toFixed(1)}% > ${CONTEXT_COMPACT_REFUSE_PERCENT}%. ` +
1673
+ `Prepared boundary-aware span preserved unchanged ` +
1674
+ `(the deterministic cut [..${cutIndex - 1}] requires no trim).`,
1675
+ );
1676
+ }
1677
+ } else {
1678
+ // Edge case: can't determine cut point - log and fall through.
1679
+ log.warn(
1680
+ `[context-manager] High-context guard: context at ${usagePercent.toFixed(1)}% ` +
1681
+ `but could not determine cut point (branch=${branch.length}, cutEntryId=${cutEntryId}). ` +
1682
+ `Falling through to normal compaction path.`,
1683
+ );
1684
+ }
1685
+ }
1686
+ } catch (err) {
1687
+ // If guard itself fails, fall through to normal compaction without modifying prep.
1688
+ log.error("[context-manager] High-context guard error, falling through:", err);
1689
+ }
1690
+ }
1691
+
1692
+ // Removes duplicate reads, resolved errors, oversized non-critical outputs.
1693
+ // Reduces context before LLM call so LLM summarization has an easier job.
1694
+ if (prep?.messagesToSummarize?.length) {
1695
+ // Type bridge: filterSafeToRemove uses its own AgentMessage interface;
1696
+ // pi's messagesToSummarize uses pi's AgentMessage. Structurally compatible.
1697
+ const { filtered, stats } = filterSafeToRemove(prep.messagesToSummarize as FilterMessage[]);
1698
+ if (stats.totalRemoved > 0) {
1699
+ const pct = Math.round((1 - stats.afterTokens / stats.beforeTokens) * 100);
1700
+ log.info(
1701
+ `[context-manager] Pre-filter: removed ${stats.totalRemoved} messages ` +
1702
+ `(from ${stats.beforeTokens} to ${stats.afterTokens} tokens, saved ~${pct}%)`,
1703
+ );
1704
+ (prep as Preparation).messagesToSummarize = filtered;
1705
+ }
1706
+ }
1707
+
1708
+ // Compresses semantic units (redundant tool results, bloated reasoning chains,
1709
+ // low-value exchanges) before LLM summarization.
1710
+ // Uses adaptive compression level based on session state (turn count,
1711
+ // context usage %) to control how aggressively we compress.
1712
+ if (prep?.messagesToSummarize?.length) {
1713
+ try {
1714
+ // Determine adaptive compression level from session metrics
1715
+ const audit = analyzeSession(ctx);
1716
+ // Use current session context usage instead of cross-session peak
1717
+ // (getPeakUsagePercent leaked peakUsage across sessions, causing
1718
+ // aggressive compression in sessions that never hit high usage).
1719
+ const currentUsage = audit.usage.percent;
1720
+ // ExtensionContext has no turnCount - use audit.branchLength as proxy
1721
+ const proxyTurnCount = audit.branchLength ?? 0;
1722
+ const decision = await determineCompressionLevel(ctx, {
1723
+ turnCount: proxyTurnCount,
1724
+ turnsSinceCompression:
1725
+ proxyTurnCount - (getCmState(ctx).lastCompressionStats?.turnRange?.to ?? 0),
1726
+ consecutiveFailures: 0,
1727
+ reasoningChainDepth: audit.recommendations.length > 3 ? 4 : 1,
1728
+ messageCount: prep.messagesToSummarize.length,
1729
+ });
1730
+ const baseLevel = decision.level;
1731
+ // Escalate compression level when current context is near-full
1732
+ const compressionLevel =
1733
+ currentUsage > 85
1734
+ ? baseLevel === "short-term"
1735
+ ? "medium-term"
1736
+ : "long-term"
1737
+ : baseLevel;
1738
+
1739
+ const { compressed, stats: scStats } = semanticCompress(
1740
+ (prep as Preparation).messagesToSummarize as CoreAgentMessage[],
1741
+ compressionLevel,
1742
+ );
1743
+ if (scStats.messagesOut < scStats.messagesIn) {
1744
+ log.info(
1745
+ `[context-manager] Semantic compress[${compressionLevel}]: ` +
1746
+ `${scStats.messagesIn}->${scStats.messagesOut} msgs ` +
1747
+ `(${scStats.unitsCollapsed} collapsed, ${scStats.unitsDropped} dropped)`,
1748
+ );
1749
+ (prep as Preparation).messagesToSummarize = compressed;
1750
+
1751
+ // Store compression metadata for retrieval quality scoring
1752
+ try {
1753
+ const state = getCmState(ctx);
1754
+ state.lastCompressionStats = {
1755
+ ...scStats,
1756
+ turnRange: {
1757
+ from: proxyTurnCount,
1758
+ to: proxyTurnCount,
1759
+ },
1760
+ timestamp: Date.now(),
1761
+ };
1762
+ } catch {
1763
+ log.warn("[context-manager] failed to emit end-of-turn context signal");
1764
+ }
1765
+ }
1766
+ } catch (err) {
1767
+ log.error("session_before_compact semantic compression error:", err);
1768
+ }
1769
+ }
1770
+
1771
+ // Bounded recovery for a summary token-cap failure (class "summary-cap"):
1772
+ // the retry cycle re-enters here, and instead of replaying the same
1773
+ // oversized single call, the span is summarized in bounded chunks with
1774
+ // reasoning off (compaction-chunked.ts), then handed to pi-core as an
1775
+ // extension compaction result. Requires the armed recovery flag AND an
1776
+ // active retry cycle — a stale flag never hijacks a user compaction.
1777
+ if (prep?.messagesToSummarize?.length) {
1778
+ try {
1779
+ const cmState = getCmState(ctx);
1780
+ const recovery = cmState.pendingSummaryCapRecovery;
1781
+ if (recovery && cmState.compactionRetryActive) {
1782
+ cmState.pendingSummaryCapRecovery = undefined;
1783
+ log.info(
1784
+ `[context-manager] Summary-cap recovery (attempt ${recovery.attempt}): ` +
1785
+ `summarizing the ${prep.messagesToSummarize.length}-message span in bounded chunks, reasoning off`,
1786
+ );
1787
+ const chunked = await summarizeSpanInChunks({
1788
+ ctx,
1789
+ span: prep.messagesToSummarize as unknown[],
1790
+ anchor: recovery.anchor,
1791
+ previousSummary: (prep as any).previousSummary,
1792
+ signal: (event as { signal?: AbortSignal }).signal,
1793
+ logPrefix: `Summary-cap recovery (attempt ${recovery.attempt})`,
1794
+ });
1795
+ if (!("error" in chunked)) {
1796
+ return {
1797
+ compaction: {
1798
+ summary: chunked.summary,
1799
+ firstKeptEntryId: (prep as any).firstKeptEntryId,
1800
+ tokensBefore: typeof prep.tokensBefore === "number" ? prep.tokensBefore : 0,
1801
+ details: { readFiles: [], modifiedFiles: [] },
1802
+ ...(chunked.usage ? { usage: chunked.usage } : {}),
1803
+ },
1804
+ };
1805
+ }
1806
+ if (chunked.failureClass === "summary-cap") {
1807
+ log.error(
1808
+ `[context-manager] Summary-cap recovery chunked summary failed (${chunked.error}) — ` +
1809
+ `bounded failure, cancelling the cycle (no fall-through to pi-core's unbounded summarizer)`,
1810
+ );
1811
+ const cmState = getCmState(ctx);
1812
+ cmState.cancelSource = "summary-cap";
1813
+ cmState.summaryCapCancelError = chunked.error;
1814
+ // This cycle IS the retry (the recovery only runs on one), so the
1815
+ // ladder ends here: release the guard and take the deterministic
1816
+ // cut instead of cancelling into a session that cannot compact.
1817
+ cmState.compactionRetryActive = false;
1818
+ const cut = buildDeterministicCut(ctx, prep as { tokensBefore?: number });
1819
+ if (cut) {
1820
+ log.error(
1821
+ `[context-manager] Summary-cap recovery failed - persisting the deterministic ` +
1822
+ `cut (no LLM summarization)`,
1823
+ );
1824
+ return cut;
1825
+ }
1826
+ return { cancel: true };
1827
+ }
1828
+ log.error(
1829
+ `[context-manager] Summary-cap recovery chunked summary failed (${chunked.error}) — ` +
1830
+ `falling through to pi-core's default summarization`,
1831
+ );
1832
+ // Fall through to pi-core's own call — arm the thinking switch.
1833
+ armSummarizerThinkingOff(pi, ctx);
1834
+ }
1835
+ } catch (err) {
1836
+ log.error("[context-manager] summary-cap recovery error:", err);
1837
+ }
1838
+ }
1839
+
1840
+ // pi core passes these to the LLM summarization call. The LLM handles all
1841
+ // chunking - we just tell it WHAT to preserve.
1842
+ // NOTE (pi-core 0.84.2 dead-code gap): event.customInstructions is NOT read
1843
+ // back by pi-core (verified agent-session.js:1422/1665) — preparation
1844
+ // steering (messagesToSummarize, firstKeptEntryId, turnPrefixMessages,
1845
+ // isSplitTurn) is the only channel that takes effect. Kept for forward
1846
+ // compatibility with pi-core versions that do read it.
1847
+ const audit = analyzeSession(ctx);
1848
+ const instructions = buildCompactionInstructions(audit);
1849
+ if (instructions.length > 0) {
1850
+ event.customInstructions = instructions.join(" ");
1851
+ }
1852
+
1853
+ try {
1854
+ eventBus.emit({
1855
+ type: "memory_evict",
1856
+ reason: "context compaction",
1857
+ count: prep?.messagesToSummarize?.length ?? 0,
1858
+ });
1859
+ } catch {
1860
+ log.warn("[context-manager] failed to emit memory_evict event");
1861
+ }
1862
+
1863
+ // This cycle hands its span to pi-core's summarizer: keep reasoning out
1864
+ // of the summary budget (switch helper above).
1865
+ if (prep?.messagesToSummarize?.length) {
1866
+ armSummarizerThinkingOff(pi, ctx);
1867
+ }
1868
+ } catch (err) {
1869
+ log.error("session_before_compact error:", err);
1870
+ }
1871
+ });
1872
+ }
1873
+
1874
+ // Session Compact (success only)
1875
+ // session_compact fires ONLY on successful compaction. pi-core 0.85.1 has no
1876
+ // `compaction_end` extension event: the post-compaction outcome handling lives
1877
+ // in registerSessionCompactOutcomeHandler (a second, deliberately separate
1878
+ // session_compact stage below) and the failure handling in
1879
+ // registerSessionCompactFailedHandler on session_compact_failed.
1880
+
1881
+ export function registerSessionCompactHandler(pi: ExtensionAPI): void {
1882
+ pi.on(SESSION_COMPACT, async (event: any, ctx: ExtensionContext) => {
1883
+ try {
1884
+ // The compaction completed: the cycle's dedup-relevant in-flight phase is
1885
+ // over. A later cycle on the same leaf must run (no lifetime block) while
1886
+ // the in-cycle double-fire stays deduped — see markCompactProcessed.
1887
+ setCompactionActive(false, ctx);
1888
+ // Cycle outcome arrived: disarm the stall watchdog.
1889
+ clearCompactionWatchdog(ctx);
1890
+ // The cycle LANDED an entry: that is progress, so the fail-safe ladder is
1891
+ // broken and the retry dispatch (if any) is over. Cleared here, before the
1892
+ // parking work below can throw, so a landed compaction can never leave a
1893
+ // cut armed against an unrelated later cycle.
1894
+ try {
1895
+ clearCompactionFailsafe(ctx);
1896
+ settleCompactionRetry();
1897
+ settleOverflowRetry();
1898
+ } catch {
1899
+ /* state unavailable - fail-safe bookkeeping degrades to the failure path */
1900
+ }
1901
+
1902
+ const entry = event.compactionEntry;
1903
+
1904
+ // Pattern 8: record the compaction-input fingerprint for this leaf so a
1905
+ // later auto-compaction with an identical input can be skipped. The
1906
+ // fingerprint was stashed at session_before_compact (before the branch
1907
+ // was mutated) and is only recorded here, on SUCCESS.
1908
+ try {
1909
+ const cmState = getCmState(ctx);
1910
+ if (cmState.pendingCompactionFingerprint) {
1911
+ const key = `${getSessionIdSafe(ctx)}::${getLeafIdSafe(ctx)}`;
1912
+ cmState.lastCompactionFingerprints ??= {};
1913
+ cmState.lastCompactionFingerprints[key] = cmState.pendingCompactionFingerprint;
1914
+ cmState.pendingCompactionFingerprint = undefined;
1915
+ }
1916
+ } catch {
1917
+ /* state unavailable - fingerprint skip degrades to off */
1918
+ }
1919
+
1920
+ if (entry) {
1921
+ addEvidence(
1922
+ ctx,
1923
+ "context_compacted",
1924
+ "session",
1925
+ `Context compressed: ${entry.summary?.slice(0, 80) ?? "no summary"}`,
1926
+ 0.8,
1927
+ );
1928
+ }
1929
+
1930
+ // FIX: Pre-append the user's queued message to sessionManager BEFORE
1931
+ // compaction_end fires (which triggers TUI's rebuildChatFromMessages).
1932
+ // Intercept appendMessage to skip the duplicate from flushCompactionQueue's
1933
+ // session.prompt() -> message_end -> appendMessage call.
1934
+ const st = getInterceptState(ctx);
1935
+ if (st.queuedDuringCompaction) {
1936
+ // Delivery through the shared park path: session write + force-persist
1937
+ // + the appendMessage wrapper that dedups the flush replay. The text
1938
+ // leaves the pending seat here - a landed cycle delivered it.
1939
+ const parked = parkOwnerTextInSession(ctx, st.queuedDuringCompaction);
1940
+ if (parked) {
1941
+ // Manual compaction: full stop. Arm the one-shot hold so the TUI
1942
+ // flush's replay prompt is swallowed in the input hook instead of
1943
+ // starting a turn from pre-compaction input. Auto reasons keep the
1944
+ // flush replay as their resume and are never armed. Snapshot the
1945
+ // text so later capture clears cannot retarget the hold.
1946
+ if (event?.reason === "manual") {
1947
+ st.holdQueuedPrompt = true;
1948
+ st.heldQueuedText = st.queuedDuringCompaction;
1949
+ log.info(
1950
+ "[context-manager] Manual compaction: hold armed - queued message will not resume the turn",
1951
+ );
1952
+ }
1953
+ } else {
1954
+ // The cycle landed but the write path was unavailable. The seat keeps
1955
+ // the text for the settle flush; it must not be cleared here.
1956
+ log.error(
1957
+ "[context-manager] Failed to park the queued message - it stays seated for the settle flush",
1958
+ );
1959
+ }
1960
+ // NOTE: st.queuedDuringCompaction stays set after intercept setup.
1961
+ // It must survive until flushCompactionQueue's session.prompt()
1962
+ // fires AFTER session_compact returns, so skipDuplicateAppend can
1963
+ // detect the duplicate user message. Cleared on turn_end or abort.
1964
+ }
1965
+
1966
+ // NOTE: Do NOT inject a resume steer here.
1967
+ // The queued message's lifecycle after a manual compaction is: parked via
1968
+ // the pre-append above, its flush replay swallowed by the input-hook hold
1969
+ // (no turn from pre-compaction input; the operator sends the next input
1970
+ // themselves). After an auto compaction (threshold/overflow) the flush
1971
+ // replay IS the resume: it fires message_start/message_end, is persisted
1972
+ // by sessionManager, and renders in the TUI. The steer from agent.steer()
1973
+ // is delivered via agent-loop _steeringMessages, never emits message_start/
1974
+ // message_end events, never reaches sessionManager.appendMessage(), and is
1975
+ // invisible in both the TUI and session tree. Adding it would only add noise
1976
+ // to agent context without any user-visible benefit.
1977
+
1978
+ // Clear overflow notification flag and retry guards on success.
1979
+ const cmState = getCmState(ctx);
1980
+ cmState.overflowNotified = false;
1981
+ cmState.compactionRetryActive = false;
1982
+ cmState.overflowRetryActive = false;
1983
+ // A landed compaction consumes the range stash and any armed recovery
1984
+ // (normally already consumed by the owning branch), and restores the
1985
+ // summarizer thinking switch this cycle armed.
1986
+ cmState.pendingRangeArchive = undefined;
1987
+ cmState.pendingSummaryCapRecovery = undefined;
1988
+ restoreSummarizerThinkingLevel(pi, ctx);
1989
+ } catch (err) {
1990
+ log.error("session_compact error:", err);
1991
+ }
1992
+ });
1993
+ }
1994
+
1995
+ /**
1996
+ * Concatenated text of a user message's content parts ("" when none). Used as
1997
+ * the delivery proof for a seated owner input, so the comparison is exact.
1998
+ */
1999
+ function userMessageText(content: unknown): string {
2000
+ if (typeof content === "string") return content;
2001
+ if (!Array.isArray(content)) return "";
2002
+ return content
2003
+ .filter(
2004
+ (part): part is { type?: string; text?: string } => typeof part === "object" && part !== null,
2005
+ )
2006
+ .map((part) => (typeof part.text === "string" ? part.text : ""))
2007
+ .join("");
2008
+ }
2009
+
2010
+ // Session Compact Outcome (success shape on session_compact)
2011
+ // pi-core 1.0.1 has no `compaction_end` extension event. The post-compaction
2012
+ // outcome (verify + telemetry + the always-on originals archive) rides
2013
+ // session_compact, fired ONCE per landed compaction entry, after
2014
+ // registerSessionCompactHandler's parking stage above. The event still carries
2015
+ // willRetry, but on 1.0.1 it means "pi will retry the aborted turn after this
2016
+ // compaction" (overflow recovery) - not "this is an intermediate firing". The
2017
+ // overflow-recovery compaction IS the one that rescued the session, so its
2018
+ // outcome must be verified and archived exactly like any other; skipping it
2019
+ // silently lost both the verify stage and the originals archive for that path.
2020
+ // session_compact_failed is the only failure signal (see the handler below).
2021
+
2022
+ interface SessionCompactOutcomeEvent {
2023
+ compactionEntry?: {
2024
+ id?: string;
2025
+ summary?: string;
2026
+ firstKeptEntryId?: string;
2027
+ tokensBefore?: number;
2028
+ };
2029
+ /** Cycle trigger: manual | threshold | overflow. */
2030
+ reason?: string;
2031
+ willRetry?: boolean;
2032
+ }
2033
+
2034
+ export function registerSessionCompactOutcomeHandler(pi: ExtensionAPI): void {
2035
+ onEvent(
2036
+ pi,
2037
+ SESSION_COMPACT,
2038
+ async (event: SessionCompactOutcomeEvent, _ctx: ExtensionContext) => {
2039
+ try {
2040
+ // Cycle outcome (intermediate or final): restore the summarizer
2041
+ // thinking switch this cycle may have armed. Idempotent no-op when
2042
+ // the switch was never armed.
2043
+ restoreSummarizerThinkingLevel(pi, _ctx);
2044
+
2045
+ const entry = event.compactionEntry;
2046
+ if (!entry) return;
2047
+
2048
+ // A stale originals capture must never leak into a later cycle. Snapshot it into a local for the always-on archive
2049
+ // write below, then clear the session state; the archive write
2050
+ // consumes and clears it in finally.
2051
+ let pendingCompactionOriginals: string | undefined;
2052
+ try {
2053
+ const cmState = getCmState(_ctx);
2054
+ pendingCompactionOriginals = cmState.pendingCompactionOriginals;
2055
+ cmState.pendingCompactionOriginals = undefined;
2056
+ } catch {
2057
+ /* state unavailable - archive write degrades to off */
2058
+ }
2059
+ // Compacted-vs-kept message counter, snapped once per cycle so
2060
+ // post-hoc loss questions are answerable from telemetry. compacted =
2061
+ // this cycle's raw summarization input (the originals capture — what
2062
+ // the summary replaced); kept = messages still live from the
2063
+ // firstKeptEntryId anchor to the branch end. Both degrade to undefined
2064
+ // — absent, never wrong.
2065
+ const compactedMessages = countSummarizedMessages(pendingCompactionOriginals);
2066
+ let keptMessages: number | undefined;
2067
+ try {
2068
+ const sm = _ctx.sessionManager as {
2069
+ getBranch?: () => Array<{ id: string; type?: string; message?: any }>;
2070
+ };
2071
+ const branch = typeof sm?.getBranch === "function" ? (sm.getBranch() ?? []) : [];
2072
+ keptMessages = countKeptMessages(branch, entry.firstKeptEntryId);
2073
+ } catch {
2074
+ /* branch unavailable - kept count degrades to absent */
2075
+ }
2076
+
2077
+ // Verify the completed compaction BEFORE recording success. Coherence
2078
+ // (non-empty summary + first-kept anchor) and budget (post-compaction
2079
+ // usage dropped below pre-compaction usage) must both pass; otherwise
2080
+ // the "success" is a silent context destroyer and must be reported
2081
+ // honestly as a failure. No destructive rollback — originals remain in
2082
+ // the append-only branch and are recoverable via context_navigate/archive.
2083
+ let preCompactionUsagePercent: number | undefined;
2084
+ try {
2085
+ preCompactionUsagePercent = getCmState(_ctx).preCompactionUsagePercent;
2086
+ } catch {
2087
+ /* state unavailable - budget verify degrades to coherence-only */
2088
+ }
2089
+ let cycleId: number | undefined;
2090
+ try {
2091
+ cycleId = getCmState(_ctx).compactionCycleId;
2092
+ } catch {
2093
+ /* state unavailable - cycle id degrades to absent */
2094
+ }
2095
+ const verify = verifyCompactionResult(
2096
+ { compactionEntry: entry, firstKeptEntryId: entry.firstKeptEntryId },
2097
+ _ctx,
2098
+ preCompactionUsagePercent,
2099
+ );
2100
+ if (!verify.ok) {
2101
+ recordCompactionOutcome("failure", {
2102
+ errorMessage: `verify: ${verify.reason}`,
2103
+ });
2104
+ // Feed outcome into advice-tracker for retry strategy adjustment
2105
+ recordAdvice("compaction", "failure", 0);
2106
+ log.error(
2107
+ `[context-manager] Compaction verify FAILED — ${verify.reason}; ` +
2108
+ `originals preserved in branch, use context_navigate/archive to recover`,
2109
+ );
2110
+ // Durable trace: the session file gains one entry naming the
2111
+ // verify class (coherence/budget), the span size, and the retry
2112
+ // count, so the rollback is visible after the fact.
2113
+ writeCompactionTrace(pi, _ctx, {
2114
+ event: "verify-failed",
2115
+ reason: event.reason,
2116
+ failureClass: String(verify.reason).startsWith("coherence:")
2117
+ ? "verify-coherence"
2118
+ : "verify-budget",
2119
+ errorMessage: `verify: ${verify.reason}`,
2120
+ spanMessages: compactedMessages,
2121
+ retryAttempt: 0,
2122
+ willRetry: false,
2123
+ cycleId,
2124
+ });
2125
+ try {
2126
+ const cmState = getCmState(_ctx);
2127
+ cmState.verifyFailed = true;
2128
+ // A verify rejection is a rollback (loss) — count it distinctly
2129
+ // from generic failures so the telemetry can measure the
2130
+ // verify/rollback stage.
2131
+ recordCompactionHealth("totalVerifyFailures");
2132
+ // The append-only originals archive also writes on the
2133
+ // verify-failure path (always-on / lossless default), with the
2134
+ // verify rejection as the reason. WriteOriginalsArchive clears
2135
+ // verifyFailed + pendingCompactionOriginals in finally.
2136
+ writeOriginalsArchive(_ctx, verify.reason, pendingCompactionOriginals, {
2137
+ compactedMessages,
2138
+ keptMessages,
2139
+ });
2140
+ } catch {
2141
+ /* state unavailable - archive write degrades to off */
2142
+ }
2143
+ return;
2144
+ }
2145
+ log.info("[context-manager] Compaction completed successfully");
2146
+ // The outcome carries the compacted-vs-kept message counter.
2147
+ // entriesRemoved (existing CompactionHealth field) records the
2148
+ // compacted side cumulatively; the kept side + both counts land in the
2149
+ // per-compaction archive line below. The same counters also surface as
2150
+ // the lastCompactedMessages/lastKeptMessages health fields, rendered by
2151
+ // formatCompactionLossLine in context_inspect.
2152
+ recordCompactionOutcome("success", {
2153
+ entriesRemoved: compactedMessages,
2154
+ compactedMessages,
2155
+ keptMessages,
2156
+ });
2157
+ log.info(
2158
+ `[context-manager] Compaction outcome: ` +
2159
+ `${compactedMessages ?? "?"} message(s) compacted into summary, ` +
2160
+ `${keptMessages ?? "?"} kept live (anchor ${entry.firstKeptEntryId ?? "none"})`,
2161
+ );
2162
+ // Always-on append-only originals archive on the healthy path too:
2163
+ // the raw originals this compaction replaced are preserved
2164
+ // even when verification passes (lossless default). reason="compact"
2165
+ // (the healthy path has no verify reason).
2166
+ writeOriginalsArchive(_ctx, "compact", pendingCompactionOriginals, {
2167
+ compactedMessages,
2168
+ keptMessages,
2169
+ });
2170
+ // Feed outcome into advice-tracker for retry strategy adjustment
2171
+ recordAdvice("compaction", "success", 0);
2172
+ } catch (err) {
2173
+ log.error("session_compact outcome error:", err);
2174
+ }
2175
+ },
2176
+ );
2177
+
2178
+ // message_end backup cleanup
2179
+ // Catches edge cases where turn_end is missed (no tools called that turn).
2180
+ // Ensures intercept state is always cleaned up before the next assistant turn.
2181
+ onEvent(pi, MESSAGE_END, async (_event, _ctx) => {
2182
+ // Delivery proof for a seated owner input: a consumed steer and a flush
2183
+ // replay both land as user messages, while text pi never consumed never
2184
+ // appears.
2185
+ const message = (_event as { message?: { role?: string; content?: unknown } } | null)?.message;
2186
+ if (message?.role === "user") {
2187
+ const text = userMessageText(message.content);
2188
+ if (text) {
2189
+ let confirmed = false;
2190
+ let parked = false;
2191
+ try {
2192
+ const st = getInterceptState(_ctx);
2193
+ confirmed = st.pendingOwnerInputs.some((i) => i.text === text);
2194
+ parked = st.deliveredOwnerInputs.includes(text);
2195
+ if (confirmed) markOwnerInputDelivered(_ctx, text);
2196
+ } catch {
2197
+ /* state unavailable - confirmation degrades to the settle flush */
2198
+ }
2199
+ // Do NOT unwrap on the delivery of a text this extension parked: pi
2200
+ // persists this message right after extension handlers run, and the
2201
+ // wrapper is what skips the duplicate entry. The next unrelated
2202
+ // message_end (or input) restores it.
2203
+ if (confirmed || parked) return;
2204
+ }
2205
+ }
2206
+ tryRestoreAppendMessage(_ctx);
2207
+ });
2208
+
2209
+ // Settle reconciliation
2210
+ // The run has settled: deliver seated owner input that no queue will carry
2211
+ // any further. pi's own queue is checked first, so an unconsumed steer
2212
+ // (drained by the next run's start) is never double-delivered.
2213
+ onEvent(pi, AGENT_SETTLED, async (_event, _ctx) => {
2214
+ try {
2215
+ flushPendingOwnerInputs(_ctx, "settle");
2216
+ } catch (err) {
2217
+ log.error("session settle owner-input flush error:", err);
2218
+ }
2219
+ });
2220
+ }
2221
+
2222
+ // Session Compact Failed (failure + abort)
2223
+ // session_compact_failed fires when a compaction cycle does not land an entry:
2224
+ // the model call failed, the fingerprint skip cancelled the cycle, or the user
2225
+ // aborted. Owns the failure/abort cleanup the previous (never-fired)
2226
+ // compaction_end registration carried: dedup guard reset, stale capture clear,
2227
+ // intercept restore, and the failure routing into the retry machinery
2228
+ // (compaction-retry.ts) that schedules ctx.compact() retries.
2229
+
2230
+ interface SessionCompactFailedShape {
2231
+ reason?: string;
2232
+ errorMessage?: string;
2233
+ aborted?: boolean;
2234
+ /**
2235
+ * pi's retry flag. On 1.0.1 it is ALWAYS false on session_compact_failed:
2236
+ * all three emit sites pass it literally (a returned compaction snapshot is
2237
+ * the only setter, and a returned compaction never fails). Kept in the shape
2238
+ * and the trace because it is pi's contract and may return.
2239
+ */
2240
+ willRetry?: boolean;
2241
+ /**
2242
+ * Whether the failed content came from this extension's own
2243
+ * session_before_compact result (pi-core's fromExtension flag).
2244
+ */
2245
+ fromExtension?: boolean;
2246
+ }
2247
+
2248
+ export function registerSessionCompactFailedHandler(pi: ExtensionAPI): void {
2249
+ onEvent(
2250
+ pi,
2251
+ SESSION_COMPACT_FAILED,
2252
+ async (event: SessionCompactFailedShape, _ctx: ExtensionContext) => {
2253
+ try {
2254
+ setCompactionActive(false, _ctx);
2255
+ // Cycle outcome arrived: restore the summarizer thinking switch this
2256
+ // cycle may have armed, and disarm the stall watchdog. Read the armed
2257
+ // timestamp and the cycle id BEFORE clearing the watchdog: the failure
2258
+ // trace below carries both (only the watchdog stall path
2259
+ // populates durationMs).
2260
+ restoreSummarizerThinkingLevel(pi, _ctx);
2261
+ let cycleId: number | undefined;
2262
+ try {
2263
+ cycleId = getCmState(_ctx).compactionCycleId;
2264
+ } catch {
2265
+ /* state unavailable - cycle id degrades to absent */
2266
+ }
2267
+ let durationMs: number | undefined;
2268
+ try {
2269
+ const armedAt = getCompactionWatchdogArmedAt(_ctx);
2270
+ if (typeof armedAt === "number") durationMs = Date.now() - armedAt;
2271
+ } catch {
2272
+ /* state unavailable - duration degrades to absent */
2273
+ }
2274
+ clearCompactionWatchdog(_ctx);
2275
+ // The cycle never landed an entry: clear the dedup guard so the next
2276
+ // compaction can run, and drop the pending fingerprint (the input was
2277
+ // never compacted, so it must not be recorded as processed).
2278
+ clearProcessedCompacts(getSessionIdSafe(_ctx), getLeafIdSafe(_ctx));
2279
+ try {
2280
+ getCmState(_ctx).pendingCompactionFingerprint = undefined;
2281
+ } catch {
2282
+ /* state unavailable */
2283
+ }
2284
+ // Span size for the trace: read the pending originals capture BEFORE
2285
+ // the clear below consumes it. Degrades to absent, never wrong.
2286
+ let spanMessages: number | undefined;
2287
+ try {
2288
+ spanMessages = countSpanMessages(getCmState(_ctx).pendingCompactionOriginals);
2289
+ } catch {
2290
+ /* state unavailable - span degrades to absent */
2291
+ }
2292
+ // Resolve who cancelled the cycle (extension skip vs watchdog vs
2293
+ // external), then consume the marker so it never leaks into a later
2294
+ // cycle's abort attribution.
2295
+ let cancelSource: string | undefined;
2296
+ let cancelSummaryCapError: string | undefined;
2297
+ try {
2298
+ cancelSource = getCmState(_ctx).cancelSource;
2299
+ getCmState(_ctx).cancelSource = undefined;
2300
+ // Carried with the "summary-cap" cancel: the bounded path's real
2301
+ // error text (names the capped chunk). Consumed with the source so
2302
+ // it never outlives the cycle.
2303
+ cancelSummaryCapError = getCmState(_ctx).summaryCapCancelError;
2304
+ getCmState(_ctx).summaryCapCancelError = undefined;
2305
+ } catch {
2306
+ /* state unavailable - untagged */
2307
+ }
2308
+ // Non-destructive failure: a cycle that landed no entry must not
2309
+ // consume parked owner text. It is delivered now when the session is
2310
+ // idle (re-queued through the same session write the success path
2311
+ // uses) or kept pending for the settle boundary; the durable seat
2312
+ // already holds it either way. clearInterceptState drops only the
2313
+ // intercept window - the seat list survives it.
2314
+ flushPendingOwnerInputs(_ctx, "failure");
2315
+ // Restore intercept state: flushCompactionQueue won't fire on failure,
2316
+ // so message_end won't trigger the normal restoration path. If we
2317
+ // don't clean up here, the wrapper stays in place and a future message
2318
+ // with matching text would be incorrectly skipped.
2319
+ tryRestoreAppendMessage(_ctx);
2320
+ clearInterceptState(_ctx);
2321
+ // A stale originals capture must never leak into a later cycle. The
2322
+ // compaction failed, so the branch still carries the originals -
2323
+ // there is nothing to archive, just clear the capture.
2324
+ try {
2325
+ getCmState(_ctx).pendingCompactionOriginals = undefined;
2326
+ } catch {
2327
+ /* state unavailable */
2328
+ }
2329
+
2330
+ // Durable trace on EVERY failed/aborted/cancelled firing. On 1.0.1
2331
+ // pi sends willRetry:false on all three emit sites, so this is the
2332
+ // final outcome of a cycle, never an intermediate retry; the field
2333
+ // stays recorded because it is pi's contract. The post-mortem triad
2334
+ // (failure class, span size, retry count) plus fromExtension and the
2335
+ // cycle id are only reconstructable from the entry sequence. The entry
2336
+ // is a plain custom entry: it lands in the session file and never
2337
+ // participates in the LLM context.
2338
+ // A "summary-cap" cancelSource is an extension cancel (no
2339
+ // errorMessage, aborted=true by pi-core's shape), which classifies as
2340
+ // "aborted"; the honest class is the one that caused the cancel.
2341
+ let failureClass = classifyCompactionFailure(event);
2342
+ if (failureClass === "aborted" && cancelSource === "summary-cap") {
2343
+ failureClass = "summary-cap";
2344
+ }
2345
+ writeCompactionTrace(pi, _ctx, {
2346
+ event: event.aborted ? "aborted" : "failure",
2347
+ reason: event.reason,
2348
+ failureClass,
2349
+ errorMessage:
2350
+ event.errorMessage ??
2351
+ (failureClass === "summary-cap" ? cancelSummaryCapError : undefined),
2352
+ spanMessages,
2353
+ retryAttempt:
2354
+ event.reason === "overflow" ? overflowRetryState.attempt : compactionRetryState.attempt,
2355
+ willRetry: event.willRetry,
2356
+ fromExtension: event.fromExtension,
2357
+ cycleId,
2358
+ cancelSource,
2359
+ durationMs,
2360
+ });
2361
+
2362
+ // pi core is retrying - nothing to do, let pi handle it. On 1.0.1
2363
+ // willRetry is always false here (a returned compaction snapshot is
2364
+ // the only setter, and a returned compaction does not fail), so this
2365
+ // branch is unreachable today; it stays because it is pi's contract.
2366
+ if (event.willRetry) return;
2367
+
2368
+ // This cycle is over and it landed no entry. Release the dispatch
2369
+ // guards the cycle held: they exist to stop a second compaction being
2370
+ // dispatched INTO a live cycle; releasing them only on success leaves
2371
+ // the first failed retry guarding the session for good - every later
2372
+ // dispatch then logs "already active"
2373
+ // and reset the ladder, so the exhausted rungs were unreachable.
2374
+ settleCompactionRetry();
2375
+ settleOverflowRetry();
2376
+ try {
2377
+ const cmState = getCmState(_ctx);
2378
+ cmState.compactionRetryActive = false;
2379
+ cmState.overflowRetryActive = false;
2380
+ } catch {
2381
+ /* state unavailable - the next dispatch's own guard check decides */
2382
+ }
2383
+
2384
+ // Fail-safe accounting: a cycle that lands no entry while the session
2385
+ // sits above the critical band is one turn of a loop, not an incident.
2386
+ // Count it and, once the loop is established, arm the deterministic cut
2387
+ // for the next cycle - the per-cycle routing below has no view of the
2388
+ // repetition, and at this usage every rung it can reach either asks the
2389
+ // operator to act (emergency rotation) or tries a summarizer that has
2390
+ // just failed. An extension cancel is the operator's own decision to
2391
+ // skip (unchanged input), so it is not counted as no progress.
2392
+ if (cancelSource !== "extension") {
2393
+ try {
2394
+ const noProgress = noteCompactionNoProgress(_ctx);
2395
+ if (noProgress >= COMPACTION_NO_PROGRESS_LIMIT) {
2396
+ const usagePercent = getCmState(_ctx).preCompactionUsagePercent;
2397
+ if (typeof usagePercent === "number" && usagePercent >= USAGE_WHISPER_CRITICAL) {
2398
+ const failSafeReason =
2399
+ `fail-safe after ${noProgress} consecutive compaction cycles landed no entry ` +
2400
+ `at ${usagePercent.toFixed(0)}% context`;
2401
+ if (armCompactionFailsafeCut(_ctx, failSafeReason)) {
2402
+ log.error(
2403
+ `[context-manager] Compaction fail-safe armed: ${failSafeReason} - the next cycle ` +
2404
+ `compacts deterministically (no LLM summarization)`,
2405
+ );
2406
+ triggerFailsafeCompaction(_ctx);
2407
+ }
2408
+ }
2409
+ }
2410
+ } catch {
2411
+ /* state unavailable - a session without fail-safe bookkeeping keeps
2412
+ the pre-existing per-cycle routing */
2413
+ }
2414
+ }
2415
+
2416
+ const { reason, aborted, errorMessage } = event;
2417
+
2418
+ // Aborted - user cancelled. Record the abort in loss telemetry, tagged
2419
+ // with whether a compaction was in-flight when the aborted cycle began
2420
+ // (the inFlightBefore capture from session_before_compact). Aborts are
2421
+ // counted distinctly from failures and successes.
2422
+ if (aborted) {
2423
+ // A watchdog cancel is a stall, not an operator abort: the cycle
2424
+ // died on a hung summarization stream and was killed by the stall
2425
+ // watchdog's ctx.abort(). Record it as a failure and re-issue a
2426
+ // bounded retry through the existing machinery, so a recoverable
2427
+ // stream cut does not leave the context uncompacted and the turn
2428
+ // stuck above its threshold.
2429
+ if (cancelSource === "watchdog") {
2430
+ const watchdogMessage =
2431
+ errorMessage ??
2432
+ `watchdog: compaction stalled >${Math.round(COMPACTION_STALL_THRESHOLD_MS / 1000)}s`;
2433
+ recordCompactionOutcome("failure", { errorMessage: watchdogMessage });
2434
+ recordAdvice("compaction", "failure", 0);
2435
+ if (reason === "overflow") {
2436
+ handleOverflowFailure(pi, event, _ctx, watchdogMessage);
2437
+ } else {
2438
+ handleThresholdFailure(pi, event, _ctx, watchdogMessage);
2439
+ }
2440
+ return;
2441
+ }
2442
+ // A summary-cap cancel came from this extension's bounded path
2443
+ // (chunked split failed with the summary-cap class and the cycle was
2444
+ // cancelled instead of falling through to pi-core's unbounded
2445
+ // summarizer). Route it exactly like a pi-core summary-cap failure:
2446
+ // the bounded recovery re-arms (with the range stash folded in) and
2447
+ // the retry ladder advances. A cancel is not a user abort — the
2448
+ // agent never pressed ESC here.
2449
+ if (cancelSource === "summary-cap") {
2450
+ recordCompactionOutcome("failure", { errorMessage: cancelSummaryCapError });
2451
+ recordAdvice("compaction", "failure", 0);
2452
+ // Watchdog rule: a summary-cap abort at the critical band lands one
2453
+ // deterministic slide, so the class can never be terminal (the
2454
+ // bounded retry can wedge on "already active"). Runs before the
2455
+ // retry arms, so the armed cut is visible to that retry cycle.
2456
+ handleSummaryCapAbort(pi, _ctx, {
2457
+ errorMessage: cancelSummaryCapError,
2458
+ spanMessages,
2459
+ });
2460
+ handleSummaryCapFailure(pi, event, _ctx, cancelSummaryCapError);
2461
+ return;
2462
+ }
2463
+ let inFlightBeforeAbort = false;
2464
+ try {
2465
+ inFlightBeforeAbort = getCmState(_ctx).inFlightBeforeCapture ?? false;
2466
+ } catch {
2467
+ /* state unavailable - untagged abort */
2468
+ }
2469
+ recordCompactionOutcome("aborted", { inFlight: inFlightBeforeAbort });
2470
+ return;
2471
+ }
2472
+
2473
+ // Summary token-cap failure: the generation hit its output budget
2474
+ // before the summary completed (class "summary-cap"). Not a context
2475
+ // emergency — recover with a
2476
+ // bounded chunked summary on the retry cycle. Checked before the
2477
+ // context-window branch: a cap failure is about the OUTPUT budget,
2478
+ // not the input fit, and must not be routed into window-error advice.
2479
+ if (classifyCompactionFailure(event) === "summary-cap") {
2480
+ recordCompactionOutcome("failure", { errorMessage });
2481
+ recordAdvice("compaction", "failure", 0);
2482
+ // Watchdog rule (see the cancel branch above): one deterministic
2483
+ // slide per cooldown window at the critical band.
2484
+ handleSummaryCapAbort(pi, _ctx, { errorMessage, spanMessages });
2485
+ handleSummaryCapFailure(pi, event, _ctx, errorMessage);
2486
+ return;
2487
+ }
2488
+
2489
+ // Context window error - context too large even for LLM summarization
2490
+ if (isContextWindowError(errorMessage)) {
2491
+ recordCompactionOutcome("failure", { errorMessage });
2492
+ // Feed outcome into advice-tracker for retry strategy adjustment
2493
+ recordAdvice("compaction", "failure", 0);
2494
+ handleContextWindowError(pi, event, _ctx, errorMessage);
2495
+ return;
2496
+ }
2497
+
2498
+ // Threshold/manual compaction failure
2499
+ if (reason === "threshold" || reason === "manual") {
2500
+ handleThresholdFailure(pi, event, _ctx, errorMessage);
2501
+ return;
2502
+ }
2503
+
2504
+ // Overflow recovery failure
2505
+ if (reason === "overflow") {
2506
+ handleOverflowFailure(pi, event, _ctx, errorMessage);
2507
+ return;
2508
+ }
2509
+
2510
+ // Transient server error (529, 500, network)
2511
+ if (isTransientCompactionError(errorMessage)) {
2512
+ handleTransientError(pi, event, _ctx, errorMessage);
2513
+ return;
2514
+ }
2515
+
2516
+ // The failed cycle's range stash was consumed by the summary-cap
2517
+ // routing (re-armed as range mode) or is stale — never outlive the
2518
+ // cycle.
2519
+ try {
2520
+ getCmState(_ctx).pendingRangeArchive = undefined;
2521
+ } catch {
2522
+ /* state unavailable */
2523
+ }
2524
+ } catch (err) {
2525
+ log.error("session_compact_failed error:", err);
2526
+ }
2527
+ },
2528
+ );
2529
+
2530
+ // Session lifecycle cleanup
2531
+ // Prevents _processedCompacts memory leak across sessions. Module-level state
2532
+ // must be explicitly cleared; LRU eviction alone is insufficient for
2533
+ // long-running agent processes with many session rotations.
2534
+ onEvent(pi, SESSION_SHUTDOWN, (_event, ctx) => {
2535
+ _processedCompacts.clear();
2536
+ // The retry ladders and the fail-safe are module-level and session-scoped
2537
+ // respectively: neither may outlive the session that armed it. A stale
2538
+ // in-flight marker would block the next session's turn-end resets, and an
2539
+ // armed cut belongs to the session that earned it.
2540
+ resetCompactionRetry();
2541
+ resetOverflowRetry();
2542
+ // A shutdown must not leave a stall timer holding a dying session's ctx,
2543
+ // nor a switched summarizer thinking level armed across the crash.
2544
+ try {
2545
+ clearCompactionWatchdog(ctx);
2546
+ clearCompactionFailsafe(ctx);
2547
+ restoreSummarizerThinkingLevel(pi, ctx);
2548
+ } catch {
2549
+ /* state unavailable */
2550
+ }
2551
+ });
2552
+ }