pi-braid 0.0.0-stage → 0.40.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (1011) hide show
  1. package/AGENTS.md +195 -0
  2. package/CONTRIBUTING.md +302 -0
  3. package/LICENSE +21 -0
  4. package/README.md +266 -2
  5. package/TOOLS.md +147 -0
  6. package/dist/extensions/cognitive/mars-reflector/index.d.ts +82 -0
  7. package/dist/extensions/cognitive/mars-reflector/index.js +327 -0
  8. package/dist/extensions/cognitive/metacognition/handlers/claim-verification.d.ts +23 -0
  9. package/dist/extensions/cognitive/metacognition/handlers/claim-verification.js +233 -0
  10. package/dist/extensions/cognitive/metacognition/handlers/finalize.d.ts +27 -0
  11. package/dist/extensions/cognitive/metacognition/handlers/finalize.js +557 -0
  12. package/dist/extensions/cognitive/metacognition/handlers/hypothesize.d.ts +19 -0
  13. package/dist/extensions/cognitive/metacognition/handlers/hypothesize.js +291 -0
  14. package/dist/extensions/cognitive/metacognition/handlers/scoring.d.ts +28 -0
  15. package/dist/extensions/cognitive/metacognition/handlers/scoring.js +173 -0
  16. package/dist/extensions/cognitive/metacognition/handlers/think-budget.d.ts +85 -0
  17. package/dist/extensions/cognitive/metacognition/handlers/think-budget.js +164 -0
  18. package/dist/extensions/cognitive/metacognition/handlers/think.d.ts +27 -0
  19. package/dist/extensions/cognitive/metacognition/handlers/think.js +374 -0
  20. package/dist/extensions/cognitive/metacognition/handlers/verify.d.ts +53 -0
  21. package/dist/extensions/cognitive/metacognition/handlers/verify.js +321 -0
  22. package/dist/extensions/cognitive/metacognition/index.d.ts +10 -0
  23. package/dist/extensions/cognitive/metacognition/index.js +90 -0
  24. package/dist/extensions/cognitive/reasoning/index.d.ts +43 -0
  25. package/dist/extensions/cognitive/reasoning/index.js +99 -0
  26. package/dist/extensions/cognitive/sycophancy-detector/index.d.ts +16 -0
  27. package/dist/extensions/cognitive/sycophancy-detector/index.js +203 -0
  28. package/dist/extensions/cognitive/topic-drift/index.d.ts +51 -0
  29. package/dist/extensions/cognitive/topic-drift/index.js +346 -0
  30. package/dist/extensions/cognitive/turn-outcome/index.d.ts +35 -0
  31. package/dist/extensions/cognitive/turn-outcome/index.js +163 -0
  32. package/dist/extensions/context-management/index.d.ts +77 -0
  33. package/dist/extensions/context-management/index.js +339 -0
  34. package/dist/extensions/core/agent-environment/index.d.ts +30 -0
  35. package/dist/extensions/core/agent-environment/index.js +89 -0
  36. package/dist/extensions/core/polyfill/index.d.ts +28 -0
  37. package/dist/extensions/core/polyfill/index.js +474 -0
  38. package/dist/extensions/core/prompt-builder/awareness-whisper.d.ts +74 -0
  39. package/dist/extensions/core/prompt-builder/awareness-whisper.js +116 -0
  40. package/dist/extensions/core/prompt-builder/context-section.d.ts +41 -0
  41. package/dist/extensions/core/prompt-builder/context-section.js +101 -0
  42. package/dist/extensions/core/prompt-builder/custom-sections.d.ts +21 -0
  43. package/dist/extensions/core/prompt-builder/custom-sections.js +11 -0
  44. package/dist/extensions/core/prompt-builder/external-tool-guidelines.d.ts +23 -0
  45. package/dist/extensions/core/prompt-builder/external-tool-guidelines.js +37 -0
  46. package/dist/extensions/core/prompt-builder/identity.d.ts +33 -0
  47. package/dist/extensions/core/prompt-builder/identity.js +77 -0
  48. package/dist/extensions/core/prompt-builder/index.d.ts +33 -0
  49. package/dist/extensions/core/prompt-builder/index.js +496 -0
  50. package/dist/extensions/core/prompt-builder/inspect.d.ts +58 -0
  51. package/dist/extensions/core/prompt-builder/inspect.js +182 -0
  52. package/dist/extensions/core/prompt-builder/instance-composition.d.ts +101 -0
  53. package/dist/extensions/core/prompt-builder/instance-composition.js +416 -0
  54. package/dist/extensions/core/prompt-builder/memory-section.d.ts +20 -0
  55. package/dist/extensions/core/prompt-builder/memory-section.js +60 -0
  56. package/dist/extensions/core/prompt-builder/pi-reference-section.d.ts +17 -0
  57. package/dist/extensions/core/prompt-builder/pi-reference-section.js +11 -0
  58. package/dist/extensions/core/prompt-builder/project-docs-section.d.ts +42 -0
  59. package/dist/extensions/core/prompt-builder/project-docs-section.js +72 -0
  60. package/dist/extensions/core/prompt-builder/section-parity.d.ts +36 -0
  61. package/dist/extensions/core/prompt-builder/section-parity.js +66 -0
  62. package/dist/extensions/core/prompt-builder/section-publish.d.ts +30 -0
  63. package/dist/extensions/core/prompt-builder/section-publish.js +16 -0
  64. package/dist/extensions/core/prompt-builder/section.d.ts +75 -0
  65. package/dist/extensions/core/prompt-builder/section.js +127 -0
  66. package/dist/extensions/core/prompt-builder/surface-discipline-section.d.ts +18 -0
  67. package/dist/extensions/core/prompt-builder/surface-discipline-section.js +20 -0
  68. package/dist/extensions/core/prompt-builder/system-info-tool.d.ts +27 -0
  69. package/dist/extensions/core/prompt-builder/system-info-tool.js +67 -0
  70. package/dist/extensions/core/prompt-builder/tool-description-trim.d.ts +56 -0
  71. package/dist/extensions/core/prompt-builder/tool-description-trim.js +129 -0
  72. package/dist/extensions/core/prompt-builder/tool-guidelines.d.ts +80 -0
  73. package/dist/extensions/core/prompt-builder/tool-guidelines.js +179 -0
  74. package/dist/extensions/core/prompt-builder/tool-pipelines.d.ts +50 -0
  75. package/dist/extensions/core/prompt-builder/tool-pipelines.js +69 -0
  76. package/dist/extensions/core/prompt-builder/top-level-extensions.d.ts +44 -0
  77. package/dist/extensions/core/prompt-builder/top-level-extensions.js +300 -0
  78. package/dist/extensions/core/skills-tool/auto-inject.d.ts +333 -0
  79. package/dist/extensions/core/skills-tool/auto-inject.js +817 -0
  80. package/dist/extensions/core/skills-tool/index.d.ts +56 -0
  81. package/dist/extensions/core/skills-tool/index.js +200 -0
  82. package/dist/extensions/core/skills-tool/loading-guidance.d.ts +50 -0
  83. package/dist/extensions/core/skills-tool/loading-guidance.js +87 -0
  84. package/dist/extensions/core/skills-tool/session-records.d.ts +114 -0
  85. package/dist/extensions/core/skills-tool/session-records.js +268 -0
  86. package/dist/extensions/core/skills-tool/skill-triggers.d.ts +48 -0
  87. package/dist/extensions/core/skills-tool/skill-triggers.js +113 -0
  88. package/dist/extensions/enforcement/detection/malformed.d.ts +9 -0
  89. package/dist/extensions/enforcement/detection/malformed.js +30 -0
  90. package/dist/extensions/enforcement/detection/verification.d.ts +10 -0
  91. package/dist/extensions/enforcement/detection/verification.js +34 -0
  92. package/dist/extensions/enforcement/enforcement-types.d.ts +33 -0
  93. package/dist/extensions/enforcement/enforcement-types.js +24 -0
  94. package/dist/extensions/enforcement/handler-registry.d.ts +12 -0
  95. package/dist/extensions/enforcement/handler-registry.js +196 -0
  96. package/dist/extensions/enforcement/handlers/analysis/bpe-handler.d.ts +10 -0
  97. package/dist/extensions/enforcement/handlers/analysis/bpe-handler.js +37 -0
  98. package/dist/extensions/enforcement/handlers/analysis/dreamer-handler.d.ts +6 -0
  99. package/dist/extensions/enforcement/handlers/analysis/dreamer-handler.js +60 -0
  100. package/dist/extensions/enforcement/handlers/analysis/drift-handler.d.ts +6 -0
  101. package/dist/extensions/enforcement/handlers/analysis/drift-handler.js +75 -0
  102. package/dist/extensions/enforcement/handlers/analysis/feedback-handler.d.ts +6 -0
  103. package/dist/extensions/enforcement/handlers/analysis/feedback-handler.js +19 -0
  104. package/dist/extensions/enforcement/handlers/analysis/mars-handler.d.ts +14 -0
  105. package/dist/extensions/enforcement/handlers/analysis/mars-handler.js +99 -0
  106. package/dist/extensions/enforcement/handlers/analysis/reflection-handler.d.ts +6 -0
  107. package/dist/extensions/enforcement/handlers/analysis/reflection-handler.js +16 -0
  108. package/dist/extensions/enforcement/handlers/blocking.d.ts +16 -0
  109. package/dist/extensions/enforcement/handlers/blocking.js +33 -0
  110. package/dist/extensions/enforcement/handlers/message-analysis.d.ts +25 -0
  111. package/dist/extensions/enforcement/handlers/message-analysis.js +70 -0
  112. package/dist/extensions/enforcement/handlers/orphan-chains.d.ts +14 -0
  113. package/dist/extensions/enforcement/handlers/orphan-chains.js +44 -0
  114. package/dist/extensions/enforcement/handlers/over-correction-gate.d.ts +73 -0
  115. package/dist/extensions/enforcement/handlers/over-correction-gate.js +565 -0
  116. package/dist/extensions/enforcement/handlers/probe-handler.d.ts +31 -0
  117. package/dist/extensions/enforcement/handlers/probe-handler.js +111 -0
  118. package/dist/extensions/enforcement/handlers/register-adherence-meter.d.ts +52 -0
  119. package/dist/extensions/enforcement/handlers/register-adherence-meter.js +158 -0
  120. package/dist/extensions/enforcement/handlers/register-agent-end-api-error.d.ts +3 -0
  121. package/dist/extensions/enforcement/handlers/register-agent-end-api-error.js +69 -0
  122. package/dist/extensions/enforcement/handlers/register-input-handler.d.ts +10 -0
  123. package/dist/extensions/enforcement/handlers/register-input-handler.js +35 -0
  124. package/dist/extensions/enforcement/handlers/register-message-end.d.ts +6 -0
  125. package/dist/extensions/enforcement/handlers/register-message-end.js +388 -0
  126. package/dist/extensions/enforcement/handlers/register-post-cycle-hygiene.d.ts +25 -0
  127. package/dist/extensions/enforcement/handlers/register-post-cycle-hygiene.js +143 -0
  128. package/dist/extensions/enforcement/handlers/register-session-compact.d.ts +50 -0
  129. package/dist/extensions/enforcement/handlers/register-session-compact.js +207 -0
  130. package/dist/extensions/enforcement/handlers/register-session-shutdown-resumption.d.ts +21 -0
  131. package/dist/extensions/enforcement/handlers/register-session-shutdown-resumption.js +116 -0
  132. package/dist/extensions/enforcement/handlers/register-session-shutdown.d.ts +6 -0
  133. package/dist/extensions/enforcement/handlers/register-session-shutdown.js +38 -0
  134. package/dist/extensions/enforcement/handlers/register-session-start-discoverability.d.ts +34 -0
  135. package/dist/extensions/enforcement/handlers/register-session-start-discoverability.js +240 -0
  136. package/dist/extensions/enforcement/handlers/register-session-start.d.ts +16 -0
  137. package/dist/extensions/enforcement/handlers/register-session-start.js +198 -0
  138. package/dist/extensions/enforcement/handlers/register-tool-call.d.ts +6 -0
  139. package/dist/extensions/enforcement/handlers/register-tool-call.js +132 -0
  140. package/dist/extensions/enforcement/handlers/register-tool-result-formatting.d.ts +18 -0
  141. package/dist/extensions/enforcement/handlers/register-tool-result-formatting.js +56 -0
  142. package/dist/extensions/enforcement/handlers/register-tool-result.d.ts +6 -0
  143. package/dist/extensions/enforcement/handlers/register-tool-result.js +91 -0
  144. package/dist/extensions/enforcement/handlers/register-turn-end-hygiene.d.ts +35 -0
  145. package/dist/extensions/enforcement/handlers/register-turn-end-hygiene.js +385 -0
  146. package/dist/extensions/enforcement/handlers/routing-handler.d.ts +42 -0
  147. package/dist/extensions/enforcement/handlers/routing-handler.js +135 -0
  148. package/dist/extensions/enforcement/handlers/tool-tracker.d.ts +9 -0
  149. package/dist/extensions/enforcement/handlers/tool-tracker.js +122 -0
  150. package/dist/extensions/enforcement/handlers/turn-analysis.d.ts +41 -0
  151. package/dist/extensions/enforcement/handlers/turn-analysis.js +109 -0
  152. package/dist/extensions/enforcement/handlers/turn-end-handler.d.ts +9 -0
  153. package/dist/extensions/enforcement/handlers/turn-end-handler.js +451 -0
  154. package/dist/extensions/enforcement/index.d.ts +15 -0
  155. package/dist/extensions/enforcement/index.js +22 -0
  156. package/dist/extensions/enforcement/judge-utils.d.ts +73 -0
  157. package/dist/extensions/enforcement/judge-utils.js +83 -0
  158. package/dist/extensions/enforcement/nudge-manager.d.ts +106 -0
  159. package/dist/extensions/enforcement/nudge-manager.js +203 -0
  160. package/dist/extensions/enforcement/self-state-claims.d.ts +79 -0
  161. package/dist/extensions/enforcement/self-state-claims.js +167 -0
  162. package/dist/extensions/enforcement/session-health.d.ts +107 -0
  163. package/dist/extensions/enforcement/session-health.js +251 -0
  164. package/dist/extensions/enforcement/signals.d.ts +54 -0
  165. package/dist/extensions/enforcement/signals.js +47 -0
  166. package/dist/extensions/enforcement/similarity.d.ts +16 -0
  167. package/dist/extensions/enforcement/similarity.js +64 -0
  168. package/dist/extensions/enforcement/state.d.ts +40 -0
  169. package/dist/extensions/enforcement/state.js +74 -0
  170. package/dist/extensions/enforcement/substate/context-hygiene-state.d.ts +88 -0
  171. package/dist/extensions/enforcement/substate/context-hygiene-state.js +119 -0
  172. package/dist/extensions/enforcement/substate/error-tracking-state.d.ts +20 -0
  173. package/dist/extensions/enforcement/substate/error-tracking-state.js +37 -0
  174. package/dist/extensions/enforcement/substate/memory-hygiene-state.d.ts +24 -0
  175. package/dist/extensions/enforcement/substate/memory-hygiene-state.js +37 -0
  176. package/dist/extensions/enforcement/substate/session-state.d.ts +34 -0
  177. package/dist/extensions/enforcement/substate/session-state.js +45 -0
  178. package/dist/extensions/enforcement/substate/thought-chain-state.d.ts +23 -0
  179. package/dist/extensions/enforcement/substate/thought-chain-state.js +43 -0
  180. package/dist/extensions/enforcement/substate/tool-tracking-state.d.ts +71 -0
  181. package/dist/extensions/enforcement/substate/tool-tracking-state.js +99 -0
  182. package/dist/extensions/enforcement/substate/verification-judge-state.d.ts +17 -0
  183. package/dist/extensions/enforcement/substate/verification-judge-state.js +39 -0
  184. package/dist/extensions/enforcement/task-evidence.d.ts +108 -0
  185. package/dist/extensions/enforcement/task-evidence.js +335 -0
  186. package/dist/extensions/enforcement/types.d.ts +35 -0
  187. package/dist/extensions/enforcement/types.js +5 -0
  188. package/dist/extensions/enforcement/validation.d.ts +12 -0
  189. package/dist/extensions/enforcement/validation.js +151 -0
  190. package/dist/extensions/enforcement/verification-judge.d.ts +110 -0
  191. package/dist/extensions/enforcement/verification-judge.js +214 -0
  192. package/dist/extensions/enforcement/whisper.d.ts +46 -0
  193. package/dist/extensions/enforcement/whisper.js +104 -0
  194. package/dist/extensions/heartbeat/analytics/ab-variant.d.ts +19 -0
  195. package/dist/extensions/heartbeat/analytics/ab-variant.js +86 -0
  196. package/dist/extensions/heartbeat/analytics/core.d.ts +12 -0
  197. package/dist/extensions/heartbeat/analytics/core.js +201 -0
  198. package/dist/extensions/heartbeat/analytics/format.d.ts +7 -0
  199. package/dist/extensions/heartbeat/analytics/format.js +111 -0
  200. package/dist/extensions/heartbeat/analytics/index.d.ts +14 -0
  201. package/dist/extensions/heartbeat/analytics/index.js +352 -0
  202. package/dist/extensions/heartbeat/analytics/shared.d.ts +85 -0
  203. package/dist/extensions/heartbeat/analytics/shared.js +69 -0
  204. package/dist/extensions/heartbeat/heartbeat-scheduler/index.d.ts +31 -0
  205. package/dist/extensions/heartbeat/heartbeat-scheduler/index.js +881 -0
  206. package/dist/extensions/heartbeat/heartbeat-scheduler/meta-learning.d.ts +10 -0
  207. package/dist/extensions/heartbeat/heartbeat-scheduler/meta-learning.js +49 -0
  208. package/dist/extensions/heartbeat/heartbeat-scheduler/modules/behavioral-drift.d.ts +17 -0
  209. package/dist/extensions/heartbeat/heartbeat-scheduler/modules/behavioral-drift.js +161 -0
  210. package/dist/extensions/heartbeat/heartbeat-scheduler/modules/budget.d.ts +13 -0
  211. package/dist/extensions/heartbeat/heartbeat-scheduler/modules/budget.js +101 -0
  212. package/dist/extensions/heartbeat/heartbeat-scheduler/modules/context-hygiene.d.ts +10 -0
  213. package/dist/extensions/heartbeat/heartbeat-scheduler/modules/context-hygiene.js +221 -0
  214. package/dist/extensions/heartbeat/heartbeat-scheduler/modules/evolver.d.ts +9 -0
  215. package/dist/extensions/heartbeat/heartbeat-scheduler/modules/evolver.js +65 -0
  216. package/dist/extensions/heartbeat/heartbeat-scheduler/modules/measurement.d.ts +8 -0
  217. package/dist/extensions/heartbeat/heartbeat-scheduler/modules/measurement.js +32 -0
  218. package/dist/extensions/heartbeat/heartbeat-scheduler/modules/recaller.d.ts +9 -0
  219. package/dist/extensions/heartbeat/heartbeat-scheduler/modules/recaller.js +75 -0
  220. package/dist/extensions/heartbeat/heartbeat-scheduler/modules/reflection-consolidator.d.ts +9 -0
  221. package/dist/extensions/heartbeat/heartbeat-scheduler/modules/reflection-consolidator.js +98 -0
  222. package/dist/extensions/heartbeat/heartbeat-scheduler/policies.d.ts +14 -0
  223. package/dist/extensions/heartbeat/heartbeat-scheduler/policies.js +149 -0
  224. package/dist/extensions/heartbeat/heartbeat-scheduler/state.d.ts +22 -0
  225. package/dist/extensions/heartbeat/heartbeat-scheduler/state.js +82 -0
  226. package/dist/extensions/heartbeat/heartbeat-scheduler/types.d.ts +124 -0
  227. package/dist/extensions/heartbeat/heartbeat-scheduler/types.js +7 -0
  228. package/dist/extensions/heartbeat/heartbeat-scheduler/whisper-batcher.d.ts +52 -0
  229. package/dist/extensions/heartbeat/heartbeat-scheduler/whisper-batcher.js +83 -0
  230. package/dist/extensions/manifest.d.ts +32 -0
  231. package/dist/extensions/manifest.js +251 -0
  232. package/dist/extensions/memory/context-lifecycle/helpers.d.ts +55 -0
  233. package/dist/extensions/memory/context-lifecycle/helpers.js +142 -0
  234. package/dist/extensions/memory/context-lifecycle/index.d.ts +17 -0
  235. package/dist/extensions/memory/context-lifecycle/index.js +977 -0
  236. package/dist/extensions/memory/context-lifecycle/policy-engine.d.ts +50 -0
  237. package/dist/extensions/memory/context-lifecycle/policy-engine.js +196 -0
  238. package/dist/extensions/memory/context-lifecycle/signal-detector.d.ts +28 -0
  239. package/dist/extensions/memory/context-lifecycle/signal-detector.js +224 -0
  240. package/dist/extensions/memory/context-lifecycle/state.d.ts +98 -0
  241. package/dist/extensions/memory/context-lifecycle/state.js +90 -0
  242. package/dist/extensions/memory/context-lifecycle/types.d.ts +132 -0
  243. package/dist/extensions/memory/context-lifecycle/types.js +273 -0
  244. package/dist/extensions/memory/context-manager/analysis.d.ts +47 -0
  245. package/dist/extensions/memory/context-manager/analysis.js +264 -0
  246. package/dist/extensions/memory/context-manager/handlers/compaction-chunked.d.ts +159 -0
  247. package/dist/extensions/memory/context-manager/handlers/compaction-chunked.js +658 -0
  248. package/dist/extensions/memory/context-manager/handlers/compaction-retry.d.ts +29 -0
  249. package/dist/extensions/memory/context-manager/handlers/compaction-retry.js +410 -0
  250. package/dist/extensions/memory/context-manager/handlers/compaction-trace.d.ts +74 -0
  251. package/dist/extensions/memory/context-manager/handlers/compaction-trace.js +180 -0
  252. package/dist/extensions/memory/context-manager/handlers/compaction-watchdog.d.ts +69 -0
  253. package/dist/extensions/memory/context-manager/handlers/compaction-watchdog.js +297 -0
  254. package/dist/extensions/memory/context-manager/handlers/compaction.d.ts +37 -0
  255. package/dist/extensions/memory/context-manager/handlers/compaction.js +2150 -0
  256. package/dist/extensions/memory/context-manager/handlers/context-emergency.d.ts +124 -0
  257. package/dist/extensions/memory/context-manager/handlers/context-emergency.js +364 -0
  258. package/dist/extensions/memory/context-manager/handlers/events.d.ts +5 -0
  259. package/dist/extensions/memory/context-manager/handlers/events.js +314 -0
  260. package/dist/extensions/memory/context-manager/handlers/navigation.d.ts +5 -0
  261. package/dist/extensions/memory/context-manager/handlers/navigation.js +86 -0
  262. package/dist/extensions/memory/context-manager/handlers/offload.d.ts +94 -0
  263. package/dist/extensions/memory/context-manager/handlers/offload.js +248 -0
  264. package/dist/extensions/memory/context-manager/handlers/rotation.d.ts +6 -0
  265. package/dist/extensions/memory/context-manager/handlers/rotation.js +304 -0
  266. package/dist/extensions/memory/context-manager/handlers/shared.d.ts +410 -0
  267. package/dist/extensions/memory/context-manager/handlers/shared.js +579 -0
  268. package/dist/extensions/memory/context-manager/handlers/tool-batch-boundary.d.ts +55 -0
  269. package/dist/extensions/memory/context-manager/handlers/tool-batch-boundary.js +190 -0
  270. package/dist/extensions/memory/context-manager/handlers/toolresult-capture-cap.d.ts +21 -0
  271. package/dist/extensions/memory/context-manager/handlers/toolresult-capture-cap.js +155 -0
  272. package/dist/extensions/memory/context-manager/handlers/tools/context-compress.d.ts +90 -0
  273. package/dist/extensions/memory/context-manager/handlers/tools/context-compress.js +1156 -0
  274. package/dist/extensions/memory/context-manager/handlers/tools/context-inspect.d.ts +16 -0
  275. package/dist/extensions/memory/context-manager/handlers/tools/context-inspect.js +276 -0
  276. package/dist/extensions/memory/context-manager/handlers/tools/context-navigate.d.ts +19 -0
  277. package/dist/extensions/memory/context-manager/handlers/tools/context-navigate.js +378 -0
  278. package/dist/extensions/memory/context-manager/handlers/tools/offload-recover.d.ts +13 -0
  279. package/dist/extensions/memory/context-manager/handlers/tools/offload-recover.js +181 -0
  280. package/dist/extensions/memory/context-manager/index.d.ts +3 -0
  281. package/dist/extensions/memory/context-manager/index.js +88 -0
  282. package/dist/extensions/memory/context-manager/pruning.d.ts +47 -0
  283. package/dist/extensions/memory/context-manager/pruning.js +406 -0
  284. package/dist/extensions/memory/context-manager/semantic-compress.d.ts +71 -0
  285. package/dist/extensions/memory/context-manager/semantic-compress.js +279 -0
  286. package/dist/extensions/memory/memory-agent-bridge/conflict-qa-tool.d.ts +20 -0
  287. package/dist/extensions/memory/memory-agent-bridge/conflict-qa-tool.js +71 -0
  288. package/dist/extensions/memory/memory-agent-bridge/explore-paths.d.ts +30 -0
  289. package/dist/extensions/memory/memory-agent-bridge/explore-paths.js +231 -0
  290. package/dist/extensions/memory/memory-agent-bridge/index.d.ts +28 -0
  291. package/dist/extensions/memory/memory-agent-bridge/index.js +124 -0
  292. package/dist/extensions/memory/memory-agent-bridge/memory-store-tool.d.ts +21 -0
  293. package/dist/extensions/memory/memory-agent-bridge/memory-store-tool.js +194 -0
  294. package/dist/extensions/memory/memory-agent-bridge/memory-tool.d.ts +22 -0
  295. package/dist/extensions/memory/memory-agent-bridge/memory-tool.js +548 -0
  296. package/dist/extensions/memory/scratchpad/format.d.ts +19 -0
  297. package/dist/extensions/memory/scratchpad/format.js +135 -0
  298. package/dist/extensions/memory/scratchpad/handlers.d.ts +53 -0
  299. package/dist/extensions/memory/scratchpad/handlers.js +469 -0
  300. package/dist/extensions/memory/scratchpad/index.d.ts +17 -0
  301. package/dist/extensions/memory/scratchpad/index.js +168 -0
  302. package/dist/extensions/memory/scratchpad/persistence.d.ts +46 -0
  303. package/dist/extensions/memory/scratchpad/persistence.js +343 -0
  304. package/dist/extensions/memory/scratchpad/types.d.ts +124 -0
  305. package/dist/extensions/memory/scratchpad/types.js +8 -0
  306. package/dist/extensions/memory/scratchpad/utils.d.ts +76 -0
  307. package/dist/extensions/memory/scratchpad/utils.js +236 -0
  308. package/dist/extensions/memory/session-recall/analyze.d.ts +58 -0
  309. package/dist/extensions/memory/session-recall/analyze.js +478 -0
  310. package/dist/extensions/memory/session-recall/context-aggregate.d.ts +117 -0
  311. package/dist/extensions/memory/session-recall/context-aggregate.js +315 -0
  312. package/dist/extensions/memory/session-recall/index.d.ts +29 -0
  313. package/dist/extensions/memory/session-recall/index.js +820 -0
  314. package/dist/extensions/memory/session-recall/query.d.ts +15 -0
  315. package/dist/extensions/memory/session-recall/query.js +38 -0
  316. package/dist/extensions/memory/session-recall/rank.d.ts +71 -0
  317. package/dist/extensions/memory/session-recall/rank.js +85 -0
  318. package/dist/extensions/memory/session-recall/search.d.ts +159 -0
  319. package/dist/extensions/memory/session-recall/search.js +682 -0
  320. package/dist/extensions/memory/session-recall/stats.d.ts +34 -0
  321. package/dist/extensions/memory/session-recall/stats.js +67 -0
  322. package/dist/extensions/memory/session-recall/text-utils.d.ts +82 -0
  323. package/dist/extensions/memory/session-recall/text-utils.js +184 -0
  324. package/dist/extensions/memory/three-memory-stores/episodes-disk.d.ts +43 -0
  325. package/dist/extensions/memory/three-memory-stores/episodes-disk.js +125 -0
  326. package/dist/extensions/memory/three-memory-stores/episodes.d.ts +46 -0
  327. package/dist/extensions/memory/three-memory-stores/episodes.js +299 -0
  328. package/dist/extensions/memory/three-memory-stores/handlers/whisper-recall.d.ts +25 -0
  329. package/dist/extensions/memory/three-memory-stores/handlers/whisper-recall.js +112 -0
  330. package/dist/extensions/memory/three-memory-stores/heuristics.d.ts +19 -0
  331. package/dist/extensions/memory/three-memory-stores/heuristics.js +89 -0
  332. package/dist/extensions/memory/three-memory-stores/index.d.ts +34 -0
  333. package/dist/extensions/memory/three-memory-stores/index.js +436 -0
  334. package/dist/extensions/memory/three-memory-stores/tool-reliability.d.ts +11 -0
  335. package/dist/extensions/memory/three-memory-stores/tool-reliability.js +38 -0
  336. package/dist/extensions/memory/three-memory-stores/types.d.ts +69 -0
  337. package/dist/extensions/memory/three-memory-stores/types.js +2 -0
  338. package/dist/extensions/memory/workspace-snapshot/index.d.ts +19 -0
  339. package/dist/extensions/memory/workspace-snapshot/index.js +363 -0
  340. package/dist/extensions/orchestrator/index.d.ts +19 -0
  341. package/dist/extensions/orchestrator/index.js +796 -0
  342. package/dist/extensions/scheduling/timer/fire-timing.d.ts +25 -0
  343. package/dist/extensions/scheduling/timer/fire-timing.js +28 -0
  344. package/dist/extensions/scheduling/timer/index.d.ts +102 -0
  345. package/dist/extensions/scheduling/timer/index.js +1143 -0
  346. package/dist/extensions/scheduling/timer/poller.d.ts +52 -0
  347. package/dist/extensions/scheduling/timer/poller.js +135 -0
  348. package/dist/extensions/scheduling/timer/recovery.d.ts +145 -0
  349. package/dist/extensions/scheduling/timer/recovery.js +445 -0
  350. package/dist/extensions/scheduling/timer/store-file.d.ts +38 -0
  351. package/dist/extensions/scheduling/timer/store-file.js +59 -0
  352. package/dist/extensions/scheduling/timer/timer-manager.d.ts +21 -0
  353. package/dist/extensions/scheduling/timer/timer-manager.js +143 -0
  354. package/dist/extensions/scheduling/timer/wake-retry.d.ts +455 -0
  355. package/dist/extensions/scheduling/timer/wake-retry.js +872 -0
  356. package/dist/extensions/self/auto-recovery/index.d.ts +20 -0
  357. package/dist/extensions/self/auto-recovery/index.js +89 -0
  358. package/dist/extensions/self/error-tracking/index.d.ts +3 -0
  359. package/dist/extensions/self/error-tracking/index.js +244 -0
  360. package/dist/extensions/self/health-maintenance/format.d.ts +3 -0
  361. package/dist/extensions/self/health-maintenance/format.js +60 -0
  362. package/dist/extensions/self/health-maintenance/handlers/session-health-tool.d.ts +23 -0
  363. package/dist/extensions/self/health-maintenance/handlers/session-health-tool.js +158 -0
  364. package/dist/extensions/self/health-maintenance/helpers.d.ts +25 -0
  365. package/dist/extensions/self/health-maintenance/helpers.js +67 -0
  366. package/dist/extensions/self/health-maintenance/index.d.ts +6 -0
  367. package/dist/extensions/self/health-maintenance/index.js +238 -0
  368. package/dist/extensions/self/health-maintenance/types.d.ts +14 -0
  369. package/dist/extensions/self/health-maintenance/types.js +2 -0
  370. package/dist/extensions/self/latent-activator/index.d.ts +12 -0
  371. package/dist/extensions/self/latent-activator/index.js +173 -0
  372. package/dist/extensions/self/latent-activator/mixes.d.ts +9 -0
  373. package/dist/extensions/self/latent-activator/mixes.js +20 -0
  374. package/dist/extensions/self/latent-activator/signals.d.ts +17 -0
  375. package/dist/extensions/self/latent-activator/signals.js +228 -0
  376. package/dist/extensions/self/latent-activator/state.d.ts +43 -0
  377. package/dist/extensions/self/latent-activator/state.js +59 -0
  378. package/dist/extensions/self/latent-activator/types.d.ts +8 -0
  379. package/dist/extensions/self/latent-activator/types.js +8 -0
  380. package/dist/extensions/self/watchdog/config.d.ts +4 -0
  381. package/dist/extensions/self/watchdog/config.js +79 -0
  382. package/dist/extensions/self/watchdog/engine.d.ts +256 -0
  383. package/dist/extensions/self/watchdog/engine.js +935 -0
  384. package/dist/extensions/self/watchdog/index.d.ts +23 -0
  385. package/dist/extensions/self/watchdog/index.js +485 -0
  386. package/dist/index.d.ts +25 -0
  387. package/dist/index.js +81 -0
  388. package/dist/lib/ai/consolidated-claim-critic.d.ts +84 -0
  389. package/dist/lib/ai/consolidated-claim-critic.js +191 -0
  390. package/dist/lib/ai/cost-report.d.ts +83 -0
  391. package/dist/lib/ai/cost-report.js +116 -0
  392. package/dist/lib/ai/critic-cache.d.ts +57 -0
  393. package/dist/lib/ai/critic-cache.js +100 -0
  394. package/dist/lib/ai/critic-fallbacks.d.ts +37 -0
  395. package/dist/lib/ai/critic-fallbacks.js +75 -0
  396. package/dist/lib/ai/critic-gate.d.ts +75 -0
  397. package/dist/lib/ai/critic-gate.js +81 -0
  398. package/dist/lib/ai/critic-helpers.d.ts +26 -0
  399. package/dist/lib/ai/critic-helpers.js +131 -0
  400. package/dist/lib/ai/critic-registry.d.ts +417 -0
  401. package/dist/lib/ai/critic-registry.js +639 -0
  402. package/dist/lib/ai/critic-stats.d.ts +78 -0
  403. package/dist/lib/ai/critic-stats.js +90 -0
  404. package/dist/lib/ai/judge-budget.d.ts +138 -0
  405. package/dist/lib/ai/judge-budget.js +143 -0
  406. package/dist/lib/ai/language-hint.d.ts +21 -0
  407. package/dist/lib/ai/language-hint.js +58 -0
  408. package/dist/lib/ai/llm-call.d.ts +141 -0
  409. package/dist/lib/ai/llm-call.js +745 -0
  410. package/dist/lib/ai/model-resolver.d.ts +90 -0
  411. package/dist/lib/ai/model-resolver.js +185 -0
  412. package/dist/lib/ai/models-init.d.ts +46 -0
  413. package/dist/lib/ai/models-init.js +65 -0
  414. package/dist/lib/ai/payload-hygiene.d.ts +74 -0
  415. package/dist/lib/ai/payload-hygiene.js +240 -0
  416. package/dist/lib/ai/post-loop-classify.d.ts +128 -0
  417. package/dist/lib/ai/post-loop-classify.js +87 -0
  418. package/dist/lib/ai/text-classifier.d.ts +142 -0
  419. package/dist/lib/ai/text-classifier.js +548 -0
  420. package/dist/lib/cognitive/hints.d.ts +33 -0
  421. package/dist/lib/cognitive/hints.js +223 -0
  422. package/dist/lib/cognitive/openspec.d.ts +29 -0
  423. package/dist/lib/cognitive/openspec.js +108 -0
  424. package/dist/lib/config/braid-paths.d.ts +188 -0
  425. package/dist/lib/config/braid-paths.js +340 -0
  426. package/dist/lib/config/braid-settings.d.ts +489 -0
  427. package/dist/lib/config/braid-settings.js +938 -0
  428. package/dist/lib/config/per-tool-settings.d.ts +95 -0
  429. package/dist/lib/config/per-tool-settings.js +161 -0
  430. package/dist/lib/config/session-profiles.d.ts +68 -0
  431. package/dist/lib/config/session-profiles.js +143 -0
  432. package/dist/lib/constants/injection-details.d.ts +30 -0
  433. package/dist/lib/constants/injection-details.js +30 -0
  434. package/dist/lib/constants/session-thresholds.d.ts +42 -0
  435. package/dist/lib/constants/session-thresholds.js +54 -0
  436. package/dist/lib/constants/tool-constants.d.ts +11 -0
  437. package/dist/lib/constants/tool-constants.js +12 -0
  438. package/dist/lib/core/event-names.d.ts +23 -0
  439. package/dist/lib/core/event-names.js +26 -0
  440. package/dist/lib/core/logger.d.ts +102 -0
  441. package/dist/lib/core/logger.js +274 -0
  442. package/dist/lib/detection/compression-strategy.d.ts +38 -0
  443. package/dist/lib/detection/compression-strategy.js +147 -0
  444. package/dist/lib/detection/consolidated-topic-critic.d.ts +51 -0
  445. package/dist/lib/detection/consolidated-topic-critic.js +132 -0
  446. package/dist/lib/detection/context-density.d.ts +70 -0
  447. package/dist/lib/detection/context-density.js +193 -0
  448. package/dist/lib/detection/context-thresholds.d.ts +88 -0
  449. package/dist/lib/detection/context-thresholds.js +107 -0
  450. package/dist/lib/detection/context-tiers.d.ts +80 -0
  451. package/dist/lib/detection/context-tiers.js +144 -0
  452. package/dist/lib/detection/context-usage.d.ts +75 -0
  453. package/dist/lib/detection/context-usage.js +209 -0
  454. package/dist/lib/detection/degradation-detector.d.ts +74 -0
  455. package/dist/lib/detection/degradation-detector.js +454 -0
  456. package/dist/lib/detection/test-burst.d.ts +77 -0
  457. package/dist/lib/detection/test-burst.js +126 -0
  458. package/dist/lib/detection/tool-loop-detector.d.ts +125 -0
  459. package/dist/lib/detection/tool-loop-detector.js +302 -0
  460. package/dist/lib/detection/topic-drift-detector.d.ts +80 -0
  461. package/dist/lib/detection/topic-drift-detector.js +252 -0
  462. package/dist/lib/enforcement/adherence-meter.d.ts +240 -0
  463. package/dist/lib/enforcement/adherence-meter.js +420 -0
  464. package/dist/lib/enforcement/turn-dedup.d.ts +106 -0
  465. package/dist/lib/enforcement/turn-dedup.js +195 -0
  466. package/dist/lib/errors/llm-error.d.ts +79 -0
  467. package/dist/lib/errors/llm-error.js +241 -0
  468. package/dist/lib/events/consolidation-channel.d.ts +109 -0
  469. package/dist/lib/events/consolidation-channel.js +374 -0
  470. package/dist/lib/events/consolidation-scoring.d.ts +59 -0
  471. package/dist/lib/events/consolidation-scoring.js +95 -0
  472. package/dist/lib/events/event-bus.d.ts +123 -0
  473. package/dist/lib/events/event-bus.js +108 -0
  474. package/dist/lib/events/event-types.d.ts +39 -0
  475. package/dist/lib/events/event-types.js +30 -0
  476. package/dist/lib/events/timer-bus.d.ts +21 -0
  477. package/dist/lib/events/timer-bus.js +41 -0
  478. package/dist/lib/events/timer-types.d.ts +64 -0
  479. package/dist/lib/events/timer-types.js +8 -0
  480. package/dist/lib/events/turn-end-coordinator.d.ts +52 -0
  481. package/dist/lib/events/turn-end-coordinator.js +89 -0
  482. package/dist/lib/harness/failure-trace-collector.d.ts +31 -0
  483. package/dist/lib/harness/failure-trace-collector.js +114 -0
  484. package/dist/lib/harness/index.d.ts +20 -0
  485. package/dist/lib/harness/index.js +21 -0
  486. package/dist/lib/harness/types.d.ts +85 -0
  487. package/dist/lib/harness/types.js +20 -0
  488. package/dist/lib/harness/weakness-miner.d.ts +29 -0
  489. package/dist/lib/harness/weakness-miner.js +165 -0
  490. package/dist/lib/memory/constants.d.ts +11 -0
  491. package/dist/lib/memory/constants.js +29 -0
  492. package/dist/lib/memory/index.d.ts +147 -0
  493. package/dist/lib/memory/index.js +564 -0
  494. package/dist/lib/memory/lifecycle.d.ts +50 -0
  495. package/dist/lib/memory/lifecycle.js +139 -0
  496. package/dist/lib/memory/past-insights.d.ts +35 -0
  497. package/dist/lib/memory/past-insights.js +189 -0
  498. package/dist/lib/memory/storage.d.ts +38 -0
  499. package/dist/lib/memory/storage.js +167 -0
  500. package/dist/lib/memory/store-lock.d.ts +23 -0
  501. package/dist/lib/memory/store-lock.js +69 -0
  502. package/dist/lib/memory/store-merge.d.ts +38 -0
  503. package/dist/lib/memory/store-merge.js +73 -0
  504. package/dist/lib/memory/types.d.ts +65 -0
  505. package/dist/lib/memory/types.js +5 -0
  506. package/dist/lib/memory/utils.d.ts +35 -0
  507. package/dist/lib/memory/utils.js +156 -0
  508. package/dist/lib/memory/write-log.d.ts +85 -0
  509. package/dist/lib/memory/write-log.js +124 -0
  510. package/dist/lib/memory/write-quality.d.ts +197 -0
  511. package/dist/lib/memory/write-quality.js +314 -0
  512. package/dist/lib/orchestrator/branch.d.ts +63 -0
  513. package/dist/lib/orchestrator/branch.js +192 -0
  514. package/dist/lib/orchestrator/index.d.ts +14 -0
  515. package/dist/lib/orchestrator/index.js +11 -0
  516. package/dist/lib/orchestrator/locks.d.ts +46 -0
  517. package/dist/lib/orchestrator/locks.js +122 -0
  518. package/dist/lib/orchestrator/slop-scanner.d.ts +31 -0
  519. package/dist/lib/orchestrator/slop-scanner.js +207 -0
  520. package/dist/lib/orchestrator/workers.d.ts +453 -0
  521. package/dist/lib/orchestrator/workers.js +1001 -0
  522. package/dist/lib/public.d.ts +18 -0
  523. package/dist/lib/public.js +23 -0
  524. package/dist/lib/reasoning/advice-tracker.d.ts +51 -0
  525. package/dist/lib/reasoning/advice-tracker.js +177 -0
  526. package/dist/lib/reasoning/belief-policy-engine.d.ts +48 -0
  527. package/dist/lib/reasoning/belief-policy-engine.js +268 -0
  528. package/dist/lib/reasoning/belief-types.d.ts +32 -0
  529. package/dist/lib/reasoning/belief-types.js +8 -0
  530. package/dist/lib/reasoning/classifier-offline.d.ts +72 -0
  531. package/dist/lib/reasoning/classifier-offline.js +75 -0
  532. package/dist/lib/reasoning/dreamer.d.ts +37 -0
  533. package/dist/lib/reasoning/dreamer.js +169 -0
  534. package/dist/lib/reasoning/nudge-analytics.d.ts +18 -0
  535. package/dist/lib/reasoning/nudge-analytics.js +62 -0
  536. package/dist/lib/reasoning/policy-rules.d.ts +18 -0
  537. package/dist/lib/reasoning/policy-rules.js +153 -0
  538. package/dist/lib/reasoning/reasoning-metrics.d.ts +42 -0
  539. package/dist/lib/reasoning/reasoning-metrics.js +174 -0
  540. package/dist/lib/reasoning/reasoning-summary.d.ts +34 -0
  541. package/dist/lib/reasoning/reasoning-summary.js +122 -0
  542. package/dist/lib/reasoning/tool-usage-analyzer.d.ts +50 -0
  543. package/dist/lib/reasoning/tool-usage-analyzer.js +188 -0
  544. package/dist/lib/state/async-storage.d.ts +52 -0
  545. package/dist/lib/state/async-storage.js +171 -0
  546. package/dist/lib/state/extension-state.d.ts +184 -0
  547. package/dist/lib/state/extension-state.js +373 -0
  548. package/dist/lib/state/global-state.d.ts +358 -0
  549. package/dist/lib/state/global-state.js +741 -0
  550. package/dist/lib/state/metacognitive-state.d.ts +21 -0
  551. package/dist/lib/state/metacognitive-state.js +50 -0
  552. package/dist/lib/state/session-manager.d.ts +32 -0
  553. package/dist/lib/state/session-manager.js +11 -0
  554. package/dist/lib/state/session-start-queue.d.ts +42 -0
  555. package/dist/lib/state/session-start-queue.js +105 -0
  556. package/dist/lib/state/state-checkpoint.d.ts +72 -0
  557. package/dist/lib/state/state-checkpoint.js +252 -0
  558. package/dist/lib/state/telegram-poller-liveness.d.ts +54 -0
  559. package/dist/lib/state/telegram-poller-liveness.js +67 -0
  560. package/dist/lib/state/tool-provenance.d.ts +22 -0
  561. package/dist/lib/state/tool-provenance.js +25 -0
  562. package/dist/lib/state/workspace-snapshot.d.ts +111 -0
  563. package/dist/lib/state/workspace-snapshot.js +372 -0
  564. package/dist/lib/store/belief-store.d.ts +112 -0
  565. package/dist/lib/store/belief-store.js +252 -0
  566. package/dist/lib/store/bidirectional-verifier.d.ts +87 -0
  567. package/dist/lib/store/bidirectional-verifier.js +242 -0
  568. package/dist/lib/store/claim-tracker.d.ts +66 -0
  569. package/dist/lib/store/claim-tracker.js +276 -0
  570. package/dist/lib/store/conflict-qa.d.ts +96 -0
  571. package/dist/lib/store/conflict-qa.js +283 -0
  572. package/dist/lib/store/evidence-pool.d.ts +185 -0
  573. package/dist/lib/store/evidence-pool.js +598 -0
  574. package/dist/lib/telemetry/context-heartbeat.d.ts +122 -0
  575. package/dist/lib/telemetry/context-heartbeat.js +449 -0
  576. package/dist/lib/telemetry/drift-signals.d.ts +46 -0
  577. package/dist/lib/telemetry/drift-signals.js +75 -0
  578. package/dist/lib/telemetry/rss-telemetry.d.ts +41 -0
  579. package/dist/lib/telemetry/rss-telemetry.js +53 -0
  580. package/dist/lib/types/episode-types.d.ts +31 -0
  581. package/dist/lib/types/episode-types.js +9 -0
  582. package/dist/lib/types/standard-result.d.ts +32 -0
  583. package/dist/lib/types/standard-result.js +22 -0
  584. package/dist/lib/utils/async-fs.d.ts +17 -0
  585. package/dist/lib/utils/async-fs.js +22 -0
  586. package/dist/lib/utils/bounded.d.ts +38 -0
  587. package/dist/lib/utils/bounded.js +59 -0
  588. package/dist/lib/utils/dedup.d.ts +40 -0
  589. package/dist/lib/utils/dedup.js +43 -0
  590. package/dist/lib/utils/error-guard.d.ts +15 -0
  591. package/dist/lib/utils/error-guard.js +22 -0
  592. package/dist/lib/utils/extension-utils.d.ts +36 -0
  593. package/dist/lib/utils/extension-utils.js +65 -0
  594. package/dist/lib/utils/extract-json.d.ts +23 -0
  595. package/dist/lib/utils/extract-json.js +90 -0
  596. package/dist/lib/utils/file-mutation-queue.d.ts +33 -0
  597. package/dist/lib/utils/file-mutation-queue.js +150 -0
  598. package/dist/lib/utils/filter-safe-to-remove.d.ts +26 -0
  599. package/dist/lib/utils/filter-safe-to-remove.js +256 -0
  600. package/dist/lib/utils/format-tool-result.d.ts +47 -0
  601. package/dist/lib/utils/format-tool-result.js +88 -0
  602. package/dist/lib/utils/id.d.ts +44 -0
  603. package/dist/lib/utils/id.js +59 -0
  604. package/dist/lib/utils/injection-tracker.d.ts +317 -0
  605. package/dist/lib/utils/injection-tracker.js +840 -0
  606. package/dist/lib/utils/local-time.d.ts +57 -0
  607. package/dist/lib/utils/local-time.js +181 -0
  608. package/dist/lib/utils/memory-fence.d.ts +55 -0
  609. package/dist/lib/utils/memory-fence.js +66 -0
  610. package/dist/lib/utils/sop-extractor.d.ts +75 -0
  611. package/dist/lib/utils/sop-extractor.js +259 -0
  612. package/dist/lib/utils/sop-suggestion.d.ts +34 -0
  613. package/dist/lib/utils/sop-suggestion.js +336 -0
  614. package/dist/lib/utils/wake-gate.d.ts +151 -0
  615. package/dist/lib/utils/wake-gate.js +265 -0
  616. package/dist/lib/utils/whisper-format.d.ts +95 -0
  617. package/dist/lib/utils/whisper-format.js +115 -0
  618. package/dist/lib/verification/coordination-checker.d.ts +72 -0
  619. package/dist/lib/verification/coordination-checker.js +126 -0
  620. package/dist/loader/api.d.ts +19 -0
  621. package/dist/loader/api.js +114 -0
  622. package/dist/loader/loader.d.ts +85 -0
  623. package/dist/loader/loader.js +534 -0
  624. package/docs/BEGINNERS.md +166 -0
  625. package/docs/COMPACTION-LOSS-INVESTIGATION.md +179 -0
  626. package/docs/CONTEXT-MAP.md +220 -0
  627. package/docs/CONTEXT-POLICY.md +86 -0
  628. package/docs/HISTORY.md +110 -0
  629. package/docs/LOCAL_DEV.md +246 -0
  630. package/docs/ROADMAP.md +107 -0
  631. package/docs/SETUP.md +502 -0
  632. package/package.json +97 -4
  633. package/skills/agent-testing/SKILL.md +214 -0
  634. package/skills/braid-reference/SKILL.md +88 -0
  635. package/skills/code-refactoring/SKILL.md +211 -0
  636. package/skills/code-search/SKILL.md +14 -0
  637. package/skills/documentation/SKILL.md +89 -0
  638. package/skills/dox/AGENTS.md.template +83 -0
  639. package/skills/dox/SKILL.md +86 -0
  640. package/skills/healthcheck/SKILL.md +65 -0
  641. package/skills/herdr-topology/SKILL.md +269 -0
  642. package/skills/meta-cognition/SKILL.md +24 -0
  643. package/skills/meta-improvement/SKILL.md +180 -0
  644. package/skills/misdirection-audit/SKILL.md +66 -0
  645. package/skills/pi-reference/SKILL.md +104 -0
  646. package/skills/placement-discipline/SKILL.md +69 -0
  647. package/skills/probe-evaluation/SKILL.md +85 -0
  648. package/skills/release-pipeline/SKILL.md +191 -0
  649. package/skills/research/SKILL.md +166 -0
  650. package/skills/skill-usage/SKILL.md +81 -0
  651. package/skills/software-engineer/SKILL.md +83 -0
  652. package/skills/subagent-orchestration/SKILL.md +454 -0
  653. package/skills/subagent-orchestration/scripts/workers.mjs +283 -0
  654. package/skills/subagent-verification/SKILL.md +127 -0
  655. package/skills/tone-quality/SKILL.md +176 -0
  656. package/skills/voice-replies/SKILL.md +125 -0
  657. package/src/AGENTS.md +111 -0
  658. package/src/extensions/cognitive/AGENTS.md +29 -0
  659. package/src/extensions/cognitive/mars-reflector/index.ts +415 -0
  660. package/src/extensions/cognitive/metacognition/handlers/AGENTS.md +30 -0
  661. package/src/extensions/cognitive/metacognition/handlers/claim-verification.ts +295 -0
  662. package/src/extensions/cognitive/metacognition/handlers/finalize.ts +648 -0
  663. package/src/extensions/cognitive/metacognition/handlers/hypothesize.ts +368 -0
  664. package/src/extensions/cognitive/metacognition/handlers/scoring.ts +242 -0
  665. package/src/extensions/cognitive/metacognition/handlers/think-budget.ts +199 -0
  666. package/src/extensions/cognitive/metacognition/handlers/think.ts +489 -0
  667. package/src/extensions/cognitive/metacognition/handlers/verify.ts +440 -0
  668. package/src/extensions/cognitive/metacognition/index.ts +109 -0
  669. package/src/extensions/cognitive/reasoning/index.ts +168 -0
  670. package/src/extensions/cognitive/sycophancy-detector/index.ts +286 -0
  671. package/src/extensions/cognitive/topic-drift/index.ts +429 -0
  672. package/src/extensions/cognitive/turn-outcome/index.ts +209 -0
  673. package/src/extensions/context-management/README.md +102 -0
  674. package/src/extensions/context-management/index.ts +383 -0
  675. package/src/extensions/core/AGENTS.md +34 -0
  676. package/src/extensions/core/agent-environment/index.ts +135 -0
  677. package/src/extensions/core/polyfill/index.ts +617 -0
  678. package/src/extensions/core/prompt-builder/AGENTS.md +151 -0
  679. package/src/extensions/core/prompt-builder/awareness-whisper.ts +162 -0
  680. package/src/extensions/core/prompt-builder/context-section.ts +120 -0
  681. package/src/extensions/core/prompt-builder/custom-sections.ts +27 -0
  682. package/src/extensions/core/prompt-builder/external-tool-guidelines.ts +41 -0
  683. package/src/extensions/core/prompt-builder/identity.ts +98 -0
  684. package/src/extensions/core/prompt-builder/index.ts +602 -0
  685. package/src/extensions/core/prompt-builder/inspect.ts +227 -0
  686. package/src/extensions/core/prompt-builder/instance-composition.ts +515 -0
  687. package/src/extensions/core/prompt-builder/memory-section.ts +76 -0
  688. package/src/extensions/core/prompt-builder/pi-reference-section.ts +26 -0
  689. package/src/extensions/core/prompt-builder/project-docs-section.ts +105 -0
  690. package/src/extensions/core/prompt-builder/section-parity.ts +108 -0
  691. package/src/extensions/core/prompt-builder/section-publish.ts +43 -0
  692. package/src/extensions/core/prompt-builder/section.ts +150 -0
  693. package/src/extensions/core/prompt-builder/surface-discipline-section.ts +21 -0
  694. package/src/extensions/core/prompt-builder/system-info-tool.ts +87 -0
  695. package/src/extensions/core/prompt-builder/tool-description-trim.ts +127 -0
  696. package/src/extensions/core/prompt-builder/tool-guidelines.ts +226 -0
  697. package/src/extensions/core/prompt-builder/tool-pipelines.ts +78 -0
  698. package/src/extensions/core/prompt-builder/top-level-extensions.ts +338 -0
  699. package/src/extensions/core/skills-tool/auto-inject.ts +1004 -0
  700. package/src/extensions/core/skills-tool/index.ts +240 -0
  701. package/src/extensions/core/skills-tool/loading-guidance.ts +89 -0
  702. package/src/extensions/core/skills-tool/session-records.ts +328 -0
  703. package/src/extensions/core/skills-tool/skill-triggers.ts +119 -0
  704. package/src/extensions/enforcement/AGENTS.md +69 -0
  705. package/src/extensions/enforcement/detection/malformed.ts +42 -0
  706. package/src/extensions/enforcement/detection/verification.ts +52 -0
  707. package/src/extensions/enforcement/enforcement-types.ts +42 -0
  708. package/src/extensions/enforcement/handler-registry.ts +225 -0
  709. package/src/extensions/enforcement/handlers/AGENTS.md +68 -0
  710. package/src/extensions/enforcement/handlers/analysis/AGENTS.md +40 -0
  711. package/src/extensions/enforcement/handlers/analysis/bpe-handler.ts +53 -0
  712. package/src/extensions/enforcement/handlers/analysis/dreamer-handler.ts +73 -0
  713. package/src/extensions/enforcement/handlers/analysis/drift-handler.ts +100 -0
  714. package/src/extensions/enforcement/handlers/analysis/feedback-handler.ts +22 -0
  715. package/src/extensions/enforcement/handlers/analysis/mars-handler.ts +121 -0
  716. package/src/extensions/enforcement/handlers/analysis/reflection-handler.ts +22 -0
  717. package/src/extensions/enforcement/handlers/blocking.ts +50 -0
  718. package/src/extensions/enforcement/handlers/message-analysis.ts +95 -0
  719. package/src/extensions/enforcement/handlers/orphan-chains.ts +53 -0
  720. package/src/extensions/enforcement/handlers/over-correction-gate.ts +634 -0
  721. package/src/extensions/enforcement/handlers/probe-handler.ts +133 -0
  722. package/src/extensions/enforcement/handlers/register-adherence-meter.ts +216 -0
  723. package/src/extensions/enforcement/handlers/register-agent-end-api-error.ts +82 -0
  724. package/src/extensions/enforcement/handlers/register-input-handler.ts +36 -0
  725. package/src/extensions/enforcement/handlers/register-message-end.ts +477 -0
  726. package/src/extensions/enforcement/handlers/register-post-cycle-hygiene.ts +166 -0
  727. package/src/extensions/enforcement/handlers/register-session-compact.ts +248 -0
  728. package/src/extensions/enforcement/handlers/register-session-shutdown-resumption.ts +138 -0
  729. package/src/extensions/enforcement/handlers/register-session-shutdown.ts +46 -0
  730. package/src/extensions/enforcement/handlers/register-session-start-discoverability.ts +270 -0
  731. package/src/extensions/enforcement/handlers/register-session-start.ts +240 -0
  732. package/src/extensions/enforcement/handlers/register-tool-call.ts +160 -0
  733. package/src/extensions/enforcement/handlers/register-tool-result-formatting.ts +73 -0
  734. package/src/extensions/enforcement/handlers/register-tool-result.ts +108 -0
  735. package/src/extensions/enforcement/handlers/register-turn-end-hygiene.ts +456 -0
  736. package/src/extensions/enforcement/handlers/routing-handler.ts +191 -0
  737. package/src/extensions/enforcement/handlers/tool-tracker.ts +145 -0
  738. package/src/extensions/enforcement/handlers/turn-analysis.ts +156 -0
  739. package/src/extensions/enforcement/handlers/turn-end-handler.ts +538 -0
  740. package/src/extensions/enforcement/index.ts +28 -0
  741. package/src/extensions/enforcement/judge-utils.ts +106 -0
  742. package/src/extensions/enforcement/nudge-manager.ts +298 -0
  743. package/src/extensions/enforcement/self-state-claims.ts +204 -0
  744. package/src/extensions/enforcement/session-health.ts +317 -0
  745. package/src/extensions/enforcement/signals.ts +88 -0
  746. package/src/extensions/enforcement/similarity.ts +76 -0
  747. package/src/extensions/enforcement/state.ts +115 -0
  748. package/src/extensions/enforcement/substate/context-hygiene-state.ts +212 -0
  749. package/src/extensions/enforcement/substate/error-tracking-state.ts +50 -0
  750. package/src/extensions/enforcement/substate/memory-hygiene-state.ts +54 -0
  751. package/src/extensions/enforcement/substate/session-state.ts +79 -0
  752. package/src/extensions/enforcement/substate/thought-chain-state.ts +62 -0
  753. package/src/extensions/enforcement/substate/tool-tracking-state.ts +166 -0
  754. package/src/extensions/enforcement/substate/verification-judge-state.ts +52 -0
  755. package/src/extensions/enforcement/task-evidence.ts +436 -0
  756. package/src/extensions/enforcement/types.ts +38 -0
  757. package/src/extensions/enforcement/validation.ts +194 -0
  758. package/src/extensions/enforcement/verification-judge.ts +317 -0
  759. package/src/extensions/enforcement/whisper.ts +120 -0
  760. package/src/extensions/heartbeat/AGENTS.md +47 -0
  761. package/src/extensions/heartbeat/analytics/AGENTS.md +57 -0
  762. package/src/extensions/heartbeat/analytics/ab-variant.ts +106 -0
  763. package/src/extensions/heartbeat/analytics/core.ts +222 -0
  764. package/src/extensions/heartbeat/analytics/format.ts +144 -0
  765. package/src/extensions/heartbeat/analytics/index.ts +373 -0
  766. package/src/extensions/heartbeat/analytics/shared.ts +149 -0
  767. package/src/extensions/heartbeat/heartbeat-scheduler/AGENTS.md +84 -0
  768. package/src/extensions/heartbeat/heartbeat-scheduler/index.ts +1095 -0
  769. package/src/extensions/heartbeat/heartbeat-scheduler/meta-learning.ts +75 -0
  770. package/src/extensions/heartbeat/heartbeat-scheduler/modules/behavioral-drift.ts +200 -0
  771. package/src/extensions/heartbeat/heartbeat-scheduler/modules/budget.ts +113 -0
  772. package/src/extensions/heartbeat/heartbeat-scheduler/modules/context-hygiene.ts +288 -0
  773. package/src/extensions/heartbeat/heartbeat-scheduler/modules/evolver.ts +88 -0
  774. package/src/extensions/heartbeat/heartbeat-scheduler/modules/measurement.ts +47 -0
  775. package/src/extensions/heartbeat/heartbeat-scheduler/modules/recaller.ts +99 -0
  776. package/src/extensions/heartbeat/heartbeat-scheduler/modules/reflection-consolidator.ts +114 -0
  777. package/src/extensions/heartbeat/heartbeat-scheduler/policies.ts +193 -0
  778. package/src/extensions/heartbeat/heartbeat-scheduler/state.ts +88 -0
  779. package/src/extensions/heartbeat/heartbeat-scheduler/types.ts +128 -0
  780. package/src/extensions/heartbeat/heartbeat-scheduler/whisper-batcher.ts +98 -0
  781. package/src/extensions/manifest.ts +293 -0
  782. package/src/extensions/memory/AGENTS.md +93 -0
  783. package/src/extensions/memory/context-lifecycle/AGENTS.md +62 -0
  784. package/src/extensions/memory/context-lifecycle/helpers.ts +167 -0
  785. package/src/extensions/memory/context-lifecycle/index.ts +1232 -0
  786. package/src/extensions/memory/context-lifecycle/policy-engine.ts +287 -0
  787. package/src/extensions/memory/context-lifecycle/signal-detector.ts +293 -0
  788. package/src/extensions/memory/context-lifecycle/state.ts +165 -0
  789. package/src/extensions/memory/context-lifecycle/types.ts +441 -0
  790. package/src/extensions/memory/context-manager/analysis.ts +344 -0
  791. package/src/extensions/memory/context-manager/handlers/AGENTS.md +37 -0
  792. package/src/extensions/memory/context-manager/handlers/compaction-chunked.ts +800 -0
  793. package/src/extensions/memory/context-manager/handlers/compaction-retry.ts +556 -0
  794. package/src/extensions/memory/context-manager/handlers/compaction-trace.ts +243 -0
  795. package/src/extensions/memory/context-manager/handlers/compaction-watchdog.ts +366 -0
  796. package/src/extensions/memory/context-manager/handlers/compaction.ts +2552 -0
  797. package/src/extensions/memory/context-manager/handlers/context-emergency.ts +470 -0
  798. package/src/extensions/memory/context-manager/handlers/events.ts +430 -0
  799. package/src/extensions/memory/context-manager/handlers/navigation.ts +94 -0
  800. package/src/extensions/memory/context-manager/handlers/offload.ts +330 -0
  801. package/src/extensions/memory/context-manager/handlers/rotation.ts +363 -0
  802. package/src/extensions/memory/context-manager/handlers/shared.ts +961 -0
  803. package/src/extensions/memory/context-manager/handlers/tool-batch-boundary.ts +219 -0
  804. package/src/extensions/memory/context-manager/handlers/toolresult-capture-cap.ts +176 -0
  805. package/src/extensions/memory/context-manager/handlers/tools/context-compress.ts +1333 -0
  806. package/src/extensions/memory/context-manager/handlers/tools/context-inspect.ts +343 -0
  807. package/src/extensions/memory/context-manager/handlers/tools/context-navigate.ts +423 -0
  808. package/src/extensions/memory/context-manager/handlers/tools/offload-recover.ts +234 -0
  809. package/src/extensions/memory/context-manager/index.ts +111 -0
  810. package/src/extensions/memory/context-manager/pruning.ts +479 -0
  811. package/src/extensions/memory/context-manager/semantic-compress.ts +321 -0
  812. package/src/extensions/memory/memory-agent-bridge/AGENTS.md +62 -0
  813. package/src/extensions/memory/memory-agent-bridge/conflict-qa-tool.ts +106 -0
  814. package/src/extensions/memory/memory-agent-bridge/explore-paths.ts +283 -0
  815. package/src/extensions/memory/memory-agent-bridge/index.ts +163 -0
  816. package/src/extensions/memory/memory-agent-bridge/memory-store-tool.ts +284 -0
  817. package/src/extensions/memory/memory-agent-bridge/memory-tool.ts +746 -0
  818. package/src/extensions/memory/scratchpad/AGENTS.md +148 -0
  819. package/src/extensions/memory/scratchpad/format.ts +161 -0
  820. package/src/extensions/memory/scratchpad/handlers.ts +601 -0
  821. package/src/extensions/memory/scratchpad/index.ts +230 -0
  822. package/src/extensions/memory/scratchpad/persistence.ts +374 -0
  823. package/src/extensions/memory/scratchpad/types.ts +149 -0
  824. package/src/extensions/memory/scratchpad/utils.ts +268 -0
  825. package/src/extensions/memory/session-recall/AGENTS.md +104 -0
  826. package/src/extensions/memory/session-recall/analyze.ts +605 -0
  827. package/src/extensions/memory/session-recall/context-aggregate.ts +381 -0
  828. package/src/extensions/memory/session-recall/index.ts +956 -0
  829. package/src/extensions/memory/session-recall/query.ts +44 -0
  830. package/src/extensions/memory/session-recall/rank.ts +121 -0
  831. package/src/extensions/memory/session-recall/search.ts +801 -0
  832. package/src/extensions/memory/session-recall/stats.ts +93 -0
  833. package/src/extensions/memory/session-recall/text-utils.ts +209 -0
  834. package/src/extensions/memory/three-memory-stores/AGENTS.md +66 -0
  835. package/src/extensions/memory/three-memory-stores/episodes-disk.ts +138 -0
  836. package/src/extensions/memory/three-memory-stores/episodes.ts +371 -0
  837. package/src/extensions/memory/three-memory-stores/handlers/whisper-recall.ts +132 -0
  838. package/src/extensions/memory/three-memory-stores/heuristics.ts +109 -0
  839. package/src/extensions/memory/three-memory-stores/index.ts +549 -0
  840. package/src/extensions/memory/three-memory-stores/tool-reliability.ts +58 -0
  841. package/src/extensions/memory/three-memory-stores/types.ts +74 -0
  842. package/src/extensions/memory/workspace-snapshot/AGENTS.md +19 -0
  843. package/src/extensions/memory/workspace-snapshot/index.ts +455 -0
  844. package/src/extensions/orchestrator/index.ts +1141 -0
  845. package/src/extensions/scheduling/AGENTS.md +26 -0
  846. package/src/extensions/scheduling/timer/AGENTS.md +259 -0
  847. package/src/extensions/scheduling/timer/fire-timing.ts +46 -0
  848. package/src/extensions/scheduling/timer/index.ts +1331 -0
  849. package/src/extensions/scheduling/timer/poller.ts +138 -0
  850. package/src/extensions/scheduling/timer/recovery.ts +462 -0
  851. package/src/extensions/scheduling/timer/store-file.ts +59 -0
  852. package/src/extensions/scheduling/timer/timer-manager.ts +161 -0
  853. package/src/extensions/scheduling/timer/wake-retry.ts +1057 -0
  854. package/src/extensions/self/AGENTS.md +30 -0
  855. package/src/extensions/self/auto-recovery/index.ts +112 -0
  856. package/src/extensions/self/error-tracking/AGENTS.md +38 -0
  857. package/src/extensions/self/error-tracking/index.ts +299 -0
  858. package/src/extensions/self/health-maintenance/AGENTS.md +42 -0
  859. package/src/extensions/self/health-maintenance/format.ts +87 -0
  860. package/src/extensions/self/health-maintenance/handlers/session-health-tool.ts +182 -0
  861. package/src/extensions/self/health-maintenance/helpers.ts +78 -0
  862. package/src/extensions/self/health-maintenance/index.ts +308 -0
  863. package/src/extensions/self/health-maintenance/types.ts +14 -0
  864. package/src/extensions/self/latent-activator/AGENTS.md +64 -0
  865. package/src/extensions/self/latent-activator/index.ts +206 -0
  866. package/src/extensions/self/latent-activator/mixes.ts +22 -0
  867. package/src/extensions/self/latent-activator/signals.ts +237 -0
  868. package/src/extensions/self/latent-activator/state.ts +79 -0
  869. package/src/extensions/self/latent-activator/types.ts +47 -0
  870. package/src/extensions/self/watchdog/AGENTS.md +27 -0
  871. package/src/extensions/self/watchdog/config.ts +73 -0
  872. package/src/extensions/self/watchdog/engine.ts +1246 -0
  873. package/src/extensions/self/watchdog/index.ts +577 -0
  874. package/src/index.ts +93 -0
  875. package/src/lib/AGENTS.md +39 -0
  876. package/src/lib/ai/AGENTS.md +37 -0
  877. package/src/lib/ai/consolidated-claim-critic.ts +287 -0
  878. package/src/lib/ai/cost-report.ts +206 -0
  879. package/src/lib/ai/critic-cache.ts +122 -0
  880. package/src/lib/ai/critic-fallbacks.ts +74 -0
  881. package/src/lib/ai/critic-gate.ts +135 -0
  882. package/src/lib/ai/critic-helpers.ts +135 -0
  883. package/src/lib/ai/critic-registry.ts +754 -0
  884. package/src/lib/ai/critic-stats.ts +158 -0
  885. package/src/lib/ai/judge-budget.ts +241 -0
  886. package/src/lib/ai/language-hint.ts +70 -0
  887. package/src/lib/ai/llm-call.ts +975 -0
  888. package/src/lib/ai/model-resolver.ts +224 -0
  889. package/src/lib/ai/models-init.ts +68 -0
  890. package/src/lib/ai/payload-hygiene.ts +265 -0
  891. package/src/lib/ai/post-loop-classify.ts +185 -0
  892. package/src/lib/ai/text-classifier.ts +746 -0
  893. package/src/lib/cognitive/AGENTS.md +40 -0
  894. package/src/lib/cognitive/hints.ts +254 -0
  895. package/src/lib/cognitive/openspec.ts +124 -0
  896. package/src/lib/config/AGENTS.md +17 -0
  897. package/src/lib/config/braid-paths.ts +401 -0
  898. package/src/lib/config/braid-settings.ts +1442 -0
  899. package/src/lib/config/per-tool-settings.ts +197 -0
  900. package/src/lib/config/session-profiles.ts +165 -0
  901. package/src/lib/constants/AGENTS.md +15 -0
  902. package/src/lib/constants/injection-details.ts +32 -0
  903. package/src/lib/constants/session-thresholds.ts +64 -0
  904. package/src/lib/constants/tool-constants.ts +16 -0
  905. package/src/lib/core/AGENTS.md +23 -0
  906. package/src/lib/core/event-names.ts +31 -0
  907. package/src/lib/core/logger.ts +334 -0
  908. package/src/lib/detection/AGENTS.md +21 -0
  909. package/src/lib/detection/compression-strategy.ts +183 -0
  910. package/src/lib/detection/consolidated-topic-critic.ts +188 -0
  911. package/src/lib/detection/context-density.ts +237 -0
  912. package/src/lib/detection/context-thresholds.ts +132 -0
  913. package/src/lib/detection/context-tiers.ts +201 -0
  914. package/src/lib/detection/context-usage.ts +270 -0
  915. package/src/lib/detection/degradation-detector.ts +583 -0
  916. package/src/lib/detection/test-burst.ts +170 -0
  917. package/src/lib/detection/tool-loop-detector.ts +364 -0
  918. package/src/lib/detection/topic-drift-detector.ts +323 -0
  919. package/src/lib/enforcement/AGENTS.md +20 -0
  920. package/src/lib/enforcement/adherence-meter.ts +578 -0
  921. package/src/lib/enforcement/turn-dedup.ts +246 -0
  922. package/src/lib/errors/llm-error.ts +288 -0
  923. package/src/lib/events/AGENTS.md +23 -0
  924. package/src/lib/events/consolidation-channel.ts +493 -0
  925. package/src/lib/events/consolidation-scoring.ts +112 -0
  926. package/src/lib/events/event-bus.ts +213 -0
  927. package/src/lib/events/event-types.ts +53 -0
  928. package/src/lib/events/timer-bus.ts +53 -0
  929. package/src/lib/events/timer-types.ts +64 -0
  930. package/src/lib/events/turn-end-coordinator.ts +108 -0
  931. package/src/lib/harness/AGENTS.md +20 -0
  932. package/src/lib/harness/failure-trace-collector.ts +157 -0
  933. package/src/lib/harness/index.ts +41 -0
  934. package/src/lib/harness/types.ts +122 -0
  935. package/src/lib/harness/weakness-miner.ts +209 -0
  936. package/src/lib/memory/AGENTS.md +36 -0
  937. package/src/lib/memory/constants.ts +34 -0
  938. package/src/lib/memory/index.ts +705 -0
  939. package/src/lib/memory/lifecycle.ts +159 -0
  940. package/src/lib/memory/past-insights.ts +221 -0
  941. package/src/lib/memory/storage.ts +187 -0
  942. package/src/lib/memory/store-lock.ts +70 -0
  943. package/src/lib/memory/store-merge.ts +100 -0
  944. package/src/lib/memory/types.ts +82 -0
  945. package/src/lib/memory/utils.ts +173 -0
  946. package/src/lib/memory/write-log.ts +174 -0
  947. package/src/lib/memory/write-quality.ts +383 -0
  948. package/src/lib/orchestrator/branch.ts +193 -0
  949. package/src/lib/orchestrator/index.ts +78 -0
  950. package/src/lib/orchestrator/locks.ts +160 -0
  951. package/src/lib/orchestrator/slop-scanner.ts +258 -0
  952. package/src/lib/orchestrator/workers.ts +1382 -0
  953. package/src/lib/public.ts +43 -0
  954. package/src/lib/reasoning/AGENTS.md +25 -0
  955. package/src/lib/reasoning/advice-tracker.ts +244 -0
  956. package/src/lib/reasoning/belief-policy-engine.ts +342 -0
  957. package/src/lib/reasoning/belief-types.ts +45 -0
  958. package/src/lib/reasoning/classifier-offline.ts +111 -0
  959. package/src/lib/reasoning/dreamer.ts +215 -0
  960. package/src/lib/reasoning/nudge-analytics.ts +85 -0
  961. package/src/lib/reasoning/policy-rules.ts +172 -0
  962. package/src/lib/reasoning/reasoning-metrics.ts +202 -0
  963. package/src/lib/reasoning/reasoning-summary.ts +154 -0
  964. package/src/lib/reasoning/tool-usage-analyzer.ts +248 -0
  965. package/src/lib/state/AGENTS.md +192 -0
  966. package/src/lib/state/async-storage.ts +189 -0
  967. package/src/lib/state/extension-state.ts +419 -0
  968. package/src/lib/state/global-state.ts +1046 -0
  969. package/src/lib/state/metacognitive-state.ts +65 -0
  970. package/src/lib/state/session-manager.ts +43 -0
  971. package/src/lib/state/session-start-queue.ts +135 -0
  972. package/src/lib/state/state-checkpoint.ts +352 -0
  973. package/src/lib/state/telegram-poller-liveness.ts +75 -0
  974. package/src/lib/state/tool-provenance.ts +26 -0
  975. package/src/lib/state/workspace-snapshot.ts +466 -0
  976. package/src/lib/store/AGENTS.md +24 -0
  977. package/src/lib/store/belief-store.ts +325 -0
  978. package/src/lib/store/bidirectional-verifier.ts +316 -0
  979. package/src/lib/store/claim-tracker.ts +382 -0
  980. package/src/lib/store/conflict-qa.ts +385 -0
  981. package/src/lib/store/evidence-pool.ts +779 -0
  982. package/src/lib/telemetry/AGENTS.md +28 -0
  983. package/src/lib/telemetry/context-heartbeat.ts +555 -0
  984. package/src/lib/telemetry/drift-signals.ts +105 -0
  985. package/src/lib/telemetry/rss-telemetry.ts +57 -0
  986. package/src/lib/types/AGENTS.md +21 -0
  987. package/src/lib/types/episode-types.ts +31 -0
  988. package/src/lib/types/standard-result.ts +40 -0
  989. package/src/lib/utils/AGENTS.md +30 -0
  990. package/src/lib/utils/async-fs.ts +23 -0
  991. package/src/lib/utils/bounded.ts +58 -0
  992. package/src/lib/utils/dedup.ts +44 -0
  993. package/src/lib/utils/error-guard.ts +27 -0
  994. package/src/lib/utils/extension-utils.ts +72 -0
  995. package/src/lib/utils/extract-json.ts +89 -0
  996. package/src/lib/utils/file-mutation-queue.ts +172 -0
  997. package/src/lib/utils/filter-safe-to-remove.ts +301 -0
  998. package/src/lib/utils/format-tool-result.ts +109 -0
  999. package/src/lib/utils/id.ts +64 -0
  1000. package/src/lib/utils/injection-tracker.ts +1014 -0
  1001. package/src/lib/utils/local-time.ts +196 -0
  1002. package/src/lib/utils/memory-fence.ts +70 -0
  1003. package/src/lib/utils/sop-extractor.ts +329 -0
  1004. package/src/lib/utils/sop-suggestion.ts +426 -0
  1005. package/src/lib/utils/wake-gate.ts +318 -0
  1006. package/src/lib/utils/whisper-format.ts +120 -0
  1007. package/src/lib/verification/coordination-checker.ts +183 -0
  1008. package/src/loader/AGENTS.md +32 -0
  1009. package/src/loader/api.ts +138 -0
  1010. package/src/loader/loader.ts +600 -0
  1011. package/src/types/extension-context.d.ts +85 -0
@@ -0,0 +1,1143 @@
1
+ /**
2
+ * Timer Extension - Non-blocking Pomodoro-style reminders
3
+ *
4
+ * Agent sets a timer, continues working, gets a reminder when it fires.
5
+ * This replaces bash `sleep` which blocks the tool call.
6
+ *
7
+ * Session scoping:
8
+ * Timers are stored per-session (keyed by ctx.sessionManager.getSessionId()).
9
+ * Each pi session has its own poller that only fires its own timers.
10
+ * This prevents cross-session leaks: when session A's context_compress
11
+ * cancels its resume timers, session B's resume timers are untouched.
12
+ *
13
+ * The sessionId is required for cancelTimersByTag() (fail fast) and is
14
+ * stamped on each ScheduledTimer for traceability.
15
+ *
16
+ * Single-process-per-session assumption:────────
17
+ * The `poller` below is a closure-captured `let` inside the extension
18
+ * factory. Each call to `timerExtension(pi)` creates a fresh closure
19
+ * with its own `poller` variable, which is correct for the standard
20
+ * pi lifecycle (one process per session, one extension registration
21
+ * per session, one poller per session).
22
+ *
23
+ * The assumption breaks if a single Node process ever runs MORE THAN
24
+ * ONE pi session concurrently, because the `poller`, `sessionState`,
25
+ * and `sessionIdResolved` closures would conflict. The `TimerManager`
26
+ * class (above) is already keyed by sessionId and is safe across
27
+ * concurrent sessions; only the extension-factory state is not.
28
+ *
29
+ * If multi-session-per-process ever becomes a real requirement, the
30
+ * fix is to migrate `poller` and `sessionState` to
31
+ * `getExtensionState(ctx, "timer", ...)` keyed by the ctx's session
32
+ * id. The factory pattern of getExtensionState doesn't accept ctx in
33
+ * the factory closure, so this requires either (a) adding a
34
+ * `setExtensionState` setter or (b) a custom WeakMap. Documented
35
+ * here so future contributors know the assumption is load-bearing.
36
+ *
37
+ * A debug-mode counter (`_extensionFactoryCallCount`) at the bottom
38
+ * of this file logs a warning if `timerExtension(pi)` is called more
39
+ * than once in the same process. In dev/CI this catches the
40
+ * accidental double-registration early.
41
+ */
42
+ import { createLogger } from "../../../lib/core/logger.js";
43
+ import { Type } from "typebox";
44
+ import { sendTrackedMessage } from "../../../lib/utils/injection-tracker.js";
45
+ import { getSessionIdSafe } from "../../../lib/state/extension-state.js";
46
+ import { getTimerExtensionFactoryState, getTurnStartGate, } from "../../../lib/state/global-state.js";
47
+ import { readFileSync, existsSync, mkdirSync, appendFileSync } from "node:fs";
48
+ import { dirname } from "node:path";
49
+ import { getTimerFilePath } from "../../../lib/config/braid-paths.js";
50
+ import { getTerminalBreakerConfig, getWakeDeliveryAlertConfig, } from "../../../lib/config/braid-settings.js";
51
+ import { getWatchdogWakeDeliveryFeed, setWatchdogWakeDueProvider, } from "../../../lib/state/global-state.js";
52
+ import { formatLocalTime } from "../../../lib/utils/local-time.js";
53
+ import { describeFireTiming } from "./fire-timing.js";
54
+ /** Get the timer file path for the current process CWD.
55
+ * Each project CWD has its own timer file for independent timer pools. */
56
+ function timerFilePath() {
57
+ return getTimerFilePath(process.cwd());
58
+ }
59
+ function loadPendingTimers() {
60
+ try {
61
+ const file = timerFilePath();
62
+ if (!existsSync(file))
63
+ return [];
64
+ const raw = readFileSync(file, "utf-8").trim();
65
+ if (!raw)
66
+ return [];
67
+ return raw.split("\n").map((line) => JSON.parse(line));
68
+ }
69
+ catch {
70
+ return [];
71
+ }
72
+ }
73
+ function savePendingTimers(timers) {
74
+ try {
75
+ writeTimerStore(timerFilePath(), timers.map((t) => JSON.stringify(t)));
76
+ }
77
+ catch (err) {
78
+ // Swallowing a persist failure silently drops every pending timer on
79
+ // restart — surface it, but never break the timer fire path.
80
+ log.warn(`timer persistence failed (timers lost on restart): ${err}`);
81
+ }
82
+ }
83
+ function persistTimerToDisk(timer) {
84
+ try {
85
+ const file = timerFilePath();
86
+ mkdirSync(dirname(file), { recursive: true });
87
+ appendFileSync(file, JSON.stringify(timer) + "\n", "utf-8");
88
+ }
89
+ catch (err) {
90
+ // Silent loss here means the timer never fires after restart.
91
+ log.warn(`timer append failed (timer lost on restart): ${err}`);
92
+ }
93
+ }
94
+ function removeTimerFromDisk(id) {
95
+ const timers = loadPendingTimers().filter((t) => t.id !== id);
96
+ savePendingTimers(timers);
97
+ }
98
+ /**
99
+ * Persist a recurring timer's re-arm: read-modify-write that replaces the
100
+ * line with the matching id (new firesAt / intervalMs) or appends it if
101
+ * missing. Never called for one-shot timers — those use removeTimerFromDisk.
102
+ */
103
+ function rearmTimerOnDisk(timer) {
104
+ const timers = loadPendingTimers().filter((t) => t.id !== timer.id);
105
+ timers.push(timer);
106
+ savePendingTimers(timers);
107
+ }
108
+ import { BRAID_INJECTED, BRAID_SOURCE } from "../../../lib/constants/injection-details.js";
109
+ import { TimerPoller } from "./poller.js";
110
+ import { wakeRetryQueue, flushRecoveredFires } from "./wake-retry.js";
111
+ import { recoverPersistedTimers, sweepProjectStoresRetention } from "./recovery.js";
112
+ import { writeTimerStore } from "./store-file.js";
113
+ const log = createLogger("timer");
114
+ import { TimerManager, timerManager } from "./timer-manager.js";
115
+ export { TimerManager, timerManager };
116
+ /**
117
+ * Defensive sessionId extraction. Returns "anonymous" if the ctx is missing
118
+ * or sessionManager is unavailable - those timers will be cancelled together
119
+ * in the "anonymous" bucket. Prefer passing a real sessionId.
120
+ *
121
+ * Delegates to the canonical `getSessionIdSafe` helper in
122
+ * `lib/state/extension-state.ts` — one implementation of the typed
123
+ * extraction, not per-caller `as` casts.
124
+ */
125
+ function getSessionId(ctx) {
126
+ return getSessionIdSafe(ctx) ?? "anonymous";
127
+ }
128
+ /**
129
+ * Programmatic timer API - schedule a timer for a specific session.
130
+ * Returns the timer ID. Timer fires and delivers a CustomMessage
131
+ * (whisper-style) that wakes the agent when wake: true.
132
+ *
133
+ * @param wake if true (default), the fire delivers a CustomMessage
134
+ * (pi.sendMessage with customType "timer-fire" and triggerTurn: true).
135
+ * This shows as a whisper in the TUI, not a filled-in input box, and
136
+ * wakes the agent immediately (subject to the busy guard which defers
137
+ * mid-tool-execution to TOOL_EXECUTION_END). This is the right path
138
+ * for automatic timers (post-compaction auto-resume, agent-scheduled
139
+ * reminders): no human is typing, and the input box should not be
140
+ * filled with "[TIMER FIRED]". Pass wake: false for silent reminders
141
+ * (visible in TUI but no forced turn) - used by background heartbeats.
142
+ */
143
+ export function scheduleTimer(sessionId, delayMs, reason, tag, wake = true, intervalMs, count) {
144
+ const id = timerManager.setTimer(sessionId, delayMs, reason, tag, wake, intervalMs, count);
145
+ persistTimerToDisk({
146
+ id,
147
+ sessionId,
148
+ firesAt: Date.now() + delayMs,
149
+ reason: reason ?? "Timer",
150
+ tag,
151
+ createdAt: Date.now(),
152
+ wake,
153
+ ...(intervalMs ? { intervalMs } : {}),
154
+ ...(count !== undefined ? { count } : {}),
155
+ ...(intervalMs ? { fires: 0 } : {}),
156
+ });
157
+ return id;
158
+ }
159
+ /** Cancel a timer by ID in a specific session.
160
+ *
161
+ * Cancel retires the fire: the timer's outstanding wake, armed retry
162
+ * ladder, and parked recovered fires are withdrawn with it, so no further
163
+ * redeliveries fire for a timer the owner cancelled. Retires even when the
164
+ * manager lookup misses — a fired one-shot leaves the manager at expiry
165
+ * (delete-on-detection) but its wake ladder may still be armed; the cancel
166
+ * must reach it. Returns the manager-cancel result (true only if a live
167
+ * timer was removed). */
168
+ export function cancelTimer(sessionId, id) {
169
+ const cancelled = timerManager.cancelTimer(sessionId, id);
170
+ if (cancelled)
171
+ removeTimerFromDisk(id);
172
+ wakeRetryQueue.retireTimer(id);
173
+ return cancelled;
174
+ }
175
+ /**
176
+ * Restore a persisted timer into memory without writing to disk
177
+ * (the disk entry already exists). Used by process-restart recovery
178
+ * to re-arm unexpired timers so the poller fires them on schedule.
179
+ * Returns the new in-memory timer id.
180
+ */
181
+ export function restoreTimer(sessionId, delayMs, reason, tag, wake, intervalMs, count, firedCount) {
182
+ return timerManager.setTimer(sessionId, delayMs, reason, tag, wake, intervalMs, count, firedCount);
183
+ }
184
+ /** List all active timers for a session. Sorted by firesAt. */
185
+ export function listTimers(sessionId) {
186
+ return timerManager.listTimers(sessionId);
187
+ }
188
+ /**
189
+ * Cancel all active timers for a session matching a tag.
190
+ * Used by compaction paths to invalidate stale resume timers from a
191
+ * previous compaction cycle. CRITICAL: only cancels the given session's
192
+ * timers - does NOT touch other sessions running in the same process.
193
+ * Returns the number of timers cancelled.
194
+ *
195
+ * Cancel retires the fire: every matching timer's wake state (outstanding
196
+ * wake, armed ladder, parked recovered fires) is withdrawn via the queue's
197
+ * own records — which also reaches fired one-shots whose live timer is
198
+ * already gone from the manager map but whose wake ladder is still armed.
199
+ */
200
+ export function cancelTimersByTag(sessionId, tag) {
201
+ wakeRetryQueue.retireTimersWhere((t) => t.sessionId === sessionId && t.tag === tag);
202
+ return timerManager.cancelTimersByTag(sessionId, tag);
203
+ }
204
+ /** Clear all timers for a session. Used on session_shutdown to free memory.
205
+ * Also retires the session's wake fires: a shut-down session's timers can
206
+ * never fire again, and their armed ladders must not outlive the session
207
+ * (a lingering retry would otherwise redeliver into whatever session is
208
+ * live in this process next). */
209
+ export function clearSessionTimers(sessionId) {
210
+ wakeRetryQueue.retireTimersWhere((t) => t.sessionId === sessionId);
211
+ return timerManager.clearSession(sessionId);
212
+ }
213
+ // Fire Handlers (via shared bus)
214
+ // We import the shared bus to bridge timer fires -> heartbeat surfacing
215
+ import { emitTimerReminder } from "../../../lib/events/timer-bus.js";
216
+ import { TURN_END, TOOL_CALL, TOOL_EXECUTION_END, SESSION_SHUTDOWN, SESSION_START, AGENT_SETTLED, AGENT_END, } from "../../../lib/core/event-names.js";
217
+ // Fire Handlers (via shared bus)
218
+ // Real-time polling (per-pi instance)
219
+ // Timer expiry checked every second - independent of turn_end so timers fire
220
+ // even when the agent is between turns or blocked in a long tool call.
221
+ // This is the primary fire mechanism; turn_end is a backup.
222
+ //
223
+ // TimerPoller extracted to ./poller.ts. The class is constructed with
224
+ // callbacks for expired-timer lookup and fire (so it doesn't depend on
225
+ // the closure-scoped timerManager and fireTimer in this file).
226
+ /**
227
+ * Should this wake fire run without starting a turn?
228
+ *
229
+ * Consumer gate for the terminal-error breaker: the scheduling layer asks the
230
+ * published turn-start gate one latch question and nothing else — why a turn
231
+ * is blocked stays entirely on the publisher's side of the seam. The flag is
232
+ * read once per fire. Fail-open on a missing ctx, a missing gate or a broken
233
+ * reader — a wake must never be silently swallowed by a health lookup; the
234
+ * reminder is still delivered, just non-waking, when the latch is open.
235
+ */
236
+ function terminalBreakerBlocksWake(ctx) {
237
+ try {
238
+ if (!ctx)
239
+ return false;
240
+ const cfg = getTerminalBreakerConfig();
241
+ if (!cfg.enabled)
242
+ return false;
243
+ const gate = getTurnStartGate();
244
+ if (!gate)
245
+ return false;
246
+ return gate.isBlocked(ctx, cfg.threshold);
247
+ }
248
+ catch {
249
+ return false;
250
+ }
251
+ }
252
+ /** The non-waking delivery of a fire whose wake is suppressed. Same message,
253
+ * `{ delivery: "park", deliverAs: "steer" }`: visible in the TUI, no turn. */
254
+ function deliverDemotedFire(pi, params) {
255
+ try {
256
+ sendTrackedMessage(pi, {
257
+ customType: params.customType,
258
+ content: [{ type: "text", text: params.text }],
259
+ display: true,
260
+ details: params.details,
261
+ }, { delivery: "park", deliverAs: "steer" }, { type: "heartbeat", source: "timer/fire" }, { bypassFloodCap: true });
262
+ }
263
+ catch (e) {
264
+ log.warn(`[timer] demoted fire delivery failed (agent may be mid-turn): ${e.message}`);
265
+ }
266
+ }
267
+ function fireTimer(timer, pi, ctx) {
268
+ // Cancel retires the fire: a timer cancelled in the deferred-fire window
269
+ // (checkExpired returned it, the setTimeout(0) delivery not yet run) must
270
+ // not deliver. The manager map entry is already gone (delete-on-
271
+ // detection), so this mark is the only thing that can win the race.
272
+ if (wakeRetryQueue.isRetired(timer.id)) {
273
+ log.info(`[timer] fire suppressed — timer cancelled before delivery: ${timer.id}`);
274
+ return;
275
+ }
276
+ emitTimerReminder(timer); // -> heartbeat bus -> agent reminder on next tick
277
+ log.info(`[timer] fired: ${timer.id} (session=${timer.sessionId}) - ${timer.reason}`);
278
+ // Recurring timers (intervalMs set) are NOT removed from disk on fire —
279
+ // they are re-armed instead, so the interval lives across a reload. The
280
+ // next firesAt (and the post-fire fires counter) is read from the live map
281
+ // entry, which checkExpired() already re-armed synchronously (in-place)
282
+ // before this deferred fire ran.
283
+ //
284
+ // If the lookup misses, the live entry is gone: either the timer was
285
+ // cancelled in the deferred-fire window (agent cancelled between expiry
286
+ // detection and this callback), OR its count bound exhausted and
287
+ // checkExpired removed it as completed. In BOTH cases the disk entry is
288
+ // removed so cancel wins and a finished recurrence cannot resurrect on
289
+ // the next reload.
290
+ if (timer.intervalMs && timer.intervalMs > 0) {
291
+ const live = timerManager.listTimers(timer.sessionId ?? "").find((t) => t.id === timer.id);
292
+ if (live) {
293
+ // Re-armed (unbounded, or bounded with fires remaining): persist the
294
+ // new cadence so the recurrence lives across a reload. `live` carries
295
+ // the post-fire fires counter; the count bound is preserved verbatim.
296
+ rearmTimerOnDisk({
297
+ id: timer.id,
298
+ sessionId: timer.sessionId ?? "anonymous",
299
+ firesAt: live.firesAt,
300
+ reason: timer.reason,
301
+ tag: timer.tag,
302
+ createdAt: timer.createdAt,
303
+ wake: timer.wake === true,
304
+ intervalMs: timer.intervalMs,
305
+ count: timer.count,
306
+ fires: live.fires ?? 0,
307
+ });
308
+ }
309
+ else {
310
+ // The live entry is gone: either the timer was cancelled in the
311
+ // deferred-fire window (cancel wins — don't resurrect it on reload)
312
+ // OR its count bound exhausted and checkExpired removed it as
313
+ // completed. In BOTH cases the disk entry must go: a finished or
314
+ // cancelled recurrence must not fire again on the next restart.
315
+ removeTimerFromDisk(timer.id);
316
+ }
317
+ }
318
+ else {
319
+ // One-shot: remove from disk persistence so it doesn't fire again on
320
+ // next restart.
321
+ removeTimerFromDisk(timer.id);
322
+ }
323
+ // Timer honesty:
324
+ // Every fire renders scheduled vs actual fire time + drift in the owner
325
+ // TZ (the ONE formatter). Timers can fire late (busy agent, mid-tool
326
+ // deferral, process gap) — the agent needs the drift to reason about
327
+ // what "5 minutes" actually meant. Example:
328
+ // set for 16:58 MSK (UTC+3), fired 17:05 MSK (UTC+3) — drift 7m
329
+ // Recovered fires reuse the exact same marker (fire-timing.ts).
330
+ const { fireTiming, elapsedSec } = describeFireTiming(timer.createdAt, timer.firesAt, Date.now());
331
+ // Two delivery paths based on `wake`:
332
+ //
333
+ // wake: true (DEFAULT for all timers — one-shot AND recurring — since
334
+ // silent requires an explicit wake:false)
335
+ // -> pi.sendMessage({ customType, content, display: true }, { triggerTurn: true })
336
+ // A CustomMessage (whisper-style in TUI, distinguishable from
337
+ // user input) that wakes the agent. Per SDK docs:
338
+ // 'sendUserMessage ... sends an actual user message that appears
339
+ // as if typed by the user. Always triggers a turn.' That is the
340
+ // WRONG behavior for an automatic timer: no human is typing, and
341
+ // filling the input box with "[TIMER FIRED]" looks nonsensical
342
+ // in the TUI. sendMessage + triggerTurn:true is the correct path
343
+ // for automatic wake-ups.
344
+ //
345
+ // Why not deliverAs:'steer'? The 'steer' mode defers delivery
346
+ // until the current tool call finishes, which means if the agent
347
+ // is mid-tool when a resume timer fires, the wake is delayed. For
348
+ // 'remind me in 5 min' that's acceptable. For post-compaction
349
+ // auto-resume it's bad: the agent may be idle, and we want the
350
+ // wake to land NOW. triggerTurn:true handles both: if the agent
351
+ // is idle it triggers immediately; if it's mid-stream, the busy
352
+ // guard (TOOL_EXECUTION_END fallback in the poller) defers to
353
+ // the next non-busy tick. We do NOT use deliverAs:'steer' here
354
+ // to avoid the SDK's own deferral that ignores mid-tool state.
355
+ //
356
+ // HARDENING (busy-send deferral): sending { triggerTurn: true } with NO
357
+ // deliverAs is the residual exposure — a deferred wake landing while
358
+ // the session is busy (isStreaming=false: the prompt() pre-flight, the
359
+ // compaction boundary, or a compaction that outlived the wake-gate's
360
+ // fail-safe) would make pi-core start a COMPETING agent run and the
361
+ // outer prompt() throws pi-core's activeRun guard. Two layers cover
362
+ // this at send time (see lib/utils/wake-gate.ts): the state-based
363
+ // busy check defers the wake into the wake-retry queue (the onBusy
364
+ // hook below) whenever the session is busy at send time, and the
365
+ // run-region gate in injection-tracker additionally rewrites such a
366
+ // wake to a queued steer while a run region is active.
367
+ //
368
+ // wake: false (silent reminder, used for background heartbeats etc.)
369
+ // -> sendTrackedMessage (custom-message whisper, per-source cap applies)
370
+ // Whisper is visible in TUI and survives compaction (via
371
+ // _braidInjected) but does NOT force a new turn.
372
+ //
373
+ // Both paths are wrapped by the [braid-whisper - timer] envelope via
374
+ // sendTrackedMessage, so the agent can recognize them in the conversation
375
+ // stream. wake: true includes the elapsed time for context.
376
+ if (timer.wake === true) {
377
+ const wakeText = `${timer.reason} - ${fireTiming}. ${elapsedSec}s elapsed since scheduled. Resume the task.`;
378
+ // Terminal-error breaker open: deliver the reminder without starting a
379
+ // turn, and do NOT track it — there is no turn whose outcome could retry.
380
+ if (terminalBreakerBlocksWake(ctx)) {
381
+ log.info(`[timer] wake demoted to non-waking (turn-start blocked): ${timer.id}`);
382
+ deliverDemotedFire(pi, {
383
+ customType: "timer-fire",
384
+ text: wakeText,
385
+ details: {
386
+ [BRAID_INJECTED]: true,
387
+ [BRAID_SOURCE]: "timer/fire",
388
+ timerId: timer.id,
389
+ sessionId: timer.sessionId,
390
+ wake: true,
391
+ elapsedSec,
392
+ breakerSuppressed: true,
393
+ },
394
+ });
395
+ return;
396
+ }
397
+ // Track the wake BEFORE delivery so its turn outcome is resolved
398
+ // at agent_end/agent_settled — a provider 401/413/5xx on the wake turn
399
+ // re-arms this fire for a bounded-backoff redelivery instead of leaving
400
+ // the content stuck in history until an unrelated turn.
401
+ wakeRetryQueue.trackWake(timer);
402
+ const text = wakeText;
403
+ // sendTrackedMessage (unified delivery path). bypassFloodCap ensures
404
+ // the timer fire reaches the agent even when 2+ timer fires already
405
+ // happened in this turn (per-source cap would otherwise drop this one).
406
+ // trackInjection records the wake for observability.
407
+ try {
408
+ sendTrackedMessage(pi, {
409
+ customType: "timer-fire",
410
+ content: [{ type: "text", text }],
411
+ display: true,
412
+ details: {
413
+ _braidInjected: true,
414
+ _braidSource: "timer/fire",
415
+ timerId: timer.id,
416
+ sessionId: timer.sessionId,
417
+ wake: true,
418
+ elapsedSec,
419
+ },
420
+ }, { triggerTurn: true }, { type: "heartbeat", source: "timer/fire" }, { bypassFloodCap: true }, {
421
+ // Cancel retires the wake while this send waits for its macrotask
422
+ // (the isRetired guard at fireTimer's entry ran before that
423
+ // window): the seam asks again at send time and drops it.
424
+ isWithdrawn: () => wakeRetryQueue.isRetired(timer.id),
425
+ // Session busy at send time (compaction / pre-flight window):
426
+ // park the fire for redelivery on a later tick instead of
427
+ // sending a raw triggerTurn into a busy session.
428
+ onBusy: () => wakeRetryQueue.deferBusyWake(timer, 0),
429
+ });
430
+ }
431
+ catch (e) {
432
+ log.warn(`[timer] whisper-wake delivery failed: ${e.message}`);
433
+ }
434
+ }
435
+ else {
436
+ const text = `${timer.reason} (${fireTiming})`;
437
+ // sendTrackedMessage (unified delivery path). bypassFloodCap ensures
438
+ // the silent reminder reaches the agent even when 2+ timer fires
439
+ // already happened in this turn. See wake:true branch above for the
440
+ // rationale.
441
+ try {
442
+ sendTrackedMessage(pi, {
443
+ customType: "timer",
444
+ content: [{ type: "text", text }],
445
+ display: true,
446
+ details: {
447
+ [BRAID_INJECTED]: true,
448
+ [BRAID_SOURCE]: "timer/fire",
449
+ timerId: timer.id,
450
+ sessionId: timer.sessionId,
451
+ wake: false,
452
+ },
453
+ }, { delivery: "park", deliverAs: "steer" }, { type: "heartbeat", source: "timer/fire" }, { bypassFloodCap: true });
454
+ }
455
+ catch (e) {
456
+ log.warn(`[timer] steer delivery failed (agent may be mid-turn): ${e.message}`);
457
+ }
458
+ }
459
+ }
460
+ // failed-wake redelivery
461
+ /**
462
+ * Re-deliver a wake fire after its backoff elapsed: either its turn FAILED
463
+ * (provider 401/413/5xx) or its send was DEFERRED while the session was busy
464
+ * (cause "busy" — the redelivery text says held, not failed). Called from
465
+ * the drain callback on poll ticks and the TOOL_EXECUTION_END / TURN_END
466
+ * path — each call is deferred via setTimeout(0) so the redelivery keeps the
467
+ * same macrotask discipline as the primary fireTimer path. The redelivery
468
+ * re-tracks the wake so a second failure escalates the backoff tier; a
469
+ * redelivery landing in a busy session is parked again (onBusy hook); after
470
+ * the effective cap (default 3, braid.timers.maxWakeAttempts) the fire is
471
+ * dropped with a visible notice + error log (never silently lost).
472
+ */
473
+ function redeliverWakeFire(pi, timer, attempt, cause = "failed", ctx) {
474
+ // Cancel retires the fire: a retry popped from the ladder but not yet sent
475
+ // (drainDue -> setTimeout(0)) must not deliver for a cancelled timer. The
476
+ // redelivery is not re-tracked, so no chain continues from it.
477
+ if (wakeRetryQueue.isRetired(timer.id)) {
478
+ log.info(`[timer] wake retry suppressed — timer cancelled since the retry was armed: ${timer.id}`);
479
+ return;
480
+ }
481
+ const maxAttempts = wakeRetryQueue.getMaxAttempts();
482
+ const heldNote = cause === "busy"
483
+ ? "held while the session was busy; re-delivered"
484
+ : cause === "timeout"
485
+ ? "no turn outcome within the window; re-delivered"
486
+ : "an earlier wake-fire turn failed; re-delivered";
487
+ const text = `${timer.reason} — [wake retry ${attempt}/${maxAttempts}: ` + `${heldNote}]. Resume the task.`;
488
+ // Terminal-error breaker open: the retry rides non-waking and is not
489
+ // re-tracked, so the ladder stops here instead of spending another doomed
490
+ // model call.
491
+ if (terminalBreakerBlocksWake(ctx)) {
492
+ log.info(`[timer] wake retry demoted to non-waking (turn-start blocked): ${timer.id}`);
493
+ deliverDemotedFire(pi, {
494
+ customType: "timer-fire",
495
+ text,
496
+ details: {
497
+ [BRAID_INJECTED]: true,
498
+ [BRAID_SOURCE]: "timer/fire-retry",
499
+ timerId: timer.id,
500
+ sessionId: timer.sessionId,
501
+ wake: true,
502
+ retryAttempt: attempt,
503
+ breakerSuppressed: true,
504
+ },
505
+ });
506
+ return;
507
+ }
508
+ wakeRetryQueue.trackWake(timer, attempt);
509
+ try {
510
+ sendTrackedMessage(pi, {
511
+ customType: "timer-fire",
512
+ content: [{ type: "text", text }],
513
+ display: true,
514
+ details: {
515
+ _braidInjected: true,
516
+ _braidSource: "timer/fire-retry",
517
+ timerId: timer.id,
518
+ sessionId: timer.sessionId,
519
+ wake: true,
520
+ retryAttempt: attempt,
521
+ },
522
+ }, { triggerTurn: true }, { type: "heartbeat", source: "timer/fire-retry" }, { bypassFloodCap: true }, {
523
+ // Cancel retires the fire: this retry spent its macrotask window
524
+ // after the isRetired guard above, so the seam re-asks at send time.
525
+ isWithdrawn: () => wakeRetryQueue.isRetired(timer.id),
526
+ onBusy: () => wakeRetryQueue.deferBusyWake(timer, attempt),
527
+ });
528
+ }
529
+ catch (e) {
530
+ log.warn(`[timer] wake retry delivery failed: ${e.message}`);
531
+ }
532
+ }
533
+ /** Human duration for the busy-held note: `45s`, `3m`, `1h05m`. */
534
+ function formatHeldDuration(ms) {
535
+ const seconds = Math.max(0, Math.round(ms / 1000));
536
+ if (seconds < 60)
537
+ return `${seconds}s`;
538
+ const minutes = Math.floor(seconds / 60);
539
+ if (minutes < 60)
540
+ return `${minutes}m`;
541
+ const hours = Math.floor(minutes / 60);
542
+ const remMin = minutes % 60;
543
+ return remMin === 0 ? `${hours}h` : `${hours}h${String(remMin).padStart(2, "0")}m`;
544
+ }
545
+ /**
546
+ * Deliver a wake fire whose SEND was held while the session was busy for
547
+ * longer than the bounded redelivery ladder. The ladder's budget is spent,
548
+ * but nothing failed — the fire was parked (deferBusyWake), never dropped.
549
+ * This is its one late delivery, with the honest held-while-busy cause and
550
+ * the whole hold duration in the text. A send deferred AGAIN is held again
551
+ * (onBusy): one fresh rung, and a re-park only once the cap is hit again.
552
+ */
553
+ function deliverParkedBusyFire(pi, timer, heldMs, ctx) {
554
+ // Cancel withdraws the fire: retirement reaches a parked fire (the entry is
555
+ // still in the queue's outstanding map) and this guard covers the in-flight
556
+ // window between the drain tick and the deferred send.
557
+ if (wakeRetryQueue.isRetired(timer.id)) {
558
+ log.info(`[timer] parked wake fire suppressed — timer cancelled before delivery: ${timer.id}`);
559
+ wakeRetryQueue.forgetParkedBusy(timer.id);
560
+ return;
561
+ }
562
+ const held = formatHeldDuration(heldMs);
563
+ const text = `${timer.reason} — [held while the session was busy for ${held}; delivered late]. ` +
564
+ `Resume the task.`;
565
+ // Terminal-error breaker open: show the content without starting a turn and
566
+ // stop the chain here (a wake turn would only burn another doomed call).
567
+ if (terminalBreakerBlocksWake(ctx)) {
568
+ log.info(`[timer] parked wake demoted to non-waking (turn-start blocked): ${timer.id}`);
569
+ wakeRetryQueue.forgetParkedBusy(timer.id);
570
+ deliverDemotedFire(pi, {
571
+ customType: "timer-fire",
572
+ text,
573
+ details: {
574
+ [BRAID_INJECTED]: true,
575
+ [BRAID_SOURCE]: "timer/fire-retry",
576
+ timerId: timer.id,
577
+ sessionId: timer.sessionId,
578
+ wake: true,
579
+ heldWhileBusyMs: heldMs,
580
+ breakerSuppressed: true,
581
+ },
582
+ });
583
+ return;
584
+ }
585
+ // Re-tracked at attempt 0: the busy ladder never delivered, so a turn that
586
+ // fails now starts a fresh (still capped) failed-redelivery ladder instead
587
+ // of inheriting the spent busy one. `continueHold` keeps this fire's hold
588
+ // origin across the handoff, so the text and the log state the whole held
589
+ // window rather than only the stretch since this handoff.
590
+ wakeRetryQueue.trackWake(timer, 0, { continueHold: true });
591
+ // The send defers to a macrotask and the busy check that decides send vs
592
+ // hold runs THERE, so "delivered late" cannot be stated before that
593
+ // decision: a handoff landing in a still-busy window is held again
594
+ // (onBusy), never sent, and a line claiming a late delivery would describe
595
+ // a delivery the hold withdrew. The same seam answers a cancel that landed
596
+ // in that window (isWithdrawn), so the line stays silent for a withdrawn
597
+ // fire too. The hooks record both withdrawals; the line rides a later
598
+ // macrotask and fires only for a fire that was actually delivered (the
599
+ // re-held handoff is logged by the queue as a park instead).
600
+ let heldAgain = false;
601
+ let cancelled = false;
602
+ try {
603
+ sendTrackedMessage(pi, {
604
+ customType: "timer-fire",
605
+ content: [{ type: "text", text }],
606
+ display: true,
607
+ details: {
608
+ _braidInjected: true,
609
+ _braidSource: "timer/fire-retry",
610
+ timerId: timer.id,
611
+ sessionId: timer.sessionId,
612
+ wake: true,
613
+ heldWhileBusyMs: heldMs,
614
+ },
615
+ }, { triggerTurn: true }, { type: "heartbeat", source: "timer/fire-retry" }, { bypassFloodCap: true }, {
616
+ // Cancel withdraws the fire in this window too: neither the send nor
617
+ // a re-park (deferBusyWake would arm a fresh ladder for the retired
618
+ // id) may happen, and the late-delivery line above must not claim it.
619
+ isWithdrawn: () => {
620
+ if (!wakeRetryQueue.isRetired(timer.id))
621
+ return false;
622
+ cancelled = true;
623
+ return true;
624
+ },
625
+ onBusy: () => {
626
+ heldAgain = true;
627
+ wakeRetryQueue.deferBusyWake(timer, 0);
628
+ },
629
+ });
630
+ setTimeout(() => {
631
+ if (heldAgain || cancelled)
632
+ return;
633
+ log.info(`[timer] wake fire held while the session was busy for ${held} — delivered late: ${timer.id}`);
634
+ }, 0);
635
+ }
636
+ catch (e) {
637
+ log.warn(`[timer] parked wake delivery failed: ${e.message}`);
638
+ }
639
+ }
640
+ /** Final notice when a wake fire exhausts its retry bound (last resort —
641
+ * the fire is visible as lost instead of silently vanishing). */
642
+ function notifyExhaustedWake(pi, timer) {
643
+ try {
644
+ sendTrackedMessage(pi, {
645
+ customType: "timer",
646
+ content: [
647
+ {
648
+ type: "text",
649
+ text: `Wake fire permanently undelivered after ${wakeRetryQueue.getMaxAttempts()} retries: ${timer.reason}`,
650
+ },
651
+ ],
652
+ display: true,
653
+ details: {
654
+ [BRAID_INJECTED]: true,
655
+ [BRAID_SOURCE]: "timer/fire-retry",
656
+ timerId: timer.id,
657
+ exhausted: true,
658
+ },
659
+ }, { delivery: "park", deliverAs: "steer" }, { type: "heartbeat", source: "timer/fire-retry" });
660
+ }
661
+ catch {
662
+ /* notice only — the error log in WakeRetryQueue already recorded it */
663
+ }
664
+ }
665
+ // Extension
666
+ /**
667
+ * Whether wake-delivery alerting is on (`braid.timers.wakeAlert`, read fresh
668
+ * on every event like every braid-settings reader). "off" forwards nothing —
669
+ * the detection feed is the only thing it disables; delivery itself (retry
670
+ * budgets, backoff, caps) is untouched either way.
671
+ */
672
+ function wakeAlertOn() {
673
+ try {
674
+ return getWakeDeliveryAlertConfig().mode === "on";
675
+ }
676
+ catch {
677
+ return false; // a settings failure must not enable alerting
678
+ }
679
+ }
680
+ function createTimerTool(sessionState) {
681
+ return {
682
+ name: "timer",
683
+ label: "Timer",
684
+ promptSnippet: "Set, list, or cancel non-blocking session-scoped timers",
685
+ description: "Manage non-blocking timers for the current session. " +
686
+ "Use action=set with delay_seconds/reason (and optional tag, interval_seconds, count, wake) to schedule. " +
687
+ "Use action=list to see active timers. " +
688
+ "Use action=cancel with timer_id to cancel. " +
689
+ "Provide interval_seconds to make a timer re-fire on that cadence until cancelled; " +
690
+ "add count=N to bound it to exactly N total fires (then it stops itself). " +
691
+ "Timers WAKE the agent on each fire by default (recurring included); pass wake:false for a silent advisory reminder. " +
692
+ "Timers are scoped to the current session; another session's timer_cancel will not affect this one.",
693
+ parameters: Type.Object({
694
+ action: Type.Union([Type.Literal("set"), Type.Literal("list"), Type.Literal("cancel")], {
695
+ description: "Action: set | list | cancel",
696
+ }),
697
+ delay_seconds: Type.Optional(Type.Number({ minimum: 1, maximum: 86400, description: "Delay in seconds (set)" })),
698
+ reason: Type.Optional(Type.String({ minLength: 1, description: "Reason text (set)" })),
699
+ tag: Type.Optional(Type.String({ description: "Optional tag for grouping (set)" })),
700
+ interval_seconds: Type.Optional(Type.Number({
701
+ minimum: 1,
702
+ maximum: 86400,
703
+ description: "Repeat interval in seconds (set). Recurring timer re-fires every interval until cancelled.",
704
+ })),
705
+ count: Type.Optional(Type.Number({
706
+ minimum: 1,
707
+ maximum: 100000,
708
+ description: "Total fires for a recurring timer (set). Bounds the recurrence: after count fires the timer removes itself (e.g. repeat every 60s x5 then stop). Omit for unbounded recurrence until cancelled.",
709
+ })),
710
+ wake: Type.Optional(Type.Boolean({
711
+ description: "Wake the agent on each fire (set). Defaults to true for ALL timers (recurring included); pass false for a silent (advisory) reminder.",
712
+ })),
713
+ // cancel-only
714
+ timer_id: Type.Optional(Type.String({ description: "Timer ID to cancel (cancel)" })),
715
+ }),
716
+ execute: async (_id, params, _signal, _onUpdate, ctx) => {
717
+ if (!sessionState.resolved) {
718
+ sessionState.id = getSessionId(ctx);
719
+ sessionState.resolved = true;
720
+ }
721
+ switch (params?.action) {
722
+ case "set": {
723
+ const { delay_seconds, reason, tag, interval_seconds, count, wake } = params;
724
+ if (tag && !/^[a-zA-Z0-9_-]+$/.test(tag)) {
725
+ throw new Error(`Invalid tag "${tag}" - use alphanumeric + dash/underscore`);
726
+ }
727
+ const delayMs = (delay_seconds ?? 60) * 1000;
728
+ const intervalMs = (interval_seconds ?? 0) * 1000;
729
+ const isRecurring = intervalMs > 0;
730
+ if (count !== undefined && !isRecurring) {
731
+ throw new Error("count requires interval_seconds (a recurring timer). One-shot timers fire once by definition.");
732
+ }
733
+ // Every timer wakes by default at the tool surface —
734
+ // recurring included; without a default wake, recurring fires
735
+ // arrive only as whispers attached to the next user turn (stacked
736
+ // overnight, delivered many hours late). Silence is strictly
737
+ // opt-in via wake:false.
738
+ const effectiveWake = wake ?? true;
739
+ const id = scheduleTimer(sessionState.id, delayMs, reason ?? "Timer", tag, effectiveWake, isRecurring ? intervalMs : undefined, isRecurring ? count : undefined);
740
+ const firesAt = Date.now() + delayMs;
741
+ // The confirmation carries the owner-TZ wall-clock (the ONE
742
+ // formatter), not the raw server-TZ toLocaleTimeString.
743
+ const when = isRecurring
744
+ ? `Repeats every ${interval_seconds}s${count !== undefined ? `, ${count} times total` : " until cancelled"}${effectiveWake ? " (waking)" : " (silent)"}; next fires at ${formatLocalTime(new Date(firesAt), true)}`
745
+ : `Will fire at ${formatLocalTime(new Date(firesAt), true)}`;
746
+ return {
747
+ content: [
748
+ {
749
+ type: "text",
750
+ text: `Timer set for ${delay_seconds}s (ID: ${id}, session=${sessionState.id}). ${when}. Continue working - reminder will arrive automatically. Use timer action=cancel with this ID to cancel.`,
751
+ },
752
+ ],
753
+ details: {
754
+ timer_id: id,
755
+ fires_at: new Date(firesAt).toISOString(),
756
+ fires_in_seconds: delay_seconds,
757
+ interval_seconds: isRecurring ? interval_seconds : undefined,
758
+ count: isRecurring ? count : undefined,
759
+ fires: isRecurring ? 0 : undefined,
760
+ recurring: isRecurring,
761
+ wake: effectiveWake,
762
+ active_timers: timerManager.getActiveCount(sessionState.id),
763
+ session_id: sessionState.id,
764
+ },
765
+ };
766
+ }
767
+ case "list": {
768
+ const timers = timerManager.listTimers(sessionState.id);
769
+ const now = Date.now();
770
+ if (timers.length === 0) {
771
+ return {
772
+ content: [{ type: "text", text: "No active timers." }],
773
+ details: { active_timers: 0, timers: [], session_id: sessionState.id },
774
+ };
775
+ }
776
+ const formatted = timers.map((t) => ({
777
+ timer_id: t.id,
778
+ tag: t.tag ?? "(untagged)",
779
+ reason: t.reason,
780
+ interval_seconds: t.intervalMs ? Math.round(t.intervalMs / 1000) : undefined,
781
+ count: t.count,
782
+ fires: t.fires ?? 0,
783
+ fires_in_seconds: Math.max(0, Math.ceil((t.firesAt - now) / 1000)),
784
+ fires_at: formatLocalTime(new Date(t.firesAt)),
785
+ }));
786
+ return {
787
+ content: [
788
+ {
789
+ type: "text",
790
+ text: `${timers.length} active timer(s). ${formatted.map((t) => `ID:${t.timer_id} [${t.tag}]${t.interval_seconds ? ` every ${t.interval_seconds}s (repeat ${t.fires}/${t.count ?? "∞"}), next in` : " fires in"} ${t.fires_in_seconds}s: ${t.reason}`).join("; ")}`,
791
+ },
792
+ ],
793
+ details: {
794
+ active_timers: timers.length,
795
+ timers: formatted,
796
+ session_id: sessionState.id,
797
+ },
798
+ };
799
+ }
800
+ case "cancel": {
801
+ // Was there a fire to retire (outstanding wake, armed ladder, or
802
+ // parked recovered fire)? Checked BEFORE the cancel: a fired
803
+ // one-shot is already gone from the manager map, but its wake
804
+ // ladder may still be armed — that cancel must succeed (the
805
+ // retirement is its whole effect), not throw "not found".
806
+ const hadFireState = wakeRetryQueue.hasWakeFireState(params.timer_id);
807
+ const cancelled = cancelTimer(sessionState.id, params.timer_id);
808
+ if (!cancelled && !hadFireState) {
809
+ throw new Error(`Timer "${params.timer_id}" not found in session ${sessionState.id} or already fired.`);
810
+ }
811
+ const note = cancelled
812
+ ? `Timer "${params.timer_id}" cancelled.`
813
+ : `Timer "${params.timer_id}" already fired; its outstanding wake ladder was retired.`;
814
+ return {
815
+ content: [{ type: "text", text: note }],
816
+ details: {
817
+ cancelled: true,
818
+ retired_fire: hadFireState,
819
+ timer_id: params.timer_id,
820
+ active_timers: timerManager.getActiveCount(sessionState.id),
821
+ session_id: sessionState.id,
822
+ },
823
+ };
824
+ }
825
+ default:
826
+ throw new Error(`Unknown timer action: ${params?.action}. Use: set, list, cancel.`);
827
+ }
828
+ },
829
+ };
830
+ }
831
+ /** True only when the ctx positively reports an idle session. Undetermined
832
+ * (missing isIdle reader, stale ctx whose getters throw) counts as NOT idle:
833
+ * the post-settle flush stays the fallback, never a race. */
834
+ function sessionIsIdle(ctx) {
835
+ try {
836
+ const isIdle = ctx?.isIdle;
837
+ return typeof isIdle === "function" && isIdle.call(ctx) === true;
838
+ }
839
+ catch {
840
+ return false;
841
+ }
842
+ }
843
+ /** True only when the ctx POSITIVELY reports a busy session: a run, its
844
+ * pre-flight/bookkeeping, or a compaction is in flight (isIdle() live-reads
845
+ * current runtime state — a ctx captured at any earlier event still answers
846
+ * truthfully minutes later; see wake-gate.ts). Undetermined ctx (missing
847
+ * reader, stale getters) counts as NOT busy: the wake-retry queue's outcome
848
+ * timeout then arms as before — a broken reader must never suppress retries
849
+ * (a wake is never silently lost), it only costs a spurious-retry risk.
850
+ * Wired into the queue as the long-run grace predicate. */
851
+ function sessionBusy(ctx) {
852
+ try {
853
+ const isIdle = ctx?.isIdle;
854
+ return typeof isIdle === "function" && isIdle.call(ctx) === false;
855
+ }
856
+ catch {
857
+ return false;
858
+ }
859
+ }
860
+ export default function timerExtension(pi) {
861
+ // Runtime check on that assumption: count factory invocations and warn if the
862
+ // single-process-per-session assumption is violated. The counter lives
863
+ // in global-state.ts (not as a module-level let here) so the
864
+ // no-module-level-let contract is satisfied. See the top-of-file
865
+ // comment block (lines 16-41) for the full assumption + migration path.
866
+ const factoryState = getTimerExtensionFactoryState();
867
+ factoryState.callCount += 1;
868
+ if (factoryState.callCount > 1) {
869
+ log.warn(`[timer] timerExtension(pi) called ${factoryState.callCount} times in this process. ` +
870
+ `The single-process-per-session assumption is violated; ` +
871
+ `poller/sessionState closures may conflict across sessions. ` +
872
+ `See src/extensions/scheduling/timer/index.ts:16-41 for the migration path.`);
873
+ }
874
+ // Long-run grace wiring
875
+ // The wake-retry queue's outcome timeout (240s with no settle) must not
876
+ // arm a redelivery while the session is actively running the turn the
877
+ // fire landed in: a multi-minute run is not a lost send, and an arming
878
+ // mid-run both redelivers mid-turn and (via the watchdog feed) pages a
879
+ // "wedged loop" for a healthy run. The queue takes a read-only predicate;
880
+ // this extension owns the wiring. The ctx getters are LIVE (each call
881
+ // reads current runtime state — wake-gate.ts), so the last-seen ctx
882
+ // answers truthfully whenever a drain tick consults it, however long ago
883
+ // it was captured. No ctx captured yet (before session_start) or a broken
884
+ // reader: the predicate answers false — the pre-grace arming applies
885
+ // (a wake is never silently lost), never the grace.
886
+ let lastSeenCtx = null;
887
+ const captureCtx = (ctx) => {
888
+ if (ctx)
889
+ lastSeenCtx = ctx;
890
+ };
891
+ wakeRetryQueue.setActiveRunCheck(() => sessionBusy(lastSeenCtx));
892
+ // Wake-delivery liveness feed (watchdog seam)
893
+ // The retry queue is where dead wake delivery is KNOWN first (repeated
894
+ // outcome timeouts for one fire, exhausted redelivery chains); the
895
+ // watchdog engine owns the episode latch + out-of-band escalation. This
896
+ // observer is the thread between them: threshold-crossing facts only,
897
+ // delivery untouched, disabled entirely by braid.timers.wakeAlert.mode
898
+ // = "off". The threshold (outcomeTimeouts, default 2) is applied here so
899
+ // one 240s outcome window — a normal long turn — never forwards. A
900
+ // timeout fact can only exist when NO agent run was active at arming
901
+ // time (drainDue's long-run grace), so what reaches the watchdog is a
902
+ // dead delivery, not a busy loop; a wedged ACTIVE run pages via the
903
+ // turn-stall condition instead.
904
+ wakeRetryQueue.setWakeObserver({
905
+ onOutcomeTimeout: (timer, timeouts) => {
906
+ if (!wakeAlertOn())
907
+ return;
908
+ try {
909
+ const cfg = getWakeDeliveryAlertConfig();
910
+ if (timeouts < cfg.outcomeTimeouts)
911
+ return;
912
+ getWatchdogWakeDeliveryFeed()?.recordWakeOutcomeTimeout(timer.id, timer.reason, timeouts);
913
+ }
914
+ catch {
915
+ // alerting never breaks retry arming
916
+ }
917
+ },
918
+ onWakeDelivered: (timer) => {
919
+ if (!wakeAlertOn())
920
+ return;
921
+ try {
922
+ getWatchdogWakeDeliveryFeed()?.recordWakeDelivered(timer.id);
923
+ }
924
+ catch {
925
+ // alerting never breaks outcome resolution
926
+ }
927
+ },
928
+ onCleanTurn: () => {
929
+ // A wake turn settled without a failure outcome: a real clean turn.
930
+ // The breaker resets its counter only here (not on internal LLM calls),
931
+ // so a session whose wakes are working closes the latch naturally.
932
+ if (lastSeenCtx) {
933
+ try {
934
+ getTurnStartGate()?.noteCleanTurn(lastSeenCtx);
935
+ }
936
+ catch {
937
+ // a throwing gate must never break settlement
938
+ }
939
+ }
940
+ },
941
+ });
942
+ // sessionId is determined lazily on first tool call. We register a
943
+ // session_start handler to capture it eagerly.
944
+ // Wrapped in a state object so the createTimerTool() factory can
945
+ // mutate it (objects pass by reference; primitives don't).
946
+ const sessionState = { id: "anonymous", resolved: false };
947
+ // Consolidated timer tool with 3 actions (set/list/cancel)
948
+ pi.registerTool(createTimerTool(sessionState));
949
+ // Per-pi poller: one per session
950
+ // The poller is created LAZILY on first session-aware event, because we
951
+ // need the sessionId. Once captured, it lives until SESSION_SHUTDOWN.
952
+ let poller = null;
953
+ // Busy-held fires whose bounded ladder is spent are parked, not dropped;
954
+ // deliver each one late, once the session is idle (the send's own onBusy
955
+ // hook re-parks a delivery that still lands in a busy window). Called from
956
+ // the same ticks as the retry drain AND at the settle, so the held fire
957
+ // lands at the next settle rather than at the next ladder rung.
958
+ const flushParkedBusyFires = () => {
959
+ for (const { timer, heldMs } of wakeRetryQueue.drainParkedBusy()) {
960
+ setTimeout(() => deliverParkedBusyFire(pi, timer, heldMs, lastSeenCtx), 0);
961
+ }
962
+ };
963
+ // Drain due failed-wake retries on the same ticks that fire expired
964
+ // timers. Each due retry is redelivered via setTimeout(0) (same macrotask
965
+ // discipline as the fire path); exhausted fires get a final silent notice.
966
+ const drainWakeRetries = () => {
967
+ for (const { timer, attempt, cause } of wakeRetryQueue.drainDue()) {
968
+ setTimeout(() => redeliverWakeFire(pi, timer, attempt, cause, lastSeenCtx), 0);
969
+ }
970
+ flushParkedBusyFires();
971
+ for (const timer of wakeRetryQueue.takeExhausted()) {
972
+ notifyExhaustedWake(pi, timer);
973
+ // Drop = dead-delivery episode signal (first event or absorbed by the
974
+ // watchdog's episode latch — one bark per episode either way).
975
+ if (wakeAlertOn()) {
976
+ try {
977
+ getWatchdogWakeDeliveryFeed()?.recordWakeUndelivered(timer.id, timer.reason, wakeRetryQueue.getMaxAttempts());
978
+ }
979
+ catch {
980
+ // alerting never breaks the exhausted notice
981
+ }
982
+ }
983
+ }
984
+ };
985
+ const ensurePoller = (ctx) => {
986
+ if (!poller) {
987
+ const sid = getSessionId(ctx);
988
+ sessionState.id = sid;
989
+ sessionState.resolved = true;
990
+ poller = new TimerPoller(sid, (sessionId, now) => timerManager.checkExpired(sessionId, now), (timer) => fireTimer(timer, pi, lastSeenCtx), log, drainWakeRetries);
991
+ }
992
+ return poller;
993
+ };
994
+ // Start polling on session_start so we have a sessionId available
995
+ pi.on(SESSION_START, (_event, ctx) => {
996
+ captureCtx(ctx);
997
+ const p = ensurePoller(ctx);
998
+ p.setPiRef(pi);
999
+ p.start();
1000
+ // Publish the wake-due question for the watchdog's stall classifier: a
1001
+ // due timer/wake is a legitimate reason for a session to look quiet.
1002
+ // Answered live from the manager (not captured) so a re-arm or cancel is
1003
+ // visible immediately; cleared at shutdown below.
1004
+ setWatchdogWakeDueProvider(() => {
1005
+ try {
1006
+ if (!sessionState.resolved)
1007
+ return false;
1008
+ return timerManager.listTimers(sessionState.id).some((t) => t.firesAt <= Date.now());
1009
+ }
1010
+ catch {
1011
+ return false;
1012
+ }
1013
+ });
1014
+ // A restart converts active timers into passive ones: recovery parks
1015
+ // overdue fires in before_agent_start and only an agent_settled flush
1016
+ // delivered them, so a recovered wake waited for an unrelated turn to
1017
+ // settle (observed: a wake fire recovered after a restart sat 23 minutes
1018
+ // until a turn started for entirely different reasons). At session_start
1019
+ // the sweep can run itself: recover now, and when the session is idle
1020
+ // with parked fires, flush on the next macrotask — no turn, no settle
1021
+ // needed. The post-settle flush stays the fallback when the session is
1022
+ // busy here, and the send-time onBusy hook re-parks a flush whose
1023
+ // macrotask lands in a busy window, so this path is safe by the same
1024
+ // machinery, not by luck.
1025
+ recoverPersistedTimers(pi, sessionState.id);
1026
+ sweepProjectStoresRetention(sessionState.id);
1027
+ if (!sessionIsIdle(ctx))
1028
+ return;
1029
+ if (wakeRetryQueue.deferredRecoveredCount() === 0)
1030
+ return;
1031
+ setTimeout(() => flushRecoveredFires(pi, lastSeenCtx), 0);
1032
+ });
1033
+ // Busy guard: set true on tool_call, false on tool_execution_end.
1034
+ //
1035
+ // Earlier this guard used TURN_END to reset busy, but that had a bug:
1036
+ // a long-running tool followed by a long LLM thinking phase would keep
1037
+ // busy=true for the entire turn, even though the actual tool was long
1038
+ // done. A 30s timer set just before a slow tool would be stuck waiting
1039
+ // for turn_end (which might be minutes away if the LLM is thinking).
1040
+ //
1041
+ // The correct guard is per-tool-execution:
1042
+ // - tool_call (before tool runs) -> busy=true
1043
+ // - tool_execution_end (after tool returns) -> busy=false
1044
+ // - turn_end -> busy=false (safety net for turns with no tool calls)
1045
+ //
1046
+ // This is still safe against the post-compaction stack overflow because
1047
+ // it blocks whisper injection only during actual tool execution, not
1048
+ // during LLM thinking (which can't chain into synchronous re-entry).
1049
+ pi.on(TOOL_CALL, (_event, ctx) => {
1050
+ captureCtx(ctx);
1051
+ const p = ensurePoller(ctx);
1052
+ p.setBusy(true);
1053
+ });
1054
+ pi.on(TOOL_EXECUTION_END, (_event, ctx) => {
1055
+ captureCtx(ctx);
1056
+ const p = ensurePoller(ctx);
1057
+ p.setBusy(false);
1058
+ // Opportunistically fire any expired timers that piled up during the
1059
+ // tool execution. This is the primary fire path for timers that
1060
+ // expired mid-tool - they don't have to wait for turn_end.
1061
+ p.fireExpired();
1062
+ });
1063
+ pi.on(TURN_END, (_event, ctx) => {
1064
+ captureCtx(ctx);
1065
+ const p = ensurePoller(ctx);
1066
+ p.setBusy(false);
1067
+ // Backup fire path: catch any expired timers the per-tool path missed
1068
+ // (e.g., turns with no tool calls, or edge cases where TOOL_EXECUTION_END
1069
+ // didn't fire).
1070
+ p.fireExpired();
1071
+ });
1072
+ // failed-wake retry wiring
1073
+ // agent_end carries the run's messages: the LAST assistant message's
1074
+ // stopReason === "error" marks a provider/auth failure (401/413/5xx).
1075
+ // "aborted" is a deliberate user stop — content is already in history,
1076
+ // so it resolves as delivered, not retried.
1077
+ pi.on(AGENT_END, (event, ctx) => {
1078
+ captureCtx(ctx);
1079
+ // The errorMessage rides along — a retryable class
1080
+ // (transport/timeout/5xx) starts the wake-retry hold so the outcome
1081
+ // timeout cannot arm a redelivery while pi-core is still auto-retrying
1082
+ // the run.
1083
+ const messages = event?.messages ?? [];
1084
+ // Delivery confirmation (delivered-once invariant): a wake fire whose
1085
+ // injected CustomMessage is among the run's messages LANDED, even when
1086
+ // the run later failed — the failure belongs to the agent's own work,
1087
+ // not to the delivery. Collected for the queue so the failed settle
1088
+ // re-arms only fires whose message is absent here.
1089
+ const landedTimerIds = new Set();
1090
+ for (const m of messages) {
1091
+ const details = m?.details;
1092
+ if (!details || m.role !== "custom")
1093
+ continue;
1094
+ if (details[BRAID_INJECTED] !== true)
1095
+ continue;
1096
+ const source = details[BRAID_SOURCE];
1097
+ if (typeof source !== "string" || !source.startsWith("timer/"))
1098
+ continue;
1099
+ if (typeof details.timerId === "string")
1100
+ landedTimerIds.add(details.timerId);
1101
+ }
1102
+ let failed = false;
1103
+ let errorMessage;
1104
+ for (let i = messages.length - 1; i >= 0; i--) {
1105
+ if (messages[i]?.role === "assistant") {
1106
+ failed = messages[i].stopReason === "error";
1107
+ errorMessage = messages[i].errorMessage;
1108
+ break;
1109
+ }
1110
+ }
1111
+ wakeRetryQueue.onAgentEnd(failed, errorMessage, landedTimerIds);
1112
+ });
1113
+ // agent_settled fires in the prompt() finally — AFTER auto-retries,
1114
+ // compaction, and queued continuations are done, even for failed runs —
1115
+ // so resolving here cannot race a pi-core retry. Idempotent (empty
1116
+ // outstanding → no-op), so the prompt-builder fallback listener cannot
1117
+ // double-resolve. flushRecoveredFires delivers the recovered persisted
1118
+ // fires deferred by recoverPersistedTimers post-settle, where a
1119
+ // wake:true fire safely starts its own turn.
1120
+ pi.on(AGENT_SETTLED, (_event, ctx) => {
1121
+ captureCtx(ctx);
1122
+ wakeRetryQueue.onAgentSettled();
1123
+ flushRecoveredFires(pi, lastSeenCtx);
1124
+ // The session just went idle: a busy-held fire parked during the run gets
1125
+ // its one late delivery now, at the settle — not at the next ladder rung.
1126
+ flushParkedBusyFires();
1127
+ });
1128
+ // Clean up polling + clear session timers on shutdown to prevent leaks
1129
+ pi.on(SESSION_SHUTDOWN, (_event, ctx) => {
1130
+ setWatchdogWakeDueProvider(null);
1131
+ if (poller) {
1132
+ poller.stop();
1133
+ poller = null;
1134
+ }
1135
+ const sid = getSessionId(ctx);
1136
+ const cleared = timerManager.clearSession(sid);
1137
+ if (cleared > 0) {
1138
+ log.info(`[timer] session ${sid} shutdown: cleared ${cleared} timer(s)`);
1139
+ }
1140
+ });
1141
+ log.info("[timer] loaded: timer (set/list/cancel actions)");
1142
+ }
1143
+ //# sourceMappingURL=index.js.map