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,1057 @@
1
+ /**
2
+ * Wake-retry queue — timer wake reliability.
3
+ *
4
+ * Four related guarantees live here:
5
+ *
6
+ * 1. FAILED-WAKE RETRY: a wake fire (triggerTurn:true) whose turn
7
+ * FAILS with a provider/auth error (assistant stopReason "error") must not
8
+ * sit in history until an unrelated turn processes it, surfacing hours
9
+ * later. The queue tracks every delivered wake fire as "outstanding"; a
10
+ * failed run (onAgentEnd(true) + onAgentSettled()) re-arms it for
11
+ * redelivery with bounded exponential backoff (5s/15s/45s/2m/5m, capped —
12
+ * default 3 redeliveries, braid.timers.maxWakeAttempts). A wake whose turn
13
+ * never produced an outcome (pi-core pre-flight abort emits NO extension
14
+ * event) times out after WAKE_OUTCOME_TIMEOUT_MS and retries anyway. A
15
+ * wake fire is therefore never silently lost.
16
+ *
17
+ * 1b. BUSY-SEND DEFERRAL: a wake whose SEND was held back because the
18
+ * session was busy at send time (isAgentBusy() — compaction or run
19
+ * bookkeeping; a raw triggerTurn there would start a competing agent
20
+ * run) re-enters this queue via deferBusyWake() and redelivers on the
21
+ * same bounded ladder, with an honest "held while busy" cause so the
22
+ * redelivery text does not claim a failed turn. The outstanding entry is
23
+ * marked busy-deferred until a redelivery actually sends: a settle of an
24
+ * unrelated run that merely overlaps the deferral window must not
25
+ * resolve the wake as delivered. When the bounded ladder is spent and
26
+ * nothing FAILED, the fire is PARKED (parkedBusy) rather than dropped:
27
+ * drainParkedBusy() hands it to one late delivery at the next idle tick
28
+ * (the settle's own drain), with the hold duration in the text. The cap
29
+ * bounds the retries, not the delivery — a session busy longer than the
30
+ * ladder still receives the fire exactly once, and a busy-held fire
31
+ * never enters the exhausted set (the watchdog's "permanently
32
+ * undelivered" page stays reserved for genuinely unsalvageable cases).
33
+ *
34
+ * 2. RECOVERED-FIRE DEFERRAL: recoverPersistedTimers
35
+ * (scheduling/timer/recovery.ts) must not deliver expired persisted fires
36
+ * INLINE inside before_agent_start — a turn is already starting, so a
37
+ * triggerTurn there races the pre-flight (pi-core activeRun guard) and a
38
+ * steer dies with the run if the pre-flight aborts. Recovery parks fires
39
+ * via deferRecoveredFire(); the timer extension's agent_settled handler
40
+ * calls flushRecoveredFires(), which delivers AFTER the run has fully
41
+ * settled — where a wake:true fire safely starts its own turn — and feeds
42
+ * failed deliveries into the retry machinery above.
43
+ *
44
+ * 3. DRAIN LIVENESS: the retry queue is drained by the SAME ticks
45
+ * that fire expired timers (TimerPoller poll tick and the
46
+ * TOOL_EXECUTION_END / TURN_END fireExpired path) — retries never wait
47
+ * for a user turn.
48
+ *
49
+ * 4. HONEST ATTRIBUTION, CANCEL RETIREMENT, LONG-RUN GRACE: a redelivery
50
+ * carries a WakeRetryCause rendered verbatim in its text — "failed"
51
+ * (the turn's settle was a provider/auth error), "busy" (the send was
52
+ * deferred), or "timeout" (the outcome window elapsed with no settle and
53
+ * no run in flight). The outcome timeout must not claim a failed turn.
54
+ * LONG-RUN GRACE: drainDue does not arm (or count) an outcome timeout
55
+ * while an agent run is active for a wake whose send was not busy-
56
+ * deferred — the run is plausibly the wake's own turn and a merely-long
57
+ * run is not a lost send; the 240s window keeps its job for the send
58
+ * that never started a turn (pre-flight abort). The active-run predicate
59
+ * is wired by timer/index.ts from the captured session ctx; absent or
60
+ * throwing it degrades to the pre-grace arming (never suppress retries
61
+ * on a broken reader). CANCEL RETIREMENT: cancelTimer/cancelTimersByTag
62
+ * (and the session-shutdown clear) withdraw the fire with the timer —
63
+ * retireTimer/retireTimersWhere drop the outstanding wake, the armed
64
+ * ladder, parked recovered fires, and the timeout-count bookkeeping, and
65
+ * mark the id retired so an in-flight deferred send (fireTimer or a
66
+ * popped redelivery) is suppressed at send time. Retirement is a
67
+ * WITHDRAWAL, not a delivery: stats.succeeded stays untouched.
68
+ *
69
+ * Mitigations (wake-retry flood):
70
+ *
71
+ * a. Outcome window: legitimate wake turns run 2-4min; a shorter window
72
+ * arms spurious "false timeout" retries mid-turn (the 5s backoff usually
73
+ * drains before the settle's success-clear can cancel).
74
+ *
75
+ * b. Retryable-failure hold: pi-core auto-retries a RETRYABLE provider
76
+ * failure (transport/timeout/5xx — RETRYABLE_PROVIDER_ERROR_PATTERN
77
+ * classes) inside the SAME run, and those auto_retry_start/end events
78
+ * are NOT surfaceable to extensions (absent from ExtensionAPI's
79
+ * ExtensionEvent union), so the queue instead mirrors pi-core's
80
+ * retryable classes (isRetryableWakeError) and HOLDS the outcome
81
+ * timeout for a bounded window matching pi-core's retry budget
82
+ * (baseDelayMs * 2^maxRetries, read from settings.json `retry` —
83
+ * getWakeRetryHoldMs). While the hold is active, drainDue cannot arm a
84
+ * mid-cycle redelivery; the settle (which fires only after pi-core's
85
+ * retry loop is done) is the sole arming authority for retryable
86
+ * failures — final failure arms exactly one ladder, success clears
87
+ * everything. A hold expires harmlessly: the next drainDue tick
88
+ * after expiry re-checks the (still missing) outcome and arms.
89
+ *
90
+ * c. Redelivery cap (WAKE_RETRY_MAX_ATTEMPTS), owner-tunable via
91
+ * braid.timers.maxWakeAttempts (braid-settings.ts) — a deep ladder on a
92
+ * flaky provider out-floods the session.
93
+ *
94
+ * Failure detection: agent_end carries the run's messages; the LAST assistant
95
+ * message's stopReason === "error" marks the run failed (provider 401/413/5xx
96
+ * path). "aborted" is deliberate user action — the content is already in
97
+ * history, so it resolves as delivered, not retried.
98
+ *
99
+ * All pi event wiring lives in timer/index.ts; this module holds no event
100
+ * listeners and no module-level mutable state beyond the exported singleton
101
+ * (class instance — same pattern as timerManager).
102
+ */
103
+
104
+ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
105
+ import type { ScheduledTimer } from "../../../lib/events/timer-types.js";
106
+ import { createLogger } from "../../../lib/core/logger.js";
107
+ import { sendTrackedMessage } from "../../../lib/utils/injection-tracker.js";
108
+ import { BRAID_INJECTED, BRAID_SOURCE } from "../../../lib/constants/injection-details.js";
109
+ import { describeFireTiming } from "./fire-timing.js";
110
+ import {
111
+ MAX_WAKE_ATTEMPTS_DEFAULT,
112
+ getMaxWakeAttempts,
113
+ getTerminalBreakerConfig,
114
+ getWakeRetryHoldMs,
115
+ } from "../../../lib/config/braid-settings.js";
116
+ import { getTurnStartGate } from "../../../lib/state/global-state.js";
117
+
118
+ const log = createLogger("timer-wake-retry");
119
+
120
+ /**
121
+ * Consumer gate shared by the wake sends: is the terminal-error breaker open,
122
+ * so this fire must ride non-waking? Asks the published turn-start gate one
123
+ * latch question and nothing else. Flag read once per fire; a missing ctx, a
124
+ * missing gate or a broken reader fails open (never silently drop a wake).
125
+ * Mirrors the helper in index.ts — kept here so the recovered-fire flush can
126
+ * use it without importing back from the module that imports this one.
127
+ */
128
+ function terminalBreakerBlocksWake(ctx: unknown): boolean {
129
+ try {
130
+ if (!ctx) return false;
131
+ const cfg = getTerminalBreakerConfig();
132
+ if (!cfg.enabled) return false;
133
+ const gate = getTurnStartGate();
134
+ if (!gate) return false;
135
+ return gate.isBlocked(ctx, cfg.threshold);
136
+ } catch {
137
+ return false;
138
+ }
139
+ }
140
+
141
+ /** A wake fire awaiting its turn outcome (delivery -> agent_end/agent_settled). */
142
+ export interface OutstandingWake {
143
+ timer: ScheduledTimer;
144
+ /** 0 = original fire; N = the Nth redelivery. */
145
+ attempt: number;
146
+ sentAt: number;
147
+ /** A retry is already armed for this delivery — by the outcome timeout
148
+ * (the window elapsed with no settle; the entry is KEPT, not deleted, so
149
+ * the eventual settle of this delivery still resolves it: a success
150
+ * clears the armed retry, a failure re-arms at the same tier) or by a
151
+ * busy deferral (deferBusyWake). Cleared when the retry is popped
152
+ * (re-tracked fresh) or when the chain exhausts. */
153
+ timedOut?: boolean;
154
+ /** The send was deferred: the session was busy at send time, so no turn
155
+ * has run for this wake. Settles must not resolve it as delivered —
156
+ * the pending redelivery chain owns its liveness. */
157
+ busyDeferred?: boolean;
158
+ /** When the FIRST busy deferral of this delivery chain happened — the
159
+ * holder for the "held while the session was busy for X" late-delivery
160
+ * text. Survives re-tracking (trackWake) within the same fire's delivery
161
+ * chain so the reported hold is the whole held window, not just the last
162
+ * rung; a newer fire of the same timer id starts its own origin (see
163
+ * trackWake). */
164
+ heldSince?: number;
165
+ /** The busy ladder is spent; the fire waits for one late delivery at the
166
+ * next idle drain (drainParkedBusy) instead of being dropped. */
167
+ parkedBusy?: boolean;
168
+ /** A parked fire already handed to the late-delivery path; guards the
169
+ * in-flight window between the drain tick and the deferred send so one
170
+ * parked fire is handed off exactly once. */
171
+ parkedDelivering?: boolean;
172
+ }
173
+
174
+ /** Why a redelivery was armed: the wake's turn failed at its settle, its
175
+ * send was deferred because the session was busy at send time, or its
176
+ * outcome window elapsed with no settle and no run in flight. The cause is
177
+ * rendered verbatim in the redelivery text — a timeout-armed retry must
178
+ * never claim a failed turn (the turn may simply have never started). */
179
+ export type WakeRetryCause = "failed" | "busy" | "timeout";
180
+
181
+ /** A scheduled redelivery of a wake fire whose turn failed (or whose send
182
+ * was deferred — see WakeRetryCause). */
183
+ interface RetryEntry {
184
+ timer: ScheduledTimer;
185
+ attempt: number;
186
+ nextAttemptAt: number;
187
+ cause: WakeRetryCause;
188
+ }
189
+
190
+ /** An expired persisted timer parked by recoverPersistedTimers (fix 3). */
191
+ export interface RecoveredFire {
192
+ id: string;
193
+ sessionId?: string;
194
+ reason: string;
195
+ tag?: string;
196
+ createdAt?: number;
197
+ firesAt?: number;
198
+ wake: boolean;
199
+ }
200
+
201
+ /** Outcome window: a wake with no agent_end/agent_settled within this window
202
+ * (e.g. pi-core pre-flight abort — no extension event on that path) is
203
+ * re-armed for retry. 240s comfortably exceeds a normal long turn (babysit
204
+ * wake turns run 2-4min); a shorter window arms a spurious retry mid-run.
205
+ * A genuinely hung run is rarer than a long one. */
206
+ export const WAKE_OUTCOME_TIMEOUT_MS = 240_000;
207
+
208
+ /** Backoff tiers between redelivery attempts (index = attempt - 1). */
209
+ export const WAKE_RETRY_BACKOFF_MS = [5_000, 15_000, 45_000, 120_000, 300_000];
210
+
211
+ /** Redelivery bound. Attempt > the effective cap (WAKE_RETRY_MAX_ATTEMPTS
212
+ * default, owner-tunable via braid.timers.maxWakeAttempts) exhausts the
213
+ * fire — a deep ladder on a flaky provider out-floods the session. */
214
+ export const WAKE_RETRY_MAX_ATTEMPTS = MAX_WAKE_ATTEMPTS_DEFAULT;
215
+
216
+ // retryable-failure classification (pi-core mirror)
217
+
218
+ /** Quota/billing-class failures pi-ai never retries: the same literals pi-ai
219
+ * builds NON_RETRYABLE_PROVIDER_LIMIT_ERROR_PATTERN from
220
+ * (pi-ai/dist/utils/retry.js). Checked first: pi-ai refuses to retry these, so
221
+ * the run's outcome is final and the wake must never be held for an auto-retry
222
+ * that will not come. The bare phrase "usage limit" is deliberately absent: it
223
+ * also vetoes texts pi-ai DOES retry (a 429 whose body mentions a usage limit),
224
+ * which suppresses the hold that retry needs.
225
+ *
226
+ * Pinned by test/runtime/lib/test-wake-retry-nonretryable-mirror.mjs, which
227
+ * reads the token array out of the installed pi-ai module and requires each
228
+ * one to be vetoed here. The retryable side below is NOT pinned: it is a
229
+ * hand-written subset of pi-ai's retryable classes, so a failure pi-ai retries
230
+ * but this mirror does not match settles with no hold. */
231
+ const WAKE_NON_RETRYABLE_ERROR_PATTERN = new RegExp(
232
+ [
233
+ "GoUsageLimitError",
234
+ "FreeUsageLimitError",
235
+ "Monthly usage limit reached",
236
+ "available balance",
237
+ "insufficient_quota",
238
+ "out of budget",
239
+ "quota exceeded",
240
+ "billing",
241
+ "subscription_sharing_usage_limit_exceeded",
242
+ ].join("|"),
243
+ "i",
244
+ );
245
+
246
+ /** The retryable classes braid mirrors from pi-core's
247
+ * RETRYABLE_PROVIDER_ERROR_PATTERN (pi-ai/dist/utils/retry.js): transport
248
+ * failures, premature stream endings, timeouts, HTTP 5xx/429. A failed
249
+ * agent_end matching this means pi-core will auto-retry inside the SAME
250
+ * run — the run's outcome is not final yet (see the hold in
251
+ * onAgentEnd/drainDue). */
252
+ const WAKE_RETRYABLE_ERROR_PATTERN = new RegExp(
253
+ [
254
+ "overloaded",
255
+ "rate.?limit",
256
+ "too many requests",
257
+ "\\b429\\b",
258
+ "\\b5\\d\\d\\b",
259
+ "service.?unavailable",
260
+ "server.?error",
261
+ "network.?error",
262
+ "connection.?error",
263
+ "connection.?refused",
264
+ "other side closed",
265
+ "fetch failed",
266
+ "upstream.?connect",
267
+ "socket hang up",
268
+ "timed? out",
269
+ "timeout",
270
+ "terminated",
271
+ "ended without",
272
+ "stream ended before",
273
+ ].join("|"),
274
+ "i",
275
+ );
276
+
277
+ /** Whether an agent_end errorMessage belongs to a failure class pi-core
278
+ * auto-retries (hold the wake outcome); quota/auth-class errors never hold. */
279
+ export function isRetryableWakeError(errorMessage?: string): boolean {
280
+ if (!errorMessage) return false;
281
+ if (WAKE_NON_RETRYABLE_ERROR_PATTERN.test(errorMessage)) return false;
282
+ return WAKE_RETRYABLE_ERROR_PATTERN.test(errorMessage);
283
+ }
284
+
285
+ /**
286
+ * Liveness observer for the wake-delivery watchdog feed. Production wiring
287
+ * lives in timer/index.ts: it forwards threshold-crossing facts to the
288
+ * watchdog's wake-delivery condition (published via the global-state seam),
289
+ * which owns the episode latch + out-of-band escalation. The queue itself
290
+ * stays notification-agnostic — the observer changes nothing about delivery
291
+ * (retry budgets, backoff, caps are untouched), and a throwing observer must
292
+ * never break redelivery (call sites guard).
293
+ */
294
+ export interface WakeRetryObserver {
295
+ /** The outcome window elapsed with no settle for this timer — `timeouts`
296
+ * is the cumulative count for the timer id across its redelivery chain. */
297
+ onOutcomeTimeout?(timer: ScheduledTimer, timeouts: number): void;
298
+ /** A tracked wake resolved as delivered (its turn settled non-failed or
299
+ * its message landed) — the signal that wakes resumed. */
300
+ onWakeDelivered?(timer: ScheduledTimer): void;
301
+ /** A wake turn settled WITHOUT a failure outcome — a real clean turn, as
302
+ * opposed to an internal LLM call. The terminal-error breaker resets its
303
+ * counter here so only completed turns close it. */
304
+ onCleanTurn?(): void;
305
+ }
306
+
307
+ export interface WakeRetryStats {
308
+ /** Wake fires tracked (originals + redeliveries). */
309
+ tracked: number;
310
+ /** Wake fires resolved as delivered (successful or aborted run). */
311
+ succeeded: number;
312
+ /** Outstanding wakes that hit the outcome timeout. */
313
+ timedOut: number;
314
+ /** Fires dropped after exceeding WAKE_RETRY_MAX_ATTEMPTS. */
315
+ exhausted: number;
316
+ /** Busy-held fires parked for one late delivery (never dropped).
317
+ * Test-only today: no production reader consumes WakeRetryStats — the
318
+ * park logs its own line at park time — so this field is kept for the
319
+ * busy-hold tests and a future status surface to publish. */
320
+ heldBusy: number;
321
+ }
322
+
323
+ /** A retry due for redelivery (returned by drainDue). */
324
+ export interface DueRetry {
325
+ timer: ScheduledTimer;
326
+ attempt: number;
327
+ cause: WakeRetryCause;
328
+ }
329
+
330
+ /** A busy-held fire whose bounded ladder is spent and that is due for its
331
+ * one honest late delivery (returned by drainParkedBusy). */
332
+ export interface ParkedBusyDelivery {
333
+ timer: ScheduledTimer;
334
+ /** How long the send was held while the session was busy. */
335
+ heldMs: number;
336
+ }
337
+
338
+ export class WakeRetryQueue {
339
+ private outstanding = new Map<string, OutstandingWake>();
340
+ private retries: RetryEntry[] = [];
341
+ private exhaustedFires: ScheduledTimer[] = [];
342
+ private deferredRecovered: RecoveredFire[] = [];
343
+ private lastRunFailed: boolean | null = null;
344
+ /** Timer ids whose injected messages were present in the just-ended run's
345
+ * messages (extracted from agent_end by the timer extension). A fire on
346
+ * this list was DELIVERED — a later run failure is the agent's own work
347
+ * failing, not the delivery, and must not re-arm it. */
348
+ private landedTimerIds: Set<string> | null = null;
349
+ private stats: WakeRetryStats = {
350
+ tracked: 0,
351
+ succeeded: 0,
352
+ timedOut: 0,
353
+ exhausted: 0,
354
+ heldBusy: 0,
355
+ };
356
+ private now: () => number = () => Date.now();
357
+ /** While set and not expired, the outcome timeout must not arm —
358
+ * pi-core may still be auto-retrying the run (outcome undecided). */
359
+ private retryHoldUntil: number | null = null;
360
+ /** Test hooks: pin the hold window / redelivery cap. null restores the
361
+ * settings-derived values (getWakeRetryHoldMs / braid.timers
362
+ * .maxWakeAttempts). */
363
+ private retryHoldOverrideMs: number | null = null;
364
+ private maxAttemptsOverride: number | null = null;
365
+ /** Cumulative outcome-timeout count per timer id, across the fire's whole
366
+ * redelivery chain (original + redeliveries). Feeds the repeated-timeout
367
+ * stall signal: one 240s window is a normal long turn, a SECOND one for
368
+ * the same fire is a wedged loop. Cleared when the fire resolves delivered
369
+ * or exhausts. Factory/instance state — never a module-level let. */
370
+ private timeoutCounts = new Map<string, number>();
371
+ /** Optional liveness observer (timer/index.ts wires the watchdog feed). */
372
+ private wakeObserver: WakeRetryObserver | null = null;
373
+ /** Live read-only predicate: is an agent run (or its pre-flight /
374
+ * compaction tail) active right now? Wired by timer/index.ts from the
375
+ * captured session ctx. Absent or throwing = not active — the arming
376
+ * behavior degrades to the pre-grace form (a wake is never silently
377
+ * lost, so a broken reader must not suppress retries). */
378
+ private activeRunCheck: (() => boolean) | null = null;
379
+ /** Timer ids retired by a cancel (the fire and its ladder withdrawn by
380
+ * the owner). Guards the in-flight windows: a fire deferred inside the
381
+ * poller (checkExpired -> setTimeout(0)) and a redelivery popped from
382
+ * the ladder (drainDue -> setTimeout(0)) both re-check this mark at
383
+ * send time, so a cancel landing inside either window suppresses the
384
+ * send. Cleared by trackWake — a fresh fire of the same id (recovered
385
+ * after a restart, say) re-arms its own chain. */
386
+ private retired = new Set<string>();
387
+
388
+ /** Set (or clear with null) the wake-liveness observer. Invoked at the
389
+ * timeout-arming and delivered-resolve points only; never on the send
390
+ * path. */
391
+ setWakeObserver(observer: WakeRetryObserver | null): void {
392
+ this.wakeObserver = observer;
393
+ }
394
+
395
+ /** Test hook: pin the clock (backoff/timeout math). null restores Date.now(). */
396
+ _setClockForTests(fn: (() => number) | null): void {
397
+ this.now = fn ?? (() => Date.now());
398
+ }
399
+
400
+ /** Test hook: pin the retryable-failure hold window (ms). */
401
+ _setRetryHoldForTests(ms: number | null): void {
402
+ this.retryHoldOverrideMs = ms;
403
+ }
404
+
405
+ /** Test hook: pin the redelivery cap. */
406
+ _setMaxAttemptsForTests(n: number | null): void {
407
+ this.maxAttemptsOverride = n;
408
+ }
409
+
410
+ /** Wire (or clear with null) the live active-run predicate. Consulted by
411
+ * drainDue's outcome-timeout path: while a run is active for a wake whose
412
+ * send was NOT busy-deferred, the run is plausibly the wake's own turn —
413
+ * a merely-long run must not arm a redelivery (and via the observer, a
414
+ * page). See the long-run grace contract in the module header. */
415
+ setActiveRunCheck(fn: (() => boolean) | null): void {
416
+ this.activeRunCheck = fn;
417
+ }
418
+
419
+ private isFireTurnRunning(): boolean {
420
+ const fn = this.activeRunCheck;
421
+ if (!fn) return false;
422
+ try {
423
+ return fn() === true;
424
+ } catch {
425
+ return false;
426
+ }
427
+ }
428
+
429
+ /** Effective redelivery cap: braid.timers.maxWakeAttempts (default 3). */
430
+ getMaxAttempts(): number {
431
+ return this.maxAttemptsOverride ?? getMaxWakeAttempts();
432
+ }
433
+
434
+ private holdWindowMs(): number {
435
+ return this.retryHoldOverrideMs ?? getWakeRetryHoldMs();
436
+ }
437
+
438
+ /**
439
+ * Track a wake fire BEFORE (or at) delivery so its turn outcome can be
440
+ * resolved. `attempt` 0 = original fire; the redelivery path re-tracks with
441
+ * the drained attempt number. Re-tracking the same timer id refreshes the
442
+ * outcome window (the newest delivery is the one whose outcome matters).
443
+ *
444
+ * `continueHold` marks an attempt-0 re-track that continues the SAME fire's
445
+ * delivery chain (the parked handoff in deliverParkedBusyFire) instead of
446
+ * starting a newer fire's. Only a chain continuation keeps a busy-deferred
447
+ * predecessor's hold origin; a numbered re-track (attempt >= 1) is one by
448
+ * construction, since the ladder redelivers the fire that armed it.
449
+ */
450
+ trackWake(timer: ScheduledTimer, attempt = 0, options?: { continueHold?: boolean }): void {
451
+ // A newer delivery of the same timer supersedes any pending redelivery of
452
+ // an older instance (recurring overlap): letting it fire alongside the
453
+ // newer delivery duplicates the reason content. Safe for the redelivery
454
+ // path itself — it re-tracks only after its retry was popped from the
455
+ // list by drainDue.
456
+ this.cancelPendingRetries(timer.id);
457
+ // A fresh fire of a previously-cancelled id re-arms its own chain.
458
+ this.retired.delete(timer.id);
459
+ // A re-track of a busy-deferred delivery keeps the original hold start —
460
+ // the late-delivery text must state the WHOLE held window, not just the
461
+ // last ladder rung. Only a chain continuation keeps it: a NEWER fire of
462
+ // the same id (a recurring cadence) supersedes the parked predecessor and
463
+ // starts its own hold origin, so its late-delivery text reports its own
464
+ // hold and not the predecessor chain's.
465
+ const prev = this.outstanding.get(timer.id);
466
+ const continuesChain = attempt >= 1 || options?.continueHold === true;
467
+ const heldSince = continuesChain && prev?.busyDeferred ? prev.heldSince : undefined;
468
+ this.outstanding.set(timer.id, { timer, attempt, sentAt: this.now(), heldSince });
469
+ this.stats.tracked++;
470
+ }
471
+
472
+ /**
473
+ * Record the outcome of the run that just ended. Called from agent_end.
474
+ * A retryable errorMessage (transport/timeout/5xx — pi-core
475
+ * auto-retries inside the SAME run) starts a hold window that defers the
476
+ * outcome-timeout arming in drainUntil the retry cycle resolves; the hold
477
+ * is refreshed on every retryable failure so a long multi-attempt cycle
478
+ * stays covered. Non-retryable failures (auth/quota) arm at settle
479
+ * immediately, as before.
480
+ */
481
+ onAgentEnd(failed: boolean, errorMessage?: string, landedTimerIds?: ReadonlySet<string>): void {
482
+ this.lastRunFailed = failed;
483
+ // Accumulate across the run's agent_end events: pi-core emits one per
484
+ // loop (main run + every continuation), each carrying only its own
485
+ // messages — the settled landed set is their union. Consumed and cleared
486
+ // at settle.
487
+ if (landedTimerIds) {
488
+ this.landedTimerIds ??= new Set();
489
+ for (const id of landedTimerIds) this.landedTimerIds.add(id);
490
+ }
491
+ if (failed && isRetryableWakeError(errorMessage)) {
492
+ this.retryHoldUntil = this.now() + this.holdWindowMs();
493
+ }
494
+ }
495
+
496
+ /**
497
+ * Resolve outstanding wakes at the settle boundary (agent_settled — fired
498
+ * after retries/compaction/continuations are done, even for failed runs).
499
+ * A failed run re-arms every outstanding wake; anything else (success or
500
+ * user abort) counts as delivered. Idempotent: a second call with no
501
+ * outstanding wakes is a no-op, so multiple settle listeners cannot
502
+ * double-schedule.
503
+ *
504
+ * A SUCCESSFUL wake turn also clears the pending retry chain for its
505
+ * timer id. Without this, the outcome-timeout path (drainDue) can arm a
506
+ * retry for a fire whose turn is merely LONG (>60s), the turn then settles
507
+ * successfully, the armed retry still fires, and the chain re-delivers a
508
+ * fire whose failure no longer exists — burning the retry cap on
509
+ * duplicates. Only genuinely-failed fires keep retrying to the cap.
510
+ */
511
+ onAgentSettled(): void {
512
+ const failed = this.lastRunFailed === true;
513
+ const landed = this.landedTimerIds;
514
+ this.lastRunFailed = null;
515
+ this.landedTimerIds = null;
516
+ // The settle fires after pi-core's retry loop is done (it lives in
517
+ // _runAgentPrompt's finally) — the outcome is final, any hold is void.
518
+ this.retryHoldUntil = null;
519
+ const now = this.now();
520
+ for (const [id, w] of this.outstanding) {
521
+ if (w.busyDeferred) {
522
+ // No turn ran for this wake (send deferred: session busy at send
523
+ // time). This settle belongs to an unrelated run — it must neither
524
+ // resolve the wake as delivered nor clear its armed retry, and the
525
+ // entry is KEPT: the pending busy rung, or the parked late delivery,
526
+ // owns its liveness past this settle.
527
+ continue;
528
+ }
529
+ if (failed && !landed?.has(w.timer.id)) {
530
+ this.scheduleRetry(w.timer, w.attempt + 1, now);
531
+ } else {
532
+ this.stats.succeeded++;
533
+ this.timeoutCounts.delete(w.timer.id);
534
+ this.cancelPendingRetries(w.timer.id);
535
+ try {
536
+ this.wakeObserver?.onWakeDelivered?.(w.timer);
537
+ } catch {
538
+ // alerting must never break outcome resolution
539
+ }
540
+ try {
541
+ // The wake path is the layer that knows a TURN completed cleanly —
542
+ // an internal LLM call cannot distinguish itself — so the breaker's
543
+ // clean-turn reset lives here, not in the raw success counter.
544
+ this.wakeObserver?.onCleanTurn?.();
545
+ } catch {
546
+ // a throwing observer must never break settlement
547
+ }
548
+ }
549
+ this.outstanding.delete(id);
550
+ }
551
+ }
552
+
553
+ /**
554
+ * Arm a redelivery for a wake whose SEND was deferred: the session was
555
+ * busy at send time (ctx.signal undefined while ctx.isIdle() is false —
556
+ * compaction / run bookkeeping; a raw triggerTurn there would start a
557
+ * competing agent run). Rides the same bounded backoff ladder and cap as
558
+ * failed-turn redeliveries; the redelivery text says "held while the
559
+ * session was busy" instead of claiming a failed turn. The outstanding
560
+ * entry is marked busy-deferred so a settle of an unrelated run that
561
+ * overlaps the deferral window cannot resolve the wake as delivered.
562
+ *
563
+ * When the ladder is spent the fire is PARKED, never dropped: nothing
564
+ * failed, so the exhausted path (and the watchdog's undelivered page) does
565
+ * not apply. drainParkedBusy() then hands it to one late delivery once the
566
+ * session is idle, with the full hold duration in the text.
567
+ */
568
+ deferBusyWake(timer: ScheduledTimer, attempt: number): void {
569
+ const now = this.now();
570
+ const w = this.outstanding.get(timer.id);
571
+ if (w) {
572
+ w.busyDeferred = true;
573
+ if (w.heldSince === undefined) w.heldSince = now;
574
+ }
575
+ if (attempt + 1 > this.getMaxAttempts()) {
576
+ this.parkBusyFire(timer, w, attempt, now);
577
+ return;
578
+ }
579
+ const armed = this.scheduleRetry(timer, attempt + 1, now, "busy");
580
+ if (armed && w) {
581
+ // The deferral armed the ladder itself: mark the entry so the outcome
582
+ // window neither re-arms it (which would only push the redelivery
583
+ // back out) nor feeds the repeated-timeout stall signal. The ladder
584
+ // drains at its own backoff; the wake resolves delivered when its
585
+ // eventual turn settles.
586
+ w.timedOut = true;
587
+ }
588
+ }
589
+
590
+ /** Park a busy-held fire whose bounded ladder is spent. The fire is NOT
591
+ * dropped and NOT counted as exhausted: it waits for one late delivery at
592
+ * the next idle drain. An untracked deferral (a wiring defect — every wake
593
+ * path tracks before sending) is parked on a fresh entry so a held wake
594
+ * can never be lost here. */
595
+ private parkBusyFire(
596
+ timer: ScheduledTimer,
597
+ w: OutstandingWake | undefined,
598
+ attempt: number,
599
+ now: number,
600
+ ): void {
601
+ if (w) {
602
+ w.parkedBusy = true;
603
+ w.timedOut = true;
604
+ } else {
605
+ this.outstanding.set(timer.id, {
606
+ timer,
607
+ attempt,
608
+ sentAt: now,
609
+ busyDeferred: true,
610
+ heldSince: now,
611
+ parkedBusy: true,
612
+ timedOut: true,
613
+ });
614
+ log.warn(`[timer] busy deferral for an untracked fire — parked it directly: ${timer.id}`);
615
+ }
616
+ this.timeoutCounts.delete(timer.id);
617
+ this.stats.heldBusy++;
618
+ log.info(
619
+ `[timer] wake fire held while the session was busy — ` +
620
+ `${this.getMaxAttempts()} attempt(s) spent, parked for one late delivery: ${timer.id}`,
621
+ );
622
+ }
623
+
624
+ /**
625
+ * Hand off parked busy-held fires that can be delivered now: the session is
626
+ * not positively busy (an active run / pre-flight / compaction keeps them
627
+ * parked — the send's own onBusy hook would only hold the fire again, so
628
+ * waiting keeps this to one handoff per settle rather than one attempt per
629
+ * poll tick). Each handed-off fire is marked in-flight so a concurrent tick
630
+ * cannot hand it off twice; the caller re-tracks it (trackWake) and a send
631
+ * that is deferred again is held again — one fresh rung, then a re-park once
632
+ * the cap is hit again.
633
+ */
634
+ drainParkedBusy(): ParkedBusyDelivery[] {
635
+ if (this.isFireTurnRunning()) return [];
636
+ const now = this.now();
637
+ const out: ParkedBusyDelivery[] = [];
638
+ for (const [, w] of this.outstanding) {
639
+ if (!w.parkedBusy || w.parkedDelivering) continue;
640
+ w.parkedDelivering = true;
641
+ out.push({ timer: w.timer, heldMs: Math.max(0, now - (w.heldSince ?? w.sentAt)) });
642
+ }
643
+ return out;
644
+ }
645
+
646
+ /** Forget a parked busy-held fire without a late delivery — its content was
647
+ * shown non-waking (terminal-error breaker) or the caller withdrew it. */
648
+ forgetParkedBusy(timerId: string): void {
649
+ if (this.outstanding.get(timerId)?.parkedBusy) this.outstanding.delete(timerId);
650
+ }
651
+
652
+ /**
653
+ * Called on every poll tick / TOOL_EXECUTION_END / TURN_END (the same
654
+ * ticks that fire expired timers). First re-arms outstanding wakes that
655
+ * never got an outcome (timeout fallback), then returns retries whose
656
+ * backoff has elapsed. The CALLER performs the redelivery (deferred via
657
+ * setTimeout(0), like every fire-path send) and re-tracks the outcome via
658
+ * trackWake(timer, attempt).
659
+ */
660
+ drainDue(): DueRetry[] {
661
+ const now = this.now();
662
+ // A retryable failure may still be inside pi-core's auto-retry
663
+ // cycle — the run's final outcome is undecided, so the outcome timeout
664
+ // must NOT arm a mid-cycle redelivery (the flood source). After the hold
665
+ // expires the normal timeout math applies (bounded re-check); a settle
666
+ // in the meantime clears the hold entirely.
667
+ const holdActive = this.retryHoldUntil !== null && now < this.retryHoldUntil;
668
+ // Long-run grace: an outcome window that elapses while a run is active
669
+ // for a wake whose send was NOT busy-deferred is a merely-long turn, not
670
+ // a lost send. Do not arm (and do not count it toward the repeated-
671
+ // timeout stall signal): the run's own settle resolves the wake. The
672
+ // 240s window keeps its job for the send that never started a turn
673
+ // (pre-flight abort — no run is active then, so the timeout arms with
674
+ // the honest "timeout" cause and the recovery path survives).
675
+ const runActive = !holdActive && this.isFireTurnRunning();
676
+ for (const [id, w] of this.outstanding) {
677
+ if (w.timedOut) continue; // A retry is already armed for this delivery
678
+ if (holdActive) continue;
679
+ if (runActive && !w.busyDeferred) continue; // long-run grace
680
+ if (now - w.sentAt < WAKE_OUTCOME_TIMEOUT_MS) continue;
681
+ this.stats.timedOut++;
682
+ const timeouts = (this.timeoutCounts.get(id) ?? 0) + 1;
683
+ this.timeoutCounts.set(id, timeouts);
684
+ log.warn(
685
+ `[timer] wake outcome timeout (${WAKE_OUTCOME_TIMEOUT_MS}ms, #${timeouts} for this fire) for ${id} — re-arming for retry`,
686
+ );
687
+ try {
688
+ this.wakeObserver?.onOutcomeTimeout?.(w.timer, timeouts);
689
+ } catch {
690
+ // alerting must never break the retry arming
691
+ }
692
+ const armed = this.scheduleRetry(
693
+ w.timer,
694
+ w.attempt + 1,
695
+ now,
696
+ w.busyDeferred ? "busy" : "timeout",
697
+ );
698
+ if (armed) {
699
+ // Keep the entry (marked) so the eventual settle of this
700
+ // delivery — success OR failure — still resolves it. Deleting here
701
+ // orphaned the chain: the later successful settle found
702
+ // an empty outstanding map and the armed retry kept firing.
703
+ w.timedOut = true;
704
+ } else {
705
+ // Exhausted (pre-flight-abort chain): nothing left to resolve.
706
+ this.outstanding.delete(id);
707
+ }
708
+ }
709
+ const due: DueRetry[] = [];
710
+ const remaining: RetryEntry[] = [];
711
+ for (const r of this.retries) {
712
+ if (r.nextAttemptAt <= now) {
713
+ due.push({ timer: r.timer, attempt: r.attempt, cause: r.cause });
714
+ } else {
715
+ remaining.push(r);
716
+ }
717
+ }
718
+ this.retries = remaining;
719
+ return due;
720
+ }
721
+
722
+ /** Fires dropped after exceeding the redelivery bound (for a final notice). */
723
+ takeExhausted(): ScheduledTimer[] {
724
+ const out = this.exhaustedFires;
725
+ this.exhaustedFires = [];
726
+ return out;
727
+ }
728
+
729
+ /** Park a recovered persisted fire for post-settle delivery (fix 3). */
730
+ deferRecoveredFire(fire: RecoveredFire): void {
731
+ this.deferredRecovered.push(fire);
732
+ }
733
+
734
+ /** Drain parked recovered fires (one-shot; re-park on delivery failure). */
735
+ takeRecoveredFires(): RecoveredFire[] {
736
+ const out = this.deferredRecovered;
737
+ this.deferredRecovered = [];
738
+ return out;
739
+ }
740
+
741
+ deferredRecoveredCount(): number {
742
+ return this.deferredRecovered.length;
743
+ }
744
+
745
+ outstandingCount(): number {
746
+ return this.outstanding.size;
747
+ }
748
+
749
+ /**
750
+ * Whether any OUTSTANDING wake is a redelivery
751
+ * (attempt >= 1 — re-tracked via trackWake(timer, attempt) by the
752
+ * redelivery path). While true, a wake fire re-delivered after a failed
753
+ * turn is in flight and its outcome has not settled. Read-only query —
754
+ * NO redelivery behavior change (redelivery logic itself is out of scope
755
+ * for callers of this accessor).
756
+ *
757
+ * Precision note: if the wake-gate rewrote the retry into a queued steer
758
+ * inside an active run, this stays true until that run settles, so one
759
+ * unrelated mid-run judge opportunity may be skipped. A skipped judge is
760
+ * merely delayed (next non-redelivery turn judges); a false FAIL audit of
761
+ * a fragment turn is the failure mode this gate exists to prevent.
762
+ */
763
+ hasOutstandingRedelivery(): boolean {
764
+ for (const w of this.outstanding.values()) {
765
+ if (w.attempt >= 1) return true;
766
+ }
767
+ return false;
768
+ }
769
+
770
+ pendingRetryCount(): number {
771
+ return this.retries.length;
772
+ }
773
+
774
+ /**
775
+ * Retire a cancelled timer's fire: drop its outstanding wake (if any), its
776
+ * armed ladder, any parked recovered fire for the id, and the repeated-
777
+ * timeout bookkeeping. Marks the id retired so an in-flight send is
778
+ * suppressed (see `retired`). Called from cancelTimer — including when the
779
+ * timer is no longer in the manager map (a fired one-shot is deleted from
780
+ * it at expiry, but its wake ladder may still be armed; the cancel must
781
+ * reach it). Retirement is a WITHDRAWAL, not a delivery: stats.succeeded
782
+ * stays untouched.
783
+ */
784
+ retireTimer(timerId: string): void {
785
+ const hadOutstanding = this.outstanding.delete(timerId);
786
+ const retriesBefore = this.retries.length;
787
+ this.retries = this.retries.filter((r) => r.timer.id !== timerId);
788
+ const droppedRetries = retriesBefore - this.retries.length;
789
+ const recoveredBefore = this.deferredRecovered.length;
790
+ this.deferredRecovered = this.deferredRecovered.filter((f) => f.id !== timerId);
791
+ const droppedRecovered = recoveredBefore - this.deferredRecovered.length;
792
+ this.timeoutCounts.delete(timerId);
793
+ this.retired.add(timerId);
794
+ if (hadOutstanding || droppedRetries > 0 || droppedRecovered > 0) {
795
+ log.info(
796
+ `[timer] timer cancelled — retired its fire ` +
797
+ `(outstanding wake: ${hadOutstanding ? "cleared" : "none"}, ` +
798
+ `pending retries: ${droppedRetries}, parked recovered fires: ${droppedRecovered}): ${timerId}`,
799
+ );
800
+ }
801
+ }
802
+
803
+ /**
804
+ * Retire every fire matching the predicate (tag/session-scoped cancels).
805
+ * Walks the queue's own records — the outstanding wakes, the armed
806
+ * ladders, and the parked recovered fires — so it also reaches fires that
807
+ * already left the manager map (fired one-shots; delete-on-detection).
808
+ * Returns the retired timer ids.
809
+ */
810
+ retireTimersWhere(predicate: (t: ScheduledTimer) => boolean): string[] {
811
+ const ids = new Set<string>();
812
+ for (const [, w] of this.outstanding) if (predicate(w.timer)) ids.add(w.timer.id);
813
+ for (const r of this.retries) if (predicate(r.timer)) ids.add(r.timer.id);
814
+ for (const f of this.deferredRecovered) {
815
+ if (f.wake && f.sessionId) {
816
+ const asTimer: ScheduledTimer = {
817
+ id: f.id,
818
+ sessionId: f.sessionId,
819
+ firesAt: f.firesAt ?? 0,
820
+ reason: f.reason,
821
+ tag: f.tag,
822
+ createdAt: f.createdAt ?? 0,
823
+ wake: true,
824
+ };
825
+ if (predicate(asTimer)) ids.add(f.id);
826
+ }
827
+ }
828
+ const out = [...ids];
829
+ for (const id of out) this.retireTimer(id);
830
+ return out;
831
+ }
832
+
833
+ /** Whether the id is retired (cancel guard for in-flight sends). */
834
+ isRetired(timerId: string): boolean {
835
+ return this.retired.has(timerId);
836
+ }
837
+
838
+ /** Whether any live wake state exists for the id (outstanding wake, armed
839
+ * ladder, parked recovered fire). Read BEFORE a cancel so the caller can
840
+ * distinguish "nothing to cancel" from "the fire already left the timer
841
+ * map but its ladder was retired". */
842
+ hasWakeFireState(timerId: string): boolean {
843
+ if (this.outstanding.has(timerId)) return true;
844
+ if (this.retries.some((r) => r.timer.id === timerId)) return true;
845
+ return this.deferredRecovered.some((f) => f.id === timerId);
846
+ }
847
+
848
+ getStats(): WakeRetryStats {
849
+ return { ...this.stats };
850
+ }
851
+
852
+ /** Reset all state. Test helper (process-lifetime singleton). */
853
+ resetForTests(): void {
854
+ this.outstanding.clear();
855
+ this.retries = [];
856
+ this.exhaustedFires = [];
857
+ this.deferredRecovered = [];
858
+ this.lastRunFailed = null;
859
+ this.landedTimerIds = null;
860
+ this.retryHoldUntil = null;
861
+ this.retryHoldOverrideMs = null;
862
+ this.maxAttemptsOverride = null;
863
+ this.timeoutCounts.clear();
864
+ this.retired.clear();
865
+ // setWakeObserver wiring deliberately survives: it is production wiring,
866
+ // not per-test outcome state (the timer extension sets it once at load).
867
+ // The active-run predicate survives the same way.
868
+ this.stats = { tracked: 0, succeeded: 0, timedOut: 0, exhausted: 0, heldBusy: 0 };
869
+ }
870
+
871
+ /** Drop pending redeliveries for a timer id (success clears the chain). */
872
+ private cancelPendingRetries(timerId: string): void {
873
+ const before = this.retries.length;
874
+ this.retries = this.retries.filter((r) => r.timer.id !== timerId);
875
+ if (this.retries.length < before) {
876
+ log.info(
877
+ `[timer] wake turn succeeded — cleared ${before - this.retries.length} pending retry(ies) for ${timerId}`,
878
+ );
879
+ }
880
+ }
881
+
882
+ /**
883
+ * Arm (or replace) the pending redelivery for a fire. Replace-by-id —
884
+ * the outcome-timeout path may already have armed a retry while the failed
885
+ * turn was still running; a genuine settle-failure must escalate that entry
886
+ * in place, never stack a second redelivery for the same fire.
887
+ * Returns true if armed, false if the bound is exhausted.
888
+ */
889
+ private scheduleRetry(
890
+ timer: ScheduledTimer,
891
+ attempt: number,
892
+ now: number,
893
+ cause: WakeRetryCause = "failed",
894
+ ): boolean {
895
+ const maxAttempts = this.getMaxAttempts();
896
+ if (attempt > maxAttempts) {
897
+ this.stats.exhausted++;
898
+ this.timeoutCounts.delete(timer.id);
899
+ this.exhaustedFires.push(timer);
900
+ log.error(
901
+ `[timer] wake fire permanently undelivered after ${maxAttempts} redeliveries: ` +
902
+ `${timer.id} (${timer.reason})`,
903
+ );
904
+ return false;
905
+ }
906
+ const backoff = WAKE_RETRY_BACKOFF_MS[Math.min(attempt - 1, WAKE_RETRY_BACKOFF_MS.length - 1)];
907
+ this.retries = this.retries.filter((r) => r.timer.id !== timer.id);
908
+ this.retries.push({ timer, attempt, nextAttemptAt: now + backoff, cause });
909
+ log.info(
910
+ `[timer] wake fire undelivered (attempt ${attempt}/${maxAttempts}, ${cause}) — retry in ${backoff}ms: ${timer.id}`,
911
+ );
912
+ return true;
913
+ }
914
+ }
915
+
916
+ /** The process-wide queue (single pi session per process). */
917
+ export const wakeRetryQueue = new WakeRetryQueue();
918
+
919
+ /**
920
+ * Read accessor: is a wake-retry redelivery (attempt >= 1)
921
+ * currently in flight (tracked, outcome not settled)? The enforcement
922
+ * verification judge uses this to SKIP auditing the redelivered tail turn —
923
+ * a fragment the judge would otherwise treat as the whole task. Read-only;
924
+ * no redelivery behavior change.
925
+ */
926
+ export function isWakeRedeliveryInFlight(): boolean {
927
+ return wakeRetryQueue.hasOutstandingRedelivery();
928
+ }
929
+
930
+ /**
931
+ * Deliver parked recovered fires post-settle. Called from
932
+ * agent_settled handlers (timer extension primary + prompt-builder fallback —
933
+ * takeRecoveredFires() drains, so double registration cannot double-deliver;
934
+ * onAgentSettled() is idempotent, so outcome resolution is order-safe).
935
+ *
936
+ * wake:true fires start their own turn (safe here: the run has fully settled
937
+ * and pi-core released activeRun; the triggerTurn deferral in
938
+ * sendTrackedMessage keeps the macrotask boundary). If the session is busy
939
+ * at flush time anyway (an overlapping compaction, say), the busy hook
940
+ * re-parks the fire — the next settle flushes it; never silently lost.
941
+ * wake:false fires ride as advisory steers, as before. Every delivered wake
942
+ * is tracked so a failed delivery retries with backoff.
943
+ */
944
+ export function flushRecoveredFires(pi: ExtensionAPI, ctx?: unknown): void {
945
+ const fires = wakeRetryQueue.takeRecoveredFires();
946
+ // Resolve any outstanding wake outcomes FIRST so the freshly-flushed fires
947
+ // are never mis-attributed to the previous run's failure.
948
+ wakeRetryQueue.onAgentSettled();
949
+ if (fires.length === 0) return;
950
+ log.info(`[timer] flushing ${fires.length} recovered persisted fire(s) post-settle`);
951
+ for (const t of fires) {
952
+ // Every recovered fire carries the SAME timing marker as a live fire
953
+ // (fire-timing.ts): a fire recovered after a restart can be very late,
954
+ // and a bare reason line reads as on-time — the agent needs the drift
955
+ // to reason about what it is resuming.
956
+ const { fireTiming, elapsedSec, driftLabel } = describeFireTiming(
957
+ t.createdAt,
958
+ t.firesAt,
959
+ Date.now(),
960
+ );
961
+ if (driftLabel !== "0m") {
962
+ log.info(`[timer] recovered fire ${t.id} delivered late by ${driftLabel}`);
963
+ }
964
+ const text =
965
+ t.wake === true
966
+ ? `${t.reason} - ${fireTiming}. ${elapsedSec}s elapsed since scheduled. Resume the task.`
967
+ : `${t.reason} (${fireTiming}) (recovered after restart)`;
968
+ try {
969
+ if (t.wake === true && terminalBreakerBlocksWake(ctx)) {
970
+ // Terminal-error breaker open: the recovered reminder is still shown,
971
+ // but rides non-waking and is not tracked (no turn to resolve).
972
+ log.info(`[timer] recovered fire ${t.id} demoted to non-waking (turn-start blocked)`);
973
+ sendTrackedMessage(
974
+ pi,
975
+ {
976
+ customType: "timer-fire",
977
+ content: [{ type: "text" as const, text }],
978
+ display: true,
979
+ details: {
980
+ [BRAID_INJECTED]: true,
981
+ [BRAID_SOURCE]: "timer/persisted-fire",
982
+ timerId: t.id,
983
+ sessionId: t.sessionId,
984
+ recovered: true,
985
+ wake: true,
986
+ breakerSuppressed: true,
987
+ },
988
+ },
989
+ { delivery: "park", deliverAs: "steer" },
990
+ { type: "heartbeat", source: "timer/persisted-fire" },
991
+ { bypassFloodCap: true },
992
+ );
993
+ continue;
994
+ }
995
+ if (t.wake === true) {
996
+ wakeRetryQueue.trackWake({
997
+ id: t.id,
998
+ sessionId: t.sessionId,
999
+ firesAt: t.firesAt ?? Date.now(),
1000
+ reason: t.reason,
1001
+ tag: t.tag,
1002
+ createdAt: t.createdAt ?? Date.now(),
1003
+ wake: true,
1004
+ });
1005
+ sendTrackedMessage(
1006
+ pi,
1007
+ {
1008
+ customType: "timer-fire",
1009
+ content: [{ type: "text" as const, text }],
1010
+ display: true,
1011
+ details: {
1012
+ [BRAID_INJECTED]: true,
1013
+ [BRAID_SOURCE]: "timer/persisted-fire",
1014
+ timerId: t.id,
1015
+ sessionId: t.sessionId,
1016
+ recovered: true,
1017
+ wake: true,
1018
+ },
1019
+ },
1020
+ { triggerTurn: true },
1021
+ { type: "heartbeat", source: "timer/persisted-fire" },
1022
+ { bypassFloodCap: true },
1023
+ {
1024
+ onBusy: () => {
1025
+ // Session busy at send time: re-park; the next settle flushes.
1026
+ wakeRetryQueue.deferRecoveredFire(t);
1027
+ },
1028
+ },
1029
+ );
1030
+ } else {
1031
+ sendTrackedMessage(
1032
+ pi,
1033
+ {
1034
+ customType: "timer",
1035
+ content: [{ type: "text" as const, text }],
1036
+ display: true,
1037
+ details: {
1038
+ [BRAID_INJECTED]: true,
1039
+ [BRAID_SOURCE]: "timer/persisted-fire",
1040
+ timerId: t.id,
1041
+ recovered: true,
1042
+ wake: false,
1043
+ },
1044
+ },
1045
+ { delivery: "park", deliverAs: "steer" },
1046
+ { type: "heartbeat", source: "timer/persisted-fire" },
1047
+ { bypassFloodCap: true },
1048
+ );
1049
+ }
1050
+ } catch (e) {
1051
+ // Send failed: park it again — the next settle retries. Never
1052
+ // silently lose a recovered fire.
1053
+ log.warn(`[timer] recovered fire delivery failed, re-deferred: ${(e as Error).message}`);
1054
+ wakeRetryQueue.deferRecoveredFire(t);
1055
+ }
1056
+ }
1057
+ }