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,1442 @@
1
+ /**
2
+ * Braid Settings - unified reader for pi settings.json braid config.
3
+ *
4
+ * The settings.json file mixes pi-native settings with braid config under a
5
+ * top-level `braid` key. This module reads that config safely and provides
6
+ * a single source of truth for all braid-related feature flags.
7
+ */
8
+
9
+ import { existsSync, readFileSync } from "node:fs";
10
+
11
+ import { createLogger } from "../core/logger.js";
12
+ import {
13
+ USAGE_COMPACT_MEDIUM,
14
+ USAGE_WHISPER_CRITICAL,
15
+ USAGE_WHISPER_WARNING,
16
+ } from "../detection/context-thresholds.js";
17
+ import {
18
+ MEMORY_WRITE_GATE_DEFAULTS,
19
+ WRITE_GATE_SITES,
20
+ type MemoryWriteGateConfig,
21
+ type MemoryWriteGateMode,
22
+ type WriteGateSite,
23
+ } from "../memory/write-quality.js";
24
+ import { getSettingsPath } from "./per-tool-settings.js";
25
+
26
+ const _log = createLogger("braid-settings");
27
+
28
+ interface BraidConfig {
29
+ suppressNudges?: boolean;
30
+ /**
31
+ * Owner time zone (local-time standard).
32
+ * IANA name — formatLocalTime() renders HH:MM TZ (UTC±X) in this zone.
33
+ * Default: Europe/Moscow (owner TZ, UTC+3).
34
+ *
35
+ * Example: "braid": { "timezone": "Europe/Berlin" }
36
+ */
37
+ timezone?: string;
38
+ /**
39
+ * Enforcement-layer overrides. Schema-validated at read time by the
40
+ * NudgeManager (which owns the NudgeType schema); invalid entries
41
+ * are logged and dropped. Empty object = no overrides (use defaults).
42
+ *
43
+ * Example:
44
+ * "braid": {
45
+ * "enforcement": {
46
+ * "nudgeConfigs": {
47
+ * "validation": { "baseCooldownMs": 30000 },
48
+ * "malformed": { "deduplicate": false }
49
+ * }
50
+ * }
51
+ * }
52
+ */
53
+ enforcement?: {
54
+ /**
55
+ * Per-NudgeType config overrides. Keys are NudgeType values
56
+ * (validation, recordFailure, malformed, memory, scratchpad,
57
+ * context, sessionSignals). Values are partial NudgeConfig -
58
+ * only the fields to override.
59
+ */
60
+ nudgeConfigs?: Record<string, unknown>;
61
+ /**
62
+ * Accusation-triggered irreversible-action gate. `mode` is "off"
63
+ * (default, inert), "shadow" (whisper only) or "on" (block).
64
+ */
65
+ overCorrectionGate?: {
66
+ mode?: string;
67
+ };
68
+ };
69
+ /**
70
+ * Memory-layer config. Review-before-write quality gate on durable episode
71
+ * writes: `writeGate` controls the per-site policies (repair/dedupe/reject)
72
+ * and the heartbeat cooldown. Defaults live in
73
+ * `lib/memory/write-quality.ts` (MEMORY_WRITE_GATE_DEFAULTS).
74
+ */
75
+ memory?: {
76
+ /**
77
+ * Write-quality gate on episode writes.
78
+ * enabled: gate ON by default (no-write for junk); false restores
79
+ * pre-gate behavior exactly.
80
+ * cooldownMs: minimum interval between gated heartbeat writes (anti-thrash).
81
+ * mode: "enforce" (default) applies decisions; "warn" logs them and
82
+ * writes anyway (staged rollout).
83
+ * sites: per-writer opt-out for incident rollback; false restores
84
+ * pre-gate behavior for that site.
85
+ *
86
+ * Example:
87
+ * "braid": { "memory": { "writeGate": { "enabled": true, "cooldownMs": 1800000, "mode": "warn" } } }
88
+ */
89
+ writeGate?: {
90
+ enabled?: boolean;
91
+ cooldownMs?: number;
92
+ mode?: MemoryWriteGateMode;
93
+ sites?: Partial<Record<WriteGateSite, boolean>>;
94
+ };
95
+ };
96
+ /**
97
+ * Context-layer config. decouples braid's effective context window
98
+ * from provider catalog truth. The catalog keeps the true model context
99
+ * size (packages/providers/** is untouched); this cap tunes the number
100
+ * braid uses for its own computations (usage percent math, density
101
+ * tokenRatio, window fallbacks).
102
+ *
103
+ * Example:
104
+ * "braid": { "context": { "contextLimitTokens": 262000 } }
105
+ */
106
+ /**
107
+ * Timer-layer config. `maxWakeAttempts` bounds how many times a
108
+ * failed wake fire (provider 401/413/5xx turn) is redelivered before it is
109
+ * dropped with a visible exhausted-notice.
110
+ *
111
+ * Example:
112
+ * "braid": { "timers": { "maxWakeAttempts": 3 } }
113
+ */
114
+ session?: {
115
+ /**
116
+ * Terminal-error wake breaker: while a session has accumulated
117
+ * `threshold` terminal-class LLM errors since its last clean turn, timer
118
+ * wake fires are demoted to non-waking steers so they stop spending
119
+ * doomed model calls. Which error classes are "terminal" is decided by
120
+ * the enforcement health state, not here. Default { enabled: true,
121
+ * threshold: 3 }.
122
+ *
123
+ * Example:
124
+ * "braid": { "session": { "terminalBreaker": { "enabled": false } } }
125
+ */
126
+ terminalBreaker?: {
127
+ /** false disables the gate entirely (byte-identical to pre-gate behavior). */
128
+ enabled?: boolean;
129
+ /** Terminal errors before the gate closes. Default 3. */
130
+ threshold?: number;
131
+ };
132
+ };
133
+ timers?: {
134
+ /**
135
+ * Redelivery bound for a failed wake fire. Default 3
136
+ * (MAX_WAKE_ATTEMPTS_DEFAULT). Integer 1..MAX_WAKE_ATTEMPTS_MAX; other
137
+ * values are ignored with a once-per-process warning and treated as
138
+ * unset.
139
+ */
140
+ maxWakeAttempts?: number;
141
+ /**
142
+ * Wake-delivery stall alerting: forwards dead-wake facts (repeated
143
+ * outcome timeouts, exhausted redelivery drops) from the timer's retry
144
+ * queue to the watchdog's wake-delivery condition, which pages the owner
145
+ * out of band (telegram) — one alert per episode, one recovery line.
146
+ * Default { mode: "on", outcomeTimeouts: 2 }.
147
+ */
148
+ wakeAlert?: {
149
+ /** "off" disables the feed entirely (zero behavioral change). */
150
+ mode?: "on" | "off";
151
+ /** Outcome timeouts for ONE fire before the early stall page
152
+ * (integer 2..WAKE_ALERT_OUTCOME_TIMEOUTS_MAX; 1 would page on every
153
+ * normal long turn — the flood the 240s window exists to prevent). */
154
+ outcomeTimeouts?: number;
155
+ };
156
+ };
157
+ context?: {
158
+ /**
159
+ * Effective context window in tokens. Precedence (ONE resolver,
160
+ * resolveContextLimitTokens): contextLimitTokens as a CEILING over the
161
+ * model/provider contextWindow - min(cap, provider) when the provider
162
+ * window is known, the cap alone when it is not; the cap never widens a
163
+ * model past its true window. 0/negative/non-number are ignored with a
164
+ * once-per-process warning and treated as unset.
165
+ */
166
+ contextLimitTokens?: number;
167
+ /**
168
+ * Age/size-based offload of stale large toolResults. Deterministic
169
+ * (no LLM): eligible results are flushed losslessly to disk and replaced
170
+ * in the per-request context by a stub. Default OFF — when absent or
171
+ * disabled, zero behavior change. Resolver:
172
+ * resolveStaleToolResultOffloadConfig; defaults in
173
+ * STALE_TOOL_RESULT_OFFLOAD_DEFAULTS.
174
+ *
175
+ * Example:
176
+ * "braid": { "context": { "staleToolResultOffload": { "enabled": true } } }
177
+ */
178
+ staleToolResultOffload?: StaleToolResultOffloadSettings;
179
+ /**
180
+ * Emergency size-driven offload of the LARGEST toolResults
181
+ * when a context_window (413 payload-too-large) error fires. Deterministic
182
+ * (no LLM): the largest results are flushed losslessly to disk and replaced
183
+ * in the per-request context by a stub, then the send is retried once.
184
+ * This is the health-gate exception: it runs from llm-call's retry path,
185
+ * the compaction context-window handler, and the heartbeat consolidation
186
+ * gate's context_overflow branch — exactly when shrinking is needed and
187
+ * the normal pipeline refuses. Default ON (a 413 loop burns quota; the
188
+ * offload is lossless). Resolver: resolveContextEmergencyOffloadConfig;
189
+ * defaults in CONTEXT_EMERGENCY_OFFLOAD_DEFAULTS.
190
+ *
191
+ * Example:
192
+ * "braid": { "context": { "contextEmergencyOffload": { "enabled": true } } }
193
+ */
194
+ contextEmergencyOffload?: ContextEmergencyOffloadSettings;
195
+ /**
196
+ * Capture-time cap on toolResult size. When a tool result
197
+ * exceeds maxChars at capture time (tool_result event), the full content
198
+ * is flushed to disk (same offload dir as the stale offloader) and the
199
+ * stored session entry carries a stub + the first 500 chars. Screenshots
200
+ * and base64 blobs never enter context in the first place. Default ON.
201
+ * Resolver: resolveToolResultSizeCapConfig; defaults in
202
+ * TOOL_RESULT_SIZE_CAP_DEFAULTS.
203
+ */
204
+ toolResultSizeCap?: ToolResultSizeCapSettings;
205
+ /**
206
+ * Usage-driven auto-arm of a deterministic slide compaction. When live
207
+ * usage sits at or above armPercent for confirmTicks consecutive
208
+ * heartbeat observations, ONE slide is armed through the same pending
209
+ * queue the context_compress tool uses; it fires at the next turn
210
+ * boundary, never mid-run. Default ON (a session that never gets a
211
+ * manual cleanup still gets relief); set enabled=false to opt out.
212
+ * Resolver: resolveAutoCompactConfig; defaults in
213
+ * AUTO_COMPACT_DEFAULTS.
214
+ *
215
+ * Example:
216
+ * "braid": { "context": { "contextAutoCompact": { "enabled": false } } }
217
+ */
218
+ contextAutoCompact?: AutoCompactSettings;
219
+ };
220
+ }
221
+
222
+ /** Raw (unvalidated) owner settings for braid.context.contextAutoCompact. */
223
+ export interface AutoCompactSettings {
224
+ /** Master gate. Default true — sustained high usage must get relief. */
225
+ enabled?: boolean;
226
+ /** Usage percent at or above which an observation counts (1..100). */
227
+ armPercent?: number;
228
+ /** Consecutive above-threshold observations required before arming. */
229
+ confirmTicks?: number;
230
+ }
231
+
232
+ /** Raw (unvalidated) owner settings for braid.context.contextEmergencyOffload. */
233
+ export interface ContextEmergencyOffloadSettings {
234
+ /** Master gate. Default true — a 413 loop burns quota; shrinking must win. */
235
+ enabled?: boolean;
236
+ /** Minimum result size (chars) before a toolResult is eligible. */
237
+ minChars?: number;
238
+ /** Per-run cap on offloaded chars (bounds the rewrite of one context pass). */
239
+ maxCharsPerRun?: number;
240
+ /** Hard recency guard: never touch the last N tool results. */
241
+ keepRecentTurns?: number;
242
+ }
243
+
244
+ /** Raw (unvalidated) owner settings for braid.context.toolResultSizeCap. */
245
+ export interface ToolResultSizeCapSettings {
246
+ /** Master gate. Default true — oversized blobs must never enter context. */
247
+ enabled?: boolean;
248
+ /** Size threshold (chars) above which a toolResult is flushed + stubbed. */
249
+ maxChars?: number;
250
+ }
251
+
252
+ /**
253
+ * Raw (unvalidated) owner settings for braid.context.staleToolResultOffload.
254
+ * All fields optional; validation/defaults live in
255
+ * resolveStaleToolResultOffloadConfig.
256
+ */
257
+ export interface StaleToolResultOffloadSettings {
258
+ /** Master gate. Default false — the offloader never runs unless opted in. */
259
+ enabled?: boolean;
260
+ /** Minimum result size (chars) before a toolResult is eligible. */
261
+ minChars?: number;
262
+ /** Minimum age (in toolResults-after) before a result is eligible. */
263
+ stalenessTurns?: number;
264
+ /** Hard recency guard: never touch the last N tool results. */
265
+ keepRecentTurns?: number;
266
+ /** Per-LLM-call cap on offloaded chars (prevents mass rewrites in one turn). */
267
+ maxOffloadCharsPerRun?: number;
268
+ }
269
+
270
+ interface Settings {
271
+ braid?: BraidConfig;
272
+ /**
273
+ * pi-core's own retry config (top-level `retry` key, read by
274
+ * settings-manager.getRetrySettings). Braid only READS it — for the
275
+ * wake-retry hold window (getWakeRetryHoldMs) so the hold tracks the
276
+ * actual pi-core retry budget instead of hardcoding one.
277
+ */
278
+ retry?: {
279
+ maxRetries?: number;
280
+ baseDelayMs?: number;
281
+ };
282
+ /**
283
+ * pi-core's own compaction config (top-level `compaction` key, read by
284
+ * settings-manager.getCompactionTokenSetting). Braid only READS it — to
285
+ * detect a reserve that is incoherent with the effective window (see
286
+ * applyCompactionReserveTokens).
287
+ */
288
+ compaction?: {
289
+ reserveTokens?: number;
290
+ modelOverrides?: Record<string, { reserveTokens?: number }>;
291
+ };
292
+ }
293
+
294
+ /** Read and parse settings.json. Not cached - always reads fresh to respect runtime changes. */
295
+
296
+ /** Warned once per process about an unreadable settings.json. */
297
+ let _warnedUnreadableSettings = false;
298
+
299
+ function readSettings(): Settings {
300
+ let result: Settings = {};
301
+ try {
302
+ if (existsSync(getSettingsPath())) {
303
+ result = JSON.parse(readFileSync(getSettingsPath(), "utf-8")) as Settings;
304
+ }
305
+ } catch (e) {
306
+ // Non-fatal: fall through to empty settings - but never silently: a
307
+ // corrupt file reverts every braid setting (context cap, write gate,
308
+ // timer redelivery bound, offload toggles) and that must be visible.
309
+ if ((e as NodeJS.ErrnoException)?.code !== "ENOENT" && !_warnedUnreadableSettings) {
310
+ _warnedUnreadableSettings = true;
311
+ _log.warn(
312
+ "Cannot read settings.json - braid settings in it are ignored until " +
313
+ "the file is fixed (using defaults).",
314
+ { error: (e as Error).message },
315
+ );
316
+ }
317
+ }
318
+ return result;
319
+ }
320
+
321
+ /**
322
+ * Whether cognitive nudges (enforcement whispers, heartbeat suggestions,
323
+ * feedback reminders) should be suppressed entirely.
324
+ *
325
+ * Controlled by braid.suppressNudges in settings.json.
326
+ * Default: false - nudges are ENABLED by default.
327
+ *
328
+ * A user who wants to skip Y/n prompts would set that in pi's native settings -
329
+ * this flag only affects braid's own cognitive nudges.
330
+ */
331
+ export function areCognitiveNudgesDisabled(): boolean {
332
+ const settings = readSettings();
333
+ if (settings.braid?.suppressNudges !== undefined) {
334
+ return settings.braid.suppressNudges === true;
335
+ }
336
+ // Default: nudges are enabled (safe default - braid's value prop is ON)
337
+ return false;
338
+ }
339
+
340
+ /**
341
+ * Read the raw braid.enforcement.nudgeConfigs block from settings.json.
342
+ *
343
+ * Returns an UNVALIDATED shape. Callers must pass the result through
344
+ * NudgeManager.validateNudgeConfig() (or parseNudgeConfigOverrides())
345
+ * before constructing a NudgeManager - the validation lives next to
346
+ * the NudgeType schema to keep the type knowledge in one place.
347
+ *
348
+ * Returns {} when:
349
+ * - settings.json doesn't exist
350
+ * - the braid key isn't present
351
+ * - the enforcement key isn't present
352
+ * - nudgeConfigs is missing or not an object
353
+ */
354
+ export function getRawNudgeConfigOverrides(): Record<string, unknown> {
355
+ const settings = readSettings();
356
+ const raw = settings.braid?.enforcement?.nudgeConfigs;
357
+ if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
358
+ return {};
359
+ }
360
+ return raw as Record<string, unknown>;
361
+ }
362
+
363
+ // ── over-correction gate (braid.enforcement.overCorrectionGate) ──────────
364
+ // The gate withholds a conservative set of destructive calls while a recent
365
+ // accusation or a hot acceptance signal is live (see
366
+ // extensions/enforcement/handlers/over-correction-gate.ts). Shipped default:
367
+ // off — the gate is inert until an operator opts in.
368
+
369
+ /** Gate modes: off (inert), shadow (whisper only), on (whisper + block). */
370
+ export type OverCorrectionGateMode = "off" | "shadow" | "on";
371
+
372
+ export interface OverCorrectionGateConfig {
373
+ mode: OverCorrectionGateMode;
374
+ }
375
+
376
+ /** Default mode: off — the shipped default is inert. */
377
+ export const OVER_CORRECTION_GATE_DEFAULTS: OverCorrectionGateConfig = { mode: "off" };
378
+
379
+ /** Warned once per process about an invalid overCorrectionGate.mode. */
380
+ let _warnedInvalidOverCorrectionGate = false;
381
+
382
+ function _warnInvalidOverCorrectionGate(value: unknown): void {
383
+ if (_warnedInvalidOverCorrectionGate) return;
384
+ _warnedInvalidOverCorrectionGate = true;
385
+ _log.warn(
386
+ "Invalid braid.enforcement.overCorrectionGate in settings.json - ignoring and " +
387
+ 'using the default (mode "off"). Expected { mode: "off" | "shadow" | "on" }.',
388
+ { value },
389
+ );
390
+ }
391
+
392
+ /**
393
+ * Pure resolver for braid.enforcement.overCorrectionGate. Absent block ⇒
394
+ * mode "off". A non-object block or a mode outside the enum warns once and
395
+ * falls back to "off", so a typo can never enable the gate. Kept pure so
396
+ * the default merge is unit-testable without touching live settings.json.
397
+ */
398
+ export function resolveOverCorrectionGate(raw: unknown): OverCorrectionGateConfig {
399
+ if (raw === undefined || raw === null) return { ...OVER_CORRECTION_GATE_DEFAULTS };
400
+ if (typeof raw !== "object" || Array.isArray(raw)) {
401
+ _warnInvalidOverCorrectionGate(raw);
402
+ return { ...OVER_CORRECTION_GATE_DEFAULTS };
403
+ }
404
+ const mode = (raw as { mode?: unknown }).mode;
405
+ if (mode === "off" || mode === "shadow" || mode === "on") return { mode };
406
+ _warnInvalidOverCorrectionGate(mode);
407
+ return { ...OVER_CORRECTION_GATE_DEFAULTS };
408
+ }
409
+
410
+ /**
411
+ * Read the effective over-correction gate config from settings.json, fresh
412
+ * on every call (no caching), like the other readers. Default: mode "off".
413
+ */
414
+ export function getOverCorrectionGateConfig(): OverCorrectionGateConfig {
415
+ return resolveOverCorrectionGate(readSettings().braid?.enforcement?.overCorrectionGate);
416
+ }
417
+
418
+ /**
419
+ * Read the braid.memory.writeGate block from settings.json.
420
+ *
421
+ * Returns MEMORY_WRITE_GATE_DEFAULTS (gate ON, mode "enforce") when the block
422
+ * is absent or any field is invalid — junk is not written unless an operator
423
+ * explicitly opts the gate out. Settings-only by design: no env vars
424
+ * (settings-over-env).
425
+ */
426
+ export function getMemoryWriteGateConfig(): MemoryWriteGateConfig {
427
+ const settings = readSettings();
428
+ return resolveMemoryWriteGateConfig(
429
+ settings.braid?.memory?.writeGate as RawWriteGateBlock | undefined,
430
+ );
431
+ }
432
+
433
+ /** Raw settings block as read from JSON — every field validated in the resolver. */
434
+ interface RawWriteGateBlock {
435
+ enabled?: unknown;
436
+ cooldownMs?: unknown;
437
+ mode?: unknown;
438
+ sites?: unknown;
439
+ }
440
+
441
+ /**
442
+ * Pure resolver for the braid.memory.writeGate block. Absent/partial/invalid
443
+ * fields fall back to MEMORY_WRITE_GATE_DEFAULTS (mode "enforce", sites empty
444
+ * = every site gated). Unknown site keys and non-boolean opt-outs are dropped,
445
+ * so a typo cannot silently disable a writer. Kept pure so the default merge
446
+ * is unit-testable without touching live settings.json.
447
+ */
448
+ export function resolveMemoryWriteGateConfig(raw?: RawWriteGateBlock): MemoryWriteGateConfig {
449
+ const enabled =
450
+ typeof raw?.enabled === "boolean" ? raw.enabled : MEMORY_WRITE_GATE_DEFAULTS.enabled;
451
+ const cooldownMs =
452
+ typeof raw?.cooldownMs === "number" && raw.cooldownMs >= 0
453
+ ? raw.cooldownMs
454
+ : MEMORY_WRITE_GATE_DEFAULTS.cooldownMs;
455
+ const mode: MemoryWriteGateMode =
456
+ raw?.mode === "warn" || raw?.mode === "enforce" ? raw.mode : MEMORY_WRITE_GATE_DEFAULTS.mode;
457
+ return { enabled, cooldownMs, mode, sites: normalizeWriteGateSites(raw?.sites) };
458
+ }
459
+
460
+ /** Keep only known site names with boolean values; absent = gated. */
461
+ function normalizeWriteGateSites(raw: unknown): Partial<Record<WriteGateSite, boolean>> {
462
+ const sites: Partial<Record<WriteGateSite, boolean>> = {};
463
+ if (!raw || typeof raw !== "object" || Array.isArray(raw)) return sites;
464
+ for (const site of WRITE_GATE_SITES) {
465
+ const value = (raw as Record<string, unknown>)[site];
466
+ if (typeof value === "boolean") sites[site] = value;
467
+ }
468
+ return sites;
469
+ }
470
+
471
+ /**
472
+ * The owner time zone for all braid-facing time rendering (lib/utils/local-time.ts).
473
+ * braid.timezone in settings.json when set to a non-empty string; otherwise
474
+ * DEFAULT_TIME_ZONE (Europe/Moscow). Never throws; an invalid IANA name is
475
+ * the caller's concern (local-time.ts validates and falls back).
476
+ */
477
+ export const DEFAULT_TIME_ZONE = "Europe/Moscow";
478
+
479
+ export function getOwnerTimeZone(): string {
480
+ const settings = readSettings();
481
+ const tz = settings.braid?.timezone;
482
+ return typeof tz === "string" && tz.trim() ? tz.trim() : DEFAULT_TIME_ZONE;
483
+ }
484
+
485
+ // ── stale toolResult offload (braid.context.staleToolResultOffload) ────
486
+
487
+ /**
488
+ * Sane defaults for the optional staleToolResultOffload params (defined next
489
+ * to the schema per the design contract). Investigation suggests a size
490
+ * floor of ~4k chars and a keep-recent window of ~20 calls; stalenessTurns
491
+ * adds a conservative age policy above the guard; maxOffloadCharsPerRun
492
+ * bounds the per-request rewrite to 64k chars.
493
+ */
494
+ export const STALE_TOOL_RESULT_OFFLOAD_DEFAULTS = {
495
+ enabled: false,
496
+ minChars: 4_000,
497
+ stalenessTurns: 40,
498
+ keepRecentTurns: 20,
499
+ maxOffloadCharsPerRun: 65_536,
500
+ } as const;
501
+
502
+ /** The validated, effective staleToolResultOffload config. */
503
+ export interface ResolvedStaleToolResultOffloadConfig {
504
+ enabled: boolean;
505
+ minChars: number;
506
+ stalenessTurns: number;
507
+ keepRecentTurns: number;
508
+ maxOffloadCharsPerRun: number;
509
+ }
510
+
511
+ /** Warned once per process about an invalid braid.context.staleToolResultOffload. */
512
+ let _warnedInvalidStaleToolResultOffload = false;
513
+
514
+ function _warnInvalidStaleToolResultOffload(value: unknown): void {
515
+ if (_warnedInvalidStaleToolResultOffload) return;
516
+ _warnedInvalidStaleToolResultOffload = true;
517
+ _log.warn(
518
+ "Invalid braid.context.staleToolResultOffload in settings.json - ignoring " +
519
+ "invalid fields and using defaults (offloader stays OFF unless enabled is true).",
520
+ { value },
521
+ );
522
+ }
523
+
524
+ /**
525
+ * Pure resolver for the braid.context.staleToolResultOffload block.
526
+ * Absent → all defaults (enabled: false). Non-object shape, or any field
527
+ * violating its type/range, falls back to that field's default; the FIRST
528
+ * invalid input also emits a once-per-process warning (mirrors the
529
+ * log-once pattern). Kept pure so the default merge is unit-testable without
530
+ * touching live settings.json.
531
+ */
532
+ export function resolveStaleToolResultOffloadConfig(
533
+ raw: unknown,
534
+ ): ResolvedStaleToolResultOffloadConfig {
535
+ const defaults: ResolvedStaleToolResultOffloadConfig = STALE_TOOL_RESULT_OFFLOAD_DEFAULTS;
536
+ if (raw === undefined) {
537
+ return {
538
+ enabled: defaults.enabled,
539
+ minChars: defaults.minChars,
540
+ stalenessTurns: defaults.stalenessTurns,
541
+ keepRecentTurns: defaults.keepRecentTurns,
542
+ maxOffloadCharsPerRun: defaults.maxOffloadCharsPerRun,
543
+ };
544
+ }
545
+ if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
546
+ _warnInvalidStaleToolResultOffload(raw);
547
+ return {
548
+ enabled: defaults.enabled,
549
+ minChars: defaults.minChars,
550
+ stalenessTurns: defaults.stalenessTurns,
551
+ keepRecentTurns: defaults.keepRecentTurns,
552
+ maxOffloadCharsPerRun: defaults.maxOffloadCharsPerRun,
553
+ };
554
+ }
555
+ const r = raw as StaleToolResultOffloadSettings;
556
+ const d: ResolvedStaleToolResultOffloadConfig = STALE_TOOL_RESULT_OFFLOAD_DEFAULTS;
557
+ let invalid = false;
558
+ let enabled = d.enabled;
559
+ if (typeof r.enabled === "boolean") {
560
+ enabled = r.enabled;
561
+ } else if (r.enabled !== undefined) {
562
+ invalid = true;
563
+ }
564
+ let minChars = d.minChars;
565
+ if (typeof r.minChars === "number" && Number.isFinite(r.minChars) && r.minChars >= 0) {
566
+ minChars = r.minChars;
567
+ } else if (r.minChars !== undefined) {
568
+ invalid = true;
569
+ }
570
+ let stalenessTurns = d.stalenessTurns;
571
+ if (
572
+ typeof r.stalenessTurns === "number" &&
573
+ Number.isInteger(r.stalenessTurns) &&
574
+ r.stalenessTurns >= 1
575
+ ) {
576
+ stalenessTurns = r.stalenessTurns;
577
+ } else if (r.stalenessTurns !== undefined) {
578
+ invalid = true;
579
+ }
580
+ let keepRecentTurns = d.keepRecentTurns;
581
+ if (
582
+ typeof r.keepRecentTurns === "number" &&
583
+ Number.isInteger(r.keepRecentTurns) &&
584
+ r.keepRecentTurns >= 0
585
+ ) {
586
+ keepRecentTurns = r.keepRecentTurns;
587
+ } else if (r.keepRecentTurns !== undefined) {
588
+ invalid = true;
589
+ }
590
+ let maxOffloadCharsPerRun = d.maxOffloadCharsPerRun;
591
+ if (
592
+ typeof r.maxOffloadCharsPerRun === "number" &&
593
+ Number.isFinite(r.maxOffloadCharsPerRun) &&
594
+ r.maxOffloadCharsPerRun >= 1
595
+ ) {
596
+ maxOffloadCharsPerRun = r.maxOffloadCharsPerRun;
597
+ } else if (r.maxOffloadCharsPerRun !== undefined) {
598
+ invalid = true;
599
+ }
600
+ if (invalid) _warnInvalidStaleToolResultOffload(raw);
601
+ return { enabled, minChars, stalenessTurns, keepRecentTurns, maxOffloadCharsPerRun };
602
+ }
603
+
604
+ /**
605
+ * Read the effective staleToolResultOffload config from settings.json, fresh
606
+ * on every call (no caching), like the other readers. Default: all defaults
607
+ * with enabled=false (the offloader is a no-op unless the owner opts in).
608
+ */
609
+ export function getStaleToolResultOffloadConfig(): ResolvedStaleToolResultOffloadConfig {
610
+ return resolveStaleToolResultOffloadConfig(readSettings().braid?.context?.staleToolResultOffload);
611
+ }
612
+
613
+ // ── emergency context-window offload (braid.context.contextEmergencyOffload) ──
614
+
615
+ /**
616
+ * Defaults for the P0-A emergency offloader. The size floor matches the P0-B
617
+ * capture cap (256KB): below that, a 413 is not caused by this class of blob.
618
+ * Per-run budget of 1MB chars covers several oversized results in one pass.
619
+ * keepRecentTurns=1: the immediately-latest toolResult stays visible so the
620
+ * agent keeps the freshest decision evidence; everything older is fair game
621
+ * in an emergency (sendability outranks recency, and the flush is lossless).
622
+ */
623
+ export const CONTEXT_EMERGENCY_OFFLOAD_DEFAULTS = {
624
+ enabled: true,
625
+ minChars: 262_144,
626
+ maxCharsPerRun: 1_048_576,
627
+ keepRecentTurns: 1,
628
+ } as const;
629
+
630
+ /** The validated, effective contextEmergencyOffload config. */
631
+ export interface ResolvedContextEmergencyOffloadConfig {
632
+ enabled: boolean;
633
+ minChars: number;
634
+ maxCharsPerRun: number;
635
+ keepRecentTurns: number;
636
+ }
637
+
638
+ /** Warned once per process about an invalid braid.context.contextEmergencyOffload. */
639
+ let _warnedInvalidContextEmergencyOffload = false;
640
+
641
+ function _warnInvalidContextEmergencyOffload(value: unknown): void {
642
+ if (_warnedInvalidContextEmergencyOffload) return;
643
+ _warnedInvalidContextEmergencyOffload = true;
644
+ _log.warn(
645
+ "Invalid braid.context.contextEmergencyOffload in settings.json - ignoring " +
646
+ "invalid fields and using defaults (emergency offload stays ON unless " +
647
+ "enabled is explicitly false).",
648
+ { value },
649
+ );
650
+ }
651
+
652
+ /**
653
+ * Pure resolver for the braid.context.contextEmergencyOffload block.
654
+ * Absent → all defaults (enabled: true — the 413 fix must be active by
655
+ * default). Non-object shape, or any field violating its type/range, falls
656
+ * back to that field's default; the FIRST invalid input also emits a
657
+ * once-per-process warning (mirrors the log-once pattern). Kept pure so
658
+ * the default merge is unit-testable without touching live settings.json.
659
+ */
660
+ export function resolveContextEmergencyOffloadConfig(
661
+ raw: unknown,
662
+ ): ResolvedContextEmergencyOffloadConfig {
663
+ const defaults: ResolvedContextEmergencyOffloadConfig = CONTEXT_EMERGENCY_OFFLOAD_DEFAULTS;
664
+ if (raw === undefined) {
665
+ return { ...defaults };
666
+ }
667
+ if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
668
+ _warnInvalidContextEmergencyOffload(raw);
669
+ return { ...defaults };
670
+ }
671
+ const r = raw as ContextEmergencyOffloadSettings;
672
+ const d: ResolvedContextEmergencyOffloadConfig = CONTEXT_EMERGENCY_OFFLOAD_DEFAULTS;
673
+ let invalid = false;
674
+ let enabled = d.enabled;
675
+ if (typeof r.enabled === "boolean") {
676
+ enabled = r.enabled;
677
+ } else if (r.enabled !== undefined) {
678
+ invalid = true;
679
+ }
680
+ let minChars = d.minChars;
681
+ if (typeof r.minChars === "number" && Number.isFinite(r.minChars) && r.minChars >= 1) {
682
+ minChars = r.minChars;
683
+ } else if (r.minChars !== undefined) {
684
+ invalid = true;
685
+ }
686
+ let maxCharsPerRun = d.maxCharsPerRun;
687
+ if (
688
+ typeof r.maxCharsPerRun === "number" &&
689
+ Number.isFinite(r.maxCharsPerRun) &&
690
+ r.maxCharsPerRun >= minChars
691
+ ) {
692
+ maxCharsPerRun = r.maxCharsPerRun;
693
+ } else if (r.maxCharsPerRun !== undefined) {
694
+ invalid = true;
695
+ }
696
+ let keepRecentTurns = d.keepRecentTurns;
697
+ if (
698
+ typeof r.keepRecentTurns === "number" &&
699
+ Number.isInteger(r.keepRecentTurns) &&
700
+ r.keepRecentTurns >= 0
701
+ ) {
702
+ keepRecentTurns = r.keepRecentTurns;
703
+ } else if (r.keepRecentTurns !== undefined) {
704
+ invalid = true;
705
+ }
706
+ if (invalid) _warnInvalidContextEmergencyOffload(raw);
707
+ return { enabled, minChars, maxCharsPerRun, keepRecentTurns };
708
+ }
709
+
710
+ /**
711
+ * Read the effective contextEmergencyOffload config from settings.json, fresh
712
+ * on every call (no caching), like the other readers. Default: enabled=true.
713
+ */
714
+ export function getContextEmergencyOffloadConfig(): ResolvedContextEmergencyOffloadConfig {
715
+ return resolveContextEmergencyOffloadConfig(
716
+ readSettings().braid?.context?.contextEmergencyOffload,
717
+ );
718
+ }
719
+
720
+ // ── capture-time toolResult size cap (braid.context.toolResultSizeCap) ─
721
+
722
+ /**
723
+ * Defaults for the P0-B capture cap: 256KB (chars) — a blob over this is a
724
+ * screenshot/base64-class payload that never belongs in context. Default ON:
725
+ * capture-time substitution is lossless (full content flushed to disk first)
726
+ * and strictly cheaper than the 413 loops it prevents.
727
+ */
728
+ export const TOOL_RESULT_SIZE_CAP_DEFAULTS = {
729
+ enabled: true,
730
+ maxChars: 262_144,
731
+ } as const;
732
+
733
+ /** The validated, effective toolResultSizeCap config. */
734
+ export interface ResolvedToolResultSizeCapConfig {
735
+ enabled: boolean;
736
+ maxChars: number;
737
+ }
738
+
739
+ /** Warned once per process about an invalid braid.context.toolResultSizeCap. */
740
+ let _warnedInvalidToolResultSizeCap = false;
741
+
742
+ function _warnInvalidToolResultSizeCap(value: unknown): void {
743
+ if (_warnedInvalidToolResultSizeCap) return;
744
+ _warnedInvalidToolResultSizeCap = true;
745
+ _log.warn(
746
+ "Invalid braid.context.toolResultSizeCap in settings.json - ignoring " +
747
+ "invalid fields and using defaults (capture cap stays ON unless " +
748
+ "enabled is explicitly false).",
749
+ { value },
750
+ );
751
+ }
752
+
753
+ /**
754
+ * Pure resolver for the braid.context.toolResultSizeCap block.
755
+ * Absent → all defaults (enabled: true). Non-object shape, or any field
756
+ * violating its type/range, falls back to that field's default with a
757
+ * once-per-process warning. Kept pure for unit-testability.
758
+ */
759
+ export function resolveToolResultSizeCapConfig(raw: unknown): ResolvedToolResultSizeCapConfig {
760
+ const defaults: ResolvedToolResultSizeCapConfig = TOOL_RESULT_SIZE_CAP_DEFAULTS;
761
+ if (raw === undefined) {
762
+ return { ...defaults };
763
+ }
764
+ if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
765
+ _warnInvalidToolResultSizeCap(raw);
766
+ return { ...defaults };
767
+ }
768
+ const r = raw as ToolResultSizeCapSettings;
769
+ const d: ResolvedToolResultSizeCapConfig = TOOL_RESULT_SIZE_CAP_DEFAULTS;
770
+ let invalid = false;
771
+ let enabled = d.enabled;
772
+ if (typeof r.enabled === "boolean") {
773
+ enabled = r.enabled;
774
+ } else if (r.enabled !== undefined) {
775
+ invalid = true;
776
+ }
777
+ let maxChars = d.maxChars;
778
+ if (typeof r.maxChars === "number" && Number.isFinite(r.maxChars) && r.maxChars >= 1) {
779
+ maxChars = r.maxChars;
780
+ } else if (r.maxChars !== undefined) {
781
+ invalid = true;
782
+ }
783
+ if (invalid) _warnInvalidToolResultSizeCap(raw);
784
+ return { enabled, maxChars };
785
+ }
786
+
787
+ /**
788
+ * Read the effective toolResultSizeCap config from settings.json, fresh on
789
+ * every call (no caching), like the other readers. Default: enabled=true.
790
+ */
791
+ export function getToolResultSizeCapConfig(): ResolvedToolResultSizeCapConfig {
792
+ return resolveToolResultSizeCapConfig(readSettings().braid?.context?.toolResultSizeCap);
793
+ }
794
+
795
+ // ── usage-driven auto-arm of a slide compaction (braid.context.contextAutoCompact) ─
796
+
797
+ /**
798
+ * Defaults for the usage-driven auto-arm. Default ON: an armed cleanup that
799
+ * never lands while a run stays alive is the failure mode this exists to
800
+ * close, and the armed action is the deterministic slide (no LLM call, cut
801
+ * bounded by the keep window). confirmTicks=2 makes "crosses and STAYS there"
802
+ * the arming condition — a transient spike never arms.
803
+ */
804
+ export const AUTO_COMPACT_DEFAULTS = {
805
+ enabled: true,
806
+ armPercent: 60,
807
+ confirmTicks: 2,
808
+ } as const;
809
+
810
+ /** The validated, effective contextAutoCompact config. */
811
+ export interface ResolvedAutoCompactConfig {
812
+ enabled: boolean;
813
+ armPercent: number;
814
+ confirmTicks: number;
815
+ }
816
+
817
+ /** Warned once per process about an invalid braid.context.contextAutoCompact. */
818
+ let _warnedInvalidAutoCompact = false;
819
+
820
+ function _warnInvalidAutoCompact(value: unknown): void {
821
+ if (_warnedInvalidAutoCompact) return;
822
+ _warnedInvalidAutoCompact = true;
823
+ _log.warn(
824
+ "Invalid braid.context.contextAutoCompact in settings.json - ignoring " +
825
+ "invalid fields and using defaults (auto-arm stays ON unless " +
826
+ "enabled is explicitly false).",
827
+ { value },
828
+ );
829
+ }
830
+
831
+ /**
832
+ * Pure resolver for the braid.context.contextAutoCompact block.
833
+ * Absent → all defaults. Non-object shape, or any field violating its
834
+ * type/range (armPercent must be 1..100, confirmTicks an integer >= 1), falls
835
+ * back to that field's default with a once-per-process warning. Kept pure for
836
+ * unit-testability.
837
+ */
838
+ export function resolveAutoCompactConfig(raw: unknown): ResolvedAutoCompactConfig {
839
+ const d: ResolvedAutoCompactConfig = AUTO_COMPACT_DEFAULTS;
840
+ if (raw === undefined) {
841
+ return { ...d };
842
+ }
843
+ if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
844
+ _warnInvalidAutoCompact(raw);
845
+ return { ...d };
846
+ }
847
+ const r = raw as AutoCompactSettings;
848
+ let invalid = false;
849
+ let enabled = d.enabled;
850
+ if (typeof r.enabled === "boolean") {
851
+ enabled = r.enabled;
852
+ } else if (r.enabled !== undefined) {
853
+ invalid = true;
854
+ }
855
+ let armPercent = d.armPercent;
856
+ if (
857
+ typeof r.armPercent === "number" &&
858
+ Number.isFinite(r.armPercent) &&
859
+ r.armPercent >= 1 &&
860
+ r.armPercent <= 100
861
+ ) {
862
+ armPercent = r.armPercent;
863
+ } else if (r.armPercent !== undefined) {
864
+ invalid = true;
865
+ }
866
+ let confirmTicks = d.confirmTicks;
867
+ if (
868
+ typeof r.confirmTicks === "number" &&
869
+ Number.isInteger(r.confirmTicks) &&
870
+ r.confirmTicks >= 1
871
+ ) {
872
+ confirmTicks = r.confirmTicks;
873
+ } else if (r.confirmTicks !== undefined) {
874
+ invalid = true;
875
+ }
876
+ if (invalid) _warnInvalidAutoCompact(raw);
877
+ return { enabled, armPercent, confirmTicks };
878
+ }
879
+
880
+ /**
881
+ * Read the effective contextAutoCompact config from settings.json, fresh on
882
+ * every call (no caching), like the other readers. Default: enabled=true.
883
+ */
884
+ export function getAutoCompactConfig(): ResolvedAutoCompactConfig {
885
+ return resolveAutoCompactConfig(readSettings().braid?.context?.contextAutoCompact);
886
+ }
887
+
888
+ // ── wake-retry redelivery cap (braid.timers.maxWakeAttempts) ─────────
889
+
890
+ /** Default redelivery bound for a failed wake fire. */
891
+ export const MAX_WAKE_ATTEMPTS_DEFAULT = 3;
892
+
893
+ /** Upper bound for the braid.timers.maxWakeAttempts setting. */
894
+ export const MAX_WAKE_ATTEMPTS_MAX = 10;
895
+
896
+ /** Warned once per process about an invalid braid.timers.maxWakeAttempts. */
897
+ let _warnedInvalidMaxWakeAttempts = false;
898
+
899
+ function _warnInvalidMaxWakeAttempts(value: unknown): void {
900
+ if (_warnedInvalidMaxWakeAttempts) return;
901
+ _warnedInvalidMaxWakeAttempts = true;
902
+ _log.warn(
903
+ "Invalid braid.timers.maxWakeAttempts in settings.json - ignoring and " +
904
+ `using the default (${MAX_WAKE_ATTEMPTS_DEFAULT}). Expected an integer 1..${MAX_WAKE_ATTEMPTS_MAX}.`,
905
+ { value },
906
+ );
907
+ }
908
+
909
+ /**
910
+ * Pure resolver for braid.timers.maxWakeAttempts. Absent →
911
+ * MAX_WAKE_ATTEMPTS_DEFAULT; an integer 1..MAX_WAKE_ATTEMPTS_MAX passes
912
+ * through; anything else warns once and falls back to the default. Kept pure
913
+ * so the validation is unit-testable without touching live settings.json.
914
+ */
915
+ export function resolveMaxWakeAttempts(raw: unknown): number {
916
+ if (raw === undefined) return MAX_WAKE_ATTEMPTS_DEFAULT;
917
+ if (
918
+ typeof raw === "number" &&
919
+ Number.isInteger(raw) &&
920
+ raw >= 1 &&
921
+ raw <= MAX_WAKE_ATTEMPTS_MAX
922
+ ) {
923
+ return raw;
924
+ }
925
+ _warnInvalidMaxWakeAttempts(raw);
926
+ return MAX_WAKE_ATTEMPTS_DEFAULT;
927
+ }
928
+
929
+ /**
930
+ * Read the effective wake-retry redelivery cap from settings.json, fresh on
931
+ * every call (no caching), like the other readers. Default:
932
+ * MAX_WAKE_ATTEMPTS_DEFAULT (3).
933
+ */
934
+ export function getMaxWakeAttempts(): number {
935
+ return resolveMaxWakeAttempts(readSettings().braid?.timers?.maxWakeAttempts);
936
+ }
937
+
938
+ // ── terminal-error wake breaker (braid.session.terminalBreaker) ──────────
939
+
940
+ /** Default terminal-error count before timer wakes stop starting turns. */
941
+ export const TERMINAL_BREAKER_DEFAULT_THRESHOLD = 3;
942
+ /** Upper bound for a configured threshold (guards a typo'd huge value). */
943
+ export const TERMINAL_BREAKER_THRESHOLD_MAX = 20;
944
+
945
+ export interface TerminalBreakerConfig {
946
+ /** Master gate. Default true. */
947
+ enabled: boolean;
948
+ /** Terminal-class errors before wakes stop waking. Default 3. */
949
+ threshold: number;
950
+ }
951
+
952
+ /** Warned once per process about an invalid terminalBreaker.threshold. */
953
+ let _warnedInvalidTerminalBreakerThreshold = false;
954
+
955
+ /**
956
+ * Pure resolver for braid.session.terminalBreaker. Absent block ⇒ default-on
957
+ * with threshold 3. `enabled: false` ⇒ the gate is off. A threshold that is
958
+ * not an integer 1..TERMINAL_BREAKER_THRESHOLD_MAX warns once and falls back
959
+ * to the default. Kept pure so the validation is unit-testable without
960
+ * touching live settings.json.
961
+ */
962
+ export function resolveTerminalBreaker(raw: unknown): TerminalBreakerConfig {
963
+ if (raw === undefined || raw === null || typeof raw !== "object") {
964
+ return { enabled: true, threshold: TERMINAL_BREAKER_DEFAULT_THRESHOLD };
965
+ }
966
+ const block = raw as { enabled?: unknown; threshold?: unknown };
967
+ const enabled = block.enabled !== false;
968
+ const threshold = block.threshold;
969
+ if (threshold === undefined) {
970
+ return { enabled, threshold: TERMINAL_BREAKER_DEFAULT_THRESHOLD };
971
+ }
972
+ if (
973
+ typeof threshold === "number" &&
974
+ Number.isInteger(threshold) &&
975
+ threshold >= 1 &&
976
+ threshold <= TERMINAL_BREAKER_THRESHOLD_MAX
977
+ ) {
978
+ return { enabled, threshold };
979
+ }
980
+ if (!_warnedInvalidTerminalBreakerThreshold) {
981
+ _warnedInvalidTerminalBreakerThreshold = true;
982
+ _log.warn(
983
+ "Invalid braid.session.terminalBreaker.threshold in settings.json - ignoring and " +
984
+ `using the default (${TERMINAL_BREAKER_DEFAULT_THRESHOLD}). Expected an integer 1..${TERMINAL_BREAKER_THRESHOLD_MAX}.`,
985
+ { value: threshold },
986
+ );
987
+ }
988
+ return { enabled, threshold: TERMINAL_BREAKER_DEFAULT_THRESHOLD };
989
+ }
990
+
991
+ /**
992
+ * Read the effective terminal-error wake-breaker config from settings.json,
993
+ * fresh on every call (no caching), like the other readers. The wake path
994
+ * reads this once per fire.
995
+ */
996
+ export function getTerminalBreakerConfig(): TerminalBreakerConfig {
997
+ return resolveTerminalBreaker(readSettings().braid?.session?.terminalBreaker);
998
+ }
999
+
1000
+ // ── wake-delivery stall alert (braid.timers.wakeAlert) ───────────────
1001
+
1002
+ /** Default wake-delivery alerting: on, page after 2 outcome timeouts. */
1003
+ export const WAKE_DELIVERY_ALERT_DEFAULT: WakeDeliveryAlertConfig = {
1004
+ mode: "on",
1005
+ outcomeTimeouts: 2,
1006
+ };
1007
+
1008
+ /** Upper bound for the outcome-timeout page threshold. */
1009
+ export const WAKE_ALERT_OUTCOME_TIMEOUTS_MAX = 10;
1010
+
1011
+ export interface WakeDeliveryAlertConfig {
1012
+ /** "off" disables the timer→watchdog feed entirely. */
1013
+ mode: "on" | "off";
1014
+ /** Outcome timeouts for ONE fire before the early stall page. */
1015
+ outcomeTimeouts: number;
1016
+ }
1017
+
1018
+ /** Warned once per process about an invalid braid.timers.wakeAlert. */
1019
+ let _warnedInvalidWakeAlert = false;
1020
+
1021
+ function _warnInvalidWakeAlert(value: unknown): void {
1022
+ if (_warnedInvalidWakeAlert) return;
1023
+ _warnedInvalidWakeAlert = true;
1024
+ _log.warn(
1025
+ "Invalid braid.timers.wakeAlert in settings.json - ignoring it and using " +
1026
+ `the defaults (mode ${WAKE_DELIVERY_ALERT_DEFAULT.mode}, outcomeTimeouts ` +
1027
+ `${WAKE_DELIVERY_ALERT_DEFAULT.outcomeTimeouts}). Expected { mode: "on" | "off", ` +
1028
+ `outcomeTimeouts: integer 2..${WAKE_ALERT_OUTCOME_TIMEOUTS_MAX} }.`,
1029
+ { value },
1030
+ );
1031
+ }
1032
+
1033
+ /**
1034
+ * Pure resolver for braid.timers.wakeAlert. Absent → defaults; mode
1035
+ * "on"/"off" passes through; outcomeTimeouts must be an integer 2..MAX (1
1036
+ * would page on every normal long turn — the flood the 240s outcome window
1037
+ * exists to prevent). An invalid present value warns once and falls back to
1038
+ * the default for that field. Kept pure so the validation is unit-testable
1039
+ * without touching live settings.json.
1040
+ */
1041
+ export function resolveWakeDeliveryAlertConfig(raw: unknown): WakeDeliveryAlertConfig {
1042
+ const cfg: WakeDeliveryAlertConfig = { ...WAKE_DELIVERY_ALERT_DEFAULT };
1043
+ if (raw === undefined) return cfg;
1044
+ if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
1045
+ _warnInvalidWakeAlert(raw);
1046
+ return cfg;
1047
+ }
1048
+ const r = raw as Record<string, unknown>;
1049
+ if (r.mode === "on" || r.mode === "off") cfg.mode = r.mode;
1050
+ else if (r.mode !== undefined) _warnInvalidWakeAlert(raw);
1051
+ const t = r.outcomeTimeouts;
1052
+ if (
1053
+ typeof t === "number" &&
1054
+ Number.isInteger(t) &&
1055
+ t >= 2 &&
1056
+ t <= WAKE_ALERT_OUTCOME_TIMEOUTS_MAX
1057
+ ) {
1058
+ cfg.outcomeTimeouts = t;
1059
+ } else if (t !== undefined) {
1060
+ _warnInvalidWakeAlert(raw);
1061
+ }
1062
+ return cfg;
1063
+ }
1064
+
1065
+ /**
1066
+ * Read the effective wake-delivery alert config from settings.json, fresh on
1067
+ * every call (no caching), like the other readers. Default: mode "on",
1068
+ * outcomeTimeouts 2.
1069
+ */
1070
+ export function getWakeDeliveryAlertConfig(): WakeDeliveryAlertConfig {
1071
+ return resolveWakeDeliveryAlertConfig(readSettings().braid?.timers?.wakeAlert);
1072
+ }
1073
+
1074
+ // ── pi-core auto-retry budget (top-level `retry` key) ─────────────────
1075
+
1076
+ /** Upper bound for the wake-retry hold window (a hold must stay bounded). */
1077
+ export const WAKE_RETRY_HOLD_MAX_MS = 300_000;
1078
+
1079
+ /**
1080
+ * Pure resolver for the wake-retry hold window: pi-core auto-retries a
1081
+ * retryable provider failure inside the SAME run with backoff
1082
+ * `baseDelayMs * 2^attempt` up to maxRetries (settings-manager
1083
+ * .getRetrySettings defaults: 2000ms, 3 retries). The hold window mirrors
1084
+ * that budget: baseDelayMs * 2^maxRetries (16s with pi-core defaults),
1085
+ * clamped to [0, WAKE_RETRY_HOLD_MAX_MS]. Kept pure for unit-testability.
1086
+ */
1087
+ export function resolveWakeRetryHoldMs(raw?: {
1088
+ maxRetries?: number;
1089
+ baseDelayMs?: number;
1090
+ }): number {
1091
+ const maxRetries =
1092
+ typeof raw?.maxRetries === "number" && Number.isFinite(raw.maxRetries) && raw.maxRetries >= 0
1093
+ ? Math.floor(raw.maxRetries)
1094
+ : 3;
1095
+ const baseDelayMs =
1096
+ typeof raw?.baseDelayMs === "number" && Number.isFinite(raw.baseDelayMs) && raw.baseDelayMs >= 0
1097
+ ? raw.baseDelayMs
1098
+ : 2000;
1099
+ const budget = baseDelayMs * 2 ** Math.min(maxRetries, 16);
1100
+ return Math.min(Math.max(Math.floor(budget), 0), WAKE_RETRY_HOLD_MAX_MS);
1101
+ }
1102
+
1103
+ /**
1104
+ * The effective wake-retry hold window, read fresh on every call (no
1105
+ * caching): pi-core's `retry` budget from settings.json, clamped.
1106
+ */
1107
+ export function getWakeRetryHoldMs(): number {
1108
+ return resolveWakeRetryHoldMs(readSettings().retry);
1109
+ }
1110
+
1111
+ // ── effective context window (contextLimitTokens) ──────────────────────
1112
+
1113
+ /** Warned once per process about an invalid braid.context.contextLimitTokens. */
1114
+ let _warnedInvalidContextLimitTokens = false;
1115
+
1116
+ /**
1117
+ * Pure resolver for the effective context window. Precedence:
1118
+ *
1119
+ * 1. `contextLimitTokens` when it is a positive finite number - a
1120
+ * CEILING, not a blind rewrite: min(cap, provider window) when the
1121
+ * provider window is known positive, the cap alone otherwise.
1122
+ * 2. `providerContextWindow` (model/provider truth) when positive finite.
1123
+ * 3. undefined — caller applies its own terminal default.
1124
+ *
1125
+ * The cap can never widen a model past its catalog size: a manual pick
1126
+ * whose true window is below the cap keeps that true window. Unset
1127
+ * (`undefined`) silently falls through to provider truth; any other
1128
+ * non-conforming value (0, negative, non-number, non-finite) is ignored with
1129
+ * a once-per-process warning and also falls through. Kept pure so the
1130
+ * precedence merge is unit-testable without touching live settings.json.
1131
+ */
1132
+ export function resolveContextLimitTokens(
1133
+ raw: unknown,
1134
+ providerContextWindow?: number | null,
1135
+ ): number | undefined {
1136
+ const provider =
1137
+ typeof providerContextWindow === "number" &&
1138
+ Number.isFinite(providerContextWindow) &&
1139
+ providerContextWindow > 0
1140
+ ? providerContextWindow
1141
+ : undefined;
1142
+ if (typeof raw === "number" && Number.isFinite(raw) && raw > 0) {
1143
+ return provider !== undefined ? Math.min(raw, provider) : raw;
1144
+ }
1145
+ if (raw !== undefined && !_warnedInvalidContextLimitTokens) {
1146
+ _warnedInvalidContextLimitTokens = true;
1147
+ _log.warn(
1148
+ "Invalid braid.context.contextLimitTokens in settings.json - ignoring " +
1149
+ "and using the provider context window instead.",
1150
+ { value: raw },
1151
+ );
1152
+ }
1153
+ return provider;
1154
+ }
1155
+
1156
+ /**
1157
+ * The effective context window braid uses for its computations, resolved
1158
+ * through the ONE resolver: braid.context.contextLimitTokens override,
1159
+ * else the provider/model context window. Returns undefined when neither is
1160
+ * known - callers apply their own terminal default (e.g. 200000, 100_000).
1161
+ * Reads settings fresh on every call (no caching), like the other readers.
1162
+ */
1163
+ export function getResolvedContextWindow(
1164
+ providerContextWindow?: number | null,
1165
+ ): number | undefined {
1166
+ return resolveContextLimitTokens(
1167
+ readSettings().braid?.context?.contextLimitTokens,
1168
+ providerContextWindow,
1169
+ );
1170
+ }
1171
+
1172
+ /**
1173
+ * The RAW configured window override (braid.context.contextLimitTokens),
1174
+ * undefined when unset. Separated from getResolvedContextWindow so callers
1175
+ * that must label the window source (configured vs provider) can read the
1176
+ * override directly instead of reverse-engineering it from the merged value.
1177
+ */
1178
+ export function getConfiguredContextLimitTokens(): number | undefined {
1179
+ const raw = readSettings().braid?.context?.contextLimitTokens;
1180
+ return typeof raw === "number" && Number.isFinite(raw) && raw > 0 ? raw : undefined;
1181
+ }
1182
+
1183
+ // ── plumb the configured window into pi-core (the executed invariant) ──
1184
+
1185
+ /** Warned once per process when the configured window could not be applied. */
1186
+ let _warnedUnapplyableContextWindow = false;
1187
+
1188
+ export interface ConfiguredWindowApplyResult {
1189
+ /** true = the session model now reports the configured window. */
1190
+ applied: boolean;
1191
+ /** The window pi-core reports for the session model after the call. */
1192
+ contextWindow?: number;
1193
+ /** Why nothing changed: unset | no-model | unchanged | frozen. */
1194
+ reason?: "unset" | "no-model" | "unchanged" | "frozen";
1195
+ }
1196
+
1197
+ /**
1198
+ * Make the session model report the configured window so pi-core's OWN
1199
+ * compaction decisions use it. pi-core reads `model.contextWindow` at every
1200
+ * window-dependent decision point (threshold compaction in
1201
+ * `_compactBeforeNextAssistantResponse` / `_checkCompaction` via
1202
+ * `shouldCompact`, overflow detection, usage percent); it never sees braid's
1203
+ * setting today, so when `contextLimitTokens < provider window` no automatic
1204
+ * actor can fire and the configured cap is enforced by nobody.
1205
+ *
1206
+ * This is the write side of the ONE resolver: same setting, same validation
1207
+ * (`getConfiguredContextLimitTokens`), same ceiling merge. The value written
1208
+ * is the resolver's effective window, so the setting can never widen a model
1209
+ * past its true window (configured 1M over a 202752 model leaves 202752 in
1210
+ * place); only an unknown true window takes the cap alone. When the setting
1211
+ * is unset or invalid this is a no-op and pi-core keeps provider-window
1212
+ * semantics. The model object is the live `agent.state.model` instance
1213
+ * pi-core hands to the extension context, so patching it in place steers
1214
+ * every downstream reader; a frozen object (models.json-derived catalogs)
1215
+ * degrades to a once-per-process warning and provider semantics rather than
1216
+ * throwing mid-run.
1217
+ *
1218
+ * Idempotent: callers may re-apply on every run start (also re-arms after a
1219
+ * model switch, since the newly selected model carries the provider window).
1220
+ */
1221
+ export function applyConfiguredContextWindow(ctx: unknown): ConfiguredWindowApplyResult {
1222
+ const configured = getConfiguredContextLimitTokens();
1223
+ if (configured === undefined) return { applied: false, reason: "unset" };
1224
+ const model = (ctx as { model?: { contextWindow?: number } } | undefined)?.model;
1225
+ if (!model || typeof model !== "object") return { applied: false, reason: "no-model" };
1226
+ const target = resolveContextLimitTokens(configured, model.contextWindow) ?? configured;
1227
+ if (model.contextWindow === target) {
1228
+ return { applied: false, reason: "unchanged", contextWindow: target };
1229
+ }
1230
+ try {
1231
+ model.contextWindow = target;
1232
+ return { applied: true, contextWindow: target };
1233
+ } catch {
1234
+ if (!_warnedUnapplyableContextWindow) {
1235
+ _warnedUnapplyableContextWindow = true;
1236
+ _log.warn(
1237
+ "Could not apply braid.context.contextLimitTokens to the session model " +
1238
+ "(read-only model object): native threshold compaction keeps using the " +
1239
+ "provider window for this model.",
1240
+ );
1241
+ }
1242
+ return { applied: false, reason: "frozen", contextWindow: model.contextWindow };
1243
+ }
1244
+ }
1245
+
1246
+ // ── compaction reserve coherence with the configured window ────────────
1247
+
1248
+ /**
1249
+ * Floor for the derived reserve: pi-core's own shipped default
1250
+ * (DEFAULT_COMPACTION_SETTINGS.reserveTokens). The reserve doubles as the
1251
+ * budget for the post-compaction summary request (pi-core caps it at 80% of
1252
+ * the reserve), so a thinner one starts failing the compaction it exists to
1253
+ * fund; the derivation never goes below it.
1254
+ */
1255
+ export const MIN_COMPACTION_RESERVE_TOKENS = 16384;
1256
+
1257
+ /** Derived reserve for one window, with the trigger it produces. */
1258
+ export interface CompactionReserveDerivation {
1259
+ /** Window − trigger, floored at MIN_COMPACTION_RESERVE_TOKENS. */
1260
+ reserveTokens: number;
1261
+ /** contextTokens above which pi-core's shouldCompact() fires. */
1262
+ triggerTokens: number;
1263
+ /** triggerTokens as a percent of the window (the coherence target). */
1264
+ triggerPercent: number;
1265
+ }
1266
+
1267
+ /**
1268
+ * Pure resolver for the compaction reserve that puts native threshold
1269
+ * compaction at USAGE_WHISPER_CRITICAL of the window: reserve = window −
1270
+ * trigger, i.e. the same 75/25 split the usage bands already treat as
1271
+ * coherent (compaction at USAGE_WHISPER_CRITICAL, before the archiving band
1272
+ * opens at USAGE_COMPACT_MEDIUM). pi-core's shouldCompact() compares raw
1273
+ * token counts (contextTokens > contextWindow − reserveTokens), never
1274
+ * percents, so a reserve that is not a fixed share of the plumbed window
1275
+ * silently re-anchors the trigger — that is the incoherence this derives
1276
+ * away.
1277
+ *
1278
+ * Returns undefined when no reserve can be derived: a non-number, non-finite
1279
+ * or non-positive window, or a window so small that even the floor reserve
1280
+ * (MIN_COMPACTION_RESERVE_TOKENS) leaves no room to compact into. Kept pure
1281
+ * so the split is unit-testable without touching live settings.json.
1282
+ */
1283
+ export function resolveCompactionReserveTokens(
1284
+ window: number | null | undefined,
1285
+ ): CompactionReserveDerivation | undefined {
1286
+ if (typeof window !== "number" || !Number.isFinite(window) || window <= 0) {
1287
+ return undefined;
1288
+ }
1289
+ const target = Math.round((window * USAGE_WHISPER_CRITICAL) / 100);
1290
+ const reserveTokens = Math.max(window - target, MIN_COMPACTION_RESERVE_TOKENS);
1291
+ if (reserveTokens >= window) return undefined;
1292
+ const triggerTokens = window - reserveTokens;
1293
+ return {
1294
+ reserveTokens,
1295
+ triggerTokens,
1296
+ triggerPercent: (triggerTokens / window) * 100,
1297
+ };
1298
+ }
1299
+
1300
+ /**
1301
+ * The reserve pi-core would actually use for this model: the per-model
1302
+ * `compaction.modelOverrides[provider/id].reserveTokens` first, then
1303
+ * `compaction.reserveTokens`, else undefined (pi-core's own default, i.e.
1304
+ * MIN_COMPACTION_RESERVE_TOKENS). Reads settings fresh, like the other
1305
+ * readers.
1306
+ */
1307
+ export function getConfiguredCompactionReserveTokens(
1308
+ provider?: string | null,
1309
+ modelId?: string | null,
1310
+ ): number | undefined {
1311
+ const compaction = readSettings().compaction;
1312
+ if (!compaction || typeof compaction !== "object") return undefined;
1313
+ const key = provider && modelId ? `${provider}/${modelId}` : undefined;
1314
+ const override = key !== undefined ? compaction.modelOverrides?.[key]?.reserveTokens : undefined;
1315
+ const candidate = typeof override === "number" ? override : compaction.reserveTokens;
1316
+ return typeof candidate === "number" && Number.isFinite(candidate) && candidate > 0
1317
+ ? candidate
1318
+ : undefined;
1319
+ }
1320
+
1321
+ /** Warned once per process about each compaction-reserve coherence class. */
1322
+ let _warnedUnderivableCompactionReserve = false;
1323
+ let _warnedIncoherentCompactionReserve = false;
1324
+ let _warnedUnreachableCompactionReserve = false;
1325
+
1326
+ export interface CompactionReserveApplyResult {
1327
+ /** Derived reserve (window − trigger); absent when no derivation exists. */
1328
+ reserveTokens?: number;
1329
+ /** Token count at which native threshold compaction fires under the derivation. */
1330
+ triggerTokens?: number;
1331
+ /** triggerTokens as a percent of the window (target: USAGE_WHISPER_CRITICAL). */
1332
+ triggerPercent?: number;
1333
+ /** Why nothing was applied. */
1334
+ reason?: "unset" | "no-derivation" | "window-not-plumbed" | "unreachable" | "unchanged";
1335
+ }
1336
+
1337
+ /**
1338
+ * Derive the compaction reserve that makes pi-core's native threshold
1339
+ * compaction fire at the SAME share of the window braid's usage bands assume.
1340
+ * applyConfiguredContextWindow() gives pi-core the braid window; this pairs
1341
+ * with it, because pi-core then decides WHEN to compact from its own
1342
+ * independent `compaction.reserveTokens` (a fixed token count, default
1343
+ * 16384) - untouched, that count re-anchors the trigger to an arbitrary
1344
+ * percent of the plumbed window. The window here is the effective one the
1345
+ * plumb writes or keeps (`min(cap, true window)` when the true window is
1346
+ * known), never the raw cap, so the two sides cannot size against different
1347
+ * windows.
1348
+ *
1349
+ * The derivation is computed, but it cannot be APPLIED from an extension on
1350
+ * pi 1.0.2: ctx.sessionManager is pi-core's session manager and carries no
1351
+ * settings object, and the ExtensionAPI's only settings surface,
1352
+ * getSettings(), returns a structuredClone of the effective settings - a
1353
+ * write would never reach pi-core's compaction reader. The operator-facing
1354
+ * warning is therefore the channel: it fires once per process and spells out
1355
+ * the value to set.
1356
+ *
1357
+ * Warnings (each once per process): an incoherent CONFIGURED reserve (its
1358
+ * trigger falls outside the USAGE_WHISPER_WARNING..USAGE_COMPACT_MEDIUM band
1359
+ * the usage layers work in) and an unappliable reserve - the owner has to set
1360
+ * the value by hand.
1361
+ */
1362
+ export function applyCompactionReserveTokens(ctx: unknown): CompactionReserveApplyResult {
1363
+ const configured = getConfiguredContextLimitTokens();
1364
+ if (configured === undefined) return { reason: "unset" };
1365
+ const model = (
1366
+ ctx as { model?: { contextWindow?: number; id?: string; provider?: string } } | undefined
1367
+ )?.model;
1368
+ // Same effective window the plumb writes or keeps (see
1369
+ // applyConfiguredContextWindow): min(cap, true window) when the true window
1370
+ // is known, the cap alone otherwise. The raw cap would size a reserve
1371
+ // against a window pi-core never sees whenever the ceiling binds.
1372
+ const window = resolveContextLimitTokens(configured, model?.contextWindow) ?? configured;
1373
+ const derivation = resolveCompactionReserveTokens(window);
1374
+ if (!derivation) {
1375
+ if (!_warnedUnderivableCompactionReserve) {
1376
+ _warnedUnderivableCompactionReserve = true;
1377
+ _log.warn(
1378
+ "braid.context.contextLimitTokens leaves no room for a compaction reserve " +
1379
+ "(a 25% reserve does not fit and pi-core's own floor consumes the whole " +
1380
+ "window) - native threshold compaction keeps its defaults.",
1381
+ { window, floorReserve: MIN_COMPACTION_RESERVE_TOKENS },
1382
+ );
1383
+ }
1384
+ return { reason: "no-derivation" };
1385
+ }
1386
+ const { reserveTokens, triggerTokens, triggerPercent } = derivation;
1387
+ const configuredReserve =
1388
+ getConfiguredCompactionReserveTokens(model?.provider, model?.id) ??
1389
+ MIN_COMPACTION_RESERVE_TOKENS;
1390
+ const configuredTrigger = window - configuredReserve;
1391
+ const configuredPercent = (configuredTrigger / window) * 100;
1392
+ const belowBand = configuredPercent <= USAGE_WHISPER_WARNING;
1393
+ const aboveBand = configuredPercent >= USAGE_COMPACT_MEDIUM;
1394
+ if (
1395
+ configuredReserve !== reserveTokens &&
1396
+ (belowBand || aboveBand) &&
1397
+ !_warnedIncoherentCompactionReserve
1398
+ ) {
1399
+ _warnedIncoherentCompactionReserve = true;
1400
+ const where = belowBand
1401
+ ? `before the ${USAGE_WHISPER_WARNING}% warning band`
1402
+ : `inside the archiving band (${USAGE_COMPACT_MEDIUM}%+), where braid archives instead`;
1403
+ _log.warn(
1404
+ `Compaction reserve ${configuredReserve} is incoherent with the ${window}-token ` +
1405
+ `window: native compaction fires at ${configuredTrigger} tokens ` +
1406
+ `(${configuredPercent.toFixed(1)}%), ${where} - the coherent reserve is ` +
1407
+ `${reserveTokens} (trigger ${triggerTokens}, ${triggerPercent.toFixed(1)}%).`,
1408
+ {
1409
+ window,
1410
+ configuredReserve,
1411
+ configuredTrigger,
1412
+ configuredPercent,
1413
+ derivedReserve: reserveTokens,
1414
+ derivedTrigger: triggerTokens,
1415
+ },
1416
+ );
1417
+ }
1418
+ if (model && typeof model === "object" && model.contextWindow !== window) {
1419
+ return { reason: "window-not-plumbed", reserveTokens, triggerTokens, triggerPercent };
1420
+ }
1421
+ if (configuredReserve === reserveTokens) {
1422
+ return { reason: "unchanged", reserveTokens, triggerTokens, triggerPercent };
1423
+ }
1424
+ // No writable settings handle exists to steer: pi-core hands the extension a
1425
+ // session manager without settings, and getSettings() returns a copy. The
1426
+ // warning is the honest channel - it names the value for the operator once
1427
+ // per process.
1428
+ if (!_warnedUnreachableCompactionReserve) {
1429
+ _warnedUnreachableCompactionReserve = true;
1430
+ _log.warn(
1431
+ "Native threshold compaction cannot be re-anchored from an extension here: " +
1432
+ "pi-core exposes no writable settings handle (ctx.sessionManager carries none; " +
1433
+ `pi.getSettings() returns a copy), so the derived reserve ` +
1434
+ `${reserveTokens} was not applied to the ${window}-token window (reserve stays ` +
1435
+ `${configuredReserve}, trigger ${configuredTrigger}). Set ` +
1436
+ `compaction.reserveTokens = ${reserveTokens} in settings.json for a ` +
1437
+ `${triggerPercent.toFixed(1)}% trigger.`,
1438
+ { window, configuredReserve, derivedReserve: reserveTokens, derivedTrigger: triggerTokens },
1439
+ );
1440
+ }
1441
+ return { reason: "unreachable", reserveTokens, triggerTokens, triggerPercent };
1442
+ }