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,1333 @@
1
+ /**
2
+ * context_compress - Free up context space by compaction, archiving, or deep-clean.
3
+ *
4
+ * One tool for context_compact, context_archive, context_prune, and the
5
+ * tag-based/percentage/keepRecentTurns range params.
6
+ *
7
+ * Capabilities:
8
+ * - Tag-based archive range (startTag / endTag / beforeTag)
9
+ * - Percentage-based range (range: "80%")
10
+ * - Keep-recent-turns shortcut (keepRecentTurns: 20)
11
+ * - Token-savings feedback after archive
12
+ * - "deep_clean" meta-action: tag + archive + compact in one call
13
+ */
14
+
15
+ import { Type } from "typebox";
16
+ import type { CompactOptions, ExtensionAPI } from "@earendil-works/pi-coding-agent";
17
+ import { getExtensionState, readExtensionState } from "../../../../../lib/state/extension-state.js";
18
+ import { onEvent } from "../../../../../lib/events/event-types.js";
19
+ import {
20
+ TOOL_EXECUTION_START,
21
+ TOOL_EXECUTION_END,
22
+ AGENT_SETTLED,
23
+ TURN_END,
24
+ } from "../../../../../lib/core/event-names.js";
25
+ import { analyzeSession } from "../../analysis.js";
26
+ import * as timerMod from "../../../../scheduling/timer/index.js";
27
+ import { getState } from "../../../../enforcement/state.js";
28
+ import { CONTEXT_COMPACT_REFUSE_PERCENT } from "../../../../../lib/detection/context-thresholds.js";
29
+ import { getCmState, isCompactionActive, log, recordNavigationAction } from "../shared.js";
30
+ import { snapBoundaryOutsideToolBatch } from "../tool-batch-boundary.js";
31
+ import { formatTokensK } from "../../../../../lib/detection/context-usage.js";
32
+ import { formatLocalTime } from "../../../../../lib/utils/local-time.js";
33
+ import {
34
+ getAutoCompactConfig,
35
+ type ResolvedAutoCompactConfig,
36
+ } from "../../../../../lib/config/braid-settings.js";
37
+
38
+ // Helpers
39
+
40
+ /**
41
+ * Resolve a tag name to a branch entry index by scanning the session branch
42
+ * for entries whose label matches `tagName`. Returns -1 if not found.
43
+ */
44
+ function resolveTagToIndex(ctx: any, tagName: string): number {
45
+ try {
46
+ const sm = ctx.sessionManager;
47
+ if (!sm) return -1;
48
+ const branch = sm.getBranch() ?? [];
49
+ for (let i = 0; i < branch.length; i++) {
50
+ const label = sm.getLabel?.(branch[i].id);
51
+ if (label === tagName) return i;
52
+ }
53
+ return -1;
54
+ } catch {
55
+ return -1;
56
+ }
57
+ }
58
+
59
+ /**
60
+ * Capture current context usage for pre/post feedback.
61
+ */
62
+ function captureUsage(ctx: any): { percent: number; tokens: number; contextWindow: number } | null {
63
+ try {
64
+ const audit = analyzeSession(ctx);
65
+ return audit.usage;
66
+ } catch {
67
+ return null;
68
+ }
69
+ }
70
+
71
+ // Batch-settle compaction scheduler.
72
+ // Contract: the tool returns its result FIRST (execute() resolves before a
73
+ // compaction is armed), but ctx.compact() — which aborts the turn — fires only
74
+ // at a safe boundary: agent_settled (the run fully settled, abort a clean
75
+ // no-op) or turn_end inside a live run (the turn's messages and tool results
76
+ // are already persisted; the abort lands between turns, where a queued steer
77
+ // is appended before the loop polls the abort signal and its turn runs on the
78
+ // post-compaction resume). Firing on the first tool_execution_end where
79
+ // inFlight reaches 0 aborts a still-live run (the agent is streaming its
80
+ // response to the context_compress result), surfacing a spurious "This
81
+ // operation was aborted" error in the TUI and tearing the finishing turn.
82
+ // agent_settled alone never drains a run kept alive by continuous steers —
83
+ // the armed compaction stalls behind live work while usage keeps climbing,
84
+ // hence the turn_end boundary.
85
+
86
+ interface PendingCompaction {
87
+ /** Which action armed this entry. */
88
+ kind: "compact" | "archive" | "deep_clean" | "slide";
89
+ trigger: () => void;
90
+ armedAt: number;
91
+ /** Slide entry: branch id of the first kept entry (the deterministic cut). */
92
+ cutEntryId?: string;
93
+ /** Archive entry: branch id of the first kept entry (the declared boundary). */
94
+ firstKeptEntryId?: string;
95
+ }
96
+
97
+ interface BatchSettleState {
98
+ /** In-flight tool executions for the current batch (per session). */
99
+ inFlight: number;
100
+ /** Pending compactions armed by context_compress actions, drained at settle. */
101
+ pending: PendingCompaction[];
102
+ }
103
+
104
+ /**
105
+ * The pending list is bounded: one entry per armed action, capped so a
106
+ * pathological re-arming loop cannot grow it without bound. Beyond the cap the
107
+ * NEWEST entry is dropped (log) — at drain time the FIRST-armed entry is the
108
+ * one that fires (first-armed-wins for LLM-class, earliest-cut for slides), so
109
+ * dropping the oldest would discard the very compaction the queue exists to
110
+ * land. Slides beyond the first are redundant by construction (the drain
111
+ * coalesces to the earliest cut), so a dropped newest entry loses nothing.
112
+ */
113
+ const PENDING_COMPACT_QUEUE_MAX = 8;
114
+
115
+ function getBatchSettleState(ctx: any): BatchSettleState {
116
+ return getExtensionState(ctx, "context-manager/batch-settle", () => ({
117
+ inFlight: 0,
118
+ pending: [],
119
+ }));
120
+ }
121
+
122
+ /**
123
+ * Read the pending queue without creating state (inspect surfaces it).
124
+ * Exported so context_inspect and the heartbeat advisory can report
125
+ * armed-but-unfired compactions.
126
+ */
127
+ export function readPendingCompactions(ctx: any): Array<{ kind: string; armedAt: number }> {
128
+ try {
129
+ const st = readExtensionState<BatchSettleState>(ctx, "context-manager/batch-settle");
130
+ return (st?.pending ?? []).map(({ kind, armedAt }) => ({ kind, armedAt }));
131
+ } catch {
132
+ return [];
133
+ }
134
+ }
135
+
136
+ /** LLM-class kinds carry a declared range/anchor state at arm time. */
137
+ function isLlmClass(kind: string): boolean {
138
+ return kind === "compact" || kind === "archive" || kind === "deep_clean";
139
+ }
140
+
141
+ /**
142
+ * True when an LLM-class compaction is already armed and unfired. A second
143
+ * LLM-class arm must be refused BEFORE it writes its own range/anchor state:
144
+ * the drain fires the first-armed trigger, so a later arm would silently
145
+ * overwrite the range state the first trigger consumes (clobber-class loss).
146
+ */
147
+ export function hasPendingLlmCompaction(ctx: any): boolean {
148
+ return readPendingCompactions(ctx).some((p) => isLlmClass(p.kind));
149
+ }
150
+
151
+ /**
152
+ * One pending-state line for the armed-but-unfired compaction queue
153
+ * ("slide armed 17:28 — fires at the next turn boundary; live usage drops
154
+ * when it lands"). Null when nothing is pending: no surface may fabricate an
155
+ * expectation of a drop that is not armed. Shared by context_inspect and the
156
+ * heartbeat advisory so both state the same fact the same way.
157
+ */
158
+ export function formatPendingCompactionsLine(ctx: any): string | null {
159
+ const pending = readPendingCompactions(ctx);
160
+ if (pending.length === 0) return null;
161
+ const newest = pending.reduce((a, b) => (b.armedAt > a.armedAt ? b : a));
162
+ const kinds = [...new Set(pending.map((p) => p.kind))].join("+");
163
+ const armedClock = formatLocalTime(new Date(newest.armedAt));
164
+ return (
165
+ `${kinds} armed ${armedClock} — fires at the next turn boundary (turn end or run settle); ` +
166
+ `until then live usage reads pre-compaction state`
167
+ );
168
+ }
169
+
170
+ /**
171
+ * Coalesce a multi-entry queue into ONE deterministic slide compaction:
172
+ * the cut lands at the EARLIEST declared boundary (a pending slide's cut or
173
+ * an archive's firstKeptEntryId), so everything each declaration promised to
174
+ * keep stays live, and the archive anchor/summary record (appended to the
175
+ * session at arm time, inside the kept span) survives. Returns the trigger
176
+ * to fire, or null when no cut point resolves (fire-first fallback).
177
+ */
178
+ function coalesceIntoSlide(ctx: any, queue: PendingCompaction[]): { trigger: () => void } | null {
179
+ try {
180
+ const branch: Array<{ id: string }> = ctx?.sessionManager?.getBranch?.() ?? [];
181
+ const indexById = new Map(branch.map((e, i) => [e.id, i] as const));
182
+ let cutIndex = -1;
183
+ for (const entry of queue) {
184
+ const id = entry.kind === "slide" ? entry.cutEntryId : entry.firstKeptEntryId;
185
+ if (!id) continue;
186
+ const idx = indexById.get(id);
187
+ if (idx !== undefined && (cutIndex === -1 || idx < cutIndex)) cutIndex = idx;
188
+ }
189
+ if (cutIndex < 0) return null;
190
+ // The coalesced cut is a supplied boundary: snap it out of any tool batch
191
+ // it lands in (HTTP 400: a kept slice that opens with a tool result has no
192
+ // preceding tool_calls).
193
+ const snappedIndex = snapBoundaryOutsideToolBatch(branch, cutIndex);
194
+ const cutEntryId = branch[snappedIndex].id;
195
+ // Re-point the slide state the SLIDE_MODE compaction branch consumes.
196
+ getCmState(ctx).slideMode = {
197
+ active: true,
198
+ cutEntryId,
199
+ keepCount: branch.length - snappedIndex,
200
+ droppedCount: snappedIndex,
201
+ timestamp: Date.now(),
202
+ };
203
+ const slideEntry = queue.find((p) => p.kind === "slide")!;
204
+ return { trigger: slideEntry.trigger };
205
+ } catch {
206
+ return null;
207
+ }
208
+ }
209
+
210
+ function firePendingCompactionsIfSettled(ctx: any, st: BatchSettleState): void {
211
+ if (st.pending.length === 0 || st.inFlight > 0) return;
212
+ const queue = st.pending;
213
+ st.pending = [];
214
+ let trigger = queue[0].trigger;
215
+ let summary = queue.map((p) => p.kind).join(", ");
216
+ if (queue.length > 1) {
217
+ const coalesced = queue.some((p) => p.kind === "slide") ? coalesceIntoSlide(ctx, queue) : null;
218
+ if (coalesced) {
219
+ trigger = coalesced.trigger;
220
+ summary = `slide subsuming (${summary})`;
221
+ } else if (queue.some((p) => p.kind === "slide")) {
222
+ // Slide present but no cut point resolved: the slide trigger still runs
223
+ // (its own slide state was armed at arm time).
224
+ trigger = queue.find((p) => p.kind === "slide")!.trigger;
225
+ summary = `slide-first (${summary})`;
226
+ } else {
227
+ // LLM-class only (compact/archive/deep_clean): the FIRST armed wins.
228
+ // Its range/anchor state was persisted at arm time and steers the
229
+ // compaction it fires; a second back-to-back LLM compaction would run
230
+ // on the first's output for nothing.
231
+ summary = `first-armed (${summary})`;
232
+ }
233
+ log.info(
234
+ `[context-compress] ${queue.length} pending compactions coalesced at settle: ${summary}`,
235
+ );
236
+ }
237
+ // Defer to a macrotask so the current batch's tool-result messages (emitted
238
+ // right after each tool_execution_end) land before the aborting compact.
239
+ setTimeout(() => {
240
+ try {
241
+ trigger();
242
+ } catch {
243
+ // Tool already disconnected - non-fatal
244
+ }
245
+ }, 0);
246
+ }
247
+
248
+ /**
249
+ * Bounded deferral for the DEGRADED compaction path (batch-settle bookkeeping
250
+ * unavailable): a few ticks so a still-executing parallel sibling has a chance
251
+ * to land its result, but NEVER a raw setTimeout(0) — that is the exact
252
+ * mid-batch abort race this scheduler exists to remove. Exported (with
253
+ * `scheduleDegradedCompact`) so the deferral contract is directly testable.
254
+ */
255
+ export const DEGRADED_DEFERRAL_MS = 150;
256
+
257
+ /** Schedule `trigger` on the bounded degraded deferral (see DEGRADED_DEFERRAL_MS). */
258
+ export function scheduleDegradedCompact(trigger: () => void): void {
259
+ setTimeout(trigger, DEGRADED_DEFERRAL_MS);
260
+ }
261
+
262
+ /**
263
+ * Arm a one-shot compaction at a safe boundary (next turn end or run settle).
264
+ * Returns "pending-exists" when an LLM-class compaction is already armed: the
265
+ * caller must NOT have written its own range/anchor state in that case (the
266
+ * drain fires the first-armed trigger with the FIRST declaration's state).
267
+ * If batch-settle bookkeeping is unavailable (extension state failed), falls
268
+ * back to a bounded DEGRADED_DEFERRAL_MS deferral so a sibling still executing
269
+ * at schedule time has a chance to land its result before the aborting compact
270
+ * fires — never a raw setTimeout(0) (the mid-batch abort race this scheduler
271
+ * removes).
272
+ */
273
+ function scheduleCompactionAtBatchSettle(
274
+ pi: ExtensionAPI,
275
+ ctx: any,
276
+ options: CompactOptions,
277
+ meta: { kind: PendingCompaction["kind"]; cutEntryId?: string; firstKeptEntryId?: string } = {
278
+ kind: "compact",
279
+ },
280
+ ): "queued" | "pending-exists" {
281
+ const trigger = () => {
282
+ try {
283
+ // Signal to session_compact handler that this is agent-initiated
284
+ // compaction (via context_compress tool), so it should auto-resume.
285
+ // If user typed /compress, this flag is NOT set.
286
+ getState(ctx).autoResumeAfterCompaction = true;
287
+ } catch {
288
+ // Non-fatal - enforcement state unavailable
289
+ }
290
+ ctx.compact(options);
291
+ };
292
+ try {
293
+ const st = getBatchSettleState(ctx);
294
+ // LLM-class dedup at arm: a second LLM-class arm while one is pending is
295
+ // refused here so its range/anchor state never clobbers the first's (the
296
+ // drain fires the first-armed trigger). Slides always queue — the drain
297
+ // coalesces them to the earliest cut.
298
+ if (isLlmClass(meta.kind) && st.pending.some((p) => isLlmClass(p.kind))) {
299
+ log.info(
300
+ `[context-compress] ${meta.kind} arm refused: an LLM-class compaction is ` +
301
+ `already armed and will fire at the next boundary.`,
302
+ );
303
+ return "pending-exists";
304
+ }
305
+ st.pending.push({ trigger, armedAt: Date.now(), ...meta });
306
+ if (st.pending.length > PENDING_COMPACT_QUEUE_MAX) {
307
+ const dropped = st.pending.pop();
308
+ log.warn(
309
+ `[context-compress] Pending queue overflow: dropped the newest armed ${dropped?.kind}` +
310
+ ` (cap ${PENDING_COMPACT_QUEUE_MAX}); the first-armed entry still fires.`,
311
+ );
312
+ }
313
+ firePendingCompactionsIfSettled(ctx, st);
314
+ return "queued";
315
+ } catch {
316
+ // Degraded path: batch-settle bookkeeping is unavailable (extension state
317
+ // failed), so we cannot track in-flight tool executions. Do NOT fall back
318
+ // to a raw setTimeout(0) — that is the exact mid-batch abort race this
319
+ // scheduler exists to remove (a still-running parallel sibling's result
320
+ // would be discarded). Use the bounded DEGRADED_DEFERRAL_MS deferral
321
+ // instead so a sibling still executing at schedule time has a chance to
322
+ // land its result before the aborting compact fires; the compact is still
323
+ // best-effort here, but the race window is materially narrowed.
324
+ scheduleDegradedCompact(trigger);
325
+ return "queued";
326
+ }
327
+ }
328
+
329
+ /**
330
+ * Arm a deterministic slide compaction (no LLM call): cut the oldest entries
331
+ * so the most recent `keepCount` stay live. Shared by the slide tool action
332
+ * and the usage-driven auto-arm, so both produce the same cut shape: the
333
+ * boundary is snapped out of any tool batch, the slide state is persisted for
334
+ * the SLIDE_MODE compaction branch, an audit entry is appended, and the
335
+ * trigger is queued for the next safe boundary. Returns null when the branch
336
+ * is not longer than the keep window (nothing to slide).
337
+ */
338
+ function armSlideCompaction(
339
+ pi: ExtensionAPI,
340
+ ctx: any,
341
+ keepCount: number,
342
+ ): { cutEntryId: string; keptCount: number; droppedCount: number } | null {
343
+ const sm = ctx.sessionManager;
344
+ if (!sm || typeof sm.getBranch !== "function") return null;
345
+ const branch = sm.getBranch() ?? [];
346
+ if (branch.length <= keepCount) return null;
347
+
348
+ // The slide cut is a supplied boundary: snap it out of any tool batch it
349
+ // lands in (HTTP 400: a kept slice that opens with a tool result has no
350
+ // preceding tool_calls).
351
+ const cutIndex = snapBoundaryOutsideToolBatch(branch, branch.length - keepCount);
352
+ const cutEntryId = branch[cutIndex].id;
353
+ const keptCount = branch.length - cutIndex;
354
+ const droppedCount = cutIndex;
355
+
356
+ // Persist slide-mode state for session_before_compact to consume.
357
+ try {
358
+ getCmState(ctx).slideMode = {
359
+ active: true,
360
+ cutEntryId,
361
+ keepCount: keptCount,
362
+ droppedCount,
363
+ timestamp: Date.now(),
364
+ };
365
+ } catch {
366
+ log.warn("[context-compress] Failed to persist slideMode");
367
+ }
368
+
369
+ // Record the slide operation as a custom entry for audit trail.
370
+ try {
371
+ pi.appendEntry("context_compress_slide", {
372
+ keep: keepCount,
373
+ dropped: droppedCount,
374
+ branchLength: branch.length,
375
+ timestamp: Date.now(),
376
+ });
377
+ } catch {
378
+ // Non-fatal - audit trail is best-effort
379
+ }
380
+
381
+ // Cancel stale resume timers from previous compaction cycles.
382
+ try {
383
+ const sessionId =
384
+ (
385
+ ctx as { sessionManager?: { getSessionId?: () => string } }
386
+ )?.sessionManager?.getSessionId?.() ?? "anonymous";
387
+ timerMod.cancelTimersByTag(sessionId, "compaction-resume");
388
+ timerMod.cancelTimersByTag(sessionId, "auto-compaction-resume");
389
+ } catch {
390
+ // Non-fatal
391
+ }
392
+
393
+ scheduleCompactionAtBatchSettle(
394
+ pi,
395
+ ctx,
396
+ { customInstructions: "SLIDE_MODE:true" },
397
+ { kind: "slide", cutEntryId },
398
+ );
399
+ return { cutEntryId, keptCount, droppedCount };
400
+ }
401
+
402
+ /** Per-session hysteresis counter for the usage-driven auto-arm. */
403
+ interface AutoArmState {
404
+ aboveCount: number;
405
+ }
406
+
407
+ /**
408
+ * Keep window for an auto-armed slide: the recent HALF of the branch, floor
409
+ * 10 kept entries. Entry-proportional because the arming trigger is usage,
410
+ * not size — a fixed keep (the slide tool's 50) refuses on small fat branches
411
+ * and over-cuts relative to a session's own scale; halving a sustained-
412
+ * over-threshold branch lands post-cut usage near the low band, and the
413
+ * dropped span stays recoverable in the session file.
414
+ */
415
+ export function resolveAutoSlideKeep(branchLength: number): number {
416
+ return Math.max(10, Math.ceil(branchLength / 2));
417
+ }
418
+
419
+ function getAutoArmState(ctx: any): AutoArmState {
420
+ return getExtensionState(ctx, "context-manager/auto-arm", () => ({ aboveCount: 0 }));
421
+ }
422
+
423
+ /**
424
+ * Usage-driven auto-arm: when live usage sits above the configured threshold
425
+ * for `confirmTicks` consecutive observations, arm ONE deterministic slide so
426
+ * a session that never gets a manual cleanup still gets relief. Reuses the
427
+ * accounting context_inspect computes (analyzeSession), the same pending
428
+ * queue the tool arms drain through, and the same boundary discipline: arming
429
+ * only queues; the compaction itself still fires at the next turn boundary or
430
+ * settle, never mid-run.
431
+ *
432
+ * Called from the heartbeat tick — the only cadence that runs while a session
433
+ * works. Returns what happened and why, so the caller can log it.
434
+ */
435
+ export function maybeArmAutoCompaction(
436
+ pi: ExtensionAPI,
437
+ ctx: any,
438
+ ): { armed: boolean; reason: string } {
439
+ const config: ResolvedAutoCompactConfig = getAutoCompactConfig();
440
+ if (!config.enabled) return { armed: false, reason: "disabled" };
441
+ if (isCompactionActive(ctx)) return { armed: false, reason: "compaction-active" };
442
+ if (readPendingCompactions(ctx).length > 0) {
443
+ return { armed: false, reason: "already-pending" };
444
+ }
445
+ const usage = captureUsage(ctx);
446
+ if (!usage) return { armed: false, reason: "usage-unavailable" };
447
+ if (usage.percent < config.armPercent) {
448
+ getAutoArmState(ctx).aboveCount = 0;
449
+ return { armed: false, reason: `below-arm-percent (${usage.percent.toFixed(1)}%)` };
450
+ }
451
+ const st = getAutoArmState(ctx);
452
+ st.aboveCount += 1;
453
+ if (st.aboveCount < config.confirmTicks) {
454
+ return { armed: false, reason: `warming ${st.aboveCount}/${config.confirmTicks}` };
455
+ }
456
+ const branchLength = ctx?.sessionManager?.getBranch?.().length ?? 0;
457
+ const keep = resolveAutoSlideKeep(branchLength);
458
+ const armed = armSlideCompaction(pi, ctx, keep);
459
+ st.aboveCount = 0;
460
+ if (!armed) return { armed: false, reason: "branch-too-short" };
461
+ log.info(
462
+ `[context-compress] Auto-arm: usage sustained at ${usage.percent.toFixed(1)}% ` +
463
+ `(>= ${config.armPercent}% for ${config.confirmTicks} observations) — slide armed ` +
464
+ `(${armed.droppedCount} entries before the cut), fires at the next boundary.`,
465
+ );
466
+ return { armed: true, reason: `usage ${usage.percent.toFixed(1)}% sustained` };
467
+ }
468
+
469
+ // Schema
470
+
471
+ export const contextCompressSchema = Type.Object({
472
+ action: Type.String({
473
+ enum: ["compact", "archive", "deep_clean", "slide"],
474
+ description:
475
+ "compact = remove obsolete/duplicate entries (like context_compact). " +
476
+ "archive = compress a range of messages into a topic summary (like context_archive). " +
477
+ "deep_clean = tag current position, archive everything before the tag, then compact. All-in-one. " +
478
+ "slide = deterministic sliding-window compaction. Drops oldest entries, keeps recent N intact. No LLM summarization.",
479
+ }),
480
+ // compact params (also used by slide)
481
+ keep: Type.Optional(
482
+ Type.Number({
483
+ description:
484
+ "Messages to preserve: action=compact (token-based LLM) or action=slide (deterministic, no LLM). Default slide: 50.",
485
+ }),
486
+ ),
487
+ // archive params (original numeric range)
488
+ startIndex: Type.Optional(
489
+ Type.Number({
490
+ description: "First message index to compress (auto when omitted); action=archive only.",
491
+ }),
492
+ ),
493
+ endIndex: Type.Optional(
494
+ Type.Number({
495
+ description: "Last message index to compress (auto when omitted); action=archive only.",
496
+ }),
497
+ ),
498
+ // archive params (tag-based range)
499
+ startTag: Type.Optional(
500
+ Type.String({
501
+ description: "Archive start-boundary tag; overrides startIndex; action=archive only.",
502
+ }),
503
+ ),
504
+ endTag: Type.Optional(
505
+ Type.String({
506
+ description: "Archive end-boundary tag; overrides endIndex; action=archive only.",
507
+ }),
508
+ ),
509
+ beforeTag: Type.Optional(
510
+ Type.String({
511
+ description:
512
+ "Archive all entries before this tag; equals startTag+endIndex; action=archive only.",
513
+ }),
514
+ ),
515
+ // percentage-based range,
516
+ range: Type.Optional(
517
+ Type.String({
518
+ description:
519
+ 'Percent of session to archive (e.g. "80%"); overrides startIndex/endIndex; action=archive only.',
520
+ }),
521
+ ),
522
+ // keep-recent-turns shortcut,
523
+ keepRecentTurns: Type.Optional(
524
+ Type.Number({
525
+ description:
526
+ "Keep last N user turns, archive the rest; overrides startIndex/endIndex; action=archive only.",
527
+ }),
528
+ ),
529
+ // archive params (shared)
530
+ topic: Type.Optional(
531
+ Type.String({
532
+ description: "Topic label; required for action=archive and action=deep_clean.",
533
+ }),
534
+ ),
535
+ summary: Type.Optional(
536
+ Type.String({
537
+ description:
538
+ "Summary of what was accomplished; required for archive/deep_clean. Use explicit speaker labels to prevent misattribution.",
539
+ }),
540
+ ),
541
+ // deep_clean params
542
+ tagName: Type.Optional(
543
+ Type.String({
544
+ description: "Tag to create at current position; deep_clean only. Default: 'before-cleanup'.",
545
+ }),
546
+ ),
547
+ });
548
+
549
+ export function registerContextCompress(pi: ExtensionAPI): void {
550
+ // Batch-settle scheduling: track in-flight tool executions per session and
551
+ // fire the deferred compaction ONLY at agent_settled — the moment the whole
552
+ // agent run settles (session idle/promptable). Never mid-batch (would drop
553
+ // a parallel sibling's result) and never at tool_execution_end (the run is
554
+ // still live there — an aborting compact would surface a spurious
555
+ // "This operation was aborted" error and tear the finishing turn).
556
+ onEvent(pi, TOOL_EXECUTION_START, (_event: any, ctx: any) => {
557
+ try {
558
+ getBatchSettleState(ctx).inFlight++;
559
+ } catch {
560
+ // Settle tracking is unavailable — the pending compact then only fires
561
+ // via AGENT_SETTLED below, which is the conservative path.
562
+ }
563
+ });
564
+ onEvent(pi, TOOL_EXECUTION_END, (_event: any, ctx: any) => {
565
+ try {
566
+ const st = getBatchSettleState(ctx);
567
+ if (st.inFlight > 0) st.inFlight--;
568
+ // NOTE: do NOT fire here. The run is still active (the agent is
569
+ // processing this tool's result and streaming its next response); an
570
+ // aborting compact now would surface a spurious "This operation was
571
+ // aborted" error and tear the finishing turn. Safe boundaries are
572
+ // turn_end (below) and agent_settled.
573
+ } catch {
574
+ // Settle tracking unavailable — see TOOL_EXECUTION_START above; the
575
+ // AGENT_SETTLED handler remains the conservative trigger.
576
+ }
577
+ });
578
+ onEvent(pi, TURN_END, (_event: any, ctx: any) => {
579
+ // Between-turns boundary: the turn's assistant message and tool results
580
+ // are already persisted when turn_end fires, so the abort inside
581
+ // ctx.compact() cannot tear a live turn or drop a sibling result. A run
582
+ // kept alive by continuous steers never reaches agent_settled — this
583
+ // boundary keeps an armed compaction from stalling behind live work. A
584
+ // steer queued at this moment survives: the loop appends it before the
585
+ // aborted response stream, and its turn runs on the post-compaction
586
+ // resume. inFlight is NOT reset here (only agent_settled owns that
587
+ // backstop); a missed tool_execution_end keeps the boundary conservative.
588
+ try {
589
+ const st = getBatchSettleState(ctx);
590
+ if (st.pending.length === 0 || st.inFlight > 0) return;
591
+ if (isCompactionActive(ctx)) return;
592
+ firePendingCompactionsIfSettled(ctx, st);
593
+ } catch {
594
+ // A failed boundary drain must not tear the turn_end event pipeline;
595
+ // the pending compactions retry on the next boundary.
596
+ }
597
+ });
598
+ onEvent(pi, AGENT_SETTLED, (_event: any, ctx: any) => {
599
+ // Backstop boundary: the run has fully settled, so ctx.compact()'s
600
+ // abort() is a clean no-op — no spurious abort error, no torn turn, and
601
+ // the post-compaction resume wake lands when the session is
602
+ // idle/promptable. The whole pending queue drains here (coalesced);
603
+ // inFlight is reset so parked compactions always fire even if a
604
+ // sibling's end event never arrived. Turn boundaries drain first when a
605
+ // run stays alive; this handler catches everything they cannot reach.
606
+ try {
607
+ const st = getBatchSettleState(ctx);
608
+ st.inFlight = 0;
609
+ firePendingCompactionsIfSettled(ctx, st);
610
+ } catch {
611
+ // A failed settle trigger must not tear down the AGENT_SETTLED event
612
+ // pipeline; the pending compactions retry on the next settle cycle.
613
+ }
614
+ });
615
+
616
+ pi.registerTool({
617
+ name: "context_compress",
618
+ label: "Context Compress",
619
+ promptSnippet:
620
+ "Free context space by compaction or archiving; archive first, slide or compact when it can run safely",
621
+ description:
622
+ "Free up context space; prefer archive over compact. " +
623
+ "For long sessions, tag your position with context_navigate(action=tag) and archive deliberately with " +
624
+ "context_compress(action=archive) BEFORE considering compaction — compaction is a bounded safety net " +
625
+ "(substantive, skippable when input unchanged, verifiable, originals recoverable). " +
626
+ "Never in a parallel batch (it aborts the turn). Use explicit speaker labels in summaries.",
627
+ parameters: contextCompressSchema,
628
+ execute: async (
629
+ _toolCallId: string,
630
+ params: any,
631
+ _signal: any,
632
+ _onUpdate: any,
633
+ ctx: any,
634
+ ): Promise<any> => {
635
+ const action = params.action;
636
+
637
+ // COMPACT
638
+ if (action === "compact") {
639
+ try {
640
+ const usage = captureUsage(ctx);
641
+
642
+ // SAFETY GUARD: compaction (action="compact") causes "max call stack" errors
643
+ // when context exceeds the CONTEXT_COMPACT_REFUSE_PERCENT threshold (owner:
644
+ // lib/detection/context-thresholds.ts). The destructive AI-supervised compaction can
645
+ // leave the session in an unstable state (corrupted messages, 403 blocks).
646
+ // Use action="slide" instead — it's deterministic, entry-based, no LLM call.
647
+ if (usage && usage.percent > CONTEXT_COMPACT_REFUSE_PERCENT) {
648
+ return {
649
+ content: [
650
+ {
651
+ type: "text" as const,
652
+ text: [
653
+ `**Compact refused — context at ${usage.percent.toFixed(1)}% (>${CONTEXT_COMPACT_REFUSE_PERCENT}% threshold).**`,
654
+ `Destructive AI-supervised compaction (action="compact") causes max-call-stack`,
655
+ `crashes and session corruption above ${CONTEXT_COMPACT_REFUSE_PERCENT}% usage.`,
656
+ ``,
657
+ `Use **action="slide"** instead — deterministic, entry-based, no LLM:`,
658
+ ` context_compress(action="slide")`,
659
+ ` context_compress(action="slide", keep=80) # keep recent 80 entries`,
660
+ ``,
661
+ `Run context_inspect(detail="quick") first to assess current state.`,
662
+ ].join("\n"),
663
+ },
664
+ ],
665
+ details: {
666
+ action,
667
+ refused: true,
668
+ reason: `context ${usage.percent.toFixed(1)}% > ${CONTEXT_COMPACT_REFUSE_PERCENT}% threshold`,
669
+ suggestion: { tool: "context_compress", action: "slide" },
670
+ },
671
+ };
672
+ }
673
+
674
+ const usageLine2 = usage
675
+ ? `${usage.percent.toFixed(1)}% used (${formatTokensK(usage.tokens)} tokens)`
676
+ : "unknown";
677
+
678
+ const result = {
679
+ content: [
680
+ {
681
+ type: "text" as const,
682
+ text: [
683
+ `**Compaction scheduled.**`,
684
+ ` Before: ${usageLine2}`,
685
+ ` Keep recent: ${params?.keep ?? "auto"}`,
686
+ ``,
687
+ `Compaction armed; it fires at the next turn boundary (turn end or run settle) — live usage will NOT drop until it lands.`,
688
+ `Agent will resume automatically after compaction completes.`,
689
+ `Run context_inspect(detail='quick') after resume to verify.`,
690
+ ].join("\n"),
691
+ },
692
+ ],
693
+ details: {
694
+ action,
695
+ compactionTriggered: true,
696
+ keep: params?.keep ?? "auto",
697
+ nextStep: { tool: "context_inspect", detail: "quick", note: "after auto-resume" },
698
+ },
699
+ };
700
+
701
+ try {
702
+ // Cancel any stale resume timer from a previous compaction cycle.
703
+ const sessionId =
704
+ (
705
+ ctx as { sessionManager?: { getSessionId?: () => string } }
706
+ )?.sessionManager?.getSessionId?.() ?? "anonymous";
707
+ timerMod.cancelTimersByTag(sessionId, "compaction-resume");
708
+ timerMod.cancelTimersByTag(sessionId, "auto-compaction-resume");
709
+ } catch {
710
+ // Non-fatal - timer unavailable
711
+ }
712
+
713
+ const options: CompactOptions = {};
714
+ if (params?.keep != null) {
715
+ options.customInstructions = `Keep the most recent ${params.keep} messages.`;
716
+ }
717
+
718
+ // Skip compact if context is already low — pi-core returns
719
+ // "nothing to compact" as a whisper, which is confusing noise.
720
+ if (usage && usage.percent < 30) {
721
+ return {
722
+ ...result,
723
+ content: [
724
+ {
725
+ type: "text" as const,
726
+ text: [
727
+ `**Compact skipped — context at ${usage.percent.toFixed(1)}% (already low).**`,
728
+ `No compaction needed. Use context_inspect(detail="quick") to verify.`,
729
+ ].join("\n"),
730
+ },
731
+ ],
732
+ details: {
733
+ ...result.details,
734
+ skipped: true,
735
+ reason: `context ${usage.percent.toFixed(1)}% < 30% threshold`,
736
+ },
737
+ };
738
+ }
739
+
740
+ scheduleCompactionAtBatchSettle(pi, ctx, options, { kind: "compact" });
741
+
742
+ // Compact was scheduled (a real compaction is armed) — count it.
743
+ recordNavigationAction(ctx, "compact");
744
+ return result;
745
+ } catch (e: any) {
746
+ return {
747
+ content: [{ type: "text" as const, text: `Failed to compact: ${e.message}` }],
748
+ details: { action, error: e.message },
749
+ };
750
+ }
751
+ }
752
+
753
+ // ARCHIVE
754
+ if (action === "archive") {
755
+ const { topic, summary } = params;
756
+ if (!topic || !summary) {
757
+ return {
758
+ content: [
759
+ {
760
+ type: "text" as const,
761
+ text: "topic and summary are required for action=archive",
762
+ },
763
+ ],
764
+ details: { action, error: "missing required params" },
765
+ };
766
+ }
767
+
768
+ // LLM-class dedup: refuse BEFORE any state write. An already-armed
769
+ // compaction fires at the next boundary with the FIRST declaration's
770
+ // range; a second arm here would overwrite rangeMode (clobber-class
771
+ // loss) and queue an entry that can never fire.
772
+ if (hasPendingLlmCompaction(ctx)) {
773
+ return {
774
+ content: [
775
+ {
776
+ type: "text" as const,
777
+ text: [
778
+ `**Archive skipped — a compaction is already armed and will fire at the next turn boundary.**`,
779
+ `Nothing was recorded for "${topic}"; the pending compaction covers the cleanup.`,
780
+ `After it lands, re-run this archive if the range still needs a record.`,
781
+ ].join("\n"),
782
+ },
783
+ ],
784
+ details: {
785
+ action,
786
+ skipped: true,
787
+ reason: "compaction-already-pending",
788
+ topic,
789
+ },
790
+ };
791
+ }
792
+
793
+ const usageBefore = captureUsage(ctx);
794
+ const sessionLength = analyzeSession(ctx).branchLength;
795
+
796
+ // Resolve range via priority: startTag/endTag > beforeTag > range > keepRecentTurns > startIndex/endIndex > auto
797
+ let startIndex: number | undefined = params.startIndex;
798
+ let endIndex: number | undefined = params.endIndex;
799
+
800
+ // Priority 1: Tag-based range
801
+ if (params.startTag !== undefined) {
802
+ const idx = resolveTagToIndex(ctx, params.startTag);
803
+ if (idx < 0) {
804
+ return {
805
+ content: [
806
+ {
807
+ type: "text" as const,
808
+ text: `Tag '${params.startTag}' not found in session branch. Use context_navigate action=log to see available tags.`,
809
+ },
810
+ ],
811
+ details: { action, error: `tag not found: ${params.startTag}` },
812
+ };
813
+ }
814
+ startIndex = idx;
815
+
816
+ if (params.endTag !== undefined) {
817
+ const idxEnd = resolveTagToIndex(ctx, params.endTag);
818
+ if (idxEnd < 0) {
819
+ return {
820
+ content: [
821
+ {
822
+ type: "text" as const,
823
+ text: `Tag '${params.endTag}' not found in session branch. Use context_navigate action=log to see available tags.`,
824
+ },
825
+ ],
826
+ details: { action, error: `tag not found: ${params.endTag}` },
827
+ };
828
+ }
829
+ endIndex = idxEnd;
830
+ }
831
+ }
832
+
833
+ // Priority 1b: beforeTag convenience (archive everything before this tag)
834
+ if (startIndex === undefined && params.beforeTag !== undefined) {
835
+ const idx = resolveTagToIndex(ctx, params.beforeTag);
836
+ if (idx < 0) {
837
+ return {
838
+ content: [
839
+ {
840
+ type: "text" as const,
841
+ text: `Tag '${params.beforeTag}' not found in session branch. Use context_navigate action=log to see available tags.`,
842
+ },
843
+ ],
844
+ details: { action, error: `tag not found: ${params.beforeTag}` },
845
+ };
846
+ }
847
+ startIndex = 0;
848
+ endIndex = Math.max(0, idx - 1);
849
+ }
850
+
851
+ // Priority 2: Percentage-based range
852
+ if (params.range !== undefined && (startIndex === undefined || endIndex === undefined)) {
853
+ const match = String(params.range).match(/^(\d+)%$/);
854
+ if (!match) {
855
+ return {
856
+ content: [
857
+ {
858
+ type: "text" as const,
859
+ text: `Invalid range format: '${params.range}'. Use 'N%' e.g. '80%'.`,
860
+ },
861
+ ],
862
+ details: { action, error: `invalid range: ${params.range}` },
863
+ };
864
+ }
865
+ const pct = parseInt(match[1], 10);
866
+ if (pct <= 0 || pct > 100) {
867
+ return {
868
+ content: [
869
+ {
870
+ type: "text" as const,
871
+ text: `Range must be 1-100%. Got ${pct}%.`,
872
+ },
873
+ ],
874
+ details: { action, error: `invalid percentage: ${pct}` },
875
+ };
876
+ }
877
+ const count = Math.max(1, Math.floor((sessionLength * pct) / 100));
878
+ startIndex = 0;
879
+ endIndex = count - 1;
880
+ }
881
+
882
+ // Priority 3: Keep-recent-turns
883
+ if (
884
+ (startIndex === undefined || endIndex === undefined) &&
885
+ params.keepRecentTurns !== undefined
886
+ ) {
887
+ const keep = params.keepRecentTurns;
888
+ if (keep <= 0) {
889
+ return {
890
+ content: [
891
+ {
892
+ type: "text" as const,
893
+ text: "keepRecentTurns must be >= 1.",
894
+ },
895
+ ],
896
+ details: { action, error: "invalid keepRecentTurns" },
897
+ };
898
+ }
899
+
900
+ const sm = ctx.sessionManager;
901
+ const branch = sm.getBranch() ?? [];
902
+ // Branch entries wrap the message: a user turn is
903
+ // entry.type === "message" with entry.message.role === "user".
904
+ // Matching entry.type/entry.role directly never matches, which
905
+ // collapsed every keepRecentTurns span to [0..0].
906
+ let userMessagesSeen = 0;
907
+ let cutIndex = 0;
908
+ for (let i = branch.length - 1; i >= 0; i--) {
909
+ const entry = branch[i];
910
+ if (entry?.type === "message" && (entry as any).message?.role === "user") {
911
+ userMessagesSeen++;
912
+ if (userMessagesSeen >= keep) {
913
+ cutIndex = i;
914
+ break;
915
+ }
916
+ }
917
+ }
918
+ startIndex = 0;
919
+ endIndex = Math.max(0, cutIndex - 1);
920
+ }
921
+
922
+ // Default: auto-select oldest ~20%
923
+ if (startIndex === undefined || endIndex === undefined) {
924
+ const archiveCount = Math.min(Math.max(Math.floor(sessionLength * 0.2), 10), 100);
925
+ startIndex = 0;
926
+ endIndex = archiveCount - 1;
927
+ }
928
+
929
+ if (startIndex < 0 || endIndex < startIndex) {
930
+ return {
931
+ content: [
932
+ {
933
+ type: "text" as const,
934
+ text: "Invalid range: startIndex must be >= 0 and endIndex must be >= startIndex",
935
+ },
936
+ ],
937
+ details: { action, error: true },
938
+ };
939
+ }
940
+
941
+ const sm = ctx.sessionManager;
942
+
943
+ // Persist range-mode state so session_before_compact honors the declared
944
+ // range as the real compaction boundary (commitment-preserving anchor).
945
+ const branch: Array<{ id: string; type?: string; message?: unknown }> =
946
+ typeof sm.getBranch === "function" ? (sm.getBranch() ?? []) : [];
947
+ // The declared boundary is a supplied one: snap it out of any tool
948
+ // batch it lands in (HTTP 400: a kept slice that opens with a tool
949
+ // result has no preceding tool_calls). A boundary at the branch end
950
+ // stays undefined - there is no entry to keep.
951
+ const candidateBoundary = endIndex + 1;
952
+ const boundaryIndex =
953
+ candidateBoundary < branch.length
954
+ ? snapBoundaryOutsideToolBatch(branch, candidateBoundary)
955
+ : candidateBoundary;
956
+ const firstKeptEntryId = branch[boundaryIndex]?.id;
957
+ try {
958
+ const cmState = getCmState(ctx);
959
+ cmState.rangeMode = {
960
+ active: true,
961
+ startIndex,
962
+ endIndex,
963
+ summary,
964
+ topic,
965
+ firstKeptEntryId,
966
+ boundaryIsBranchEnd: boundaryIndex >= branch.length,
967
+ timestamp: Date.now(),
968
+ };
969
+ } catch {
970
+ log.warn("[context-compress] Failed to persist rangeMode");
971
+ }
972
+
973
+ pi.appendEntry("context_compression", {
974
+ topic,
975
+ startIndex,
976
+ endIndex,
977
+ summary,
978
+ timestamp: Date.now(),
979
+ });
980
+
981
+ // Honest-by-understatement feedback.
982
+ // The declared range + summary are recorded as the archive anchor
983
+ // (audit metadata entry + rangeMode), but the feedback NEVER claims a
984
+ // specific removed range ("entries N..M removed" / "Compressed N
985
+ // messages") and never promises a specific boundary — the actual cut
986
+ // is pi-core's compaction decision, so the tool reports an ESTIMATED
987
+ // cut only. Contract: claim less than what happened, never more. The
988
+ // REAL before-% is still reported (no fabricated post-% — a
989
+ // linear-token estimate would be misleading).
990
+ const count = endIndex - startIndex + 1;
991
+ const feedbackLines: string[] = [
992
+ `Archive recorded: "${topic}" — ~${count} entries before the archive point, estimated.`,
993
+ ];
994
+ if (usageBefore) {
995
+ feedbackLines.push(
996
+ ` Before: ${usageBefore.percent.toFixed(1)}% used (${formatTokensK(usageBefore.tokens)} tokens)`,
997
+ );
998
+ }
999
+ feedbackLines.push(
1000
+ "",
1001
+ "Compaction is armed and fires at the next turn boundary (turn end or run settle) — it may " +
1002
+ "land while the run stays alive; live usage will NOT drop until it fires.",
1003
+ "Verify after it lands: context_inspect(detail='quick') shows the drop and any still-pending arm.",
1004
+ );
1005
+
1006
+ // Cancel any stale resume timer from a previous compaction cycle.
1007
+ try {
1008
+ const sessionId =
1009
+ (
1010
+ ctx as { sessionManager?: { getSessionId?: () => string } }
1011
+ )?.sessionManager?.getSessionId?.() ?? "anonymous";
1012
+ timerMod.cancelTimersByTag(sessionId, "compaction-resume");
1013
+ timerMod.cancelTimersByTag(sessionId, "auto-compaction-resume");
1014
+ } catch {
1015
+ // Non-fatal - timer unavailable
1016
+ }
1017
+
1018
+ // Skip follow-up compact only when REAL usage is genuinely low (<30%).
1019
+ // Never skip on a linear-token estimate — that drops a needed
1020
+ // compaction while claiming a freed percentage.
1021
+ let compactionTriggered = true;
1022
+ if (usageBefore && usageBefore.percent < 30) {
1023
+ compactionTriggered = false;
1024
+ feedbackLines.push(
1025
+ "",
1026
+ ` Skipped follow-up compact (real context ${usageBefore.percent.toFixed(1)}% — already low). No estimation used.`,
1027
+ );
1028
+ } else {
1029
+ scheduleCompactionAtBatchSettle(
1030
+ pi,
1031
+ ctx,
1032
+ {},
1033
+ {
1034
+ kind: "archive",
1035
+ firstKeptEntryId,
1036
+ },
1037
+ );
1038
+ }
1039
+
1040
+ // The archive range was declared and compaction armed — count it.
1041
+ recordNavigationAction(ctx, "archive");
1042
+
1043
+ // An untagged session just archived without a
1044
+ // navigation checkpoint — gently remind that tagging before archiving
1045
+ // makes recovery lossless. Only on the archive SUCCESS path, only when
1046
+ // the session has zero recorded tags (adopters are not nagged).
1047
+ if ((getCmState(ctx).navigationAdoption?.tags ?? 0) === 0) {
1048
+ feedbackLines.push(
1049
+ "",
1050
+ "Tip: context_navigate(action=tag) before archives makes recovery lossless.",
1051
+ );
1052
+ }
1053
+
1054
+ return {
1055
+ content: [
1056
+ {
1057
+ type: "text" as const,
1058
+ text: feedbackLines.join("\n"),
1059
+ },
1060
+ ],
1061
+ details: {
1062
+ action,
1063
+ compressed: count,
1064
+ topic,
1065
+ startIndex,
1066
+ endIndex,
1067
+ honorRange: true,
1068
+ compactionTriggered,
1069
+ nextStep: { tool: "context_inspect", detail: "quick", note: "after auto-resume" },
1070
+ },
1071
+ };
1072
+ }
1073
+
1074
+ // DEEP_CLEAN
1075
+ if (action === "deep_clean") {
1076
+ const topic = params.topic;
1077
+ const summary = params.summary;
1078
+ if (!topic || !summary) {
1079
+ return {
1080
+ content: [
1081
+ {
1082
+ type: "text" as const,
1083
+ text: "topic and summary are required for action=deep_clean",
1084
+ },
1085
+ ],
1086
+ details: { action, error: "missing required params" },
1087
+ };
1088
+ }
1089
+
1090
+ // LLM-class dedup (same contract as archive): an armed compaction
1091
+ // fires at the next boundary; refuse before writing the tag or the
1092
+ // archive anchor so the first declaration stands unmodified.
1093
+ if (hasPendingLlmCompaction(ctx)) {
1094
+ return {
1095
+ content: [
1096
+ {
1097
+ type: "text" as const,
1098
+ text: [
1099
+ `**Deep clean skipped — a compaction is already armed and will fire at the next turn boundary.**`,
1100
+ `Nothing was tagged for "${topic}"; the pending compaction covers the cleanup.`,
1101
+ ].join("\n"),
1102
+ },
1103
+ ],
1104
+ details: {
1105
+ action,
1106
+ skipped: true,
1107
+ reason: "compaction-already-pending",
1108
+ topic,
1109
+ },
1110
+ };
1111
+ }
1112
+
1113
+ const tagName = params.tagName ?? "before-cleanup";
1114
+ const usageBefore = captureUsage(ctx);
1115
+
1116
+ try {
1117
+ const sm = ctx.sessionManager;
1118
+ const branch = sm.getBranch() ?? [];
1119
+ const currentLeaf = branch.length > 0 ? branch[branch.length - 1].id : null;
1120
+ if (currentLeaf) {
1121
+ sm.appendLabelChange(currentLeaf, tagName);
1122
+ }
1123
+
1124
+ const tagIndex = currentLeaf ? resolveTagToIndex(ctx, tagName) : -1;
1125
+ const archiveEnd = tagIndex > 0 ? tagIndex - 1 : -1;
1126
+
1127
+ if (archiveEnd >= 0) {
1128
+ pi.appendEntry("context_compression", {
1129
+ topic,
1130
+ startIndex: 0,
1131
+ endIndex: archiveEnd,
1132
+ summary,
1133
+ timestamp: Date.now(),
1134
+ fromDeepClean: true,
1135
+ });
1136
+ }
1137
+
1138
+ const options: CompactOptions = {};
1139
+ scheduleCompactionAtBatchSettle(pi, ctx, options, { kind: "deep_clean" });
1140
+
1141
+ // The deep-clean pipeline actually ran (tag + archive + compact).
1142
+ recordNavigationAction(ctx, "deep_clean");
1143
+
1144
+ const count = archiveEnd >= 0 ? archiveEnd + 1 : 0;
1145
+ const usageLine = usageBefore ? ` (before: ${usageBefore.percent.toFixed(1)}%)` : "";
1146
+
1147
+ return {
1148
+ content: [
1149
+ {
1150
+ type: "text" as const,
1151
+ text: [
1152
+ `**Deep clean triggered.**`,
1153
+ ` 1. Tagged '${tagName}' at current position`,
1154
+ ` 2. ~${count} entries before the tag point, estimated`,
1155
+ ` 3. Compaction scheduled${usageLine}`,
1156
+ "",
1157
+ `Compaction armed; it fires at the next turn boundary (turn end or run settle) — live usage will NOT drop until it lands.`,
1158
+ `Agent will resume automatically after compaction completes.`,
1159
+ `Run context_inspect(detail='quick') after resume to verify.`,
1160
+ "",
1161
+ `Topic: ${topic}`,
1162
+ ].join("\n"),
1163
+ },
1164
+ ],
1165
+ details: {
1166
+ action: "deep_clean",
1167
+ tagName,
1168
+ archived: count,
1169
+ compactionTriggered: true,
1170
+ topic,
1171
+ nextStep: { tool: "context_inspect", detail: "quick", note: "after auto-resume" },
1172
+ },
1173
+ };
1174
+ } catch (e: any) {
1175
+ return {
1176
+ content: [
1177
+ {
1178
+ type: "text" as const,
1179
+ text: `Failed to deep clean: ${e.message}`,
1180
+ },
1181
+ ],
1182
+ details: { action, error: e.message },
1183
+ };
1184
+ }
1185
+ }
1186
+
1187
+ // SLIDE
1188
+ if (action === "slide") {
1189
+ try {
1190
+ const sm = ctx.sessionManager;
1191
+ if (!sm || typeof sm.getBranch !== "function") {
1192
+ return {
1193
+ content: [
1194
+ {
1195
+ type: "text" as const,
1196
+ text: "Session manager not available.",
1197
+ },
1198
+ ],
1199
+ details: { action, error: "no session manager" },
1200
+ };
1201
+ }
1202
+
1203
+ const keepCount = params?.keep != null ? params.keep : 50;
1204
+ if (typeof keepCount !== "number" || keepCount < 1 || !Number.isFinite(keepCount)) {
1205
+ return {
1206
+ content: [
1207
+ {
1208
+ type: "text" as const,
1209
+ text: "keep must be a positive integer >= 1.",
1210
+ },
1211
+ ],
1212
+ details: { action, error: "invalid keep" },
1213
+ };
1214
+ }
1215
+
1216
+ const branch = sm.getBranch() ?? [];
1217
+ if (branch.length <= keepCount) {
1218
+ return {
1219
+ content: [
1220
+ {
1221
+ type: "text" as const,
1222
+ text: `Branch has ${branch.length} entries, which is <= keep (${keepCount}). Nothing to slide.`,
1223
+ },
1224
+ ],
1225
+ details: {
1226
+ action,
1227
+ keep: keepCount,
1228
+ branchLength: branch.length,
1229
+ slid: 0,
1230
+ },
1231
+ };
1232
+ }
1233
+
1234
+ const usage = captureUsage(ctx);
1235
+ const usageLine = usage
1236
+ ? `${usage.percent.toFixed(1)}% used (${formatTokensK(usage.tokens)} tokens)`
1237
+ : "unknown";
1238
+
1239
+ // Skip slide compact if context is already low — pi-core returns
1240
+ // "nothing to compact" as a confusing whisper. Checked BEFORE any
1241
+ // state write: a skipped slide must not leave slideMode armed for a
1242
+ // later compaction cycle to consume.
1243
+ if (usage && usage.percent < 30) {
1244
+ return {
1245
+ content: [
1246
+ {
1247
+ type: "text" as const,
1248
+ text: [
1249
+ `**Slide skipped — context at ${usage.percent.toFixed(1)}% (already low).**`,
1250
+ `No entries need dropping. Use context_inspect(detail="quick") to verify.`,
1251
+ ].join("\n"),
1252
+ },
1253
+ ],
1254
+ details: {
1255
+ action,
1256
+ skipped: true,
1257
+ reason: `context ${usage.percent.toFixed(1)}% < 30% threshold`,
1258
+ branchLength: branch.length,
1259
+ },
1260
+ };
1261
+ }
1262
+
1263
+ const armedSlide = armSlideCompaction(pi, ctx, keepCount);
1264
+ if (!armedSlide) {
1265
+ return {
1266
+ content: [
1267
+ {
1268
+ type: "text" as const,
1269
+ text: "Session manager not available.",
1270
+ },
1271
+ ],
1272
+ details: { action, error: "no session manager" },
1273
+ };
1274
+ }
1275
+ const { keptCount, droppedCount } = armedSlide;
1276
+
1277
+ // Slide window armed — count it as navigation adoption.
1278
+ recordNavigationAction(ctx, "slide");
1279
+
1280
+ return {
1281
+ content: [
1282
+ {
1283
+ type: "text" as const,
1284
+ text: [
1285
+ `**Slide window compaction triggered.**`,
1286
+ ` Keep recent: ${keptCount} entries`,
1287
+ ` ~${droppedCount} entries before the slide point, estimated`,
1288
+ ` Before: ${usageLine}`,
1289
+ ``,
1290
+ `Compaction armed; it fires at the next turn boundary (turn end or run settle) — live usage will NOT drop until it lands.`,
1291
+ `Agent will resume automatically after compaction completes.`,
1292
+ `Run context_inspect(detail='quick') after resume to verify.`,
1293
+ ].join("\n"),
1294
+ },
1295
+ ],
1296
+ details: {
1297
+ action,
1298
+ slideTriggered: true,
1299
+ keep: keepCount,
1300
+ dropped: droppedCount,
1301
+ branchLength: branch.length,
1302
+ nextStep: {
1303
+ tool: "context_inspect",
1304
+ detail: "quick",
1305
+ note: "after auto-resume",
1306
+ },
1307
+ },
1308
+ };
1309
+ } catch (e: any) {
1310
+ return {
1311
+ content: [
1312
+ {
1313
+ type: "text" as const,
1314
+ text: `Failed to slide: ${e.message}`,
1315
+ },
1316
+ ],
1317
+ details: { action, error: e.message },
1318
+ };
1319
+ }
1320
+ }
1321
+
1322
+ return {
1323
+ content: [
1324
+ {
1325
+ type: "text" as const,
1326
+ text: "Unknown action. Use compact, archive, deep_clean, or slide.",
1327
+ },
1328
+ ],
1329
+ details: { action, error: true },
1330
+ };
1331
+ },
1332
+ });
1333
+ }