pi-braid 0.0.0-stage → 0.40.1

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 +266 -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 +166 -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 +502 -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,1014 @@
1
+ /**
2
+ * Injection Tracker - tracks all messages sent via pi.sendMessage/sendUserMessage.
3
+ *
4
+ * Purpose: Make the model's context visible. When extensions inject messages
5
+ * (enforcement whispers, memory nudges, retry prompts, etc.), users should be
6
+ * able to see what the model sees.
7
+ *
8
+ * State is keyed by optional sessionId to prevent cross-session leakage.
9
+ * Defaults to a "default" bucket when no sessionId is provided.
10
+ *
11
+ * The in-memory bucket is a fast path, not the source of truth: every tracked
12
+ * injection also appends a durable session entry (`INJECTION_ENTRY_TYPE`) and
13
+ * `session_start` / `session_tree` rebuild the active bucket from
14
+ * `ctx.sessionManager.getBranch()`. Branch-sensitive state must follow the
15
+ * branch (checkout, resume), and abandoned branches are alternative histories
16
+ * that are never replayed.
17
+ *
18
+ * Usage:
19
+ * import { trackInjection, getInjections, clearInjections } from "./injection-tracker.js";
20
+ * trackInjection({ type: "enforcement", source: "enforcement/whisper", content: "..." });
21
+ */
22
+
23
+ import { createLogger } from "../core/logger.js";
24
+ import { SESSION_SHUTDOWN, MESSAGE_START, MESSAGE_END } from "../core/event-names.js";
25
+ import { tryWhisper, type WhisperPriority } from "../enforcement/turn-dedup.js";
26
+ import { BRAID_ID, BRAID_INJECTED, BRAID_SOURCE } from "../constants/injection-details.js";
27
+ import { areCognitiveNudgesDisabled } from "../config/braid-settings.js";
28
+ import { registerSessionStartHandler, SessionPhase } from "../state/session-start-queue.js";
29
+ import { nextId } from "./id.js";
30
+ import { applyWhisperEnvelope } from "./whisper-format.js";
31
+ import { gateTriggerTurnOptions, isAgentBusy } from "./wake-gate.js";
32
+
33
+ const log = createLogger("injection-tracker");
34
+
35
+ export interface Injection {
36
+ id: string;
37
+ type: "enforcement" | "memory" | "retry" | "heartbeat" | "context" | "sop-suggestion" | "other";
38
+ source: string;
39
+ content: string;
40
+ timestamp: number;
41
+ display: boolean;
42
+ steer: boolean;
43
+ turn: number;
44
+ }
45
+
46
+ interface InjectionBucket {
47
+ injections: Injection[];
48
+ maxInjections: number;
49
+ }
50
+
51
+ /**
52
+ * Custom entry type for durable injection records. Stable: reconstruction
53
+ * scans branch entries by this key, so renaming it orphans older sessions.
54
+ */
55
+ export const INJECTION_ENTRY_TYPE = "braid_injection";
56
+
57
+ /** Per-bucket cap; also applied when rebuilding a bucket from branch entries. */
58
+ export const MAX_INJECTIONS = 200;
59
+
60
+ /**
61
+ * Display cap for a tracked body. The log is a bounded render, not a store of
62
+ * record: callers whose entry IS the record (the context-manager owner-input
63
+ * seat) pass `fullContent` to keep the body verbatim.
64
+ */
65
+ const MAX_INJECTION_CONTENT = 500;
66
+
67
+ /**
68
+ * Structural appendEntry seam: the documented durable write path
69
+ * (pi.appendEntry -> sessionManager.appendCustomEntry). Same shape as
70
+ * compaction-trace's EntryAppender, so tests can double it without a full
71
+ * extension API.
72
+ */
73
+ export interface InjectionEntryAppender {
74
+ appendEntry<T = unknown>(customType: string, data?: T): void;
75
+ }
76
+
77
+ // The appender is captured from the extension API at registration time
78
+ // because trackInjection runs on deep send paths with no `pi` in scope.
79
+ // Best-effort: an unset or throwing seam degrades to the in-memory bucket,
80
+ // which is exactly the pre-durable behavior. Module-level let, documented
81
+ // exception (seam slot) in lib/state/AGENTS.md.
82
+ let _entryAppender: InjectionEntryAppender | undefined;
83
+
84
+ // _buckets: keyed by sessionId, so it IS effectively session-scoped despite
85
+ // living at module level. Cleared on SESSION_SHUTDOWN (see registerInjectionTracker).
86
+ // _activeSessionId: pointer to the most recent sessionId; fallback for callers
87
+ // that lose ctx (e.g. after compaction).
88
+ // _sendDepth: process-global re-entry counter for sendTrackedMessage.
89
+ const _buckets = new Map<string, InjectionBucket>();
90
+
91
+ let _activeSessionId: string | undefined;
92
+
93
+ // Same-body cross-call de-bloat. turn-dedup.ts only caps whispers WITHIN a
94
+ // single turn (per-turn window closes on each `input`), so a body that
95
+ // legitimately re-fires after its per-turn window — turn after turn, each a
96
+ // fresh token load — was never deduped. The benchmark measured 41% of
97
+ // 7,690 whisper deliveries (3,129) as exact-repeat bodies re-injected within
98
+ // the same session. This layer suppresses a normalised-exact-repeat body
99
+ // re-delivered inside REPRIME_COOLDOWN_MS, scoped per-session like _buckets
100
+ // and cleared on SESSION_SHUTDOWN.
101
+ //
102
+ // REPRIME_COOLDOWN_MS: a signal that still matters 20+ minutes later
103
+ // re-fires after the window elapses; the rapid turn-after-turn re-prime spam
104
+ // (the measured waste) is cut.
105
+ export const REPRIME_COOLDOWN_MS = 20 * 60 * 1000; // 20 minutes
106
+
107
+ interface ReprimeBucket {
108
+ /** normalized body key -> lastEmittedAt (ms epoch), per session. */
109
+ lastEmitted: Map<string, number>;
110
+ }
111
+
112
+ // _reprime: keyed by sessionId (same convention as _buckets). Cleared via
113
+ // the SESSION_SHUTDOWN handler in registerInjectionTracker so a body can fire
114
+ // fresh in the next session (no cross-session cooldown bleed).
115
+ // The per-session lastEmitted map grows one entry per DISTINCT whisper body
116
+ // for the whole session; only entries inside the cooldown window can ever
117
+ // matter, so expired entries are pruned on every emit and a hard cap bounds
118
+ // pathological body diversity. See REPRIME_MAX_ENTRIES below.
119
+ const _reprime = new Map<string, ReprimeBucket>();
120
+
121
+ /**
122
+ * Unresolved-advisory registry: one entry per advisory message that has been
123
+ * handed to pi but whose append event has not been observed yet.
124
+ *
125
+ * WHY: an advisory emitted while an earlier one of the same kind is still
126
+ * in flight stacks behind it (pi's follow-up lane drains one message per
127
+ * run stop), so the newer notice arrives after the work it asks for. The
128
+ * emitter checks `hasUnresolvedAdvisory()` before emitting and skips the
129
+ * emission while one is in flight; the entry retires when the delivered
130
+ * message is appended, which pi reports as `message_start` + `message_end`
131
+ * carrying the message's `details` (the same object this module tagged with
132
+ * `BRAID_ID`).
133
+ *
134
+ * Process-global, not per-session: ids are unique per process and the
135
+ * shutdown handler clears the map at the session boundary, so a new session
136
+ * never inherits an in-flight flag from the previous one. The TTL is the
137
+ * safety valve for a lost event (a suppressed send, a crash between
138
+ * emission and append): a stale entry must not wedge the emitter forever.
139
+ */
140
+ interface UnresolvedAdvisory {
141
+ id: string;
142
+ advisory: string;
143
+ emittedAt: number;
144
+ }
145
+
146
+ /**
147
+ * TTL for an unresolved advisory. Sized above any observed emission->append
148
+ * window (park flushes at the same turn_end; the follow-up tail ran to
149
+ * hours) so a live delivery is never cut off, and short enough that a lost
150
+ * event cannot wedge the emitter for the session.
151
+ */
152
+ export const UNRESOLVED_ADVISORY_TTL_MS = 30 * 60 * 1000; // 30 minutes
153
+
154
+ const _unresolvedAdvisories = new Map<string, UnresolvedAdvisory>();
155
+
156
+ // Test-only clock override so fixtures can prove the TTL opens the gate
157
+ // without waiting REAL minutes. null restores Date.now(). Same pattern as
158
+ // the reprime clock above.
159
+ let _advisoryNowOverride: number | null = null;
160
+
161
+ function advisoryNow(): number {
162
+ return _advisoryNowOverride ?? Date.now();
163
+ }
164
+
165
+ /** Drop entries whose TTL expired; a lost event must not wedge the emitter. */
166
+ function pruneUnresolvedAdvisories(now: number = advisoryNow()): void {
167
+ for (const [id, entry] of _unresolvedAdvisories) {
168
+ if (now - entry.emittedAt >= UNRESOLVED_ADVISORY_TTL_MS) _unresolvedAdvisories.delete(id);
169
+ }
170
+ }
171
+
172
+ /**
173
+ * Record an advisory as in flight. Called by the send funnel only after every
174
+ * suppression path has passed, so a suppressed message never registers.
175
+ */
176
+ export function registerUnresolvedAdvisory(entry: UnresolvedAdvisory): void {
177
+ pruneUnresolvedAdvisories();
178
+ _unresolvedAdvisories.set(entry.id, entry);
179
+ }
180
+
181
+ /**
182
+ * Retire an in-flight advisory by id. Called from the `message_start` /
183
+ * `message_end` handlers with the id the delivered message carries in its
184
+ * details; unknown ids (regular messages, other producers) are a no-op.
185
+ */
186
+ export function resolveUnresolvedAdvisory(id: string): void {
187
+ _unresolvedAdvisories.delete(id);
188
+ }
189
+
190
+ /**
191
+ * True while an advisory of this kind is in flight (and its TTL has not
192
+ * expired). Emitters use this to refuse stacking a second notice behind one
193
+ * that has not landed yet.
194
+ */
195
+ export function hasUnresolvedAdvisory(advisory: string): boolean {
196
+ pruneUnresolvedAdvisories();
197
+ for (const entry of _unresolvedAdvisories.values()) {
198
+ if (entry.advisory === advisory) return true;
199
+ }
200
+ return false;
201
+ }
202
+
203
+ /**
204
+ * Drop every in-flight advisory. Session boundary + test reset: the next
205
+ * session must not inherit the previous one's unresolved flags.
206
+ */
207
+ export function clearUnresolvedAdvisories(): void {
208
+ _unresolvedAdvisories.clear();
209
+ }
210
+
211
+ /**
212
+ * Test hook: pin the clock used by advisory TTL pruning so fixtures can
213
+ * prove the window opens without waiting real minutes. Pass null to restore
214
+ * Date.now().
215
+ */
216
+ export function _setAdvisoryClockForTests(nowMs: number | null): void {
217
+ _advisoryNowOverride = nowMs;
218
+ }
219
+
220
+ /** Hard cap on distinct tracked bodies per session (oldest evicted). */
221
+ const REPRIME_MAX_ENTRIES = 300;
222
+
223
+ // Test-only clock override so fixtures can prove the cooldown window closes
224
+ // without waiting REAL minutes. null restores Date.now().
225
+ let _nowOverride: number | null = null;
226
+
227
+ function reprimeNow(): number {
228
+ return _nowOverride ?? Date.now();
229
+ }
230
+
231
+ function getReprimeBucket(): ReprimeBucket {
232
+ const key = _activeSessionId ?? "default";
233
+ let bucket = _reprime.get(key);
234
+ if (!bucket) {
235
+ bucket = { lastEmitted: new Map() };
236
+ _reprime.set(key, bucket);
237
+ }
238
+ return bucket;
239
+ }
240
+
241
+ // Prevents unbounded recursion when pi.sendMessage(steer) triggers synchronous
242
+ // event chains (e.g., before_agent_start -> sendCompactNudge -> sendTrackedMessage
243
+ // -> pi.sendMessage -> before_agent_start ...).
244
+ // Incremented before pi.sendMessage, decremented after. If depth >= MAX_REENTRY_DEPTH,
245
+ // the message is dispatched via setTimeout(0) to break the synchronous chain.
246
+ //
247
+ // IMPORTANT: setTimeout(0) is used instead of queueMicrotask because microtasks
248
+ // run in the same event loop turn — the call stack does NOT unwind between
249
+ // microtasks. If each deferred microtask triggers another synchronous chain
250
+ // (before_agent_start → 25+ hooks → sendTrackedMessage → pi.sendMessage →
251
+ // _runAgentPrompt → ...), the stack still overflows. setTimeout(0) creates a
252
+ // real macrotask boundary: the stack fully unwinds before the deferred send.
253
+ let _sendDepth = 0;
254
+ // MAX_REENTRY_DEPTH = 1: The first sendTrackedMessage call goes through
255
+ // synchronously (depth 0 → 1). Any re-entrant send (depth >= 1) is deferred
256
+ // via setTimeout(0), breaking the synchronous chain at the macrotask boundary.
257
+ //
258
+ // Failure mode bounded here: the post-compaction stack overflow. After
259
+ // compaction the agent wakes up and calls tools (e.g., scratchpad); the
260
+ // tool_call/
261
+ // tool_execution_end events fire synchronously, and a handler that sends
262
+ // a triggerTurn:true whisper creates a recursive _runAgentPrompt call.
263
+ // With MAX_REENTRY_DEPTH=1, the first whisper goes through, but any
264
+ // re-entrant whisper triggered by the synchronous before_agent_start hooks
265
+ // is deferred to a new macrotask — the stack unwinds first.
266
+ const MAX_REENTRY_DEPTH = 1;
267
+
268
+ /**
269
+ * Set the active session ID. Call on session_start to scope injections.
270
+ */
271
+ export function setActiveSessionId(id: string | undefined): void {
272
+ _activeSessionId = id;
273
+ }
274
+
275
+ function getBucket(): InjectionBucket {
276
+ const key = _activeSessionId ?? "default";
277
+ if (!_buckets.has(key)) {
278
+ _buckets.set(key, { injections: [], maxInjections: MAX_INJECTIONS });
279
+ }
280
+ return _buckets.get(key)!;
281
+ }
282
+
283
+ /**
284
+ * Stable body key for reprime suppression.
285
+ *
286
+ * Mirrors the MARS advice-normalization lesson: collapse
287
+ * whitespace AND standalone digit runs so a persisting pattern whose counters
288
+ * keep ticking ("bash used 25/30 tool-turns, 83%" → "bash used #/#
289
+ * tool-turns, #%") still compares equal and stays suppressed. A different
290
+ * tool name, source, or wording produces a different key and re-fires.
291
+ *
292
+ * Boundary-aware (not unconditional) digit collapse: only STANDALONE numeric
293
+ * tokens are noise. Digits embedded in an identifier or unit are SIGNAL and
294
+ * must stay distinct so two genuinely-different whispers don't collide —
295
+ * advisory timer bodies "[timer] 30s elapsed" vs "[timer] 60s elapsed" both
296
+ * normalize to "[timer] #s elapsed" under unconditional collapse and the 2nd
297
+ * would be wrongly held for 20 min. (Fixes a correctness gap found later —
298
+ * see the digit-collapse tests.)
299
+ *
300
+ * Exported because it is the single definition of "the same body" for the
301
+ * enforcement layer: the reprime cooldown below and the adherence meter's
302
+ * rule-signal identity (`lib/enforcement/adherence-meter.ts`) must agree on
303
+ * it, or the meter's "repeats" would drift from the suppression events it
304
+ * counts.
305
+ */
306
+ export function reprimeBodyKey(body: string): string {
307
+ return (
308
+ body
309
+ .trim()
310
+ .replace(/\s+/g, " ")
311
+ // Collapse STANDALONE numeric tokens (counts, ratios, percentages):
312
+ // a digit run not adjacent to a word char is a drifting counter, so
313
+ // collapse it; one attached to a word/unit/identifier (30s, v1, ref-2)
314
+ // is meaningful and preserved.
315
+ .replace(/(?<![\w-])\d+(?:\.\d+)?(?!\w)/g, "#")
316
+ );
317
+ }
318
+
319
+ /**
320
+ * True when the same normalized body was last emitted within the reprime
321
+ * cooldown window in this session. First occurrence (no entry) always passes.
322
+ */
323
+ function withinReprimeCooldown(key: string): boolean {
324
+ const last = getReprimeBucket().lastEmitted.get(key);
325
+ return last !== undefined && reprimeNow() - last < REPRIME_COOLDOWN_MS;
326
+ }
327
+
328
+ /** Record a delivery so a re-fire inside the cooldown window is suppressed. */
329
+ function markReprimeEmitted(key: string): void {
330
+ const bucket = getReprimeBucket();
331
+ // Opportunistic prune — only entries inside the cooldown window
332
+ // can suppress anything, so expired entries are dead weight. Iterate and
333
+ // drop expired ones while inserting the new key.
334
+ const now = reprimeNow();
335
+ for (const [key, ts] of bucket.lastEmitted) {
336
+ if (now - ts >= REPRIME_COOLDOWN_MS) bucket.lastEmitted.delete(key);
337
+ }
338
+ bucket.lastEmitted.set(key, now);
339
+ // Hard cap for pathological body diversity: evict oldest (insertion order).
340
+ while (bucket.lastEmitted.size > REPRIME_MAX_ENTRIES) {
341
+ const oldest = bucket.lastEmitted.keys().next();
342
+ if (oldest.done) break;
343
+ bucket.lastEmitted.delete(oldest.value);
344
+ }
345
+ }
346
+
347
+ /**
348
+ * Track a message injection. Call this from any extension that sends
349
+ * pi.sendMessage or pi.sendUserMessage.
350
+ */
351
+ export function trackInjection(params: {
352
+ type: Injection["type"];
353
+ source: string;
354
+ content: string;
355
+ display?: boolean;
356
+ steer?: boolean;
357
+ turn?: number;
358
+ sessionId?: string;
359
+ /**
360
+ * Keep the body verbatim instead of the display cap. For records where the
361
+ * entry IS the durable copy of the text (owner input that a compaction
362
+ * boundary may otherwise lose), a truncated record would be a partial loss.
363
+ */
364
+ fullContent?: boolean;
365
+ }): void {
366
+ const { type, source, content, display = true, steer = false, turn = 0 } = params;
367
+ const injection = createInjection(
368
+ type,
369
+ source,
370
+ content,
371
+ display,
372
+ steer,
373
+ turn,
374
+ params.fullContent === true ? undefined : MAX_INJECTION_CONTENT,
375
+ );
376
+
377
+ // If explicit sessionId provided, switch bucket temporarily
378
+ if (params.sessionId && params.sessionId !== _activeSessionId) {
379
+ const prev = _activeSessionId;
380
+ _activeSessionId = params.sessionId;
381
+ try {
382
+ const altBucket = getBucket();
383
+ altBucket.injections.push(injection);
384
+ trimBucket(altBucket);
385
+ } finally {
386
+ _activeSessionId = prev;
387
+ }
388
+ } else {
389
+ const bucket = getBucket();
390
+ bucket.injections.push(injection);
391
+ trimBucket(bucket);
392
+ }
393
+
394
+ appendInjectionEntry(injection);
395
+ }
396
+
397
+ /**
398
+ * Append the durable record for one tracked injection. Best-effort: the
399
+ * in-memory bucket already holds it, and a missing/failing seam must never
400
+ * break the send path it observes.
401
+ */
402
+ function appendInjectionEntry(injection: Injection): void {
403
+ try {
404
+ _entryAppender?.appendEntry(INJECTION_ENTRY_TYPE, injection);
405
+ } catch (e) {
406
+ log.debug(`[injection-tracker] durable injection entry append failed: ${e}`);
407
+ }
408
+ }
409
+
410
+ /**
411
+ * Rebuild the injection list from the session branch entries.
412
+ *
413
+ * Branch-sensitive: only entries on the ACTIVE branch count, so a checkout or
414
+ * a resume sees exactly the injections that branch contains. Abandoned
415
+ * branches (entries off the current leaf path) are alternative histories and
416
+ * are never replayed. Malformed payloads are skipped rather than trusted; the
417
+ * per-bucket cap is applied after the scan, dropping the oldest.
418
+ */
419
+ export function readInjectionsFromBranch(entries: readonly unknown[]): Injection[] {
420
+ const injections: Injection[] = [];
421
+ for (const raw of entries) {
422
+ const entry = raw as { type?: string; customType?: string; data?: unknown } | null;
423
+ if (entry?.type !== "custom" || entry.customType !== INJECTION_ENTRY_TYPE) continue;
424
+ const data = entry.data as Partial<Injection> | null | undefined;
425
+ if (!data || typeof data !== "object") continue;
426
+ if (typeof data.source !== "string" || typeof data.content !== "string") continue;
427
+ injections.push({
428
+ id: typeof data.id === "string" ? data.id : nextId("inj"),
429
+ type: (typeof data.type === "string" ? data.type : "other") as Injection["type"],
430
+ source: data.source,
431
+ content: data.content,
432
+ timestamp: typeof data.timestamp === "number" ? data.timestamp : 0,
433
+ display: data.display !== false,
434
+ steer: data.steer === true,
435
+ turn: typeof data.turn === "number" ? data.turn : 0,
436
+ });
437
+ }
438
+ return injections.length > MAX_INJECTIONS ? injections.slice(-MAX_INJECTIONS) : injections;
439
+ }
440
+
441
+ /**
442
+ * Read the active session key from a ctx (session file preferred, id as
443
+ * fallback). Returns undefined when the manager is absent or stale.
444
+ */
445
+ function readSessionKey(ctx: unknown): string | undefined {
446
+ try {
447
+ const sm = (
448
+ ctx as
449
+ | {
450
+ sessionManager?: { getSessionFile?: () => string | null; getSessionId?: () => string };
451
+ }
452
+ | null
453
+ | undefined
454
+ )?.sessionManager;
455
+ if (sm) return sm.getSessionFile?.() ?? sm.getSessionId?.();
456
+ } catch {
457
+ // sessionManager getter may throw on stale ctx
458
+ }
459
+ return undefined;
460
+ }
461
+
462
+ /**
463
+ * Replace the active session's bucket with the branch reconstruction.
464
+ * Replacement, not merge: the branch is the source of truth, and an in-memory
465
+ * entry that is not on the branch is an abandoned history. A stale ctx keeps
466
+ * the in-memory bucket instead of emptying it.
467
+ */
468
+ export function reconstructInjectionBucket(ctx: unknown): void {
469
+ let branch: readonly unknown[];
470
+ try {
471
+ const sm = (ctx as { sessionManager?: { getBranch?: () => unknown[] } } | null | undefined)
472
+ ?.sessionManager;
473
+ branch = typeof sm?.getBranch === "function" ? (sm.getBranch() ?? []) : [];
474
+ } catch {
475
+ return;
476
+ }
477
+ if (!Array.isArray(branch)) return;
478
+ const key = _activeSessionId ?? "default";
479
+ _buckets.set(key, {
480
+ injections: readInjectionsFromBranch(branch),
481
+ maxInjections: MAX_INJECTIONS,
482
+ });
483
+ }
484
+
485
+ function createInjection(
486
+ type: Injection["type"],
487
+ source: string,
488
+ content: string,
489
+ display: boolean,
490
+ steer: boolean,
491
+ turn: number,
492
+ contentLimit: number | undefined,
493
+ ): Injection {
494
+ return {
495
+ id: nextId("inj"),
496
+ type,
497
+ source,
498
+ content: contentLimit === undefined ? content : content.slice(0, contentLimit),
499
+ timestamp: Date.now(),
500
+ display,
501
+ steer,
502
+ turn,
503
+ };
504
+ }
505
+
506
+ function trimBucket(bucket: InjectionBucket): void {
507
+ if (bucket.injections.length > bucket.maxInjections) {
508
+ bucket.injections = bucket.injections.slice(-bucket.maxInjections);
509
+ }
510
+ }
511
+
512
+ /**
513
+ * Get all injections tracked for the active session.
514
+ */
515
+ export function getInjections(sessionId?: string): Injection[] {
516
+ if (sessionId) {
517
+ const bucket = _buckets.get(sessionId);
518
+ return bucket ? [...bucket.injections] : [];
519
+ }
520
+ return [...getBucket().injections];
521
+ }
522
+
523
+ /**
524
+ * Extract plain text from message content array for tracking.
525
+ */
526
+ export function extractText(content: unknown[]): string {
527
+ if (!Array.isArray(content)) return String(content ?? "").slice(0, 200);
528
+ return content
529
+ .filter((c): c is { type: string; text?: string } => typeof c === "object" && c !== null)
530
+ .map((c) => c.text ?? "")
531
+ .join(" ")
532
+ .slice(0, 200);
533
+ }
534
+
535
+ /**
536
+ * Wrapper around pi.sendMessage that also tracks the injection.
537
+ * Use this instead of pi.sendMessage for all extension-injected messages.
538
+ */
539
+ /**
540
+ * Map a source to a priority tier for the per-turn whisper cap.
541
+ * Default: "low" (most whispers are advisory).
542
+ *
543
+ * Critical: auto-recovery, agent loops,
544
+ * timer/fire (user-scheduled and compaction-resume wake-ups).
545
+ * Bypasses WHISPER_CAPS.high - only subject to PER_SOURCE_CAP.
546
+ * A user-set timer is time-critical by definition: if 3 other
547
+ * high-priority whispers have already fired in the turn, the
548
+ * timer whisper must still reach the agent, otherwise the user
549
+ * perceives "timer didn't fire." See test-timer-fire-suppression.
550
+ * High: enforcement-critical, compaction-retry exhausted, threshold-exhausted
551
+ * Medium: context-80%+, analytics, navigation
552
+ * Low: hints, suggestions, drift, dreamer, etc.
553
+ */
554
+ function priorityFromSource(source: string, options?: { triggerTurn?: boolean }): WhisperPriority {
555
+ if (/auto-recovery|turn-outcome\/loop|timer\/fire/.test(source)) {
556
+ return "critical";
557
+ }
558
+ if (
559
+ /enforcement\/whisper|exhausted|compaction-retry|context-manager\/rotation/.test(source) ||
560
+ options?.triggerTurn === true
561
+ ) {
562
+ return "high";
563
+ }
564
+ if (/analytics|navigation|context-full|register-session-start/.test(source)) {
565
+ return "medium";
566
+ }
567
+ return "low";
568
+ }
569
+
570
+ /**
571
+ * Translate the funnel's delivery class into pi-core's `sendCustomMessage`
572
+ * option shape (see the DELIVERY CONTRACT above `sendTrackedMessage`).
573
+ *
574
+ * - `deliverAs: "nextTurn"` is returned unchanged (branch 1).
575
+ * - `triggerTurn: true` is returned unchanged (branch 2 while streaming,
576
+ * branch 3 when idle).
577
+ * - `delivery: "live"` resolves to `{ deliverAs }` with triggerTurn OMITTED:
578
+ * branch 2 requires `triggerTurn !== false` while streaming, and omission
579
+ * never starts a run when idle.
580
+ * - `delivery: "park"` resolves to `{ deliverAs, triggerTurn: false }`:
581
+ * branch 4 while streaming, branch 5 when idle.
582
+ * - no class: returned unchanged.
583
+ */
584
+ function resolveDeliveryOptions(options?: {
585
+ triggerTurn?: boolean;
586
+ deliverAs?: string;
587
+ delivery?: "live" | "park";
588
+ }): { triggerTurn?: boolean; deliverAs?: string } | undefined {
589
+ if (!options) return options;
590
+ if (options.deliverAs === "nextTurn") return options;
591
+ if (options.triggerTurn === true) return options;
592
+ if (options.delivery === "live") return { deliverAs: options.deliverAs ?? "steer" };
593
+ if (options.delivery === "park") {
594
+ return { deliverAs: options.deliverAs ?? "steer", triggerTurn: false };
595
+ }
596
+ return options;
597
+ }
598
+
599
+ /**
600
+ * Deliver one agent-bound message and report whether it was ACCEPTED for
601
+ * delivery, so a counter that claims a message was sent can be held to
602
+ * what actually left this function.
603
+ *
604
+ * DELIVERY CONTRACT (pi-core 1.0.2 `AgentSession.sendCustomMessage`, branch
605
+ * order at dist/core/agent-session.js:1756-1782):
606
+ * 1. deliverAs === "nextTurn" -> queued for the next user prompt
607
+ * 2. isStreaming && triggerTurn !== false -> agent.steer() (agent.followUp()
608
+ * for deliverAs "followUp") - the
609
+ * only branch that reaches a live run
610
+ * 3. triggerTurn (truthy) -> starts a run (_runAgentPrompt)
611
+ * 4. isStreaming -> parked to the end-of-turn flush
612
+ * (_pendingCustomMessages)
613
+ * 5. otherwise -> appended to the session now
614
+ * `delivery` names the intent for the streaming case; this funnel is the one
615
+ * place that translates it into pi-core's option shape:
616
+ * - "live": steer into the running loop (branch 2). The resolved shape OMITS
617
+ * triggerTurn - pi 0.84.2 made `triggerTurn: false` park (branch 4,
618
+ * PR #8022), so `{ deliverAs: "steer", triggerTurn: false }` no longer
619
+ * steers. When idle a live send is appended (branch 5): it never starts a
620
+ * run by itself.
621
+ * - "park": record for the end-of-turn flush while a run is active (branch 4),
622
+ * resolved as `{ deliverAs, triggerTurn: false }`. When idle: appended.
623
+ * - triggerTurn: true keeps its wake meaning whatever `delivery` says
624
+ * (branch 3 when idle, branch 2 while streaming).
625
+ * - deliverAs: "nextTurn" is passed through unchanged (branch 1).
626
+ * A send with no class passes through unchanged (the pre-class call shape).
627
+ *
628
+ * RETURN CONTRACT: `true` when the message was handed to `pi.sendMessage`
629
+ * (now, or scheduled on the deferred macrotask when `triggerTurn` defers),
630
+ * `false` when a suppression path dropped it outright: cognitive nudges
631
+ * disabled, the per-turn/per-source flood cap, or the cross-call reprime
632
+ * cooldown. Callers that count what they sent MUST branch on this value;
633
+ * callers that treat whispers as best-effort may ignore it.
634
+ *
635
+ * `true` is not a guarantee that the model reads it: for a `triggerTurn`
636
+ * wake with a `wakeDefer` hook the send can still be withdrawn or parked by
637
+ * the CALLER's own liveness answer inside the deferred macrotask (that
638
+ * caller already owns redelivery, so it does not need this signal). Every
639
+ * non-deferred message reaches pi-core's session stream: a live send steers
640
+ * the running loop, a park send is appended immediately when idle and parked
641
+ * for the end-of-turn flush when a run is active - a suppression upstream of
642
+ * `pi.sendMessage` is the only way a whisper reaches no stream at all.
643
+ */
644
+ export function sendTrackedMessage(
645
+ pi: any,
646
+ params: {
647
+ customType?: string;
648
+ content: { type: string; text?: string }[];
649
+ display?: boolean;
650
+ details?: unknown;
651
+ },
652
+ options?: { triggerTurn?: boolean; deliverAs?: string; delivery?: "live" | "park" },
653
+ injectionMeta: {
654
+ type: Injection["type"];
655
+ source: string;
656
+ steer?: boolean;
657
+ /**
658
+ * Mark this send as an advisory of the given kind. The funnel then
659
+ * registers it in the unresolved-advisory registry, tags the delivered
660
+ * message's details with its correlation id (`BRAID_ID`), and the append
661
+ * events (`message_start`/`message_end`) retire it. Only accepted sends
662
+ * register: every suppression path above returns before the
663
+ * registration. Advisory kinds are owned by their emitters; this module
664
+ * never learns what any kind means.
665
+ */
666
+ advisory?: string;
667
+ } = { type: "other", source: "unknown" },
668
+ /**
669
+ * `bypassFloodCap: true` skips the per-source / per-priority flood
670
+ * protection in `turn-dedup.tryWhisper`. Use this ONLY for
671
+ * user/agent-contracted events where dropping the message is a
672
+ * correctness bug: timer fires (user scheduled, post-compaction
673
+ * resume), session-shutdown warnings, hard errors. The cap still
674
+ * applies to other system whispers (enforcement, dreamer, heartbeats).
675
+ */
676
+ bypass: { bypassFloodCap?: boolean } = {},
677
+ /**
678
+ * Busy-deferral for triggerTurn wakes. When set and the deferred
679
+ * macrotask finds the session busy at send time (isAgentBusy():
680
+ * ctx.signal undefined while ctx.isIdle() is false — a compaction or
681
+ * pre-flight window where pi-core's sendCustomMessage would route the raw
682
+ * triggerTurn into _runAgentPrompt and start a competing agent run),
683
+ * onBusy() runs INSTEAD of the send and the caller owns redelivery (the
684
+ * timer's wake-retry queue). Wakes without this hook send unchanged — the
685
+ * run-region gate below stays their catch-all rewrite.
686
+ *
687
+ * isWithdrawn() is the caller's own liveness answer for that same moment:
688
+ * this send is no longer wanted (the timer's cancel retired the wake), so
689
+ * it must neither go out nor be re-parked. Asked BEFORE the busy check —
690
+ * withdrawal is terminal and monotone, busyness is a transient hold, and
691
+ * re-parking a withdrawn send would resurrect the delivery state its
692
+ * retirer already dropped. Omitted, the busy check is the only gate,
693
+ * exactly as before.
694
+ */
695
+ wakeDefer?: { onBusy: () => void; isWithdrawn?: () => boolean },
696
+ ): boolean {
697
+ // braid.suppressNudges is the universal
698
+ // off-switch. Apply it here so every sendTrackedMessage call site
699
+ // (20+ callers across enforcement, dreamer, memory, timer, drift,
700
+ // hints, etc.) automatically respects the setting without each
701
+ // site needing its own check. This was previously checked in only
702
+ // 4 sites (sendEnforcementWhisper + 3 analytics/index.ts sites),
703
+ // so setting braid.suppressNudges=true still delivered ~70% of
704
+ // agent-facing whispers. Now the check is centralized at the
705
+ // single entry point.
706
+ if (areCognitiveNudgesDisabled()) {
707
+ log.debug(
708
+ `[injection-tracker] Tracked message suppressed via braid.suppressNudges=true ` +
709
+ `(source: ${injectionMeta.source})`,
710
+ );
711
+ return false;
712
+ }
713
+
714
+ // ROADMAP EW-7.12+: apply the universal whisper envelope so the agent
715
+ // can distinguish system-injected messages from human user input. Done
716
+ // before the flood cap so the tracked (and potentially suppressed)
717
+ // content reflects what would have been delivered. See
718
+ // `lib/utils/whisper-format.ts` for the rationale and migration story.
719
+ applyWhisperEnvelope(params.content, injectionMeta.source);
720
+
721
+ // Per-turn whisper cap (flood protection). Critical paths always pass;
722
+ // other priorities are capped per WHISPER_CAPS in turn-dedup.ts.
723
+ // We track the suppressed whisper in the injection log so users can see
724
+ // it was filtered (not silently lost).
725
+ // bypassFloodCap:true skips the cap entirely - reserved for
726
+ // user/agent-contracted events (see JSDoc).
727
+ if (!bypass.bypassFloodCap) {
728
+ const priority = priorityFromSource(injectionMeta.source, options);
729
+ if (!tryWhisper(priority, injectionMeta.source)) {
730
+ trackInjection({
731
+ type: injectionMeta.type,
732
+ source: injectionMeta.source,
733
+ content: extractText(params.content),
734
+ display: false,
735
+ steer: false,
736
+ turn: 0,
737
+ });
738
+ log.debug(`[flood-cap] ${priority} whisper from ${injectionMeta.source} suppressed`);
739
+ return false;
740
+ }
741
+ }
742
+
743
+ const text = extractText(params.content);
744
+
745
+ // Cross-call exact-repeat de-bloat. The per-turn flood cap above only caps
746
+ // whispers WITHIN a turn, so a body that re-fires after its per-turn window
747
+ // closed was re-injected turn after turn — 41% of whisper deliveries (3,129
748
+ // of 7,690) measured as exact-repeat bodies in the same session. Same
749
+ // digit-normalized body inside REPRIME_COOLDOWN_MS is suppressed (tracked
750
+ // display:false so it is visible as filtered, matching the flood-cap path).
751
+ // triggerTurn:true wakes always pass — a dropped wake is a correctness bug.
752
+ // First occurrence and genuinely different bodies always pass. See
753
+ // docs/ tool-whisper-benchmark.md .1 and the MARS dedup lesson
754
+ // for the digit-collapse key.
755
+ const reprimeKey = reprimeBodyKey(text);
756
+ const suppressReprime = options?.triggerTurn !== true && withinReprimeCooldown(reprimeKey);
757
+ if (suppressReprime) {
758
+ trackInjection({
759
+ type: injectionMeta.type,
760
+ source: injectionMeta.source,
761
+ content: text,
762
+ display: false,
763
+ steer: false,
764
+ turn: 0,
765
+ });
766
+ log.debug(
767
+ `[reprime] exact-repeat body suppressed (source ${injectionMeta.source}, within ${REPRIME_COOLDOWN_MS}ms window)`,
768
+ );
769
+ return false;
770
+ }
771
+ markReprimeEmitted(reprimeKey);
772
+
773
+ trackInjection({
774
+ type: injectionMeta.type,
775
+ source: injectionMeta.source,
776
+ content: text,
777
+ display: params.display ?? true,
778
+ steer: injectionMeta.steer ?? false,
779
+ turn: 0,
780
+ });
781
+
782
+ // Tag message metadata so compaction can identify injected messages
783
+ // and exclude them from LLM summarization (prevents nudge conflate).
784
+ // An advisory also carries its registry correlation id here: the append
785
+ // events repeat the same `details` object, which is how the registry
786
+ // entry retires (see the registry block above).
787
+ const advisory = injectionMeta.advisory;
788
+ const advisoryId = advisory === undefined ? undefined : nextId("adv");
789
+ if (injectionMeta.type !== "other" || advisoryId !== undefined) {
790
+ const existingDetails =
791
+ typeof params.details === "object" && params.details !== null
792
+ ? (params.details as Record<string, unknown>)
793
+ : {};
794
+ if (injectionMeta.type !== "other") {
795
+ existingDetails[BRAID_INJECTED] = true;
796
+ existingDetails[BRAID_SOURCE] = injectionMeta.source;
797
+ }
798
+ if (advisoryId !== undefined) existingDetails[BRAID_ID] = advisoryId;
799
+ params.details = existingDetails;
800
+ }
801
+ if (advisoryId !== undefined && advisory !== undefined) {
802
+ registerUnresolvedAdvisory({ id: advisoryId, advisory, emittedAt: advisoryNow() });
803
+ }
804
+
805
+ // Translate the declared delivery class into pi-core's option shape once.
806
+ // The run-region gate below only ever rewrites triggerTurn wakes, at send
807
+ // time; the class translation itself is static.
808
+ const resolvedOptions = resolveDeliveryOptions(options);
809
+
810
+ // This is the nuclear fix for the recurring post-compaction stack overflow.
811
+ // When triggerTurn:true is set, pi.sendMessage calls sendCustomMessage →
812
+ // _runAgentPrompt → agent loop synchronously (the async function preamble
813
+ // before the first await sets up the chain). If the agent loop fires events
814
+ // whose handlers call sendTrackedMessage with triggerTurn:true, the chain
815
+ // becomes recursive and overflows the V8 stack — even with the
816
+ // MAX_REENTRY_DEPTH guard below, because the guard only catches the SECOND
817
+ // re-entrant call, not the first synchronous chain from the agent loop.
818
+ //
819
+ // setTimeout(0) creates a real macrotask boundary: the call stack fully
820
+ // unwinds before _runAgentPrompt starts. This prevents ALL synchronous
821
+ // re-entry, regardless of the call depth or event chain complexity.
822
+ //
823
+ // For non-triggerTurn messages (steer, followUp, silent push), the
824
+ // synchronous path is preserved — they don't enter the agent loop and
825
+ // can't cause stack overflow.
826
+ const shouldDefer = options?.triggerTurn === true;
827
+ if (shouldDefer || _sendDepth >= MAX_REENTRY_DEPTH) {
828
+ if (!shouldDefer) {
829
+ log.warn(
830
+ `sendTrackedMessage re-entry depth ${_sendDepth}/${MAX_REENTRY_DEPTH} - deferring to setTimeout(0)`,
831
+ );
832
+ }
833
+ // Mark depth as busy before deferring so the agent loop that starts from
834
+ // the deferred pi.sendMessage inherits the depth guard. Without this,
835
+ // non-triggerTurn sendTrackedMessage calls from tool_result handlers
836
+ // during that agent turn would re-enter synchronously.
837
+ _sendDepth++;
838
+ setTimeout(() => {
839
+ try {
840
+ // Withdrawal check at SEND time, before the busy check: the caller
841
+ // may have retired this wake in the window between the deferral and
842
+ // this macrotask (timer cancel -> retireTimer). A withdrawn send
843
+ // must not go out, and must not be re-parked either — onBusy()
844
+ // exists to hold a LIVE wake for later, and handing it a withdrawn
845
+ // one re-arms delivery state (a retry ladder, a parked fire) for an
846
+ // id the canceller already dropped, which only a downstream guard
847
+ // would then have to suppress a second time.
848
+ if (options?.triggerTurn === true && wakeDefer?.isWithdrawn?.() === true) {
849
+ log.debug(
850
+ `[injection-tracker] deferred send withdrawn by its caller (source: ${injectionMeta.source})`,
851
+ );
852
+ return;
853
+ }
854
+ // State-based busy check at SEND time: the deferred macrotask may
855
+ // land in a window the region flag does not cover — a compaction
856
+ // that outlived the gate's fail-safe (region auto-cleared), or any
857
+ // busy slice between events. A positively-determined busy state
858
+ // with a re-queue hook holds the wake instead of sending it into a
859
+ // session whose next raw triggerTurn send would start a competing
860
+ // agent run and hit pi-core's activeRun guard. The run-region gate
861
+ // below remains the catch-all rewrite for wakes without a hook.
862
+ if (options?.triggerTurn === true && wakeDefer && isAgentBusy()) {
863
+ wakeDefer.onBusy();
864
+ return;
865
+ }
866
+ // Gate triggerTurn on the run-region state at send time: the
867
+ // deferred macrotask may land in a session prompt() pre-flight,
868
+ // where pi-core's isStreaming flag is false but a run is imminent.
869
+ // When gated, the wake becomes a live steer (steer into the streaming
870
+ // run / append to the session in the pre-flight) instead of a raw
871
+ // agent.prompt re-entry that would hit pi-core's activeRun guard.
872
+ pi.sendMessage(params, gateTriggerTurnOptions(resolvedOptions));
873
+ } finally {
874
+ _sendDepth--;
875
+ }
876
+ }, 0);
877
+ return true;
878
+ }
879
+
880
+ _sendDepth++;
881
+ try {
882
+ // Defense in depth: apply the gate on the synchronous path too (it only
883
+ // rewrites when a run region is active; otherwise it is a no-op).
884
+ pi.sendMessage(params, gateTriggerTurnOptions(resolvedOptions));
885
+ } finally {
886
+ _sendDepth--;
887
+ }
888
+ return true;
889
+ }
890
+
891
+ /**
892
+ * Clear injection history (e.g., on session_start fresh).
893
+ */
894
+ export function clearInjections(sessionId?: string): void {
895
+ if (sessionId) {
896
+ _buckets.delete(sessionId);
897
+ } else {
898
+ const key = _activeSessionId ?? "default";
899
+ _buckets.delete(key);
900
+ }
901
+ }
902
+
903
+ /**
904
+ * Clear ALL injection buckets, per-session reprime state, and in-flight
905
+ * advisory registrations. Nuclear option for testing.
906
+ */
907
+ export function clearAllBuckets(): void {
908
+ _buckets.clear();
909
+ _reprime.clear();
910
+ clearUnresolvedAdvisories();
911
+ }
912
+
913
+ /**
914
+ * Test hook: pin the clock used by reprime cooldown checks so fixtures can
915
+ * prove the cooldown window closes without waiting real minutes.
916
+ * Pass null to restore Date.now().
917
+ */
918
+ export function _setReprimeClockForTests(nowMs: number | null): void {
919
+ _nowOverride = nowMs;
920
+ }
921
+
922
+ /**
923
+ * Register session lifecycle handlers for injection tracking.
924
+ * Call from an extension that has access to pi events.
925
+ * Automatically scopes injections to the current session.
926
+ *
927
+ * Durable path: the extension API's `appendEntry` is captured as the write
928
+ * seam for branch entries, and `session_start` / `session_tree` rebuild the
929
+ * active bucket from `getBranch()`. The rebuild is registered in the
930
+ * Background phase on purpose: context-lifecycle clears the tracker in its
931
+ * MemoryState session_start handler, so a rebuild registered there would be
932
+ * wiped before it was ever read. Background runs last by construction.
933
+ */
934
+ export function registerInjectionTracker(pi: {
935
+ on: (event: string, handler: (...args: any[]) => any) => void;
936
+ appendEntry?: <T = unknown>(customType: string, data?: T) => void;
937
+ }): void {
938
+ // Capture the durable write path. The arrow defers dispatch to call time so
939
+ // the runtime's own appendEntry (initialized only after the session starts)
940
+ // is resolved on each write; an API without the seam degrades to in-memory.
941
+ _entryAppender =
942
+ typeof pi.appendEntry === "function"
943
+ ? { appendEntry: (customType, data) => pi.appendEntry!(customType, data) }
944
+ : undefined;
945
+
946
+ // The local type widens ExtensionAPI's overloaded on() so we can
947
+ // pass any event name + handler without TypeScript asking which
948
+ // overload applies. The caller must provide a real ExtensionAPI.
949
+ const onAny = pi.on as (event: string, handler: (...args: any[]) => any) => void;
950
+
951
+ onAny("session_start", (_event: unknown, ctx: unknown) => {
952
+ setActiveSessionId(readSessionKey(ctx));
953
+ });
954
+
955
+ // pi-native tree navigation (`/tree`, ctx.navigateTree) emits session_tree;
956
+ // realign the bucket with the new branch immediately instead of waiting for
957
+ // the next session_start. (A branch change committed directly through
958
+ // sessionManager.branchWithSummary emits nothing; that path realigns at the
959
+ // next session_start, which the durable entries make correct.)
960
+ onAny("session_tree", (_event: unknown, ctx: unknown) => {
961
+ const sessionId = readSessionKey(ctx);
962
+ if (sessionId) setActiveSessionId(sessionId);
963
+ reconstructInjectionBucket(ctx);
964
+ });
965
+
966
+ // Advisory retirement: pi emits `message_start` + `message_end` when a
967
+ // custom message is appended (both for the immediate append and for a
968
+ // parked flush; a steered message emits them when the running loop consumes
969
+ // it). The event's message carries the `details` object this module tagged
970
+ // with `BRAID_ID`, so the id in the event is the whole correlation. Both
971
+ // events are handled: one fires on append, and pairing them means a future
972
+ // pi change to either emission point still retires the entry.
973
+ const retireAdvisoryFromEvent = (event: unknown) => {
974
+ const message = (event as { message?: { details?: unknown } } | null | undefined)?.message;
975
+ const details = message?.details as Record<string, unknown> | undefined;
976
+ const id = details?.[BRAID_ID];
977
+ if (typeof id === "string") resolveUnresolvedAdvisory(id);
978
+ };
979
+ onAny(MESSAGE_START, retireAdvisoryFromEvent);
980
+ onAny(MESSAGE_END, retireAdvisoryFromEvent);
981
+
982
+ // Branch reconstruction at the session boundary. Background phase: after
983
+ // every MemoryState handler (including context-lifecycle's clearInjections)
984
+ // has run. Synchronous body on purpose: the rebuild must be in place before
985
+ // the first agent turn tracks an injection.
986
+ registerSessionStartHandler(
987
+ pi,
988
+ SessionPhase.Background,
989
+ async (_event: unknown, ctx: unknown) => {
990
+ const sessionId = readSessionKey(ctx);
991
+ if (sessionId) setActiveSessionId(sessionId);
992
+ reconstructInjectionBucket(ctx);
993
+ },
994
+ "injection-tracker-branch-rebuild",
995
+ );
996
+
997
+ pi.on(SESSION_SHUTDOWN, (_event, ctx) => {
998
+ // Clear per-session reprime state so a body can fire fresh in the next
999
+ // session (no cross-session cooldown bleed).
1000
+ const sessionId = readSessionKey(ctx);
1001
+ if (sessionId) _reprime.delete(sessionId);
1002
+ if (_activeSessionId) _reprime.delete(_activeSessionId);
1003
+ // Delete the ended session's injection bucket so per-session state does
1004
+ // not accumulate for the process lifetime. The durable entries stay in
1005
+ // the session file, so the next session_start reconstructs them.
1006
+ if (sessionId) _buckets.delete(sessionId);
1007
+ if (_activeSessionId) _buckets.delete(_activeSessionId);
1008
+ // In-flight advisories belong to the session that emitted them; the next
1009
+ // session must not inherit an unresolved flag (its own notices would be
1010
+ // silently suppressed until the TTL).
1011
+ clearUnresolvedAdvisories();
1012
+ setActiveSessionId(undefined);
1013
+ });
1014
+ }