pi-braid 0.0.0-stage → 0.40.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (1011) hide show
  1. package/AGENTS.md +195 -0
  2. package/CONTRIBUTING.md +302 -0
  3. package/LICENSE +21 -0
  4. package/README.md +260 -2
  5. package/TOOLS.md +147 -0
  6. package/dist/extensions/cognitive/mars-reflector/index.d.ts +82 -0
  7. package/dist/extensions/cognitive/mars-reflector/index.js +327 -0
  8. package/dist/extensions/cognitive/metacognition/handlers/claim-verification.d.ts +23 -0
  9. package/dist/extensions/cognitive/metacognition/handlers/claim-verification.js +233 -0
  10. package/dist/extensions/cognitive/metacognition/handlers/finalize.d.ts +27 -0
  11. package/dist/extensions/cognitive/metacognition/handlers/finalize.js +557 -0
  12. package/dist/extensions/cognitive/metacognition/handlers/hypothesize.d.ts +19 -0
  13. package/dist/extensions/cognitive/metacognition/handlers/hypothesize.js +291 -0
  14. package/dist/extensions/cognitive/metacognition/handlers/scoring.d.ts +28 -0
  15. package/dist/extensions/cognitive/metacognition/handlers/scoring.js +173 -0
  16. package/dist/extensions/cognitive/metacognition/handlers/think-budget.d.ts +85 -0
  17. package/dist/extensions/cognitive/metacognition/handlers/think-budget.js +164 -0
  18. package/dist/extensions/cognitive/metacognition/handlers/think.d.ts +27 -0
  19. package/dist/extensions/cognitive/metacognition/handlers/think.js +374 -0
  20. package/dist/extensions/cognitive/metacognition/handlers/verify.d.ts +53 -0
  21. package/dist/extensions/cognitive/metacognition/handlers/verify.js +321 -0
  22. package/dist/extensions/cognitive/metacognition/index.d.ts +10 -0
  23. package/dist/extensions/cognitive/metacognition/index.js +90 -0
  24. package/dist/extensions/cognitive/reasoning/index.d.ts +43 -0
  25. package/dist/extensions/cognitive/reasoning/index.js +99 -0
  26. package/dist/extensions/cognitive/sycophancy-detector/index.d.ts +16 -0
  27. package/dist/extensions/cognitive/sycophancy-detector/index.js +203 -0
  28. package/dist/extensions/cognitive/topic-drift/index.d.ts +51 -0
  29. package/dist/extensions/cognitive/topic-drift/index.js +346 -0
  30. package/dist/extensions/cognitive/turn-outcome/index.d.ts +35 -0
  31. package/dist/extensions/cognitive/turn-outcome/index.js +163 -0
  32. package/dist/extensions/context-management/index.d.ts +77 -0
  33. package/dist/extensions/context-management/index.js +339 -0
  34. package/dist/extensions/core/agent-environment/index.d.ts +30 -0
  35. package/dist/extensions/core/agent-environment/index.js +89 -0
  36. package/dist/extensions/core/polyfill/index.d.ts +28 -0
  37. package/dist/extensions/core/polyfill/index.js +474 -0
  38. package/dist/extensions/core/prompt-builder/awareness-whisper.d.ts +74 -0
  39. package/dist/extensions/core/prompt-builder/awareness-whisper.js +116 -0
  40. package/dist/extensions/core/prompt-builder/context-section.d.ts +41 -0
  41. package/dist/extensions/core/prompt-builder/context-section.js +101 -0
  42. package/dist/extensions/core/prompt-builder/custom-sections.d.ts +21 -0
  43. package/dist/extensions/core/prompt-builder/custom-sections.js +11 -0
  44. package/dist/extensions/core/prompt-builder/external-tool-guidelines.d.ts +23 -0
  45. package/dist/extensions/core/prompt-builder/external-tool-guidelines.js +37 -0
  46. package/dist/extensions/core/prompt-builder/identity.d.ts +33 -0
  47. package/dist/extensions/core/prompt-builder/identity.js +77 -0
  48. package/dist/extensions/core/prompt-builder/index.d.ts +33 -0
  49. package/dist/extensions/core/prompt-builder/index.js +496 -0
  50. package/dist/extensions/core/prompt-builder/inspect.d.ts +58 -0
  51. package/dist/extensions/core/prompt-builder/inspect.js +182 -0
  52. package/dist/extensions/core/prompt-builder/instance-composition.d.ts +101 -0
  53. package/dist/extensions/core/prompt-builder/instance-composition.js +416 -0
  54. package/dist/extensions/core/prompt-builder/memory-section.d.ts +20 -0
  55. package/dist/extensions/core/prompt-builder/memory-section.js +60 -0
  56. package/dist/extensions/core/prompt-builder/pi-reference-section.d.ts +17 -0
  57. package/dist/extensions/core/prompt-builder/pi-reference-section.js +11 -0
  58. package/dist/extensions/core/prompt-builder/project-docs-section.d.ts +42 -0
  59. package/dist/extensions/core/prompt-builder/project-docs-section.js +72 -0
  60. package/dist/extensions/core/prompt-builder/section-parity.d.ts +36 -0
  61. package/dist/extensions/core/prompt-builder/section-parity.js +66 -0
  62. package/dist/extensions/core/prompt-builder/section-publish.d.ts +30 -0
  63. package/dist/extensions/core/prompt-builder/section-publish.js +16 -0
  64. package/dist/extensions/core/prompt-builder/section.d.ts +75 -0
  65. package/dist/extensions/core/prompt-builder/section.js +127 -0
  66. package/dist/extensions/core/prompt-builder/surface-discipline-section.d.ts +18 -0
  67. package/dist/extensions/core/prompt-builder/surface-discipline-section.js +20 -0
  68. package/dist/extensions/core/prompt-builder/system-info-tool.d.ts +27 -0
  69. package/dist/extensions/core/prompt-builder/system-info-tool.js +67 -0
  70. package/dist/extensions/core/prompt-builder/tool-description-trim.d.ts +56 -0
  71. package/dist/extensions/core/prompt-builder/tool-description-trim.js +129 -0
  72. package/dist/extensions/core/prompt-builder/tool-guidelines.d.ts +80 -0
  73. package/dist/extensions/core/prompt-builder/tool-guidelines.js +179 -0
  74. package/dist/extensions/core/prompt-builder/tool-pipelines.d.ts +50 -0
  75. package/dist/extensions/core/prompt-builder/tool-pipelines.js +69 -0
  76. package/dist/extensions/core/prompt-builder/top-level-extensions.d.ts +44 -0
  77. package/dist/extensions/core/prompt-builder/top-level-extensions.js +300 -0
  78. package/dist/extensions/core/skills-tool/auto-inject.d.ts +333 -0
  79. package/dist/extensions/core/skills-tool/auto-inject.js +817 -0
  80. package/dist/extensions/core/skills-tool/index.d.ts +56 -0
  81. package/dist/extensions/core/skills-tool/index.js +200 -0
  82. package/dist/extensions/core/skills-tool/loading-guidance.d.ts +50 -0
  83. package/dist/extensions/core/skills-tool/loading-guidance.js +87 -0
  84. package/dist/extensions/core/skills-tool/session-records.d.ts +114 -0
  85. package/dist/extensions/core/skills-tool/session-records.js +268 -0
  86. package/dist/extensions/core/skills-tool/skill-triggers.d.ts +48 -0
  87. package/dist/extensions/core/skills-tool/skill-triggers.js +113 -0
  88. package/dist/extensions/enforcement/detection/malformed.d.ts +9 -0
  89. package/dist/extensions/enforcement/detection/malformed.js +30 -0
  90. package/dist/extensions/enforcement/detection/verification.d.ts +10 -0
  91. package/dist/extensions/enforcement/detection/verification.js +34 -0
  92. package/dist/extensions/enforcement/enforcement-types.d.ts +33 -0
  93. package/dist/extensions/enforcement/enforcement-types.js +24 -0
  94. package/dist/extensions/enforcement/handler-registry.d.ts +12 -0
  95. package/dist/extensions/enforcement/handler-registry.js +196 -0
  96. package/dist/extensions/enforcement/handlers/analysis/bpe-handler.d.ts +10 -0
  97. package/dist/extensions/enforcement/handlers/analysis/bpe-handler.js +37 -0
  98. package/dist/extensions/enforcement/handlers/analysis/dreamer-handler.d.ts +6 -0
  99. package/dist/extensions/enforcement/handlers/analysis/dreamer-handler.js +60 -0
  100. package/dist/extensions/enforcement/handlers/analysis/drift-handler.d.ts +6 -0
  101. package/dist/extensions/enforcement/handlers/analysis/drift-handler.js +75 -0
  102. package/dist/extensions/enforcement/handlers/analysis/feedback-handler.d.ts +6 -0
  103. package/dist/extensions/enforcement/handlers/analysis/feedback-handler.js +19 -0
  104. package/dist/extensions/enforcement/handlers/analysis/mars-handler.d.ts +14 -0
  105. package/dist/extensions/enforcement/handlers/analysis/mars-handler.js +99 -0
  106. package/dist/extensions/enforcement/handlers/analysis/reflection-handler.d.ts +6 -0
  107. package/dist/extensions/enforcement/handlers/analysis/reflection-handler.js +16 -0
  108. package/dist/extensions/enforcement/handlers/blocking.d.ts +16 -0
  109. package/dist/extensions/enforcement/handlers/blocking.js +33 -0
  110. package/dist/extensions/enforcement/handlers/message-analysis.d.ts +25 -0
  111. package/dist/extensions/enforcement/handlers/message-analysis.js +70 -0
  112. package/dist/extensions/enforcement/handlers/orphan-chains.d.ts +14 -0
  113. package/dist/extensions/enforcement/handlers/orphan-chains.js +44 -0
  114. package/dist/extensions/enforcement/handlers/over-correction-gate.d.ts +73 -0
  115. package/dist/extensions/enforcement/handlers/over-correction-gate.js +565 -0
  116. package/dist/extensions/enforcement/handlers/probe-handler.d.ts +31 -0
  117. package/dist/extensions/enforcement/handlers/probe-handler.js +111 -0
  118. package/dist/extensions/enforcement/handlers/register-adherence-meter.d.ts +52 -0
  119. package/dist/extensions/enforcement/handlers/register-adherence-meter.js +158 -0
  120. package/dist/extensions/enforcement/handlers/register-agent-end-api-error.d.ts +3 -0
  121. package/dist/extensions/enforcement/handlers/register-agent-end-api-error.js +69 -0
  122. package/dist/extensions/enforcement/handlers/register-input-handler.d.ts +10 -0
  123. package/dist/extensions/enforcement/handlers/register-input-handler.js +35 -0
  124. package/dist/extensions/enforcement/handlers/register-message-end.d.ts +6 -0
  125. package/dist/extensions/enforcement/handlers/register-message-end.js +388 -0
  126. package/dist/extensions/enforcement/handlers/register-post-cycle-hygiene.d.ts +25 -0
  127. package/dist/extensions/enforcement/handlers/register-post-cycle-hygiene.js +143 -0
  128. package/dist/extensions/enforcement/handlers/register-session-compact.d.ts +50 -0
  129. package/dist/extensions/enforcement/handlers/register-session-compact.js +207 -0
  130. package/dist/extensions/enforcement/handlers/register-session-shutdown-resumption.d.ts +21 -0
  131. package/dist/extensions/enforcement/handlers/register-session-shutdown-resumption.js +116 -0
  132. package/dist/extensions/enforcement/handlers/register-session-shutdown.d.ts +6 -0
  133. package/dist/extensions/enforcement/handlers/register-session-shutdown.js +38 -0
  134. package/dist/extensions/enforcement/handlers/register-session-start-discoverability.d.ts +34 -0
  135. package/dist/extensions/enforcement/handlers/register-session-start-discoverability.js +240 -0
  136. package/dist/extensions/enforcement/handlers/register-session-start.d.ts +16 -0
  137. package/dist/extensions/enforcement/handlers/register-session-start.js +198 -0
  138. package/dist/extensions/enforcement/handlers/register-tool-call.d.ts +6 -0
  139. package/dist/extensions/enforcement/handlers/register-tool-call.js +132 -0
  140. package/dist/extensions/enforcement/handlers/register-tool-result-formatting.d.ts +18 -0
  141. package/dist/extensions/enforcement/handlers/register-tool-result-formatting.js +56 -0
  142. package/dist/extensions/enforcement/handlers/register-tool-result.d.ts +6 -0
  143. package/dist/extensions/enforcement/handlers/register-tool-result.js +91 -0
  144. package/dist/extensions/enforcement/handlers/register-turn-end-hygiene.d.ts +35 -0
  145. package/dist/extensions/enforcement/handlers/register-turn-end-hygiene.js +385 -0
  146. package/dist/extensions/enforcement/handlers/routing-handler.d.ts +42 -0
  147. package/dist/extensions/enforcement/handlers/routing-handler.js +135 -0
  148. package/dist/extensions/enforcement/handlers/tool-tracker.d.ts +9 -0
  149. package/dist/extensions/enforcement/handlers/tool-tracker.js +122 -0
  150. package/dist/extensions/enforcement/handlers/turn-analysis.d.ts +41 -0
  151. package/dist/extensions/enforcement/handlers/turn-analysis.js +109 -0
  152. package/dist/extensions/enforcement/handlers/turn-end-handler.d.ts +9 -0
  153. package/dist/extensions/enforcement/handlers/turn-end-handler.js +451 -0
  154. package/dist/extensions/enforcement/index.d.ts +15 -0
  155. package/dist/extensions/enforcement/index.js +22 -0
  156. package/dist/extensions/enforcement/judge-utils.d.ts +73 -0
  157. package/dist/extensions/enforcement/judge-utils.js +83 -0
  158. package/dist/extensions/enforcement/nudge-manager.d.ts +106 -0
  159. package/dist/extensions/enforcement/nudge-manager.js +203 -0
  160. package/dist/extensions/enforcement/self-state-claims.d.ts +79 -0
  161. package/dist/extensions/enforcement/self-state-claims.js +167 -0
  162. package/dist/extensions/enforcement/session-health.d.ts +107 -0
  163. package/dist/extensions/enforcement/session-health.js +251 -0
  164. package/dist/extensions/enforcement/signals.d.ts +54 -0
  165. package/dist/extensions/enforcement/signals.js +47 -0
  166. package/dist/extensions/enforcement/similarity.d.ts +16 -0
  167. package/dist/extensions/enforcement/similarity.js +64 -0
  168. package/dist/extensions/enforcement/state.d.ts +40 -0
  169. package/dist/extensions/enforcement/state.js +74 -0
  170. package/dist/extensions/enforcement/substate/context-hygiene-state.d.ts +88 -0
  171. package/dist/extensions/enforcement/substate/context-hygiene-state.js +119 -0
  172. package/dist/extensions/enforcement/substate/error-tracking-state.d.ts +20 -0
  173. package/dist/extensions/enforcement/substate/error-tracking-state.js +37 -0
  174. package/dist/extensions/enforcement/substate/memory-hygiene-state.d.ts +24 -0
  175. package/dist/extensions/enforcement/substate/memory-hygiene-state.js +37 -0
  176. package/dist/extensions/enforcement/substate/session-state.d.ts +34 -0
  177. package/dist/extensions/enforcement/substate/session-state.js +45 -0
  178. package/dist/extensions/enforcement/substate/thought-chain-state.d.ts +23 -0
  179. package/dist/extensions/enforcement/substate/thought-chain-state.js +43 -0
  180. package/dist/extensions/enforcement/substate/tool-tracking-state.d.ts +71 -0
  181. package/dist/extensions/enforcement/substate/tool-tracking-state.js +99 -0
  182. package/dist/extensions/enforcement/substate/verification-judge-state.d.ts +17 -0
  183. package/dist/extensions/enforcement/substate/verification-judge-state.js +39 -0
  184. package/dist/extensions/enforcement/task-evidence.d.ts +108 -0
  185. package/dist/extensions/enforcement/task-evidence.js +335 -0
  186. package/dist/extensions/enforcement/types.d.ts +35 -0
  187. package/dist/extensions/enforcement/types.js +5 -0
  188. package/dist/extensions/enforcement/validation.d.ts +12 -0
  189. package/dist/extensions/enforcement/validation.js +151 -0
  190. package/dist/extensions/enforcement/verification-judge.d.ts +110 -0
  191. package/dist/extensions/enforcement/verification-judge.js +214 -0
  192. package/dist/extensions/enforcement/whisper.d.ts +46 -0
  193. package/dist/extensions/enforcement/whisper.js +104 -0
  194. package/dist/extensions/heartbeat/analytics/ab-variant.d.ts +19 -0
  195. package/dist/extensions/heartbeat/analytics/ab-variant.js +86 -0
  196. package/dist/extensions/heartbeat/analytics/core.d.ts +12 -0
  197. package/dist/extensions/heartbeat/analytics/core.js +201 -0
  198. package/dist/extensions/heartbeat/analytics/format.d.ts +7 -0
  199. package/dist/extensions/heartbeat/analytics/format.js +111 -0
  200. package/dist/extensions/heartbeat/analytics/index.d.ts +14 -0
  201. package/dist/extensions/heartbeat/analytics/index.js +352 -0
  202. package/dist/extensions/heartbeat/analytics/shared.d.ts +85 -0
  203. package/dist/extensions/heartbeat/analytics/shared.js +69 -0
  204. package/dist/extensions/heartbeat/heartbeat-scheduler/index.d.ts +31 -0
  205. package/dist/extensions/heartbeat/heartbeat-scheduler/index.js +881 -0
  206. package/dist/extensions/heartbeat/heartbeat-scheduler/meta-learning.d.ts +10 -0
  207. package/dist/extensions/heartbeat/heartbeat-scheduler/meta-learning.js +49 -0
  208. package/dist/extensions/heartbeat/heartbeat-scheduler/modules/behavioral-drift.d.ts +17 -0
  209. package/dist/extensions/heartbeat/heartbeat-scheduler/modules/behavioral-drift.js +161 -0
  210. package/dist/extensions/heartbeat/heartbeat-scheduler/modules/budget.d.ts +13 -0
  211. package/dist/extensions/heartbeat/heartbeat-scheduler/modules/budget.js +101 -0
  212. package/dist/extensions/heartbeat/heartbeat-scheduler/modules/context-hygiene.d.ts +10 -0
  213. package/dist/extensions/heartbeat/heartbeat-scheduler/modules/context-hygiene.js +221 -0
  214. package/dist/extensions/heartbeat/heartbeat-scheduler/modules/evolver.d.ts +9 -0
  215. package/dist/extensions/heartbeat/heartbeat-scheduler/modules/evolver.js +65 -0
  216. package/dist/extensions/heartbeat/heartbeat-scheduler/modules/measurement.d.ts +8 -0
  217. package/dist/extensions/heartbeat/heartbeat-scheduler/modules/measurement.js +32 -0
  218. package/dist/extensions/heartbeat/heartbeat-scheduler/modules/recaller.d.ts +9 -0
  219. package/dist/extensions/heartbeat/heartbeat-scheduler/modules/recaller.js +75 -0
  220. package/dist/extensions/heartbeat/heartbeat-scheduler/modules/reflection-consolidator.d.ts +9 -0
  221. package/dist/extensions/heartbeat/heartbeat-scheduler/modules/reflection-consolidator.js +98 -0
  222. package/dist/extensions/heartbeat/heartbeat-scheduler/policies.d.ts +14 -0
  223. package/dist/extensions/heartbeat/heartbeat-scheduler/policies.js +149 -0
  224. package/dist/extensions/heartbeat/heartbeat-scheduler/state.d.ts +22 -0
  225. package/dist/extensions/heartbeat/heartbeat-scheduler/state.js +82 -0
  226. package/dist/extensions/heartbeat/heartbeat-scheduler/types.d.ts +124 -0
  227. package/dist/extensions/heartbeat/heartbeat-scheduler/types.js +7 -0
  228. package/dist/extensions/heartbeat/heartbeat-scheduler/whisper-batcher.d.ts +52 -0
  229. package/dist/extensions/heartbeat/heartbeat-scheduler/whisper-batcher.js +83 -0
  230. package/dist/extensions/manifest.d.ts +32 -0
  231. package/dist/extensions/manifest.js +251 -0
  232. package/dist/extensions/memory/context-lifecycle/helpers.d.ts +55 -0
  233. package/dist/extensions/memory/context-lifecycle/helpers.js +142 -0
  234. package/dist/extensions/memory/context-lifecycle/index.d.ts +17 -0
  235. package/dist/extensions/memory/context-lifecycle/index.js +977 -0
  236. package/dist/extensions/memory/context-lifecycle/policy-engine.d.ts +50 -0
  237. package/dist/extensions/memory/context-lifecycle/policy-engine.js +196 -0
  238. package/dist/extensions/memory/context-lifecycle/signal-detector.d.ts +28 -0
  239. package/dist/extensions/memory/context-lifecycle/signal-detector.js +224 -0
  240. package/dist/extensions/memory/context-lifecycle/state.d.ts +98 -0
  241. package/dist/extensions/memory/context-lifecycle/state.js +90 -0
  242. package/dist/extensions/memory/context-lifecycle/types.d.ts +132 -0
  243. package/dist/extensions/memory/context-lifecycle/types.js +273 -0
  244. package/dist/extensions/memory/context-manager/analysis.d.ts +47 -0
  245. package/dist/extensions/memory/context-manager/analysis.js +264 -0
  246. package/dist/extensions/memory/context-manager/handlers/compaction-chunked.d.ts +159 -0
  247. package/dist/extensions/memory/context-manager/handlers/compaction-chunked.js +658 -0
  248. package/dist/extensions/memory/context-manager/handlers/compaction-retry.d.ts +29 -0
  249. package/dist/extensions/memory/context-manager/handlers/compaction-retry.js +410 -0
  250. package/dist/extensions/memory/context-manager/handlers/compaction-trace.d.ts +74 -0
  251. package/dist/extensions/memory/context-manager/handlers/compaction-trace.js +180 -0
  252. package/dist/extensions/memory/context-manager/handlers/compaction-watchdog.d.ts +69 -0
  253. package/dist/extensions/memory/context-manager/handlers/compaction-watchdog.js +297 -0
  254. package/dist/extensions/memory/context-manager/handlers/compaction.d.ts +37 -0
  255. package/dist/extensions/memory/context-manager/handlers/compaction.js +2150 -0
  256. package/dist/extensions/memory/context-manager/handlers/context-emergency.d.ts +124 -0
  257. package/dist/extensions/memory/context-manager/handlers/context-emergency.js +364 -0
  258. package/dist/extensions/memory/context-manager/handlers/events.d.ts +5 -0
  259. package/dist/extensions/memory/context-manager/handlers/events.js +314 -0
  260. package/dist/extensions/memory/context-manager/handlers/navigation.d.ts +5 -0
  261. package/dist/extensions/memory/context-manager/handlers/navigation.js +86 -0
  262. package/dist/extensions/memory/context-manager/handlers/offload.d.ts +94 -0
  263. package/dist/extensions/memory/context-manager/handlers/offload.js +248 -0
  264. package/dist/extensions/memory/context-manager/handlers/rotation.d.ts +6 -0
  265. package/dist/extensions/memory/context-manager/handlers/rotation.js +304 -0
  266. package/dist/extensions/memory/context-manager/handlers/shared.d.ts +410 -0
  267. package/dist/extensions/memory/context-manager/handlers/shared.js +579 -0
  268. package/dist/extensions/memory/context-manager/handlers/tool-batch-boundary.d.ts +55 -0
  269. package/dist/extensions/memory/context-manager/handlers/tool-batch-boundary.js +190 -0
  270. package/dist/extensions/memory/context-manager/handlers/toolresult-capture-cap.d.ts +21 -0
  271. package/dist/extensions/memory/context-manager/handlers/toolresult-capture-cap.js +155 -0
  272. package/dist/extensions/memory/context-manager/handlers/tools/context-compress.d.ts +90 -0
  273. package/dist/extensions/memory/context-manager/handlers/tools/context-compress.js +1156 -0
  274. package/dist/extensions/memory/context-manager/handlers/tools/context-inspect.d.ts +16 -0
  275. package/dist/extensions/memory/context-manager/handlers/tools/context-inspect.js +276 -0
  276. package/dist/extensions/memory/context-manager/handlers/tools/context-navigate.d.ts +19 -0
  277. package/dist/extensions/memory/context-manager/handlers/tools/context-navigate.js +378 -0
  278. package/dist/extensions/memory/context-manager/handlers/tools/offload-recover.d.ts +13 -0
  279. package/dist/extensions/memory/context-manager/handlers/tools/offload-recover.js +181 -0
  280. package/dist/extensions/memory/context-manager/index.d.ts +3 -0
  281. package/dist/extensions/memory/context-manager/index.js +88 -0
  282. package/dist/extensions/memory/context-manager/pruning.d.ts +47 -0
  283. package/dist/extensions/memory/context-manager/pruning.js +406 -0
  284. package/dist/extensions/memory/context-manager/semantic-compress.d.ts +71 -0
  285. package/dist/extensions/memory/context-manager/semantic-compress.js +279 -0
  286. package/dist/extensions/memory/memory-agent-bridge/conflict-qa-tool.d.ts +20 -0
  287. package/dist/extensions/memory/memory-agent-bridge/conflict-qa-tool.js +71 -0
  288. package/dist/extensions/memory/memory-agent-bridge/explore-paths.d.ts +30 -0
  289. package/dist/extensions/memory/memory-agent-bridge/explore-paths.js +231 -0
  290. package/dist/extensions/memory/memory-agent-bridge/index.d.ts +28 -0
  291. package/dist/extensions/memory/memory-agent-bridge/index.js +124 -0
  292. package/dist/extensions/memory/memory-agent-bridge/memory-store-tool.d.ts +21 -0
  293. package/dist/extensions/memory/memory-agent-bridge/memory-store-tool.js +194 -0
  294. package/dist/extensions/memory/memory-agent-bridge/memory-tool.d.ts +22 -0
  295. package/dist/extensions/memory/memory-agent-bridge/memory-tool.js +548 -0
  296. package/dist/extensions/memory/scratchpad/format.d.ts +19 -0
  297. package/dist/extensions/memory/scratchpad/format.js +135 -0
  298. package/dist/extensions/memory/scratchpad/handlers.d.ts +53 -0
  299. package/dist/extensions/memory/scratchpad/handlers.js +469 -0
  300. package/dist/extensions/memory/scratchpad/index.d.ts +17 -0
  301. package/dist/extensions/memory/scratchpad/index.js +168 -0
  302. package/dist/extensions/memory/scratchpad/persistence.d.ts +46 -0
  303. package/dist/extensions/memory/scratchpad/persistence.js +343 -0
  304. package/dist/extensions/memory/scratchpad/types.d.ts +124 -0
  305. package/dist/extensions/memory/scratchpad/types.js +8 -0
  306. package/dist/extensions/memory/scratchpad/utils.d.ts +76 -0
  307. package/dist/extensions/memory/scratchpad/utils.js +236 -0
  308. package/dist/extensions/memory/session-recall/analyze.d.ts +58 -0
  309. package/dist/extensions/memory/session-recall/analyze.js +478 -0
  310. package/dist/extensions/memory/session-recall/context-aggregate.d.ts +117 -0
  311. package/dist/extensions/memory/session-recall/context-aggregate.js +315 -0
  312. package/dist/extensions/memory/session-recall/index.d.ts +29 -0
  313. package/dist/extensions/memory/session-recall/index.js +820 -0
  314. package/dist/extensions/memory/session-recall/query.d.ts +15 -0
  315. package/dist/extensions/memory/session-recall/query.js +38 -0
  316. package/dist/extensions/memory/session-recall/rank.d.ts +71 -0
  317. package/dist/extensions/memory/session-recall/rank.js +85 -0
  318. package/dist/extensions/memory/session-recall/search.d.ts +159 -0
  319. package/dist/extensions/memory/session-recall/search.js +682 -0
  320. package/dist/extensions/memory/session-recall/stats.d.ts +34 -0
  321. package/dist/extensions/memory/session-recall/stats.js +67 -0
  322. package/dist/extensions/memory/session-recall/text-utils.d.ts +82 -0
  323. package/dist/extensions/memory/session-recall/text-utils.js +184 -0
  324. package/dist/extensions/memory/three-memory-stores/episodes-disk.d.ts +43 -0
  325. package/dist/extensions/memory/three-memory-stores/episodes-disk.js +125 -0
  326. package/dist/extensions/memory/three-memory-stores/episodes.d.ts +46 -0
  327. package/dist/extensions/memory/three-memory-stores/episodes.js +299 -0
  328. package/dist/extensions/memory/three-memory-stores/handlers/whisper-recall.d.ts +25 -0
  329. package/dist/extensions/memory/three-memory-stores/handlers/whisper-recall.js +112 -0
  330. package/dist/extensions/memory/three-memory-stores/heuristics.d.ts +19 -0
  331. package/dist/extensions/memory/three-memory-stores/heuristics.js +89 -0
  332. package/dist/extensions/memory/three-memory-stores/index.d.ts +34 -0
  333. package/dist/extensions/memory/three-memory-stores/index.js +436 -0
  334. package/dist/extensions/memory/three-memory-stores/tool-reliability.d.ts +11 -0
  335. package/dist/extensions/memory/three-memory-stores/tool-reliability.js +38 -0
  336. package/dist/extensions/memory/three-memory-stores/types.d.ts +69 -0
  337. package/dist/extensions/memory/three-memory-stores/types.js +2 -0
  338. package/dist/extensions/memory/workspace-snapshot/index.d.ts +19 -0
  339. package/dist/extensions/memory/workspace-snapshot/index.js +363 -0
  340. package/dist/extensions/orchestrator/index.d.ts +19 -0
  341. package/dist/extensions/orchestrator/index.js +796 -0
  342. package/dist/extensions/scheduling/timer/fire-timing.d.ts +25 -0
  343. package/dist/extensions/scheduling/timer/fire-timing.js +28 -0
  344. package/dist/extensions/scheduling/timer/index.d.ts +102 -0
  345. package/dist/extensions/scheduling/timer/index.js +1143 -0
  346. package/dist/extensions/scheduling/timer/poller.d.ts +52 -0
  347. package/dist/extensions/scheduling/timer/poller.js +135 -0
  348. package/dist/extensions/scheduling/timer/recovery.d.ts +145 -0
  349. package/dist/extensions/scheduling/timer/recovery.js +445 -0
  350. package/dist/extensions/scheduling/timer/store-file.d.ts +38 -0
  351. package/dist/extensions/scheduling/timer/store-file.js +59 -0
  352. package/dist/extensions/scheduling/timer/timer-manager.d.ts +21 -0
  353. package/dist/extensions/scheduling/timer/timer-manager.js +143 -0
  354. package/dist/extensions/scheduling/timer/wake-retry.d.ts +455 -0
  355. package/dist/extensions/scheduling/timer/wake-retry.js +872 -0
  356. package/dist/extensions/self/auto-recovery/index.d.ts +20 -0
  357. package/dist/extensions/self/auto-recovery/index.js +89 -0
  358. package/dist/extensions/self/error-tracking/index.d.ts +3 -0
  359. package/dist/extensions/self/error-tracking/index.js +244 -0
  360. package/dist/extensions/self/health-maintenance/format.d.ts +3 -0
  361. package/dist/extensions/self/health-maintenance/format.js +60 -0
  362. package/dist/extensions/self/health-maintenance/handlers/session-health-tool.d.ts +23 -0
  363. package/dist/extensions/self/health-maintenance/handlers/session-health-tool.js +158 -0
  364. package/dist/extensions/self/health-maintenance/helpers.d.ts +25 -0
  365. package/dist/extensions/self/health-maintenance/helpers.js +67 -0
  366. package/dist/extensions/self/health-maintenance/index.d.ts +6 -0
  367. package/dist/extensions/self/health-maintenance/index.js +238 -0
  368. package/dist/extensions/self/health-maintenance/types.d.ts +14 -0
  369. package/dist/extensions/self/health-maintenance/types.js +2 -0
  370. package/dist/extensions/self/latent-activator/index.d.ts +12 -0
  371. package/dist/extensions/self/latent-activator/index.js +173 -0
  372. package/dist/extensions/self/latent-activator/mixes.d.ts +9 -0
  373. package/dist/extensions/self/latent-activator/mixes.js +20 -0
  374. package/dist/extensions/self/latent-activator/signals.d.ts +17 -0
  375. package/dist/extensions/self/latent-activator/signals.js +228 -0
  376. package/dist/extensions/self/latent-activator/state.d.ts +43 -0
  377. package/dist/extensions/self/latent-activator/state.js +59 -0
  378. package/dist/extensions/self/latent-activator/types.d.ts +8 -0
  379. package/dist/extensions/self/latent-activator/types.js +8 -0
  380. package/dist/extensions/self/watchdog/config.d.ts +4 -0
  381. package/dist/extensions/self/watchdog/config.js +79 -0
  382. package/dist/extensions/self/watchdog/engine.d.ts +256 -0
  383. package/dist/extensions/self/watchdog/engine.js +935 -0
  384. package/dist/extensions/self/watchdog/index.d.ts +23 -0
  385. package/dist/extensions/self/watchdog/index.js +485 -0
  386. package/dist/index.d.ts +25 -0
  387. package/dist/index.js +81 -0
  388. package/dist/lib/ai/consolidated-claim-critic.d.ts +84 -0
  389. package/dist/lib/ai/consolidated-claim-critic.js +191 -0
  390. package/dist/lib/ai/cost-report.d.ts +83 -0
  391. package/dist/lib/ai/cost-report.js +116 -0
  392. package/dist/lib/ai/critic-cache.d.ts +57 -0
  393. package/dist/lib/ai/critic-cache.js +100 -0
  394. package/dist/lib/ai/critic-fallbacks.d.ts +37 -0
  395. package/dist/lib/ai/critic-fallbacks.js +75 -0
  396. package/dist/lib/ai/critic-gate.d.ts +75 -0
  397. package/dist/lib/ai/critic-gate.js +81 -0
  398. package/dist/lib/ai/critic-helpers.d.ts +26 -0
  399. package/dist/lib/ai/critic-helpers.js +131 -0
  400. package/dist/lib/ai/critic-registry.d.ts +417 -0
  401. package/dist/lib/ai/critic-registry.js +639 -0
  402. package/dist/lib/ai/critic-stats.d.ts +78 -0
  403. package/dist/lib/ai/critic-stats.js +90 -0
  404. package/dist/lib/ai/judge-budget.d.ts +138 -0
  405. package/dist/lib/ai/judge-budget.js +143 -0
  406. package/dist/lib/ai/language-hint.d.ts +21 -0
  407. package/dist/lib/ai/language-hint.js +58 -0
  408. package/dist/lib/ai/llm-call.d.ts +141 -0
  409. package/dist/lib/ai/llm-call.js +745 -0
  410. package/dist/lib/ai/model-resolver.d.ts +90 -0
  411. package/dist/lib/ai/model-resolver.js +185 -0
  412. package/dist/lib/ai/models-init.d.ts +46 -0
  413. package/dist/lib/ai/models-init.js +65 -0
  414. package/dist/lib/ai/payload-hygiene.d.ts +74 -0
  415. package/dist/lib/ai/payload-hygiene.js +240 -0
  416. package/dist/lib/ai/post-loop-classify.d.ts +128 -0
  417. package/dist/lib/ai/post-loop-classify.js +87 -0
  418. package/dist/lib/ai/text-classifier.d.ts +142 -0
  419. package/dist/lib/ai/text-classifier.js +548 -0
  420. package/dist/lib/cognitive/hints.d.ts +33 -0
  421. package/dist/lib/cognitive/hints.js +223 -0
  422. package/dist/lib/cognitive/openspec.d.ts +29 -0
  423. package/dist/lib/cognitive/openspec.js +108 -0
  424. package/dist/lib/config/braid-paths.d.ts +188 -0
  425. package/dist/lib/config/braid-paths.js +340 -0
  426. package/dist/lib/config/braid-settings.d.ts +489 -0
  427. package/dist/lib/config/braid-settings.js +938 -0
  428. package/dist/lib/config/per-tool-settings.d.ts +95 -0
  429. package/dist/lib/config/per-tool-settings.js +161 -0
  430. package/dist/lib/config/session-profiles.d.ts +68 -0
  431. package/dist/lib/config/session-profiles.js +143 -0
  432. package/dist/lib/constants/injection-details.d.ts +30 -0
  433. package/dist/lib/constants/injection-details.js +30 -0
  434. package/dist/lib/constants/session-thresholds.d.ts +42 -0
  435. package/dist/lib/constants/session-thresholds.js +54 -0
  436. package/dist/lib/constants/tool-constants.d.ts +11 -0
  437. package/dist/lib/constants/tool-constants.js +12 -0
  438. package/dist/lib/core/event-names.d.ts +23 -0
  439. package/dist/lib/core/event-names.js +26 -0
  440. package/dist/lib/core/logger.d.ts +102 -0
  441. package/dist/lib/core/logger.js +274 -0
  442. package/dist/lib/detection/compression-strategy.d.ts +38 -0
  443. package/dist/lib/detection/compression-strategy.js +147 -0
  444. package/dist/lib/detection/consolidated-topic-critic.d.ts +51 -0
  445. package/dist/lib/detection/consolidated-topic-critic.js +132 -0
  446. package/dist/lib/detection/context-density.d.ts +70 -0
  447. package/dist/lib/detection/context-density.js +193 -0
  448. package/dist/lib/detection/context-thresholds.d.ts +88 -0
  449. package/dist/lib/detection/context-thresholds.js +107 -0
  450. package/dist/lib/detection/context-tiers.d.ts +80 -0
  451. package/dist/lib/detection/context-tiers.js +144 -0
  452. package/dist/lib/detection/context-usage.d.ts +75 -0
  453. package/dist/lib/detection/context-usage.js +209 -0
  454. package/dist/lib/detection/degradation-detector.d.ts +74 -0
  455. package/dist/lib/detection/degradation-detector.js +454 -0
  456. package/dist/lib/detection/test-burst.d.ts +77 -0
  457. package/dist/lib/detection/test-burst.js +126 -0
  458. package/dist/lib/detection/tool-loop-detector.d.ts +125 -0
  459. package/dist/lib/detection/tool-loop-detector.js +302 -0
  460. package/dist/lib/detection/topic-drift-detector.d.ts +80 -0
  461. package/dist/lib/detection/topic-drift-detector.js +252 -0
  462. package/dist/lib/enforcement/adherence-meter.d.ts +240 -0
  463. package/dist/lib/enforcement/adherence-meter.js +420 -0
  464. package/dist/lib/enforcement/turn-dedup.d.ts +106 -0
  465. package/dist/lib/enforcement/turn-dedup.js +195 -0
  466. package/dist/lib/errors/llm-error.d.ts +79 -0
  467. package/dist/lib/errors/llm-error.js +241 -0
  468. package/dist/lib/events/consolidation-channel.d.ts +109 -0
  469. package/dist/lib/events/consolidation-channel.js +374 -0
  470. package/dist/lib/events/consolidation-scoring.d.ts +59 -0
  471. package/dist/lib/events/consolidation-scoring.js +95 -0
  472. package/dist/lib/events/event-bus.d.ts +123 -0
  473. package/dist/lib/events/event-bus.js +108 -0
  474. package/dist/lib/events/event-types.d.ts +39 -0
  475. package/dist/lib/events/event-types.js +30 -0
  476. package/dist/lib/events/timer-bus.d.ts +21 -0
  477. package/dist/lib/events/timer-bus.js +41 -0
  478. package/dist/lib/events/timer-types.d.ts +64 -0
  479. package/dist/lib/events/timer-types.js +8 -0
  480. package/dist/lib/events/turn-end-coordinator.d.ts +52 -0
  481. package/dist/lib/events/turn-end-coordinator.js +89 -0
  482. package/dist/lib/harness/failure-trace-collector.d.ts +31 -0
  483. package/dist/lib/harness/failure-trace-collector.js +114 -0
  484. package/dist/lib/harness/index.d.ts +20 -0
  485. package/dist/lib/harness/index.js +21 -0
  486. package/dist/lib/harness/types.d.ts +85 -0
  487. package/dist/lib/harness/types.js +20 -0
  488. package/dist/lib/harness/weakness-miner.d.ts +29 -0
  489. package/dist/lib/harness/weakness-miner.js +165 -0
  490. package/dist/lib/memory/constants.d.ts +11 -0
  491. package/dist/lib/memory/constants.js +29 -0
  492. package/dist/lib/memory/index.d.ts +147 -0
  493. package/dist/lib/memory/index.js +564 -0
  494. package/dist/lib/memory/lifecycle.d.ts +50 -0
  495. package/dist/lib/memory/lifecycle.js +139 -0
  496. package/dist/lib/memory/past-insights.d.ts +35 -0
  497. package/dist/lib/memory/past-insights.js +189 -0
  498. package/dist/lib/memory/storage.d.ts +38 -0
  499. package/dist/lib/memory/storage.js +167 -0
  500. package/dist/lib/memory/store-lock.d.ts +23 -0
  501. package/dist/lib/memory/store-lock.js +69 -0
  502. package/dist/lib/memory/store-merge.d.ts +38 -0
  503. package/dist/lib/memory/store-merge.js +73 -0
  504. package/dist/lib/memory/types.d.ts +65 -0
  505. package/dist/lib/memory/types.js +5 -0
  506. package/dist/lib/memory/utils.d.ts +35 -0
  507. package/dist/lib/memory/utils.js +156 -0
  508. package/dist/lib/memory/write-log.d.ts +85 -0
  509. package/dist/lib/memory/write-log.js +124 -0
  510. package/dist/lib/memory/write-quality.d.ts +197 -0
  511. package/dist/lib/memory/write-quality.js +314 -0
  512. package/dist/lib/orchestrator/branch.d.ts +63 -0
  513. package/dist/lib/orchestrator/branch.js +192 -0
  514. package/dist/lib/orchestrator/index.d.ts +14 -0
  515. package/dist/lib/orchestrator/index.js +11 -0
  516. package/dist/lib/orchestrator/locks.d.ts +46 -0
  517. package/dist/lib/orchestrator/locks.js +122 -0
  518. package/dist/lib/orchestrator/slop-scanner.d.ts +31 -0
  519. package/dist/lib/orchestrator/slop-scanner.js +207 -0
  520. package/dist/lib/orchestrator/workers.d.ts +453 -0
  521. package/dist/lib/orchestrator/workers.js +1001 -0
  522. package/dist/lib/public.d.ts +18 -0
  523. package/dist/lib/public.js +23 -0
  524. package/dist/lib/reasoning/advice-tracker.d.ts +51 -0
  525. package/dist/lib/reasoning/advice-tracker.js +177 -0
  526. package/dist/lib/reasoning/belief-policy-engine.d.ts +48 -0
  527. package/dist/lib/reasoning/belief-policy-engine.js +268 -0
  528. package/dist/lib/reasoning/belief-types.d.ts +32 -0
  529. package/dist/lib/reasoning/belief-types.js +8 -0
  530. package/dist/lib/reasoning/classifier-offline.d.ts +72 -0
  531. package/dist/lib/reasoning/classifier-offline.js +75 -0
  532. package/dist/lib/reasoning/dreamer.d.ts +37 -0
  533. package/dist/lib/reasoning/dreamer.js +169 -0
  534. package/dist/lib/reasoning/nudge-analytics.d.ts +18 -0
  535. package/dist/lib/reasoning/nudge-analytics.js +62 -0
  536. package/dist/lib/reasoning/policy-rules.d.ts +18 -0
  537. package/dist/lib/reasoning/policy-rules.js +153 -0
  538. package/dist/lib/reasoning/reasoning-metrics.d.ts +42 -0
  539. package/dist/lib/reasoning/reasoning-metrics.js +174 -0
  540. package/dist/lib/reasoning/reasoning-summary.d.ts +34 -0
  541. package/dist/lib/reasoning/reasoning-summary.js +122 -0
  542. package/dist/lib/reasoning/tool-usage-analyzer.d.ts +50 -0
  543. package/dist/lib/reasoning/tool-usage-analyzer.js +188 -0
  544. package/dist/lib/state/async-storage.d.ts +52 -0
  545. package/dist/lib/state/async-storage.js +171 -0
  546. package/dist/lib/state/extension-state.d.ts +184 -0
  547. package/dist/lib/state/extension-state.js +373 -0
  548. package/dist/lib/state/global-state.d.ts +358 -0
  549. package/dist/lib/state/global-state.js +741 -0
  550. package/dist/lib/state/metacognitive-state.d.ts +21 -0
  551. package/dist/lib/state/metacognitive-state.js +50 -0
  552. package/dist/lib/state/session-manager.d.ts +32 -0
  553. package/dist/lib/state/session-manager.js +11 -0
  554. package/dist/lib/state/session-start-queue.d.ts +42 -0
  555. package/dist/lib/state/session-start-queue.js +105 -0
  556. package/dist/lib/state/state-checkpoint.d.ts +72 -0
  557. package/dist/lib/state/state-checkpoint.js +252 -0
  558. package/dist/lib/state/telegram-poller-liveness.d.ts +54 -0
  559. package/dist/lib/state/telegram-poller-liveness.js +67 -0
  560. package/dist/lib/state/tool-provenance.d.ts +22 -0
  561. package/dist/lib/state/tool-provenance.js +25 -0
  562. package/dist/lib/state/workspace-snapshot.d.ts +111 -0
  563. package/dist/lib/state/workspace-snapshot.js +372 -0
  564. package/dist/lib/store/belief-store.d.ts +112 -0
  565. package/dist/lib/store/belief-store.js +252 -0
  566. package/dist/lib/store/bidirectional-verifier.d.ts +87 -0
  567. package/dist/lib/store/bidirectional-verifier.js +242 -0
  568. package/dist/lib/store/claim-tracker.d.ts +66 -0
  569. package/dist/lib/store/claim-tracker.js +276 -0
  570. package/dist/lib/store/conflict-qa.d.ts +96 -0
  571. package/dist/lib/store/conflict-qa.js +283 -0
  572. package/dist/lib/store/evidence-pool.d.ts +185 -0
  573. package/dist/lib/store/evidence-pool.js +598 -0
  574. package/dist/lib/telemetry/context-heartbeat.d.ts +122 -0
  575. package/dist/lib/telemetry/context-heartbeat.js +449 -0
  576. package/dist/lib/telemetry/drift-signals.d.ts +46 -0
  577. package/dist/lib/telemetry/drift-signals.js +75 -0
  578. package/dist/lib/telemetry/rss-telemetry.d.ts +41 -0
  579. package/dist/lib/telemetry/rss-telemetry.js +53 -0
  580. package/dist/lib/types/episode-types.d.ts +31 -0
  581. package/dist/lib/types/episode-types.js +9 -0
  582. package/dist/lib/types/standard-result.d.ts +32 -0
  583. package/dist/lib/types/standard-result.js +22 -0
  584. package/dist/lib/utils/async-fs.d.ts +17 -0
  585. package/dist/lib/utils/async-fs.js +22 -0
  586. package/dist/lib/utils/bounded.d.ts +38 -0
  587. package/dist/lib/utils/bounded.js +59 -0
  588. package/dist/lib/utils/dedup.d.ts +40 -0
  589. package/dist/lib/utils/dedup.js +43 -0
  590. package/dist/lib/utils/error-guard.d.ts +15 -0
  591. package/dist/lib/utils/error-guard.js +22 -0
  592. package/dist/lib/utils/extension-utils.d.ts +36 -0
  593. package/dist/lib/utils/extension-utils.js +65 -0
  594. package/dist/lib/utils/extract-json.d.ts +23 -0
  595. package/dist/lib/utils/extract-json.js +90 -0
  596. package/dist/lib/utils/file-mutation-queue.d.ts +33 -0
  597. package/dist/lib/utils/file-mutation-queue.js +150 -0
  598. package/dist/lib/utils/filter-safe-to-remove.d.ts +26 -0
  599. package/dist/lib/utils/filter-safe-to-remove.js +256 -0
  600. package/dist/lib/utils/format-tool-result.d.ts +47 -0
  601. package/dist/lib/utils/format-tool-result.js +88 -0
  602. package/dist/lib/utils/id.d.ts +44 -0
  603. package/dist/lib/utils/id.js +59 -0
  604. package/dist/lib/utils/injection-tracker.d.ts +317 -0
  605. package/dist/lib/utils/injection-tracker.js +840 -0
  606. package/dist/lib/utils/local-time.d.ts +57 -0
  607. package/dist/lib/utils/local-time.js +181 -0
  608. package/dist/lib/utils/memory-fence.d.ts +55 -0
  609. package/dist/lib/utils/memory-fence.js +66 -0
  610. package/dist/lib/utils/sop-extractor.d.ts +75 -0
  611. package/dist/lib/utils/sop-extractor.js +259 -0
  612. package/dist/lib/utils/sop-suggestion.d.ts +34 -0
  613. package/dist/lib/utils/sop-suggestion.js +336 -0
  614. package/dist/lib/utils/wake-gate.d.ts +151 -0
  615. package/dist/lib/utils/wake-gate.js +265 -0
  616. package/dist/lib/utils/whisper-format.d.ts +95 -0
  617. package/dist/lib/utils/whisper-format.js +115 -0
  618. package/dist/lib/verification/coordination-checker.d.ts +72 -0
  619. package/dist/lib/verification/coordination-checker.js +126 -0
  620. package/dist/loader/api.d.ts +19 -0
  621. package/dist/loader/api.js +114 -0
  622. package/dist/loader/loader.d.ts +85 -0
  623. package/dist/loader/loader.js +534 -0
  624. package/docs/BEGINNERS.md +144 -0
  625. package/docs/COMPACTION-LOSS-INVESTIGATION.md +179 -0
  626. package/docs/CONTEXT-MAP.md +220 -0
  627. package/docs/CONTEXT-POLICY.md +86 -0
  628. package/docs/HISTORY.md +110 -0
  629. package/docs/LOCAL_DEV.md +246 -0
  630. package/docs/ROADMAP.md +107 -0
  631. package/docs/SETUP.md +459 -0
  632. package/package.json +97 -4
  633. package/skills/agent-testing/SKILL.md +214 -0
  634. package/skills/braid-reference/SKILL.md +88 -0
  635. package/skills/code-refactoring/SKILL.md +211 -0
  636. package/skills/code-search/SKILL.md +14 -0
  637. package/skills/documentation/SKILL.md +89 -0
  638. package/skills/dox/AGENTS.md.template +83 -0
  639. package/skills/dox/SKILL.md +86 -0
  640. package/skills/healthcheck/SKILL.md +65 -0
  641. package/skills/herdr-topology/SKILL.md +269 -0
  642. package/skills/meta-cognition/SKILL.md +24 -0
  643. package/skills/meta-improvement/SKILL.md +180 -0
  644. package/skills/misdirection-audit/SKILL.md +66 -0
  645. package/skills/pi-reference/SKILL.md +104 -0
  646. package/skills/placement-discipline/SKILL.md +69 -0
  647. package/skills/probe-evaluation/SKILL.md +85 -0
  648. package/skills/release-pipeline/SKILL.md +191 -0
  649. package/skills/research/SKILL.md +166 -0
  650. package/skills/skill-usage/SKILL.md +81 -0
  651. package/skills/software-engineer/SKILL.md +83 -0
  652. package/skills/subagent-orchestration/SKILL.md +454 -0
  653. package/skills/subagent-orchestration/scripts/workers.mjs +283 -0
  654. package/skills/subagent-verification/SKILL.md +127 -0
  655. package/skills/tone-quality/SKILL.md +176 -0
  656. package/skills/voice-replies/SKILL.md +125 -0
  657. package/src/AGENTS.md +111 -0
  658. package/src/extensions/cognitive/AGENTS.md +29 -0
  659. package/src/extensions/cognitive/mars-reflector/index.ts +415 -0
  660. package/src/extensions/cognitive/metacognition/handlers/AGENTS.md +30 -0
  661. package/src/extensions/cognitive/metacognition/handlers/claim-verification.ts +295 -0
  662. package/src/extensions/cognitive/metacognition/handlers/finalize.ts +648 -0
  663. package/src/extensions/cognitive/metacognition/handlers/hypothesize.ts +368 -0
  664. package/src/extensions/cognitive/metacognition/handlers/scoring.ts +242 -0
  665. package/src/extensions/cognitive/metacognition/handlers/think-budget.ts +199 -0
  666. package/src/extensions/cognitive/metacognition/handlers/think.ts +489 -0
  667. package/src/extensions/cognitive/metacognition/handlers/verify.ts +440 -0
  668. package/src/extensions/cognitive/metacognition/index.ts +109 -0
  669. package/src/extensions/cognitive/reasoning/index.ts +168 -0
  670. package/src/extensions/cognitive/sycophancy-detector/index.ts +286 -0
  671. package/src/extensions/cognitive/topic-drift/index.ts +429 -0
  672. package/src/extensions/cognitive/turn-outcome/index.ts +209 -0
  673. package/src/extensions/context-management/README.md +102 -0
  674. package/src/extensions/context-management/index.ts +383 -0
  675. package/src/extensions/core/AGENTS.md +34 -0
  676. package/src/extensions/core/agent-environment/index.ts +135 -0
  677. package/src/extensions/core/polyfill/index.ts +617 -0
  678. package/src/extensions/core/prompt-builder/AGENTS.md +151 -0
  679. package/src/extensions/core/prompt-builder/awareness-whisper.ts +162 -0
  680. package/src/extensions/core/prompt-builder/context-section.ts +120 -0
  681. package/src/extensions/core/prompt-builder/custom-sections.ts +27 -0
  682. package/src/extensions/core/prompt-builder/external-tool-guidelines.ts +41 -0
  683. package/src/extensions/core/prompt-builder/identity.ts +98 -0
  684. package/src/extensions/core/prompt-builder/index.ts +602 -0
  685. package/src/extensions/core/prompt-builder/inspect.ts +227 -0
  686. package/src/extensions/core/prompt-builder/instance-composition.ts +515 -0
  687. package/src/extensions/core/prompt-builder/memory-section.ts +76 -0
  688. package/src/extensions/core/prompt-builder/pi-reference-section.ts +26 -0
  689. package/src/extensions/core/prompt-builder/project-docs-section.ts +105 -0
  690. package/src/extensions/core/prompt-builder/section-parity.ts +108 -0
  691. package/src/extensions/core/prompt-builder/section-publish.ts +43 -0
  692. package/src/extensions/core/prompt-builder/section.ts +150 -0
  693. package/src/extensions/core/prompt-builder/surface-discipline-section.ts +21 -0
  694. package/src/extensions/core/prompt-builder/system-info-tool.ts +87 -0
  695. package/src/extensions/core/prompt-builder/tool-description-trim.ts +127 -0
  696. package/src/extensions/core/prompt-builder/tool-guidelines.ts +226 -0
  697. package/src/extensions/core/prompt-builder/tool-pipelines.ts +78 -0
  698. package/src/extensions/core/prompt-builder/top-level-extensions.ts +338 -0
  699. package/src/extensions/core/skills-tool/auto-inject.ts +1004 -0
  700. package/src/extensions/core/skills-tool/index.ts +240 -0
  701. package/src/extensions/core/skills-tool/loading-guidance.ts +89 -0
  702. package/src/extensions/core/skills-tool/session-records.ts +328 -0
  703. package/src/extensions/core/skills-tool/skill-triggers.ts +119 -0
  704. package/src/extensions/enforcement/AGENTS.md +69 -0
  705. package/src/extensions/enforcement/detection/malformed.ts +42 -0
  706. package/src/extensions/enforcement/detection/verification.ts +52 -0
  707. package/src/extensions/enforcement/enforcement-types.ts +42 -0
  708. package/src/extensions/enforcement/handler-registry.ts +225 -0
  709. package/src/extensions/enforcement/handlers/AGENTS.md +68 -0
  710. package/src/extensions/enforcement/handlers/analysis/AGENTS.md +40 -0
  711. package/src/extensions/enforcement/handlers/analysis/bpe-handler.ts +53 -0
  712. package/src/extensions/enforcement/handlers/analysis/dreamer-handler.ts +73 -0
  713. package/src/extensions/enforcement/handlers/analysis/drift-handler.ts +100 -0
  714. package/src/extensions/enforcement/handlers/analysis/feedback-handler.ts +22 -0
  715. package/src/extensions/enforcement/handlers/analysis/mars-handler.ts +121 -0
  716. package/src/extensions/enforcement/handlers/analysis/reflection-handler.ts +22 -0
  717. package/src/extensions/enforcement/handlers/blocking.ts +50 -0
  718. package/src/extensions/enforcement/handlers/message-analysis.ts +95 -0
  719. package/src/extensions/enforcement/handlers/orphan-chains.ts +53 -0
  720. package/src/extensions/enforcement/handlers/over-correction-gate.ts +634 -0
  721. package/src/extensions/enforcement/handlers/probe-handler.ts +133 -0
  722. package/src/extensions/enforcement/handlers/register-adherence-meter.ts +216 -0
  723. package/src/extensions/enforcement/handlers/register-agent-end-api-error.ts +82 -0
  724. package/src/extensions/enforcement/handlers/register-input-handler.ts +36 -0
  725. package/src/extensions/enforcement/handlers/register-message-end.ts +477 -0
  726. package/src/extensions/enforcement/handlers/register-post-cycle-hygiene.ts +166 -0
  727. package/src/extensions/enforcement/handlers/register-session-compact.ts +248 -0
  728. package/src/extensions/enforcement/handlers/register-session-shutdown-resumption.ts +138 -0
  729. package/src/extensions/enforcement/handlers/register-session-shutdown.ts +46 -0
  730. package/src/extensions/enforcement/handlers/register-session-start-discoverability.ts +270 -0
  731. package/src/extensions/enforcement/handlers/register-session-start.ts +240 -0
  732. package/src/extensions/enforcement/handlers/register-tool-call.ts +160 -0
  733. package/src/extensions/enforcement/handlers/register-tool-result-formatting.ts +73 -0
  734. package/src/extensions/enforcement/handlers/register-tool-result.ts +108 -0
  735. package/src/extensions/enforcement/handlers/register-turn-end-hygiene.ts +456 -0
  736. package/src/extensions/enforcement/handlers/routing-handler.ts +191 -0
  737. package/src/extensions/enforcement/handlers/tool-tracker.ts +145 -0
  738. package/src/extensions/enforcement/handlers/turn-analysis.ts +156 -0
  739. package/src/extensions/enforcement/handlers/turn-end-handler.ts +538 -0
  740. package/src/extensions/enforcement/index.ts +28 -0
  741. package/src/extensions/enforcement/judge-utils.ts +106 -0
  742. package/src/extensions/enforcement/nudge-manager.ts +298 -0
  743. package/src/extensions/enforcement/self-state-claims.ts +204 -0
  744. package/src/extensions/enforcement/session-health.ts +317 -0
  745. package/src/extensions/enforcement/signals.ts +88 -0
  746. package/src/extensions/enforcement/similarity.ts +76 -0
  747. package/src/extensions/enforcement/state.ts +115 -0
  748. package/src/extensions/enforcement/substate/context-hygiene-state.ts +212 -0
  749. package/src/extensions/enforcement/substate/error-tracking-state.ts +50 -0
  750. package/src/extensions/enforcement/substate/memory-hygiene-state.ts +54 -0
  751. package/src/extensions/enforcement/substate/session-state.ts +79 -0
  752. package/src/extensions/enforcement/substate/thought-chain-state.ts +62 -0
  753. package/src/extensions/enforcement/substate/tool-tracking-state.ts +166 -0
  754. package/src/extensions/enforcement/substate/verification-judge-state.ts +52 -0
  755. package/src/extensions/enforcement/task-evidence.ts +436 -0
  756. package/src/extensions/enforcement/types.ts +38 -0
  757. package/src/extensions/enforcement/validation.ts +194 -0
  758. package/src/extensions/enforcement/verification-judge.ts +317 -0
  759. package/src/extensions/enforcement/whisper.ts +120 -0
  760. package/src/extensions/heartbeat/AGENTS.md +47 -0
  761. package/src/extensions/heartbeat/analytics/AGENTS.md +57 -0
  762. package/src/extensions/heartbeat/analytics/ab-variant.ts +106 -0
  763. package/src/extensions/heartbeat/analytics/core.ts +222 -0
  764. package/src/extensions/heartbeat/analytics/format.ts +144 -0
  765. package/src/extensions/heartbeat/analytics/index.ts +373 -0
  766. package/src/extensions/heartbeat/analytics/shared.ts +149 -0
  767. package/src/extensions/heartbeat/heartbeat-scheduler/AGENTS.md +84 -0
  768. package/src/extensions/heartbeat/heartbeat-scheduler/index.ts +1095 -0
  769. package/src/extensions/heartbeat/heartbeat-scheduler/meta-learning.ts +75 -0
  770. package/src/extensions/heartbeat/heartbeat-scheduler/modules/behavioral-drift.ts +200 -0
  771. package/src/extensions/heartbeat/heartbeat-scheduler/modules/budget.ts +113 -0
  772. package/src/extensions/heartbeat/heartbeat-scheduler/modules/context-hygiene.ts +288 -0
  773. package/src/extensions/heartbeat/heartbeat-scheduler/modules/evolver.ts +88 -0
  774. package/src/extensions/heartbeat/heartbeat-scheduler/modules/measurement.ts +47 -0
  775. package/src/extensions/heartbeat/heartbeat-scheduler/modules/recaller.ts +99 -0
  776. package/src/extensions/heartbeat/heartbeat-scheduler/modules/reflection-consolidator.ts +114 -0
  777. package/src/extensions/heartbeat/heartbeat-scheduler/policies.ts +193 -0
  778. package/src/extensions/heartbeat/heartbeat-scheduler/state.ts +88 -0
  779. package/src/extensions/heartbeat/heartbeat-scheduler/types.ts +128 -0
  780. package/src/extensions/heartbeat/heartbeat-scheduler/whisper-batcher.ts +98 -0
  781. package/src/extensions/manifest.ts +293 -0
  782. package/src/extensions/memory/AGENTS.md +93 -0
  783. package/src/extensions/memory/context-lifecycle/AGENTS.md +62 -0
  784. package/src/extensions/memory/context-lifecycle/helpers.ts +167 -0
  785. package/src/extensions/memory/context-lifecycle/index.ts +1232 -0
  786. package/src/extensions/memory/context-lifecycle/policy-engine.ts +287 -0
  787. package/src/extensions/memory/context-lifecycle/signal-detector.ts +293 -0
  788. package/src/extensions/memory/context-lifecycle/state.ts +165 -0
  789. package/src/extensions/memory/context-lifecycle/types.ts +441 -0
  790. package/src/extensions/memory/context-manager/analysis.ts +344 -0
  791. package/src/extensions/memory/context-manager/handlers/AGENTS.md +37 -0
  792. package/src/extensions/memory/context-manager/handlers/compaction-chunked.ts +800 -0
  793. package/src/extensions/memory/context-manager/handlers/compaction-retry.ts +556 -0
  794. package/src/extensions/memory/context-manager/handlers/compaction-trace.ts +243 -0
  795. package/src/extensions/memory/context-manager/handlers/compaction-watchdog.ts +366 -0
  796. package/src/extensions/memory/context-manager/handlers/compaction.ts +2552 -0
  797. package/src/extensions/memory/context-manager/handlers/context-emergency.ts +470 -0
  798. package/src/extensions/memory/context-manager/handlers/events.ts +430 -0
  799. package/src/extensions/memory/context-manager/handlers/navigation.ts +94 -0
  800. package/src/extensions/memory/context-manager/handlers/offload.ts +330 -0
  801. package/src/extensions/memory/context-manager/handlers/rotation.ts +363 -0
  802. package/src/extensions/memory/context-manager/handlers/shared.ts +961 -0
  803. package/src/extensions/memory/context-manager/handlers/tool-batch-boundary.ts +219 -0
  804. package/src/extensions/memory/context-manager/handlers/toolresult-capture-cap.ts +176 -0
  805. package/src/extensions/memory/context-manager/handlers/tools/context-compress.ts +1333 -0
  806. package/src/extensions/memory/context-manager/handlers/tools/context-inspect.ts +343 -0
  807. package/src/extensions/memory/context-manager/handlers/tools/context-navigate.ts +423 -0
  808. package/src/extensions/memory/context-manager/handlers/tools/offload-recover.ts +234 -0
  809. package/src/extensions/memory/context-manager/index.ts +111 -0
  810. package/src/extensions/memory/context-manager/pruning.ts +479 -0
  811. package/src/extensions/memory/context-manager/semantic-compress.ts +321 -0
  812. package/src/extensions/memory/memory-agent-bridge/AGENTS.md +62 -0
  813. package/src/extensions/memory/memory-agent-bridge/conflict-qa-tool.ts +106 -0
  814. package/src/extensions/memory/memory-agent-bridge/explore-paths.ts +283 -0
  815. package/src/extensions/memory/memory-agent-bridge/index.ts +163 -0
  816. package/src/extensions/memory/memory-agent-bridge/memory-store-tool.ts +284 -0
  817. package/src/extensions/memory/memory-agent-bridge/memory-tool.ts +746 -0
  818. package/src/extensions/memory/scratchpad/AGENTS.md +148 -0
  819. package/src/extensions/memory/scratchpad/format.ts +161 -0
  820. package/src/extensions/memory/scratchpad/handlers.ts +601 -0
  821. package/src/extensions/memory/scratchpad/index.ts +230 -0
  822. package/src/extensions/memory/scratchpad/persistence.ts +374 -0
  823. package/src/extensions/memory/scratchpad/types.ts +149 -0
  824. package/src/extensions/memory/scratchpad/utils.ts +268 -0
  825. package/src/extensions/memory/session-recall/AGENTS.md +104 -0
  826. package/src/extensions/memory/session-recall/analyze.ts +605 -0
  827. package/src/extensions/memory/session-recall/context-aggregate.ts +381 -0
  828. package/src/extensions/memory/session-recall/index.ts +956 -0
  829. package/src/extensions/memory/session-recall/query.ts +44 -0
  830. package/src/extensions/memory/session-recall/rank.ts +121 -0
  831. package/src/extensions/memory/session-recall/search.ts +801 -0
  832. package/src/extensions/memory/session-recall/stats.ts +93 -0
  833. package/src/extensions/memory/session-recall/text-utils.ts +209 -0
  834. package/src/extensions/memory/three-memory-stores/AGENTS.md +66 -0
  835. package/src/extensions/memory/three-memory-stores/episodes-disk.ts +138 -0
  836. package/src/extensions/memory/three-memory-stores/episodes.ts +371 -0
  837. package/src/extensions/memory/three-memory-stores/handlers/whisper-recall.ts +132 -0
  838. package/src/extensions/memory/three-memory-stores/heuristics.ts +109 -0
  839. package/src/extensions/memory/three-memory-stores/index.ts +549 -0
  840. package/src/extensions/memory/three-memory-stores/tool-reliability.ts +58 -0
  841. package/src/extensions/memory/three-memory-stores/types.ts +74 -0
  842. package/src/extensions/memory/workspace-snapshot/AGENTS.md +19 -0
  843. package/src/extensions/memory/workspace-snapshot/index.ts +455 -0
  844. package/src/extensions/orchestrator/index.ts +1141 -0
  845. package/src/extensions/scheduling/AGENTS.md +26 -0
  846. package/src/extensions/scheduling/timer/AGENTS.md +259 -0
  847. package/src/extensions/scheduling/timer/fire-timing.ts +46 -0
  848. package/src/extensions/scheduling/timer/index.ts +1331 -0
  849. package/src/extensions/scheduling/timer/poller.ts +138 -0
  850. package/src/extensions/scheduling/timer/recovery.ts +462 -0
  851. package/src/extensions/scheduling/timer/store-file.ts +59 -0
  852. package/src/extensions/scheduling/timer/timer-manager.ts +161 -0
  853. package/src/extensions/scheduling/timer/wake-retry.ts +1057 -0
  854. package/src/extensions/self/AGENTS.md +30 -0
  855. package/src/extensions/self/auto-recovery/index.ts +112 -0
  856. package/src/extensions/self/error-tracking/AGENTS.md +38 -0
  857. package/src/extensions/self/error-tracking/index.ts +299 -0
  858. package/src/extensions/self/health-maintenance/AGENTS.md +42 -0
  859. package/src/extensions/self/health-maintenance/format.ts +87 -0
  860. package/src/extensions/self/health-maintenance/handlers/session-health-tool.ts +182 -0
  861. package/src/extensions/self/health-maintenance/helpers.ts +78 -0
  862. package/src/extensions/self/health-maintenance/index.ts +308 -0
  863. package/src/extensions/self/health-maintenance/types.ts +14 -0
  864. package/src/extensions/self/latent-activator/AGENTS.md +64 -0
  865. package/src/extensions/self/latent-activator/index.ts +206 -0
  866. package/src/extensions/self/latent-activator/mixes.ts +22 -0
  867. package/src/extensions/self/latent-activator/signals.ts +237 -0
  868. package/src/extensions/self/latent-activator/state.ts +79 -0
  869. package/src/extensions/self/latent-activator/types.ts +47 -0
  870. package/src/extensions/self/watchdog/AGENTS.md +27 -0
  871. package/src/extensions/self/watchdog/config.ts +73 -0
  872. package/src/extensions/self/watchdog/engine.ts +1246 -0
  873. package/src/extensions/self/watchdog/index.ts +577 -0
  874. package/src/index.ts +93 -0
  875. package/src/lib/AGENTS.md +39 -0
  876. package/src/lib/ai/AGENTS.md +37 -0
  877. package/src/lib/ai/consolidated-claim-critic.ts +287 -0
  878. package/src/lib/ai/cost-report.ts +206 -0
  879. package/src/lib/ai/critic-cache.ts +122 -0
  880. package/src/lib/ai/critic-fallbacks.ts +74 -0
  881. package/src/lib/ai/critic-gate.ts +135 -0
  882. package/src/lib/ai/critic-helpers.ts +135 -0
  883. package/src/lib/ai/critic-registry.ts +754 -0
  884. package/src/lib/ai/critic-stats.ts +158 -0
  885. package/src/lib/ai/judge-budget.ts +241 -0
  886. package/src/lib/ai/language-hint.ts +70 -0
  887. package/src/lib/ai/llm-call.ts +975 -0
  888. package/src/lib/ai/model-resolver.ts +224 -0
  889. package/src/lib/ai/models-init.ts +68 -0
  890. package/src/lib/ai/payload-hygiene.ts +265 -0
  891. package/src/lib/ai/post-loop-classify.ts +185 -0
  892. package/src/lib/ai/text-classifier.ts +746 -0
  893. package/src/lib/cognitive/AGENTS.md +40 -0
  894. package/src/lib/cognitive/hints.ts +254 -0
  895. package/src/lib/cognitive/openspec.ts +124 -0
  896. package/src/lib/config/AGENTS.md +17 -0
  897. package/src/lib/config/braid-paths.ts +401 -0
  898. package/src/lib/config/braid-settings.ts +1442 -0
  899. package/src/lib/config/per-tool-settings.ts +197 -0
  900. package/src/lib/config/session-profiles.ts +165 -0
  901. package/src/lib/constants/AGENTS.md +15 -0
  902. package/src/lib/constants/injection-details.ts +32 -0
  903. package/src/lib/constants/session-thresholds.ts +64 -0
  904. package/src/lib/constants/tool-constants.ts +16 -0
  905. package/src/lib/core/AGENTS.md +23 -0
  906. package/src/lib/core/event-names.ts +31 -0
  907. package/src/lib/core/logger.ts +334 -0
  908. package/src/lib/detection/AGENTS.md +21 -0
  909. package/src/lib/detection/compression-strategy.ts +183 -0
  910. package/src/lib/detection/consolidated-topic-critic.ts +188 -0
  911. package/src/lib/detection/context-density.ts +237 -0
  912. package/src/lib/detection/context-thresholds.ts +132 -0
  913. package/src/lib/detection/context-tiers.ts +201 -0
  914. package/src/lib/detection/context-usage.ts +270 -0
  915. package/src/lib/detection/degradation-detector.ts +583 -0
  916. package/src/lib/detection/test-burst.ts +170 -0
  917. package/src/lib/detection/tool-loop-detector.ts +364 -0
  918. package/src/lib/detection/topic-drift-detector.ts +323 -0
  919. package/src/lib/enforcement/AGENTS.md +20 -0
  920. package/src/lib/enforcement/adherence-meter.ts +578 -0
  921. package/src/lib/enforcement/turn-dedup.ts +246 -0
  922. package/src/lib/errors/llm-error.ts +288 -0
  923. package/src/lib/events/AGENTS.md +23 -0
  924. package/src/lib/events/consolidation-channel.ts +493 -0
  925. package/src/lib/events/consolidation-scoring.ts +112 -0
  926. package/src/lib/events/event-bus.ts +213 -0
  927. package/src/lib/events/event-types.ts +53 -0
  928. package/src/lib/events/timer-bus.ts +53 -0
  929. package/src/lib/events/timer-types.ts +64 -0
  930. package/src/lib/events/turn-end-coordinator.ts +108 -0
  931. package/src/lib/harness/AGENTS.md +20 -0
  932. package/src/lib/harness/failure-trace-collector.ts +157 -0
  933. package/src/lib/harness/index.ts +41 -0
  934. package/src/lib/harness/types.ts +122 -0
  935. package/src/lib/harness/weakness-miner.ts +209 -0
  936. package/src/lib/memory/AGENTS.md +36 -0
  937. package/src/lib/memory/constants.ts +34 -0
  938. package/src/lib/memory/index.ts +705 -0
  939. package/src/lib/memory/lifecycle.ts +159 -0
  940. package/src/lib/memory/past-insights.ts +221 -0
  941. package/src/lib/memory/storage.ts +187 -0
  942. package/src/lib/memory/store-lock.ts +70 -0
  943. package/src/lib/memory/store-merge.ts +100 -0
  944. package/src/lib/memory/types.ts +82 -0
  945. package/src/lib/memory/utils.ts +173 -0
  946. package/src/lib/memory/write-log.ts +174 -0
  947. package/src/lib/memory/write-quality.ts +383 -0
  948. package/src/lib/orchestrator/branch.ts +193 -0
  949. package/src/lib/orchestrator/index.ts +78 -0
  950. package/src/lib/orchestrator/locks.ts +160 -0
  951. package/src/lib/orchestrator/slop-scanner.ts +258 -0
  952. package/src/lib/orchestrator/workers.ts +1382 -0
  953. package/src/lib/public.ts +43 -0
  954. package/src/lib/reasoning/AGENTS.md +25 -0
  955. package/src/lib/reasoning/advice-tracker.ts +244 -0
  956. package/src/lib/reasoning/belief-policy-engine.ts +342 -0
  957. package/src/lib/reasoning/belief-types.ts +45 -0
  958. package/src/lib/reasoning/classifier-offline.ts +111 -0
  959. package/src/lib/reasoning/dreamer.ts +215 -0
  960. package/src/lib/reasoning/nudge-analytics.ts +85 -0
  961. package/src/lib/reasoning/policy-rules.ts +172 -0
  962. package/src/lib/reasoning/reasoning-metrics.ts +202 -0
  963. package/src/lib/reasoning/reasoning-summary.ts +154 -0
  964. package/src/lib/reasoning/tool-usage-analyzer.ts +248 -0
  965. package/src/lib/state/AGENTS.md +192 -0
  966. package/src/lib/state/async-storage.ts +189 -0
  967. package/src/lib/state/extension-state.ts +419 -0
  968. package/src/lib/state/global-state.ts +1046 -0
  969. package/src/lib/state/metacognitive-state.ts +65 -0
  970. package/src/lib/state/session-manager.ts +43 -0
  971. package/src/lib/state/session-start-queue.ts +135 -0
  972. package/src/lib/state/state-checkpoint.ts +352 -0
  973. package/src/lib/state/telegram-poller-liveness.ts +75 -0
  974. package/src/lib/state/tool-provenance.ts +26 -0
  975. package/src/lib/state/workspace-snapshot.ts +466 -0
  976. package/src/lib/store/AGENTS.md +24 -0
  977. package/src/lib/store/belief-store.ts +325 -0
  978. package/src/lib/store/bidirectional-verifier.ts +316 -0
  979. package/src/lib/store/claim-tracker.ts +382 -0
  980. package/src/lib/store/conflict-qa.ts +385 -0
  981. package/src/lib/store/evidence-pool.ts +779 -0
  982. package/src/lib/telemetry/AGENTS.md +28 -0
  983. package/src/lib/telemetry/context-heartbeat.ts +555 -0
  984. package/src/lib/telemetry/drift-signals.ts +105 -0
  985. package/src/lib/telemetry/rss-telemetry.ts +57 -0
  986. package/src/lib/types/AGENTS.md +21 -0
  987. package/src/lib/types/episode-types.ts +31 -0
  988. package/src/lib/types/standard-result.ts +40 -0
  989. package/src/lib/utils/AGENTS.md +30 -0
  990. package/src/lib/utils/async-fs.ts +23 -0
  991. package/src/lib/utils/bounded.ts +58 -0
  992. package/src/lib/utils/dedup.ts +44 -0
  993. package/src/lib/utils/error-guard.ts +27 -0
  994. package/src/lib/utils/extension-utils.ts +72 -0
  995. package/src/lib/utils/extract-json.ts +89 -0
  996. package/src/lib/utils/file-mutation-queue.ts +172 -0
  997. package/src/lib/utils/filter-safe-to-remove.ts +301 -0
  998. package/src/lib/utils/format-tool-result.ts +109 -0
  999. package/src/lib/utils/id.ts +64 -0
  1000. package/src/lib/utils/injection-tracker.ts +1014 -0
  1001. package/src/lib/utils/local-time.ts +196 -0
  1002. package/src/lib/utils/memory-fence.ts +70 -0
  1003. package/src/lib/utils/sop-extractor.ts +329 -0
  1004. package/src/lib/utils/sop-suggestion.ts +426 -0
  1005. package/src/lib/utils/wake-gate.ts +318 -0
  1006. package/src/lib/utils/whisper-format.ts +120 -0
  1007. package/src/lib/verification/coordination-checker.ts +183 -0
  1008. package/src/loader/AGENTS.md +32 -0
  1009. package/src/loader/api.ts +138 -0
  1010. package/src/loader/loader.ts +600 -0
  1011. package/src/types/extension-context.d.ts +85 -0
@@ -0,0 +1,1046 @@
1
+ /**
2
+ * Shared global state utilities for pi-braid.
3
+ *
4
+ * Module-level state shared between extensions that can't use
5
+ * getExtensionState() because they span separate extension contexts.
6
+ *
7
+ * IMPORTANT: These should only be used when module-level state won't work.
8
+ * Prefer getExtensionState() for per-session state. Slots that must be
9
+ * visible across module instances (src-tree vs compiled-dist imports) use
10
+ * globalThis keys instead - see CUSTOM_MODEL_KEYS_KEY below for the
11
+ * cross-bundle hazard.
12
+ */
13
+
14
+ // globalThis (not a module-level let/const) because the polyfill extension is
15
+ // loaded from the TS SOURCE tree (src/extensions/core/polyfill/index.ts →
16
+ // src/lib/state/global-state.ts) while contrib's model-resolver imports the
17
+ // compiled DIST (dist/lib/state/global-state.js via the pi-braid/lib export).
18
+ // That yields TWO module instances of this file in one process; a module-level
19
+ // Map would be populated by the src instance and read (empty) by the dist
20
+ // instance — the visionModel custom key would fall through to priority-3
21
+ // first-available (MiniMax 429). Same cross-bundle hazard as
22
+ // KEY_RING_FEEDBACK_KEY above; the slot must also survive /reload.
23
+ export const CUSTOM_MODEL_KEYS_KEY = "__braid_custom_model_keys";
24
+
25
+ /**
26
+ * A custom model key value: one model pattern, or an ordered list of them tried
27
+ * in order (the resolver walks the list and the provider layer decides per
28
+ * entry).
29
+ */
30
+ export type CustomModelKeyValue = string | string[];
31
+
32
+ /**
33
+ * Get the shared custom model keys map.
34
+ * polyfill writes to it (/vision-model command).
35
+ * model-resolver reads from it (model resolution).
36
+ */
37
+ export function getCustomModelKeys(): Map<string, CustomModelKeyValue> {
38
+ const slot = globalThis as Record<string, unknown>;
39
+ if (!slot[CUSTOM_MODEL_KEYS_KEY]) {
40
+ slot[CUSTOM_MODEL_KEYS_KEY] = new Map<string, CustomModelKeyValue>();
41
+ }
42
+ return slot[CUSTOM_MODEL_KEYS_KEY] as Map<string, CustomModelKeyValue>;
43
+ }
44
+
45
+ /**
46
+ * Read a custom model key (e.g. "utilityModel", "visionModel"): a pattern or an
47
+ * ordered list of them.
48
+ */
49
+ export function getCustomModelKey(key: string): CustomModelKeyValue | undefined {
50
+ return getCustomModelKeys().get(key);
51
+ }
52
+
53
+ /**
54
+ * Set a custom model key: one pattern or an ordered list. Used by polyfill for
55
+ * /utility-model and /vision-model.
56
+ */
57
+ export function setCustomModelKey(key: string, value: CustomModelKeyValue): void {
58
+ getCustomModelKeys().set(key, value);
59
+ }
60
+
61
+ // The vision role is deprecated: the key keeps priority-1 status as an alias
62
+ // for one release, after which the merged role supplies image-capable models.
63
+ export const VISION_MODEL_KEY = "visionModel";
64
+ export const UTILITY_MODEL_KEY = "utilityModel";
65
+ // The max-power role is folded into utility; the constant survives so the
66
+ // polyfill can recognize and clean the legacy key from settings.json; nothing
67
+ // resolves it as a live role.
68
+ export const MAX_POWER_MODEL_KEY = "maxPowerModel";
69
+
70
+ /**
71
+ * One-shot latch for the maxPowerModel deprecation notice. Process-global for
72
+ * the same reason as the keys above: a src-loaded and a dist-loaded instance
73
+ * of this module must agree on whether the notice already fired.
74
+ */
75
+ const MAX_POWER_NOTICE_KEY = "__braid_max_power_deprecation_notice";
76
+
77
+ /** True the first time it is called in this process, false afterwards. */
78
+ export function consumeMaxPowerDeprecationNotice(): boolean {
79
+ const slot = globalThis as Record<string, unknown>;
80
+ if (slot[MAX_POWER_NOTICE_KEY]) return false;
81
+ slot[MAX_POWER_NOTICE_KEY] = true;
82
+ return true;
83
+ }
84
+
85
+ export interface RotationState {
86
+ lastRotationTimestamp: number;
87
+ turnsSinceRotation: number;
88
+ rotationCount: number;
89
+ pendingRotation: boolean;
90
+ continuationSummary: string;
91
+ // Nudge deduplication fields
92
+ lastNudgeTimestamp: number;
93
+ lastNudgeTurn: number;
94
+ nudgeCount: number;
95
+ actionTaken: boolean;
96
+ actionTakenAtTurn: number; // turn count when action was taken (for grace period)
97
+ emergencyRotation: boolean;
98
+ // Deep-branch whisper throttle (separate from rotation nudge so a
99
+ // very-deep branch doesn't share a counter with a soon-to-rotate one)
100
+ lastDeepBranchWhisperTimestamp: number;
101
+ lastDeepBranchWhisperTurn: number;
102
+ }
103
+
104
+ function createDefaultRotationState(): RotationState {
105
+ return {
106
+ lastRotationTimestamp: Date.now(),
107
+ turnsSinceRotation: 0,
108
+ rotationCount: 0,
109
+ pendingRotation: false,
110
+ continuationSummary: "",
111
+ lastNudgeTimestamp: 0,
112
+ lastNudgeTurn: 0,
113
+ lastDeepBranchWhisperTimestamp: 0,
114
+ lastDeepBranchWhisperTurn: 0,
115
+ nudgeCount: 0,
116
+ actionTaken: false,
117
+ actionTakenAtTurn: 0,
118
+ emergencyRotation: false,
119
+ };
120
+ }
121
+
122
+ let _rotationState: RotationState | undefined;
123
+
124
+ /** Get the shared rotation state object. */
125
+ export function getRotationState(): RotationState {
126
+ if (!_rotationState) {
127
+ _rotationState = createDefaultRotationState();
128
+ }
129
+ return _rotationState;
130
+ }
131
+
132
+ /**
133
+ * Last-known nudge state from the most recent session.
134
+ * Used by code paths that read nudge state without an ExtensionContext
135
+ * (e.g., a tool result handler that already returned to the agent loop).
136
+ * When a ctx is available, prefer getExtensionState(ctx, "nudge-analytics").
137
+ */
138
+ export interface NudgeAnalyticsFallbackState {
139
+ nudgesSent: number;
140
+ nudgesSuppressed: number;
141
+ abVariant: string;
142
+ contextDensity: number;
143
+ wasDegraded: boolean;
144
+ }
145
+
146
+ function createDefaultNudgeAnalyticsFallback(): NudgeAnalyticsFallbackState {
147
+ return {
148
+ nudgesSent: 0,
149
+ nudgesSuppressed: 0,
150
+ abVariant: "control",
151
+ contextDensity: 0,
152
+ wasDegraded: false,
153
+ };
154
+ }
155
+
156
+ let _nudgeAnalyticsFallback: NudgeAnalyticsFallbackState | undefined;
157
+
158
+ /** Get the shared nudge-analytics fallback object (process-global mirror). */
159
+ export function getNudgeAnalyticsFallback(): NudgeAnalyticsFallbackState {
160
+ if (!_nudgeAnalyticsFallback) {
161
+ _nudgeAnalyticsFallback = createDefaultNudgeAnalyticsFallback();
162
+ }
163
+ return _nudgeAnalyticsFallback;
164
+ }
165
+
166
+ /**
167
+ * Process-global singleton instance of CognitiveMemory - named
168
+ * "process-global" to distinguish it from the per-session pattern in
169
+ * `extension-state.ts`. The memory engine maintains in-memory indices that
170
+ * are expensive to rebuild on every session start.
171
+ */
172
+ export interface CognitiveMemoryInstance {
173
+ // Opaque type - the actual class lives in lib/memory/index.ts. The
174
+ // getter/setter pattern here lets us declare the slot in global-state
175
+ // without importing the (heavy) class.
176
+ readonly _brand: unique symbol;
177
+ }
178
+
179
+ let _cognitiveMemoryInstance: unknown = null;
180
+
181
+ /** Set the shared CognitiveMemory instance (called once at first use). */
182
+ export function setCognitiveMemoryInstance(instance: unknown): void {
183
+ _cognitiveMemoryInstance = instance;
184
+ }
185
+
186
+ /** Get the shared CognitiveMemory instance (or null if not yet initialized). */
187
+ export function getCognitiveMemoryInstance(): unknown {
188
+ return _cognitiveMemoryInstance;
189
+ }
190
+
191
+ //
192
+ // pi-ai v0.80 moved `completeSimple` from the top-level export to the
193
+ // `/compat` subpath (deprecated); `createModels()` gives a `Models` instance,
194
+ // which is the forward-looking API. This slot holds the process-global Models
195
+ // instance created by models-init.ts at startup.
196
+ //
197
+ // Nothing on the auxiliary LLM path reads it: lib/ai/llm-call.ts dispatches
198
+ // through the session's ctx.modelRegistry (see the completion-dispatch block
199
+ // in that module), which resolves credential, provider headers and transport
200
+ // inside pi-core.
201
+ //
202
+ // Opaque type pattern (same as CognitiveMemoryInstance): the Models type is
203
+ // intentionally not imported here — the slot is typed `unknown`.
204
+
205
+ let _modelsInstance: unknown = null;
206
+
207
+ /** Set the shared pi-ai Models instance (called once at startup). */
208
+ export function setModelsInstance(instance: unknown): void {
209
+ _modelsInstance = instance;
210
+ }
211
+
212
+ /** Get the shared pi-ai Models instance (or null if not yet initialized). */
213
+ export function getModelsInstance(): unknown {
214
+ return _modelsInstance;
215
+ }
216
+
217
+ /**
218
+ * Default per-LLM-tier timeout for post-loop classify() calls, consumed by
219
+ * lib/ai/post-loop-classify.ts via getPostLoopTimeoutMs(). The post-loop
220
+ * path runs at session end, when the session model may be busy with
221
+ * finalization. A 10-minute budget per tier (20 min worst-case when both
222
+ * utility and session are tried) is the current tuning: real provider
223
+ * issues surface as real errors, while signal-driven aborts (ESC, session
224
+ * shutdown) remain the normal cancellation path - the timeout is a
225
+ * fallback for orphaned calls, not the cancellation mechanism.
226
+ */
227
+ export const DEFAULT_POST_LOOP_TIMEOUT_MS = 600_000;
228
+
229
+ let _postLoopTimeoutMs: number | undefined;
230
+
231
+ /**
232
+ * Get the per-LLM-tier timeout for post-loop classify() calls.
233
+ * Defaults to DEFAULT_POST_LOOP_TIMEOUT_MS (600_000). Tunable via
234
+ * setPostLoopTimeoutMs() - typically called from a /command or
235
+ * startup config so the value can be changed without code changes.
236
+ */
237
+ export function getPostLoopTimeoutMs(): number {
238
+ if (_postLoopTimeoutMs === undefined) {
239
+ _postLoopTimeoutMs = DEFAULT_POST_LOOP_TIMEOUT_MS;
240
+ }
241
+ return _postLoopTimeoutMs;
242
+ }
243
+
244
+ /** Override the post-loop timeout. Pass a positive number in ms. */
245
+ export function setPostLoopTimeoutMs(value: number): void {
246
+ if (!Number.isFinite(value) || value <= 0) {
247
+ throw new Error(`setPostLoopTimeoutMs: value must be a positive finite number, got ${value}`);
248
+ }
249
+ _postLoopTimeoutMs = value;
250
+ }
251
+
252
+ //
253
+ // The session-recovery proposal routes every LLM call outcome
254
+ // through SessionHealthState. To avoid forcing every call site to pass a
255
+ // callback, lib/ai/llm-call.ts exposes a process-wide listener registration.
256
+ // The enforcement extension registers listeners at session_start with a
257
+ // closure over the current ctx; calls go to whichever listener is currently
258
+ // registered.
259
+ //
260
+ // Single-listener design: only one consumer is expected (the enforcement
261
+ // extension). Multi-session / multi-consumer scenarios are a future concern.
262
+ //
263
+ // Encapsulated in global-state.ts (not module-level let in llm-call.ts) so
264
+ // the no-module-level-let contract is satisfied and the listeners can be
265
+ // reset between test runs via resetLlmCallListeners().
266
+ export type LlmErrorListener = (err: unknown) => void;
267
+ export type LlmSuccessListener = () => void;
268
+
269
+ let _llmErrorListener: LlmErrorListener | null = null;
270
+ let _llmSuccessListener: LlmSuccessListener | null = null;
271
+
272
+ /** Set the current LLM call listeners. Pass `null` to clear a slot. */
273
+ export function setLlmCallListeners(listeners: {
274
+ onError?: LlmErrorListener | null;
275
+ onSuccess?: LlmSuccessListener | null;
276
+ }): void {
277
+ if (listeners.onError !== undefined) {
278
+ _llmErrorListener = listeners.onError ?? null;
279
+ }
280
+ if (listeners.onSuccess !== undefined) {
281
+ _llmSuccessListener = listeners.onSuccess ?? null;
282
+ }
283
+ }
284
+
285
+ /** Read-only access to the current error listener (for the callLlm() body). */
286
+ export function getLlmErrorListener(): LlmErrorListener | null {
287
+ return _llmErrorListener;
288
+ }
289
+
290
+ /** Read-only access to the current success listener (for the callLlm() body). */
291
+ export function getLlmSuccessListener(): LlmSuccessListener | null {
292
+ return _llmSuccessListener;
293
+ }
294
+
295
+ /** Clear all listeners. Test helper. */
296
+ export function resetLlmCallListeners(): void {
297
+ _llmErrorListener = null;
298
+ _llmSuccessListener = null;
299
+ }
300
+
301
+ // The pi-braid-providers extension owns the API key rings; core's callLlm and
302
+ // contrib's vision wrapper make direct LLM calls that never emit message_end,
303
+ // so a 429/403 from them must feed back into the ring that owns that
304
+ // provider/model to rotate off a dead key (the ring would otherwise serve the
305
+ // same dead key forever on those paths). providers publishes its handler into
306
+ // this process-global slot at extension load (providers/ring-lifecycle.ts
307
+ // publishKeyRingFeedback).
308
+ //
309
+ // globalThis (not a module-level let) because the two packages cannot import
310
+ // each other — providers stays standalone (no pi-core import) and has no
311
+ // exports map — and the slot must survive /reload. KEY_RING_FEEDBACK_KEY is
312
+ // THE one deliberate cross-package seam; keep the literal in sync with
313
+ // packages/providers/ring-lifecycle.ts.
314
+ export const KEY_RING_FEEDBACK_KEY = "__braid_key_ring_feedback_handler";
315
+
316
+ /**
317
+ * Ring-feedback handler invoked on direct LLM-call outcomes. Structurally
318
+ * implemented by providers/ring-lifecycle.ts createKeyRingFeedbackHandler();
319
+ * modelId/providerId are the model that made the call (providers resolves the
320
+ * owning ring from them — no module-global last-writer-wins).
321
+ */
322
+ export interface KeyRingFeedbackHandler {
323
+ reportFailure(modelId: string, providerId: string | undefined, errText: string): void;
324
+ reportSuccess(modelId: string, providerId: string | undefined): void;
325
+ }
326
+
327
+ /** Read the ring-feedback handler published by the providers extension. */
328
+ export function getKeyRingFeedbackHandler(): KeyRingFeedbackHandler | null {
329
+ const h = (globalThis as Record<string, unknown>)[KEY_RING_FEEDBACK_KEY];
330
+ return h && typeof h === "object" ? (h as KeyRingFeedbackHandler) : null;
331
+ }
332
+
333
+ /** Override/clear the ring-feedback handler. Test + registration helper. */
334
+ export function setKeyRingFeedbackHandler(handler: KeyRingFeedbackHandler | null): void {
335
+ (globalThis as Record<string, unknown>)[KEY_RING_FEEDBACK_KEY] = handler ?? null;
336
+ }
337
+
338
+ /** Clear the slot. Test helper. */
339
+ export function resetKeyRingFeedbackHandler(): void {
340
+ (globalThis as Record<string, unknown>)[KEY_RING_FEEDBACK_KEY] = null;
341
+ }
342
+
343
+ // The telegram package owns the poller's consecutive getUpdates-failure counter
344
+ // and emits tunnel-down/up transitions through a process-global hub; the core
345
+ // watchdog subscribes here and surfaces the down/recovery whispers. Same
346
+ // deliberate cross-package seam style as KEY_RING_FEEDBACK_KEY — the
347
+ // WATCHDOG_TUNNEL_KEY literal AND the hub protocol MUST stay in sync with
348
+ // packages/telegram/src/lib/watchdog-tunnel.ts (whichever side runs first
349
+ // get-or-creates the hub at the same slot; telegram publishes, core
350
+ // subscribes). If the literal or protocol drifts, tunnel signals silently
351
+ // stop reaching the watchdog.
352
+ export const WATCHDOG_TUNNEL_KEY = "__braid_watchdog_tunnel";
353
+
354
+ export type WatchdogTunnelStatus = "up" | "down" | "unknown";
355
+
356
+ /** A tunnel liveness transition (mirrors telegram's WatchdogTunnelStatusEvent). */
357
+ export interface WatchdogTunnelEvent {
358
+ status: "up" | "down";
359
+ /** Consecutive getUpdates failures at the transition (0 on "up"). */
360
+ failures: number;
361
+ /** Last getUpdates error text (present on "down"). */
362
+ lastError?: string;
363
+ /** Ready-to-deliver whisper body authored by the telegram component. */
364
+ message: string;
365
+ }
366
+
367
+ /** Hub protocol mirrored verbatim by telegram (watchdog-tunnel.ts). */
368
+ export interface WatchdogTunnelHub {
369
+ status: WatchdogTunnelStatus;
370
+ failures: number;
371
+ lastError?: string;
372
+ publish(event: WatchdogTunnelEvent): void;
373
+ subscribe(fn: (event: WatchdogTunnelEvent) => void): () => void;
374
+ }
375
+
376
+ function createWatchdogTunnelHub(): WatchdogTunnelHub {
377
+ const subs = new Set<(event: WatchdogTunnelEvent) => void>();
378
+ let status: WatchdogTunnelStatus = "unknown";
379
+ let failures = 0;
380
+ let lastError: string | undefined;
381
+ const hub: WatchdogTunnelHub = {
382
+ get status(): WatchdogTunnelStatus {
383
+ return status;
384
+ },
385
+ get failures(): number {
386
+ return failures;
387
+ },
388
+ get lastError(): string | undefined {
389
+ return lastError;
390
+ },
391
+ publish(event) {
392
+ status = event.status;
393
+ failures = event.failures;
394
+ if (event.lastError !== undefined) lastError = event.lastError;
395
+ for (const fn of [...subs]) {
396
+ try {
397
+ fn(event);
398
+ } catch {
399
+ // A subscriber must never break the bus — the canary keeps running.
400
+ }
401
+ }
402
+ },
403
+ subscribe(fn) {
404
+ subs.add(fn);
405
+ return () => {
406
+ subs.delete(fn);
407
+ };
408
+ },
409
+ };
410
+ return hub;
411
+ }
412
+
413
+ /** Get-or-create the shared watchdog tunnel hub (see WATCHDOG_TUNNEL_KEY). */
414
+ export function getWatchdogTunnelHub(): WatchdogTunnelHub {
415
+ const g = globalThis as Record<string, unknown>;
416
+ const existing = g[WATCHDOG_TUNNEL_KEY] as WatchdogTunnelHub | undefined;
417
+ if (existing && typeof existing?.publish === "function") return existing;
418
+ const hub = createWatchdogTunnelHub();
419
+ g[WATCHDOG_TUNNEL_KEY] = hub;
420
+ return hub;
421
+ }
422
+
423
+ /** Current tunnel status ("unknown" when telegram never published). */
424
+ export function getWatchdogTunnelStatus(): WatchdogTunnelStatus {
425
+ return getWatchdogTunnelHub().status;
426
+ }
427
+
428
+ /** Subscribe to tunnel transitions; returns an unsubscribe function. */
429
+ export function subscribeWatchdogTunnel(fn: (event: WatchdogTunnelEvent) => void): () => void {
430
+ return getWatchdogTunnelHub().subscribe(fn);
431
+ }
432
+
433
+ // The core watchdog's escalation "keeps the remote canary warm" with an
434
+ // optional 1-line compact tg ping when the channel is up. telegram/index.ts
435
+ // publishes a plain-text sender here when the channel is enabled; an absent
436
+ // slot (telegram not loaded) makes the optional signal a silent no-op. The
437
+ // literal MUST stay in sync with packages/telegram/src/index.ts
438
+ // WATCHDOG_TG_SIGNAL_KEY.
439
+ export const WATCHDOG_TG_SIGNAL_KEY = "__braid_watchdog_tg_signal";
440
+
441
+ /** Best-effort 1-line tg sender (must never throw). */
442
+ export type WatchdogTgSignalSender = (text: string) => boolean | Promise<boolean>;
443
+
444
+ /** Read the optional tg-signal sender published by the telegram extension. */
445
+ export function getWatchdogTgSignalSender(): WatchdogTgSignalSender | null {
446
+ const fn = (globalThis as Record<string, unknown>)[WATCHDOG_TG_SIGNAL_KEY];
447
+ return typeof fn === "function" ? (fn as WatchdogTgSignalSender) : null;
448
+ }
449
+
450
+ // Dead wake delivery is KNOWN first in the timer's wake-retry queue (repeated
451
+ // outcome timeouts for one timer id, exhausted redelivery chains) — but the
452
+ // episode latch + escalation belong to the watchdog (it owns
453
+ // liveness/stall/escalation and already carries the tg-signal alert path).
454
+ // Extensions must not import sibling extensions, so the watchdog publishes a
455
+ // feed object into a process-global slot at engine build time — the same
456
+ // pattern as WATCHDOG_TG_SIGNAL_KEY above — and the timer forwards
457
+ // threshold-crossing facts into it lossy-safe (absent slot → no-op).
458
+ export const WATCHDOG_WAKE_DELIVERY_FEED_KEY = "__braid_watchdog_wake_delivery_feed";
459
+
460
+ /** Facts the timer's wake-retry queue forwards to the watchdog engine. */
461
+ export interface WatchdogWakeDeliveryFeed {
462
+ /** The outcome window elapsed with no settle for this timer (Nth time for
463
+ * the same fire — the repeated-timeout stall signal). */
464
+ recordWakeOutcomeTimeout(timerId: string, reason: string, timeouts: number): void;
465
+ /** A wake fire dropped after exhausting its redelivery bound. */
466
+ recordWakeUndelivered(timerId: string, reason: string, attempts: number): void;
467
+ /** A tracked wake resolved as delivered — wakes resumed. */
468
+ recordWakeDelivered(timerId: string): void;
469
+ }
470
+
471
+ /** Publish (or clear with null) the wake-delivery feed. */
472
+ export function setWatchdogWakeDeliveryFeed(feed: WatchdogWakeDeliveryFeed | null): void {
473
+ (globalThis as Record<string, unknown>)[WATCHDOG_WAKE_DELIVERY_FEED_KEY] = feed;
474
+ }
475
+
476
+ /** Read the wake-delivery feed published by the watchdog extension. */
477
+ export function getWatchdogWakeDeliveryFeed(): WatchdogWakeDeliveryFeed | null {
478
+ const feed = (globalThis as Record<string, unknown>)[WATCHDOG_WAKE_DELIVERY_FEED_KEY];
479
+ return feed && typeof feed === "object" ? (feed as WatchdogWakeDeliveryFeed) : null;
480
+ }
481
+
482
+ // A due timer/wake is a legitimate reason for a session to look quiet: the
483
+ // wake is about to start a turn. The fact lives with the scheduler (only it
484
+ // knows what is due); the watchdog's stall classifier is the consumer. The
485
+ // scheduling layer may not import the watchdog, so — same pattern as the
486
+ // wake-delivery feed above — it publishes a plain question into a
487
+ // process-global slot and the watchdog asks it before classifying a silent
488
+ // turn dead. Absent slot ⇒ not due (a stall must not be suppressed by a
489
+ // provider that never loaded).
490
+ export const WATCHDOG_WAKE_DUE_PROVIDER_KEY = "__braid_watchdog_wake_due_provider";
491
+
492
+ /** Answers whether a timer/wake is currently due for the active session. */
493
+ export type WatchdogWakeDueProvider = () => boolean;
494
+
495
+ /** Publish (or clear with null) the wake-due provider. */
496
+ export function setWatchdogWakeDueProvider(provider: WatchdogWakeDueProvider | null): void {
497
+ (globalThis as Record<string, unknown>)[WATCHDOG_WAKE_DUE_PROVIDER_KEY] = provider;
498
+ }
499
+
500
+ /** Read the wake-due provider published by the scheduler. */
501
+ export function getWatchdogWakeDueProvider(): WatchdogWakeDueProvider | null {
502
+ const fn = (globalThis as Record<string, unknown>)[WATCHDOG_WAKE_DUE_PROVIDER_KEY];
503
+ return typeof fn === "function" ? (fn as WatchdogWakeDueProvider) : null;
504
+ }
505
+
506
+ // Whether a new turn should start against the current session's route is a
507
+ // health fact OWNED by the enforcement layer (it sees the classified LLM
508
+ // errors); the scheduling wake path is the CONSUMER that must act on it. The
509
+ // scheduler's layer may not import an extension sibling, so — same pattern as
510
+ // the wake-delivery feed above — the enforcement layer publishes a small
511
+ // mechanism-only object into a process-global slot and the scheduler asks it
512
+ // one question. Absent slot ⇒ never blocked (a wake must fail open).
513
+ //
514
+ // Names here carry no provider, status code or error category: the shape is
515
+ // only "may a turn start" + "a turn ended cleanly", so a generic layer cannot
516
+ // learn a domain fact from it.
517
+ export const TURN_START_GATE_KEY = "__braid_turn_start_gate";
518
+
519
+ export interface TurnStartGate {
520
+ /** Should the scheduler withhold a turn-start for this session now?
521
+ * `threshold` is the caller's configured bound. */
522
+ isBlocked(ctx: unknown, threshold: number): boolean;
523
+ /** A turn settled without a failure outcome — a real clean turn. */
524
+ noteCleanTurn(ctx: unknown): void;
525
+ }
526
+
527
+ /** Publish (or clear with null) the turn-start gate. */
528
+ export function setTurnStartGate(gate: TurnStartGate | null): void {
529
+ (globalThis as Record<string, unknown>)[TURN_START_GATE_KEY] = gate;
530
+ }
531
+
532
+ /** Read the turn-start gate published by the enforcement extension. */
533
+ export function getTurnStartGate(): TurnStartGate | null {
534
+ const gate = (globalThis as Record<string, unknown>)[TURN_START_GATE_KEY];
535
+ return gate && typeof gate === "object" ? (gate as TurnStartGate) : null;
536
+ }
537
+
538
+ // The anti-sycophancy detector computes the acceptance (validation-before-
539
+ // correction) verdict at message_end; the over-correction gate needs the
540
+ // SAME already-computed verdict at tool-call time, from the enforcement
541
+ // extension. Extensions must not import each other's handlers, so — same
542
+ // pattern as TURN_START_GATE_KEY above — the detector publishes the verdict
543
+ // into a process-global slot and the gate reads it lossy-safe. The signal
544
+ // carries the producing session and a wall-clock stamp: another session's
545
+ // signal and an expired signal both read cold. Absent slot ⇒ no signal.
546
+ export const ACCEPTANCE_SIGNAL_KEY = "__braid_acceptance_signal";
547
+
548
+ export interface AcceptanceSignal {
549
+ /** Epoch ms when the detector computed the verdict. */
550
+ atMs: number;
551
+ /** The detector's VbC score (already computed; not re-derived here). */
552
+ score: number;
553
+ /** Session that produced the verdict; a signal from another session is cold. */
554
+ sessionId?: string;
555
+ }
556
+
557
+ /** Publish (or clear with null) the latest acceptance signal. */
558
+ export function setAcceptanceSignal(signal: AcceptanceSignal | null): void {
559
+ (globalThis as Record<string, unknown>)[ACCEPTANCE_SIGNAL_KEY] = signal;
560
+ }
561
+
562
+ /** Read the acceptance signal published by the sycophancy detector. */
563
+ export function getAcceptanceSignal(): AcceptanceSignal | null {
564
+ const signal = (globalThis as Record<string, unknown>)[ACCEPTANCE_SIGNAL_KEY];
565
+ if (!signal || typeof signal !== "object") return null;
566
+ const s = signal as AcceptanceSignal;
567
+ if (typeof s.atMs !== "number" || !Number.isFinite(s.atMs)) return null;
568
+ return s;
569
+ }
570
+
571
+ //
572
+ // The emergency offloader (context-manager/handlers/context-emergency.ts)
573
+ // must be callable from code that lives OUTSIDE the context-manager extension
574
+ // tree: llm-call's retry path (lib/ai), the heartbeat consolidation gate, and
575
+ // the providers pre-send guard. Those consumers cannot import the extension
576
+ // module directly (layering + heavy import chain), so — like KEY_RING_FEEDBACK_
577
+ // KEY above — context-manager publishes a runner into a process-global slot
578
+ // and consumers read it lossy-safe (absent → no-op).
579
+
580
+ export const CONTEXT_EMERGENCY_OFFLOAD_RUNNER_KEY = "__braid_context_emergency_offload_runner";
581
+
582
+ /** What one emergency offload run did (consumers decide on retry). */
583
+ export interface ContextEmergencyOffloadResult {
584
+ /** Entries actually stubbed this run (0 = nothing shrank → do NOT retry). */
585
+ offloaded: number;
586
+ /** In-context chars freed by stubbing. */
587
+ charsSaved: number;
588
+ /** Whether the run hit an error and left the context untouched. */
589
+ error?: string;
590
+ }
591
+
592
+ /**
593
+ * Run the emergency size-driven offload against the CURRENT session context.
594
+ * Implemented by context-manager (needs ctx to read session state + settings);
595
+ * reason is a short label for the log line ("llm-retry", "heartbeat-gate",
596
+ * "compaction-413", "pre-send"). Must never throw (publish side wraps).
597
+ */
598
+ export type ContextEmergencyOffloadRunner = (
599
+ ctx: unknown,
600
+ reason: string,
601
+ ) => ContextEmergencyOffloadResult | Promise<ContextEmergencyOffloadResult>;
602
+
603
+ /** Publish the emergency-offload runner (called by context-manager at load). */
604
+ export function setContextEmergencyOffloadRunner(runner: ContextEmergencyOffloadRunner): void {
605
+ (globalThis as Record<string, unknown>)[CONTEXT_EMERGENCY_OFFLOAD_RUNNER_KEY] = runner;
606
+ }
607
+
608
+ /**
609
+ * Read the published emergency-offload runner. Null when context-manager has
610
+ * not loaded (or was reloaded without re-publishing) — callers treat this as
611
+ * "cannot shrink" and proceed with their normal failure path.
612
+ */
613
+ export function getContextEmergencyOffloadRunner(): ContextEmergencyOffloadRunner | null {
614
+ const fn = (globalThis as Record<string, unknown>)[CONTEXT_EMERGENCY_OFFLOAD_RUNNER_KEY];
615
+ return typeof fn === "function" ? (fn as ContextEmergencyOffloadRunner) : null;
616
+ }
617
+
618
+ /** Clear the slot. Test helper. */
619
+ export function resetContextEmergencyOffloadRunner(): void {
620
+ delete (globalThis as Record<string, unknown>)[CONTEXT_EMERGENCY_OFFLOAD_RUNNER_KEY];
621
+ }
622
+
623
+ /**
624
+ * ExtensionContext provider. Modules under lib/ have no ctx of their own, so
625
+ * the enforcement session-start handler publishes a closure over the CURRENT
626
+ * session's ctx. Consumers: the emergency-offload retry path in llm-call.ts,
627
+ * and the auxiliary LLM path's registry/auth lookup in the same module.
628
+ * Single-session design, same as the LLM call listeners slot above.
629
+ *
630
+ * The name is general because the slot carries the whole context, not one
631
+ * consumer's slice of it: a second consumer must not need a second slot.
632
+ */
633
+ export const EXTENSION_CTX_PROVIDER_KEY = "__braid_extension_ctx_provider";
634
+
635
+ /** Publish the ctx provider (called by enforcement's session-start handler). */
636
+ export function setExtensionCtxProvider(provider: () => unknown): void {
637
+ (globalThis as Record<string, unknown>)[EXTENSION_CTX_PROVIDER_KEY] = provider;
638
+ }
639
+
640
+ /** Read the published ctx provider (null when enforcement has not loaded). */
641
+ export function getExtensionCtxProvider(): (() => unknown) | null {
642
+ const fn = (globalThis as Record<string, unknown>)[EXTENSION_CTX_PROVIDER_KEY];
643
+ return typeof fn === "function" ? (fn as () => unknown) : null;
644
+ }
645
+
646
+ /** Clear the slot. Test helper. */
647
+ export function resetExtensionCtxProvider(): void {
648
+ delete (globalThis as Record<string, unknown>)[EXTENSION_CTX_PROVIDER_KEY];
649
+ }
650
+
651
+ /**
652
+ * Emergency-offload spellings of the accessors above. Same one slot: the
653
+ * context-emergency retry path was built against these names, and a test that
654
+ * publishes through one name must be visible through the other.
655
+ */
656
+ export function setContextEmergencyCtxProvider(provider: () => unknown): void {
657
+ setExtensionCtxProvider(provider);
658
+ }
659
+
660
+ /** @see setContextEmergencyCtxProvider */
661
+ export function getContextEmergencyCtxProvider(): (() => unknown) | null {
662
+ return getExtensionCtxProvider();
663
+ }
664
+
665
+ /** @see setContextEmergencyCtxProvider */
666
+ export function resetContextEmergencyCtxProvider(): void {
667
+ resetExtensionCtxProvider();
668
+ }
669
+
670
+ //
671
+ // llm-call.ts dispatches auxiliary calls through the published extension
672
+ // context (ctx.modelRegistry). When nothing has published a context it
673
+ // degrades to pi-ai's compat transport, which carries the model's credential
674
+ // but neither the session id nor configured provider headers. That degradation
675
+ // is announced once per process, never per call. globalThis-backed rather than
676
+ // a module-level `let`: the extension module tree is re-evaluated on /reload,
677
+ // so a module-level flag would be lost and the same degradation announced
678
+ // again.
679
+ const AUX_DEGRADED_TRANSPORT_WARNED_KEY = "__braid_aux_degraded_transport_warned";
680
+
681
+ /** True once the auxiliary-call degraded-transport warning has been emitted. */
682
+ export function hasWarnedAuxDegradedTransport(): boolean {
683
+ return (globalThis as Record<string, unknown>)[AUX_DEGRADED_TRANSPORT_WARNED_KEY] === true;
684
+ }
685
+
686
+ /** Record that the auxiliary-call degraded-transport warning has been emitted. */
687
+ export function markAuxDegradedTransportWarned(): void {
688
+ (globalThis as Record<string, unknown>)[AUX_DEGRADED_TRANSPORT_WARNED_KEY] = true;
689
+ }
690
+
691
+ /** Clear the latch. Test helper. */
692
+ export function resetAuxDegradedTransportWarning(): void {
693
+ delete (globalThis as Record<string, unknown>)[AUX_DEGRADED_TRANSPORT_WARNED_KEY];
694
+ }
695
+
696
+ //
697
+ // The timer extension factory closes over a
698
+ // `poller` and `sessionState` variable, which is correct for the standard
699
+ // pi lifecycle (one process per session) but breaks under multi-session-
700
+ // per-process. The comment block in timer/index.ts:16-41 promises a
701
+ // debug-mode counter that logs a warning if `timerExtension(pi)` is called
702
+ // more than once.
703
+ //
704
+ // The counter lives here (not as a module-level let in timer/index.ts) so
705
+ // the no-module-level-let contract is satisfied. The factory call counter
706
+ // is process-global by definition (it tracks process-wide extension
707
+ // registration), so global-state.ts is the right home.
708
+ export interface TimerExtensionFactoryState {
709
+ callCount: number;
710
+ }
711
+
712
+ function createDefaultTimerExtensionFactoryState(): TimerExtensionFactoryState {
713
+ return { callCount: 0 };
714
+ }
715
+
716
+ let _timerExtensionFactoryState: TimerExtensionFactoryState | undefined;
717
+
718
+ /**
719
+ * Get the shared timer-extension-factory counter.
720
+ *
721
+ * The timer extension increments this on every `timerExtension(pi)` call
722
+ * and logs a warning when the count exceeds 1 (signaling an accidental
723
+ * double-registration that would break the single-process-per-session
724
+ * assumption).
725
+ */
726
+ export function getTimerExtensionFactoryState(): TimerExtensionFactoryState {
727
+ if (!_timerExtensionFactoryState) {
728
+ _timerExtensionFactoryState = createDefaultTimerExtensionFactoryState();
729
+ }
730
+ return _timerExtensionFactoryState;
731
+ }
732
+
733
+ // The discoverability handler in enforcement runs on every session_start and
734
+ // emits a bundled whisper with prior-session hints. On /reload, the extension
735
+ // module IS re-evaluated (so module-level `let` in the handler doesn't persist).
736
+ // _This_ module is also in the extension import tree, so a module-level `let`
737
+ // here would also be lost on reload. We use `globalThis` instead, which is the
738
+ // Node.js process global and survives any module re-evaluation.
739
+ //
740
+ // Key: process-global (not module-global). A fresh `pi` process starts with
741
+ // an empty Set (everything is "new"). Within the same process, the Set persists
742
+ // across any number of /reload calls.
743
+ //
744
+ // Two layers:
745
+ // 1. Bundle-text dedup: `_GLOBAL_KEY` (`__braid_discoverability_shown`).
746
+ // Old approach. Fragile: dynamic content changes (openPlans
747
+ // count, goal slice) cause the bundle string to vary, missing the Set.has.
748
+ // 2. Per-signal dedup: `_GLOBAL_SIGNAL_KEY` (`__braid_shown_signal_types`).
749
+ // Added. Stable across content variations. Each signal TYPE
750
+ // is a semantic key; content changes don't affect dedup.
751
+ //
752
+ // The SUPPRESSION TRUTH is now the session branch (`_GLOBAL_BRANCH_SIGNAL_KEY`
753
+ // below, rebuilt from `braid_shown_signal` entries at session_start). The
754
+ // per-project disk file is a derived write-through index, kept for
755
+ // cross-session readers and never consulted for dedup - see the branch-durable
756
+ // section below for why (a rewound branch must not inherit a project's history).
757
+
758
+ import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
759
+ import { dirname } from "node:path";
760
+ import { shownSignalsFilePath } from "../config/braid-paths.js";
761
+
762
+ const _GLOBAL_KEY = "__braid_discoverability_shown";
763
+
764
+ /**
765
+ * Get the shared discoverability dedup set. Created lazily on first access.
766
+ * The Set is stored in `globalThis` (process-global) so it survives module
767
+ * re-evaluation on /reload.
768
+ */
769
+ export function getShownDiscoveryBundles(): Set<string> {
770
+ if (!(globalThis as any)[_GLOBAL_KEY]) {
771
+ (globalThis as any)[_GLOBAL_KEY] = new Set<string>();
772
+ }
773
+ return (globalThis as any)[_GLOBAL_KEY];
774
+ }
775
+
776
+ /** Reset the dedup set. Test helper. */
777
+ export function resetShownDiscoveryBundles(): void {
778
+ delete (globalThis as any)[_GLOBAL_KEY];
779
+ }
780
+
781
+ // Bundle-text dedup misses when ANY dynamic content in the bundle changes
782
+ // (openPlans count, goal slice, tag list, etc.). Per-signal dedup tracks
783
+ // individual signal TYPES (semantic keys), so the same signal type is
784
+ // skipped on re-emission even if its content varies.
785
+ // Used by register-session-start-discoverability.ts.
786
+
787
+ const _GLOBAL_SIGNAL_KEY = "__braid_shown_signal_types";
788
+
789
+ /** Signal type identifiers used by the discoverability handler.
790
+ * These are the dedup keys — keep them stable across releases. */
791
+ export type DiscoverySignalType =
792
+ | "scratchpad_prior"
793
+ | "memory_prior"
794
+ | "sessions_prior"
795
+ | "resume"
796
+ | "tags_prior"
797
+ | "context_hygiene_tip";
798
+
799
+ /** Get the shared shown-signal-types set (process-global, survives /reload). */
800
+ export function getShownSignals(): Set<DiscoverySignalType> {
801
+ if (!(globalThis as any)[_GLOBAL_SIGNAL_KEY]) {
802
+ (globalThis as any)[_GLOBAL_SIGNAL_KEY] = new Set<DiscoverySignalType>();
803
+ }
804
+ return (globalThis as any)[_GLOBAL_SIGNAL_KEY];
805
+ }
806
+
807
+ /** Reset the shown-signal set. Test helper. */
808
+ export function resetShownSignals(): void {
809
+ delete (globalThis as any)[_GLOBAL_SIGNAL_KEY];
810
+ }
811
+
812
+ /** Check if a signal type has been shown in this process. */
813
+ export function isSignalShown(t: DiscoverySignalType): boolean {
814
+ return getShownSignals().has(t);
815
+ }
816
+
817
+ /** Mark a signal type as shown in this process. */
818
+ export function markSignalShown(t: DiscoverySignalType): void {
819
+ getShownSignals().add(t);
820
+ }
821
+
822
+ // The on-disk file at <braid>/shown-signals.json is a derived index of every
823
+ // signal mark this project has ever written. Suppression decisions do NOT
824
+ // read it: the ACTIVE BRANCH decides what this session has already shown
825
+ // (see the branch-durable section below). The file is kept as a cross-session
826
+ // index for readers that ask "has this project ever shown X" - it is written
827
+ // through on every mark and can over-report after a rewind by design.
828
+ //
829
+ // History: this layer was added for session-resume flooding, before the
830
+ // branch entries existed. The branch covers resume natively, so the file
831
+ // stopped being consulted for dedup; keeping it as an index preserves the
832
+ // accumulated project history without letting it override the branch.
833
+
834
+ const _GLOBAL_PROJECT_SIGNAL_KEY = "__braid_project_shown_signals";
835
+
836
+ /**
837
+ * Get the per-project shown-signals map from disk.
838
+ * Internal cache keyed by project slug. The on-disk file is a flat JSON
839
+ * object: `{ "<project-slug>": ["signal_type1", ...] }`.
840
+ */
841
+ function loadProjectShownSignalsFromDisk(): Record<string, DiscoverySignalType[]> {
842
+ try {
843
+ const file = shownSignalsFilePath();
844
+ if (existsSync(file)) {
845
+ const raw = readFileSync(file, "utf-8");
846
+ return JSON.parse(raw);
847
+ }
848
+ } catch {
849
+ // File corrupt or missing — start fresh
850
+ }
851
+ return {};
852
+ }
853
+
854
+ function persistProjectShownSignalsToDisk(data: Record<string, DiscoverySignalType[]>): void {
855
+ try {
856
+ const file = shownSignalsFilePath();
857
+ const dir = dirname(file);
858
+ if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
859
+ writeFileSync(file, JSON.stringify(data), "utf-8");
860
+ } catch {
861
+ // Non-fatal — persistence is a best-effort optimization
862
+ }
863
+ }
864
+
865
+ /**
866
+ * Get the process-global cache of per-project shown signals (derived index).
867
+ * Lazily loaded from disk on first access.
868
+ * Structure: { "<slug>": Set<signal_type> }
869
+ */
870
+ function getProjectShownSignalsCache(): Map<string, Set<DiscoverySignalType>> {
871
+ if (!(globalThis as any)[_GLOBAL_PROJECT_SIGNAL_KEY]) {
872
+ const fromDisk = loadProjectShownSignalsFromDisk();
873
+ const map = new Map<string, Set<DiscoverySignalType>>();
874
+ for (const [slug, types] of Object.entries(fromDisk)) {
875
+ map.set(slug, new Set(types));
876
+ }
877
+ (globalThis as any)[_GLOBAL_PROJECT_SIGNAL_KEY] = map;
878
+ }
879
+ return (globalThis as any)[_GLOBAL_PROJECT_SIGNAL_KEY];
880
+ }
881
+
882
+ // Session-scoped state must follow the active branch: each mark appends a
883
+ // durable custom entry (`SHOWN_SIGNAL_ENTRY_TYPE`), and session_start rebuilds
884
+ // the shown set from `ctx.sessionManager.getBranch()`. Without this, a signal
885
+ // the rewound branch never saw stayed suppressed by the project-level file -
886
+ // the file records project history, the branch records this conversation.
887
+
888
+ /** Custom entry type for durable shown-signal records. Stable across releases. */
889
+ export const SHOWN_SIGNAL_ENTRY_TYPE = "braid_shown_signal";
890
+
891
+ /** Structural appendEntry seam (same shape as compaction-trace's EntryAppender). */
892
+ export interface ShownSignalEntryAppender {
893
+ appendEntry<T = unknown>(customType: string, data?: T): void;
894
+ }
895
+
896
+ const _GLOBAL_BRANCH_SIGNAL_KEY = "__braid_branch_shown_signals";
897
+
898
+ /**
899
+ * Collect shown signals from branch entries into a slug -> types map.
900
+ * Malformed payloads are skipped rather than trusted. Only the ACTIVE branch
901
+ * is passed in (getBranch returns the leaf path), so abandoned-branch entries
902
+ * are never replayed.
903
+ */
904
+ export function readShownSignalsFromBranch(
905
+ entries: readonly unknown[],
906
+ ): Map<string, Set<DiscoverySignalType>> {
907
+ const map = new Map<string, Set<DiscoverySignalType>>();
908
+ for (const raw of entries) {
909
+ const entry = raw as { type?: string; customType?: string; data?: unknown } | null;
910
+ if (entry?.type !== "custom" || entry.customType !== SHOWN_SIGNAL_ENTRY_TYPE) continue;
911
+ const data = entry.data as { slug?: unknown; type?: unknown } | null | undefined;
912
+ if (!data || typeof data !== "object") continue;
913
+ if (typeof data.slug !== "string" || typeof data.type !== "string") continue;
914
+ let set = map.get(data.slug);
915
+ if (!set) {
916
+ set = new Set<DiscoverySignalType>();
917
+ map.set(data.slug, set);
918
+ }
919
+ set.add(data.type as DiscoverySignalType);
920
+ }
921
+ return map;
922
+ }
923
+
924
+ /**
925
+ * Replace the branch-reconstructed shown-signal map. Called at session_start
926
+ * (before the discoverability handler filters its signals); replacement, not
927
+ * merge: the branch is the source of truth.
928
+ */
929
+ export function reconstructShownSignalsFromBranch(entries: readonly unknown[]): void {
930
+ (globalThis as any)[_GLOBAL_BRANCH_SIGNAL_KEY] = readShownSignalsFromBranch(entries);
931
+ }
932
+
933
+ function getBranchShownSignals(): Map<string, Set<DiscoverySignalType>> {
934
+ if (!(globalThis as any)[_GLOBAL_BRANCH_SIGNAL_KEY]) {
935
+ (globalThis as any)[_GLOBAL_BRANCH_SIGNAL_KEY] = new Map<string, Set<DiscoverySignalType>>();
936
+ }
937
+ return (globalThis as any)[_GLOBAL_BRANCH_SIGNAL_KEY];
938
+ }
939
+
940
+ /**
941
+ * Check if a signal type has been shown for a project slug ON THE ACTIVE
942
+ * BRANCH. The branch decides: a rewound branch that never saw the signal
943
+ * answers false, so the signal is shown again for that branch.
944
+ */
945
+ export function isProjectSignalShown(slug: string, t: DiscoverySignalType): boolean {
946
+ const projectSet = getBranchShownSignals().get(slug);
947
+ return projectSet ? projectSet.has(t) : false;
948
+ }
949
+
950
+ /**
951
+ * Mark a signal type as shown for a project slug: update the branch map (fast
952
+ * path), append the durable entry through the extension API's appendEntry
953
+ * seam, and write through to the derived disk index (cross-session readers;
954
+ * never consulted for suppression). Both side effects are best-effort - the
955
+ * in-memory map already suppresses the current session.
956
+ */
957
+ export function markProjectSignalShown(
958
+ slug: string,
959
+ t: DiscoverySignalType,
960
+ appender?: ShownSignalEntryAppender,
961
+ ): void {
962
+ const map = getBranchShownSignals();
963
+ let projectSet = map.get(slug);
964
+ if (!projectSet) {
965
+ projectSet = new Set<DiscoverySignalType>();
966
+ map.set(slug, projectSet);
967
+ }
968
+ projectSet.add(t);
969
+
970
+ if (appender) {
971
+ try {
972
+ appender.appendEntry(SHOWN_SIGNAL_ENTRY_TYPE, {
973
+ slug,
974
+ type: t,
975
+ timestamp: Date.now(),
976
+ });
977
+ } catch {
978
+ // Non-fatal — the in-memory branch map still suppresses this session.
979
+ }
980
+ }
981
+
982
+ // Write-through derived index: accumulate into the disk cache and persist.
983
+ const cache = getProjectShownSignalsCache();
984
+ let cacheSet = cache.get(slug);
985
+ if (!cacheSet) {
986
+ cacheSet = new Set<DiscoverySignalType>();
987
+ cache.set(slug, cacheSet);
988
+ }
989
+ cacheSet.add(t);
990
+
991
+ const data: Record<string, DiscoverySignalType[]> = {};
992
+ for (const [s, set] of cache) {
993
+ data[s] = Array.from(set);
994
+ }
995
+ persistProjectShownSignalsToDisk(data);
996
+ }
997
+
998
+ //
999
+ // The heartbeat tick samples process RSS every tick (context-heartbeat.ts).
1000
+ // T3 adds a boot-time baseline and an advisory whisper that fires at most
1001
+ // ONCE PER BOOT when RSS sustains >2x baseline across a full 24-sample ring
1002
+ // (lib/telemetry/rss-telemetry.ts). Both live here, process-global, because
1003
+ // they must survive session_start resets: a new session in the same process
1004
+ // is the same boot — a session-scoped baseline would re-baseline mid-boot
1005
+ // and the latch would re-arm, violating the "one whisper per boot, no spam"
1006
+ // contract. (lib/state/AGENTS.md getter pattern; NOT a module-level let
1007
+ // outside this file.)
1008
+
1009
+ interface RssBootTelemetry {
1010
+ /** First RSS sample seen in this process (bytes). Set once. */
1011
+ baselineBytes: number | null;
1012
+ /** Whether the sustained-growth advisory whisper already fired this boot. */
1013
+ growthWhisperShown: boolean;
1014
+ }
1015
+
1016
+ let _rssBootTelemetry: RssBootTelemetry | undefined = undefined;
1017
+
1018
+ export function getRssBootTelemetry(): RssBootTelemetry | undefined {
1019
+ return _rssBootTelemetry;
1020
+ }
1021
+
1022
+ /** Set the boot baseline on the first heartbeat tick. Never overwrites. */
1023
+ export function setRssBootBaseline(bytes: number): void {
1024
+ if (!_rssBootTelemetry) {
1025
+ _rssBootTelemetry = { baselineBytes: bytes, growthWhisperShown: false };
1026
+ }
1027
+ }
1028
+
1029
+ /** Latch the sustained-growth advisory as delivered (one per boot). */
1030
+ export function markRssGrowthWhisperShown(): void {
1031
+ if (_rssBootTelemetry) {
1032
+ _rssBootTelemetry.growthWhisperShown = true;
1033
+ } else {
1034
+ _rssBootTelemetry = { baselineBytes: 0, growthWhisperShown: true };
1035
+ }
1036
+ }
1037
+
1038
+ /** Reset both (test helper only). */
1039
+ export function resetRssBootTelemetry(): void {
1040
+ _rssBootTelemetry = undefined;
1041
+ }
1042
+
1043
+ /** Whether the sustained-growth advisory already fired this boot. */
1044
+ export function getRssGrowthWhisperShown(): boolean {
1045
+ return _rssBootTelemetry?.growthWhisperShown ?? false;
1046
+ }