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,1246 @@
1
+ /**
2
+ * Watchdog Engine — pure liveness/stall state machine.
3
+ *
4
+ * monitor → detect → escalate:
5
+ * - MONITOR: turn progress (session-start / message_end / agent_start /
6
+ * agent_end / tool_call hooks → observeX), the keyring LLM feedback feed
7
+ * (reportFailure/reportSuccess → recordLlmX), and tunnel liveness
8
+ * transitions (telegram → core hub → subscribeTunnel).
9
+ * - DETECT: a small matrix, all local and zero-LLM:
10
+ * 1. turn-stall: an active turn with no tool-call AND no turn-complete
11
+ * for > stallMult × baseMs since last activity
12
+ * (activity = last tool-call or last progress, NOT wall
13
+ * clock — quiet by construction while tool-calling).
14
+ * 2. quota-loop: ≥ quotaErrors consecutive quota-class LLM failures
15
+ * (rate-limit/balance/auth/key-ring exhaustion) with no
16
+ * success. Failures are classified via
17
+ * classifyLlmError (lib/errors/llm-error); transient,
18
+ * abort, and unknown failures never count — they get a
19
+ * separate log-only streak (no escalation from it).
20
+ * 3. tunnel-down: ≥ tunnelFailures consecutive getUpdates failures
21
+ * (telegram emits the transition; this engine hosts the
22
+ * confirmation gate + escalation).
23
+ * - ESCALATE: waking whisper (wakeWhisper) + optional 1-line tg signal
24
+ * (tgSignal). The FIRST escalation of an open condition always fires
25
+ * (threshold crossing). Repeats while the condition stays continuously
26
+ * open are milestone-throttled so one long outage cannot flood the owner
27
+ * with duplicate barks (outage: dozens of near-identical
28
+ * barks from concurrent pi processes): quota/tunnel re-warn only when
29
+ * their failure count crosses one of REWARN_MILESTONES (the ladder
30
+ * resets on close, so each outage gets its own milestone set), and
31
+ * turn-stall (no natural counter) falls back to a LONG cooldown
32
+ * (STALL_REWARN_COOLDOWN_MULT × cooldownMs). The normal cooldown
33
+ * remains as a second gate — strictly-fewer barks, never more. Tunnel
34
+ * recovery emits a quiet recovery whisper.
35
+ *
36
+ * Soft backoff: base cadence (baseMs) while clean, hot cadence (hotMs) while at
37
+ * least one issue is open, back to base when all clear.
38
+ *
39
+ * Bounded stall ladder (the actuation half of turn-stall): the predicate keeps
40
+ * its first bark; an episode classifies before it actuates.
41
+ * The classification is a conjunction — the session is streaming, no provider
42
+ * stream activity for streamSilenceMs (wire heartbeat, tracked separately
43
+ * from tool-call silence), the transcript's last event is a tool result or a
44
+ * provider error with no continuation, and no timer/wake is due. The first
45
+ * fire of an episode stays advisory; a later confirmed-dead fire persists a
46
+ * resume marker (pending tool call + partial output) to a durable seat,
47
+ * aborts the dead turn once, pages the owner, and stops the ladder. Without a
48
+ * durable seat the turn is marked unready and surfaced, never killed and
49
+ * forgotten. Counter-less re-warns keep their long cooldown while the episode
50
+ * has not reached a terminal hand-back.
51
+ *
52
+ * Pure + fully injectable (fake timers/now/whispers, no network) so fixture
53
+ * tests drive the whole matrix deterministically. State lives in the factory
54
+ * closure (never a module-level let — src/lib/state/AGENTS.md contract).
55
+ *
56
+ * Owns liveness/stall/escalation only. The heartbeat-scheduler owns cognitive
57
+ * interventions (silence/context/error-accumulation triggers, meta-learning,
58
+ * whisper-batcher) — this engine does NOT re-emit those events.
59
+ */
60
+
61
+ import { classifyLlmError, extractHttpCodeFromText } from "../../../lib/errors/llm-error.js";
62
+ import { WATCHDOG_ESCALATION_BUDGET_PER_SESSION } from "../../../lib/detection/context-thresholds.js";
63
+ import { formatLocalTime } from "../../../lib/utils/local-time.js";
64
+
65
+ export type WatchdogMode = "on" | "off";
66
+
67
+ export interface WatchdogConfig {
68
+ mode: WatchdogMode;
69
+ /** BASE cadence (ms) — healthy recheck interval, resurrection target. */
70
+ baseMs: number;
71
+ /** HOT cadence (ms) — recheck interval while ≥1 issue is open. */
72
+ hotMs: number;
73
+ /** Turn-stall threshold as a multiple of baseMs (5 × 15min = 75min). */
74
+ stallMult: number;
75
+ /** Provider stream-silence threshold (ms): a streaming turn with no wire
76
+ * activity for longer than this is silent, not slow. */
77
+ streamSilenceMs: number;
78
+ /** Consecutive quota-class LLM failures (rate-limit/balance/auth/ring exhaustion, no success since) that trip quota-loop. */
79
+ quotaErrors: number;
80
+ /** Consecutive getUpdates failures (telegram confirmation gate) that trip tunnel-down. */
81
+ tunnelFailures: number;
82
+ }
83
+
84
+ /** Code-constant defaults — `broker.watchdog` in settings.json overrides. */
85
+ export const DEFAULT_WATCHDOG_CONFIG: WatchdogConfig = {
86
+ mode: "on",
87
+ baseMs: 15 * 60 * 1000, // 15 min (healthy)
88
+ hotMs: 3 * 60 * 1000, // 3 min (≥1 open issue)
89
+ stallMult: 5,
90
+ streamSilenceMs: 10 * 60 * 1000, // 10 min of wire silence while streaming
91
+ quotaErrors: 3,
92
+ tunnelFailures: 5, // gate raised from 3: sibling canaries colliding with this poller's long-poll caused false tunnel-down floods
93
+ };
94
+
95
+ /** Per-condition re-escalation cooldown = this × hotMs (2 HOT periods). */
96
+ export const WATCHDOG_COOLDOWN_MULT = 2;
97
+
98
+ /**
99
+ * Sparse re-warn milestones for continuously-open conditions that have a
100
+ * natural failure counter (quota-loop: quotaConsecutive; tunnel-down:
101
+ * tunnel.failures). A repeat escalation fires only when the count CROSSES one
102
+ * of these from below; the first bark at threshold crossing is unaffected.
103
+ * Per-condition fired-state resets ONLY when the episode latch re-arms
104
+ * (success streak) — NOT on every transient close (the close→open re-fire
105
+ * produced the measured 143-escalation flap storm,).
106
+ */
107
+ const REWARN_MILESTONES = [20, 50, 100, 200, 500] as const;
108
+ /** How many unclassified-failure records the snapshot retains. */
109
+ const UNKNOWN_FAILURE_RING_CAP = 5;
110
+
111
+ /** Final rung of the milestone ladder — the only re-warn that still fires
112
+ * after the per-session escalation budget is exhausted. */
113
+ const FINAL_REWARN_MILESTONE: number = REWARN_MILESTONES[REWARN_MILESTONES.length - 1];
114
+
115
+ /**
116
+ * Flap latch: the FIRST escalation of an open episode always fires
117
+ * (wake-up feature — with dynamic quota the first bark wakes
118
+ * the agent to retry and it may recover). Re-arm requires a SUCCESS STREAK:
119
+ * this many consecutive healthy evaluations (evaluateQuota) or consecutive
120
+ * LLM successes (recordLlmSuccess). A transient close (failures dip below
121
+ * threshold) does NOT re-arm — a close→open flap inside that window is the
122
+ * SAME episode: no new wake bark, milestone ladder retains its high-water.
123
+ */
124
+ const QUOTA_REARM_SUCCESS_STREAK = 3;
125
+
126
+ /**
127
+ * Counter-less conditions (turn-stall) cannot milestone-throttle on a failure
128
+ * count; their repeat re-warn falls back to a LONG cooldown:
129
+ * STALL_REWARN_COOLDOWN_MULT × cooldownMs (sparse but still periodic).
130
+ */
131
+ const STALL_REWARN_COOLDOWN_MULT = 4;
132
+
133
+ /**
134
+ * Escalation fires within one stall episode before the ladder attempts
135
+ * remediation: fire 1 classifies and notifies, fire 2 (confirmed dead)
136
+ * persists the resume marker and aborts once. The ladder is bounded by the
137
+ * terminal hand-backs, never by an unbounded re-warn.
138
+ */
139
+ export const STALL_SERVICE_FIRE = 2;
140
+
141
+ /** Bounds on the resume-marker payload (no unbounded text in a session entry). */
142
+ const RESUME_MARKER_TEXT_CAP = 500;
143
+ const RESUME_MARKER_ARGS_CAP = 200;
144
+
145
+ export type WatchdogConditionId =
146
+ | "turn-stall"
147
+ | "quota-loop"
148
+ | "tunnel-down"
149
+ | "wake-delivery"
150
+ | "terminal-stop";
151
+
152
+ export interface TunnelTransitionEvent {
153
+ status: "up" | "down";
154
+ failures: number;
155
+ lastError?: string;
156
+ message: string;
157
+ }
158
+
159
+ export interface TunnelStatusSnapshot {
160
+ status: "up" | "down" | "unknown";
161
+ failures: number;
162
+ }
163
+
164
+ /** Classification of an open turn-stall episode before any actuation. */
165
+ export type StallClassificationKind = "alive" | "silent" | "dead" | "remediated" | "unready";
166
+
167
+ /** The durable resume payload written before a dead turn is aborted. Carries
168
+ * what a resumed session needs to continue instead of re-running the dead
169
+ * step: the pending tool call, the partial output seen on the wire, and the
170
+ * terminal shape that classified the turn dead. */
171
+ export interface StallResumeMarker {
172
+ sessionKey: string;
173
+ detectedAt: number;
174
+ stallAgeMs: number;
175
+ /** Wire silence at detection; undefined when no stream event was ever seen. */
176
+ streamSilentForMs: number | undefined;
177
+ transcriptTerminal: boolean;
178
+ transcriptTerminalKind?: "tool-result" | "error";
179
+ /** Last tool call observed with no observed result (the unexecuted call). */
180
+ pendingToolCall?: { toolName: string; toolCallId?: string; argsPreview?: string };
181
+ /** Bounded tail of the partial assistant output observed on the wire. */
182
+ partialOutput?: string;
183
+ /** Escalation fires this episode at the moment of remediation. */
184
+ fires: number;
185
+ }
186
+
187
+ /** Per-episode stall detail for the status surface (non-clean episodes only). */
188
+ export interface StallEpisodeSnapshot {
189
+ key: string;
190
+ open: boolean;
191
+ classification: StallClassificationKind;
192
+ streamSilentForMs: number | undefined;
193
+ transcriptTerminal: boolean;
194
+ fires: number;
195
+ remediated: boolean;
196
+ ended: boolean;
197
+ }
198
+
199
+ export interface WatchdogEngineDeps {
200
+ now: () => number;
201
+ /** Schedule `cb` after `ms`; returns a cancel function (fake-timer seam). */
202
+ schedule: (cb: () => void, ms: number) => () => void;
203
+ /** Waking whisper (triggerTurn) — the escalation action. */
204
+ wakeWhisper: (text: string) => void;
205
+ /** Non-waking whisper (nextTurn/steer) — recovery notifications. */
206
+ quietWhisper: (text: string) => void;
207
+ /** Non-waking whisper for the terminal-stop episode. Falls back to
208
+ * `quietWhisper` when absent, so fixture tests can capture either. Must
209
+ * never throw. */
210
+ terminalStopWhisper?: (text: string) => void;
211
+ /** Optional 1-line tg signal; must never throw (absent = skipped). */
212
+ tgSignal?: (text: string) => void;
213
+ /** Optional tunnel transition subscription; the engine wires + disposes it. */
214
+ subscribeTunnel?: (fn: (event: TunnelTransitionEvent) => void) => () => void;
215
+ /** Optional current tunnel status snapshot (robustness against missed events). */
216
+ getTunnelStatus?: () => TunnelStatusSnapshot;
217
+ /** Optional 1-line telemetry emission per detect pass (Hook 2: the
218
+ * cheap idle-inclusive context-heartbeat line). Absent = skipped, so
219
+ * fixture tests stay hermetic. Must never throw. */
220
+ telemetryEmit?: (entry: WatchdogTelemetryEntry) => void;
221
+ /** Persist a resume marker to a durable seat (session entry). Returns true
222
+ * when the seat accepted it; absent or false means no durable checkpoint
223
+ * exists, so the ladder marks the turn unready instead of aborting. */
224
+ persistResumeMarker?: (key: string, marker: StallResumeMarker) => boolean;
225
+ /** Mechanical abort of the dead turn (the compaction cancel precedent).
226
+ * Called at most once per episode — the engine latches remediation. */
227
+ abortTurn?: (key: string) => void;
228
+ /** True when a timer/wake is due for this session: a due wake legitimately
229
+ * keeps a quiet session quiet, so the turn is not classified dead. */
230
+ isWakeDue?: (key: string) => boolean;
231
+ log?: (level: "debug" | "info" | "warn" | "error", message: string, ...rest: unknown[]) => void;
232
+ }
233
+
234
+ /** Scalar-only watchdog observer line (see lib/telemetry/context-heartbeat.ts). */
235
+ export interface WatchdogTelemetryEntry {
236
+ ts: number;
237
+ source: "watchdog";
238
+ rssBytes: number;
239
+ heapUsed: number;
240
+ cadence: "base" | "hot";
241
+ openConditions: string;
242
+ quotaConsecutive: number;
243
+ tunnelStatus: "up" | "down" | "unknown";
244
+ tunnelFailures: number;
245
+ stalledCount: number;
246
+ nextCheckInMs: number;
247
+ }
248
+
249
+ export interface WatchdogSnapshot {
250
+ enabled: boolean;
251
+ cadence: "base" | "hot";
252
+ openConditions: WatchdogConditionId[];
253
+ quotaConsecutive: number;
254
+ tunnel: TunnelStatusSnapshot;
255
+ stalledSessions: string[];
256
+ /** Non-clean stall episodes (open or terminal) with their classification. */
257
+ stallEpisodes: StallEpisodeSnapshot[];
258
+ nextCheckAt: number;
259
+ /** Unclassified LLM failures (last 5, newest last): raw bounded text +
260
+ * provider + HTTP code. During a provider outage the classifier can
261
+ * bucket dozens of failures as `unknown`, leaving nothing but a counter
262
+ * — root-causing then requires a forensic pass over logs. Classified
263
+ * failures (quota/auth/rate/exhaustion) never enter. */
264
+ unknownFailures: UnknownLlmFailure[];
265
+ /** Consecutive terminal-category (auth/balance) failures since the last
266
+ * success; feeds the terminal-stop episode. */
267
+ terminalConsecutive: number;
268
+ }
269
+
270
+ /** One unclassified LLM failure as retained by the snapshot ring. */
271
+ export interface UnknownLlmFailure {
272
+ /** Engine clock (ms) when the failure was recorded. */
273
+ at: number;
274
+ /** Bounded (≤200 chars) raw error text as the keyring reported it. */
275
+ text: string;
276
+ provider?: string;
277
+ model?: string;
278
+ /** First standalone 4xx/5xx token in the text, when present. */
279
+ statusCode?: number;
280
+ }
281
+
282
+ export interface WatchdogEngine {
283
+ start(): void;
284
+ stop(): void;
285
+ /** Session lifecycle + turn-progress bookkeeping (index.ts wires pi hooks). */
286
+ observeSessionStart(key: string): void;
287
+ /** A message ended. `assistant` also clears the terminal-transcript state:
288
+ * the last event is a completed assistant message, not a stranded call. */
289
+ observeProgress(key: string, kind?: "assistant" | "other"): void;
290
+ /** A tool call was issued; `tool` carries the resume-marker payload. */
291
+ observeToolCall(
292
+ key: string,
293
+ tool?: { toolCallId?: string; toolName?: string; argsPreview?: string },
294
+ ): void;
295
+ /** Provider stream heartbeat (assistant deltas): wire liveness. */
296
+ observeStreamActivity(key: string, partialText?: string): void;
297
+ /** A tool result landed: the transcript's last event awaits continuation. */
298
+ observeToolResult(key: string, toolCallId?: string): void;
299
+ /** The last transcript event is a provider error with no continuation. */
300
+ observeTranscriptError(key: string): void;
301
+ observeTurnStart(key: string): void;
302
+ observeTurnComplete(key: string): void;
303
+ /** Keyring/quota feed: every LLM failure (classified internally) and success.
304
+ * `meta` carries the keyring's provider/model identity so unclassified
305
+ * failures can be root-caused from the record alone. */
306
+ recordLlmFailure(detail?: string, meta?: { provider?: string; model?: string }): void;
307
+ recordLlmSuccess(): void;
308
+ /** Run one detect pass synchronously (scheduled loop + test seam). */
309
+ check(): void;
310
+ getSnapshot(): WatchdogSnapshot;
311
+ /** Wake-delivery feed (timer's retry queue → this engine, via the
312
+ * global-state seam). See WATCHDOG_WAKE_DELIVERY_FEED_KEY. */
313
+ recordWakeOutcomeTimeout(timerId: string, reason: string, timeouts: number): void;
314
+ recordWakeUndelivered(timerId: string, reason: string, attempts: number): void;
315
+ recordWakeDelivered(timerId: string): void;
316
+ }
317
+
318
+ interface StallSession {
319
+ key: string;
320
+ streaming: boolean;
321
+ lastActivityAt: number;
322
+ escalatedAt: number;
323
+ open: boolean;
324
+ /** Last provider stream event (assistant delta); undefined = never seen. */
325
+ lastStreamActivityAt: number | undefined;
326
+ /** The transcript's last event is a tool result or an error, with no
327
+ * continuation yet (the dead shape). */
328
+ transcriptTerminal: boolean;
329
+ transcriptTerminalKind: "tool-result" | "error" | undefined;
330
+ /** Last tool call observed with no observed result (resume payload). */
331
+ pendingToolCall: { toolName: string; toolCallId?: string; argsPreview?: string } | undefined;
332
+ /** Bounded tail of the partial assistant output seen on the wire. */
333
+ partialOutput: string | undefined;
334
+ /** Escalation fires in the current episode (threshold crossing + re-warns). */
335
+ fires: number;
336
+ /** Abort attempted (terminal, ladder stopped). */
337
+ remediated: boolean;
338
+ /** No durable seat accepted the marker (terminal, ladder stopped). */
339
+ unready: boolean;
340
+ /** Terminal hand-back already surfaced: no further warnings/actuation. */
341
+ episodeEnded: boolean;
342
+ }
343
+
344
+ interface ConditionSink {
345
+ open: boolean;
346
+ lastEscalatedAt: number;
347
+ /** Highest REWARN_MILESTONES value fired for the current open episode
348
+ * (0 = none). Reset ONLY when the episode latch re-arms (success
349
+ * streak) — a transient close must not re-arm the ladder mid-episode. */
350
+ lastMilestone: number;
351
+ /** / escalation-injection budget: total barks this condition has
352
+ * produced this session (never resets). Past the budget, only the final
353
+ * milestone (500) still escalates. */
354
+ escalations: number;
355
+ }
356
+
357
+ /** Compact duration for whisper text (e.g. "75m"). */
358
+ export function formatWatchdogDuration(ms: number): string {
359
+ if (ms < 60000) return `${Math.floor(ms / 1000)}s`;
360
+ if (ms < 3600000) return `${Math.floor(ms / 60000)}m`;
361
+ return `${Math.floor(ms / 3600000)}h`;
362
+ }
363
+
364
+ /**
365
+ * Key-ring rotation-exhaustion idioms. The ring reports ALL LLM failures
366
+ * (rotation needs them), and its own exhaustion messages carry no provider
367
+ * status code — they classify as `unknown` yet are quota-class by definition
368
+ * (all keys dead = the owner must act).
369
+ */
370
+ const RING_EXHAUSTION_PATTERN = /key.{0,20}exhaust|keys? exhausted|rotat\w* (exhaust|fail)/i;
371
+
372
+ /** Bounded detail rendering for log lines (never unbounded error text). */
373
+ function truncateDetail(detail: string | undefined): string {
374
+ if (!detail) return "";
375
+ return detail.length > 200 ? `: ${detail.slice(0, 197)}...` : `: ${detail}`;
376
+ }
377
+
378
+ export function createWatchdogEngine(
379
+ config: WatchdogConfig,
380
+ deps: WatchdogEngineDeps,
381
+ ): WatchdogEngine {
382
+ const {
383
+ now,
384
+ schedule,
385
+ wakeWhisper,
386
+ quietWhisper,
387
+ tgSignal,
388
+ terminalStopWhisper,
389
+ subscribeTunnel,
390
+ getTunnelStatus,
391
+ log = () => {},
392
+ } = deps;
393
+
394
+ const cooldownMs = WATCHDOG_COOLDOWN_MULT * config.hotMs;
395
+ // Raw fixture configs may predate the field; resolve once against the default.
396
+ const streamSilenceMs =
397
+ config.streamSilenceMs > 0 ? config.streamSilenceMs : DEFAULT_WATCHDOG_CONFIG.streamSilenceMs;
398
+
399
+ let started = false;
400
+ let stopped = false;
401
+ let timerCancel: (() => void) | undefined;
402
+ let disposeTunnel: (() => void) | undefined;
403
+ let nextCheckAt = 0;
404
+
405
+ // Condition state.
406
+ // Both conditions' `lastEscalatedAt` start at -Infinity ("never escalated")
407
+ // so the first occurrence of an issue always passes the cooldown check — a 0
408
+ // epoch would look like a just-now escalation under a fake clock at t=0.
409
+ const quota: ConditionSink = {
410
+ open: false,
411
+ lastEscalatedAt: Number.NEGATIVE_INFINITY,
412
+ lastMilestone: 0,
413
+ escalations: 0,
414
+ };
415
+ let quotaConsecutive = 0;
416
+ // Flap latch: first-bark availability + consecutive healthy evals or
417
+ // successes since the last escalation. Factory-closure state (never
418
+ // module-level — state contract).
419
+ let quotaLatchArmed = true;
420
+ let quotaHealthyStreak = 0;
421
+ // Transient/unknown LLM failures: tracked separately, log-only — never
422
+ // escalate from this streak (a slept Mac must not look like a quota loop).
423
+ let transientConsecutive = 0;
424
+ const tunnel: ConditionSink & {
425
+ status: "up" | "down" | "unknown";
426
+ failures: number;
427
+ lastMessageEnvelope?: string;
428
+ } = {
429
+ open: false,
430
+ lastEscalatedAt: Number.NEGATIVE_INFINITY,
431
+ lastMilestone: 0,
432
+ escalations: 0,
433
+ status: "unknown",
434
+ failures: 0,
435
+ };
436
+ const stalls = new Map<string, StallSession>();
437
+
438
+ /**
439
+ * Wake-delivery episode (fed by the timer's wake-retry queue via the
440
+ * global-state feed seam — see WATCHDOG_WAKE_DELIVERY_FEED_KEY). Event-
441
+ * driven: the retry queue's own drain ticks are the detection cadence, so
442
+ * this condition needs no detect-pass polling. Dedupe is the episode latch:
443
+ * the FIRST threshold event (repeated outcome timeouts for one fire, or an
444
+ * exhausted drop — whichever comes first) opens the episode and barks once;
445
+ * every later event of the same dead-delivery episode is absorbed. Recovery
446
+ * (a tracked wake settling delivered) closes it with one quiet line.
447
+ */
448
+ const wakeDelivery = { open: false };
449
+
450
+ /**
451
+ * Terminal-provider-stop episode: a distinct counter of auth/balance
452
+ * failures (the quota loop counts rate_limit+balance+auth together — a 429
453
+ * burst is not a terminal stop). ONE non-waking emission per episode: the
454
+ * open flag latches the first threshold crossing; later failures of the
455
+ * same episode are absorbed. Closed on a success, so a genuinely recovered
456
+ * route's next stop barks once more. No milestone re-warn ladder and no
457
+ * escalation-budget accounting: one per episode by construction.
458
+ */
459
+ const terminalStop = { open: false };
460
+ let terminalStopConsecutive = 0;
461
+ let terminalStopFirstAt: number | undefined;
462
+ let terminalStopLastCategory: string | undefined;
463
+ let terminalStopLastStatus: number | undefined;
464
+
465
+ /** Unclassified-failure ring: bounded to the last N records.
466
+ * Factory-closure state (never module-level — src/lib/state/AGENTS.md). */
467
+ const unknownFailures: UnknownLlmFailure[] = [];
468
+
469
+ function isEnabled(): boolean {
470
+ return config.mode === "on" && started && !stopped;
471
+ }
472
+
473
+ function openConditions(): WatchdogConditionId[] {
474
+ const out: WatchdogConditionId[] = [];
475
+ if (quota.open) out.push("quota-loop");
476
+ if (tunnel.open) out.push("tunnel-down");
477
+ if (wakeDelivery.open) out.push("wake-delivery");
478
+ if (terminalStop.open) out.push("terminal-stop");
479
+ for (const s of stalls.values()) if (s.open) out.push("turn-stall");
480
+ return out;
481
+ }
482
+
483
+ function anyOpen(): boolean {
484
+ return openConditions().length > 0;
485
+ }
486
+
487
+ function fireEscalation(text: string, tg: string): void {
488
+ wakeWhisper(text);
489
+ try {
490
+ tgSignal?.(tg);
491
+ } catch {
492
+ // optional — never fatal
493
+ }
494
+ }
495
+
496
+ /**
497
+ * Milestone edge-detector for repeat re-warns: the highest milestone that
498
+ * `n` has reached (n >= milestone, i.e. crossed from below) but that is
499
+ * still above `lastMilestone` (the highest already fired this episode), or
500
+ * undefined when no new milestone was crossed. The fired high-water mark
501
+ * resets only when the episode latch re-arms (success streak), so a
502
+ * flapping condition keeps its ladder while a genuinely recovered provider
503
+ * gets a fresh one for the next outage.
504
+ */
505
+ function crossedRewarnMilestone(n: number, lastMilestone: number): number | undefined {
506
+ let crossed: number | undefined;
507
+ for (const m of REWARN_MILESTONES) {
508
+ if (n >= m && m > lastMilestone) crossed = m;
509
+ }
510
+ return crossed;
511
+ }
512
+
513
+ /**
514
+ * / injection budget gate: past the per-session budget for this
515
+ * condition, only the final milestone (500) still escalates.
516
+ */
517
+ function budgetAllows(sink: ConditionSink, milestone: number): boolean {
518
+ return (
519
+ sink.escalations < WATCHDOG_ESCALATION_BUDGET_PER_SESSION ||
520
+ milestone === FINAL_REWARN_MILESTONE
521
+ );
522
+ }
523
+
524
+ /**
525
+ * Shared tunnel-down escalation gate — both the scheduled detect pass
526
+ * (evaluateTunnel) and the tunnel push subscription route through here so
527
+ * the milestone throttle cannot be bypassed by either path. Assumes
528
+ * tunnel.status / tunnel.failures already reflect current state.
529
+ */
530
+ function escalateTunnelDownGated(): void {
531
+ if (!tunnel.open) {
532
+ // Threshold crossing: the first escalation for an open condition
533
+ // always fires when the budget allows (first bark = wake-up feature).
534
+ if (!budgetAllows(tunnel, 0)) return;
535
+ tunnel.open = true;
536
+ tunnel.lastMilestone = 0;
537
+ escalateTunnelDown();
538
+ tunnel.escalations++;
539
+ tunnel.lastEscalatedAt = now();
540
+ return;
541
+ }
542
+ // Continuously open: sparse milestone re-warn, with the normal cooldown
543
+ // kept as a second gate (strictly-fewer barks, never more).
544
+ if (now() - tunnel.lastEscalatedAt < cooldownMs) return;
545
+ const m = crossedRewarnMilestone(tunnel.failures, tunnel.lastMilestone);
546
+ if (m === undefined) return;
547
+ if (!budgetAllows(tunnel, m)) return;
548
+ escalateTunnelDown();
549
+ tunnel.escalations++;
550
+ tunnel.lastEscalatedAt = now();
551
+ tunnel.lastMilestone = m;
552
+ }
553
+
554
+ // Escalation paths (per condition)
555
+
556
+ function escalateTurnStall(s: StallSession): void {
557
+ const dur = formatWatchdogDuration(now() - s.lastActivityAt);
558
+ const label = s.key.length > 48 ? `${s.key.slice(0, 45)}…` : s.key;
559
+ fireEscalation(
560
+ `Watchdog: turn stall detected — the active turn has had no tool-call and no turn-complete for >${dur} ` +
561
+ `(session ${label}). Diagnose the stall, log what you find, and take the safe action ` +
562
+ `(finish/abort the turn or resume the interrupted step) before continuing.`,
563
+ `[watchdog] turn stall >${dur} — agent alive?`,
564
+ );
565
+ }
566
+
567
+ // Stall classification + bounded ladder
568
+
569
+ function newStallSession(key: string): StallSession {
570
+ return {
571
+ key,
572
+ streaming: false,
573
+ lastActivityAt: now(),
574
+ escalatedAt: Number.NEGATIVE_INFINITY,
575
+ open: false,
576
+ lastStreamActivityAt: undefined,
577
+ transcriptTerminal: false,
578
+ transcriptTerminalKind: undefined,
579
+ pendingToolCall: undefined,
580
+ partialOutput: undefined,
581
+ fires: 0,
582
+ remediated: false,
583
+ unready: false,
584
+ episodeEnded: false,
585
+ };
586
+ }
587
+
588
+ function ensureStall(key: string): StallSession {
589
+ let s = stalls.get(key);
590
+ if (!s) {
591
+ s = newStallSession(key);
592
+ stalls.set(key, s);
593
+ }
594
+ return s;
595
+ }
596
+
597
+ /** Progress (a tool call, a tool result, a message, a turn boundary) closes
598
+ * the episode and re-arms the ladder for the next one. */
599
+ function closeStallEpisode(s: StallSession): void {
600
+ s.open = false;
601
+ s.fires = 0;
602
+ s.remediated = false;
603
+ s.unready = false;
604
+ s.episodeEnded = false;
605
+ }
606
+
607
+ function streamSilentForMs(s: StallSession): number | undefined {
608
+ return s.lastStreamActivityAt === undefined ? undefined : now() - s.lastStreamActivityAt;
609
+ }
610
+
611
+ function isWakeDue(key: string): boolean {
612
+ try {
613
+ return deps.isWakeDue?.(key) === true;
614
+ } catch {
615
+ return false;
616
+ }
617
+ }
618
+
619
+ /** The classification gate: live wire activity is not a stall; wire silence
620
+ * plus a terminal transcript (and no due wake) is dead; anything else is
621
+ * silent-ambiguous and stays advisory. */
622
+ function classifyStall(s: StallSession): StallClassificationKind {
623
+ if (s.remediated) return "remediated";
624
+ if (s.unready) return "unready";
625
+ const silentFor = streamSilentForMs(s);
626
+ const silent = silentFor === undefined || silentFor > streamSilenceMs;
627
+ if (!silent) return "alive";
628
+ if (s.transcriptTerminal && !isWakeDue(s.key)) return "dead";
629
+ return "silent";
630
+ }
631
+
632
+ function boundHead(text: string | undefined, cap: number): string | undefined {
633
+ if (!text) return undefined;
634
+ return text.length > cap ? `${text.slice(0, cap - 1)}…` : text;
635
+ }
636
+
637
+ function boundTail(text: string | undefined, cap: number): string | undefined {
638
+ if (!text) return undefined;
639
+ return text.length > cap ? `…${text.slice(-(cap - 1))}` : text;
640
+ }
641
+
642
+ function buildResumeMarker(s: StallSession): StallResumeMarker {
643
+ return {
644
+ sessionKey: s.key,
645
+ detectedAt: now(),
646
+ stallAgeMs: now() - s.lastActivityAt,
647
+ streamSilentForMs: streamSilentForMs(s),
648
+ transcriptTerminal: s.transcriptTerminal,
649
+ transcriptTerminalKind: s.transcriptTerminalKind,
650
+ pendingToolCall: s.pendingToolCall ? { ...s.pendingToolCall } : undefined,
651
+ partialOutput: s.partialOutput,
652
+ fires: s.fires,
653
+ };
654
+ }
655
+
656
+ /** Out-of-band owner page (the tg-signal seam); must never throw. */
657
+ function pageOwner(text: string): void {
658
+ try {
659
+ tgSignal?.(text);
660
+ } catch {
661
+ // optional — never fatal
662
+ }
663
+ }
664
+
665
+ /**
666
+ * Rung 3 of the ladder: persist before cancel (a cancel without a durable
667
+ * checkpoint is kill-and-forget), cancel once, hand back to the owner. A
668
+ * missing half — no seat accepted the marker, or no abort seam is wired —
669
+ * degrades to the unready hand-back instead of aborting.
670
+ */
671
+ function remediateStall(s: StallSession): void {
672
+ const marker = buildResumeMarker(s);
673
+ const silentFor = marker.streamSilentForMs;
674
+ const silenceLabel = silentFor === undefined ? "unknown" : formatWatchdogDuration(silentFor);
675
+ const terminalLabel = s.transcriptTerminalKind ?? "terminal";
676
+ let persisted = false;
677
+ try {
678
+ persisted = deps.persistResumeMarker?.(s.key, marker) === true;
679
+ } catch (err) {
680
+ log("warn", `watchdog: resume marker persist failed: ${(err as Error).message}`);
681
+ }
682
+ const canAbort = typeof deps.abortTurn === "function";
683
+ if (!persisted || !canAbort) {
684
+ s.unready = true;
685
+ s.episodeEnded = true;
686
+ const why = !persisted
687
+ ? "no durable resume seat accepted the marker"
688
+ : "no abort seam is wired";
689
+ log("warn", `watchdog: turn stall UNREADY (${why}) — abort withheld for ${s.key}`);
690
+ pageOwner(
691
+ `[watchdog] dead turn unready — no provider stream activity for ${silenceLabel}, ` +
692
+ `transcript terminal (${terminalLabel}), but ${why}; abort withheld rather than killing and forgetting. ` +
693
+ `A manual quit + resume replays the pending step.`,
694
+ );
695
+ return;
696
+ }
697
+ s.remediated = true;
698
+ s.episodeEnded = true;
699
+ try {
700
+ deps.abortTurn?.(s.key);
701
+ } catch (err) {
702
+ log("warn", `watchdog: abort of the stalled turn failed: ${(err as Error).message}`);
703
+ }
704
+ log(
705
+ "warn",
706
+ `watchdog: turn stall remediated — resume marker persisted, abort dispatched for ${s.key}`,
707
+ );
708
+ pageOwner(
709
+ `[watchdog] dead turn aborted — no provider stream activity for ${silenceLabel}, ` +
710
+ `transcript terminal (${terminalLabel}), no wake due. Resume marker written to the session; ` +
711
+ `the next turn resumes from it instead of re-running the dead step.`,
712
+ );
713
+ quietWhisper(
714
+ `Watchdog: the stalled turn was aborted after ${silenceLabel} of wire silence; a resume marker ` +
715
+ `was written to this session (pending tool call + partial output). Resume from the marker.`,
716
+ );
717
+ }
718
+
719
+ function escalateQuotaLoop(): void {
720
+ const n = quotaConsecutive;
721
+ fireEscalation(
722
+ `Watchdog: LLM rate-limit/quota loop — ${n} consecutive rate-limit/quota/auth failures with no success. ` +
723
+ `Suggest switching model, backing off, or pausing; report the provider state so the owner can act.`,
724
+ `[watchdog] LLM rate-limit/quota loop (${n}x) — backoff/pause?`,
725
+ );
726
+ }
727
+
728
+ /** ONE non-waking emission for the terminal-stop episode. Content per the
729
+ * design: count, local first-error time, last category + numeric status if
730
+ * present, and the fix line. No key material, hashes, key counts or dollar
731
+ * figures — `llm-error`'s raw text is deliberately not echoed. */
732
+ function escalateTerminalStop(): void {
733
+ const n = terminalStopConsecutive;
734
+ const since = terminalStopFirstAt ? formatLocalTime(new Date(terminalStopFirstAt)) : "unknown";
735
+ const last = terminalStopLastCategory ?? "auth/balance";
736
+ const status = terminalStopLastStatus != null ? ` ${terminalStopLastStatus}` : "";
737
+ const text =
738
+ `Watchdog: terminal provider stop — ${n} auth/balance errors since ${since} ` +
739
+ `(last: ${last}${status}). Timer wakes are paused for this session; no retry will be attempted. ` +
740
+ `Fix the cause, then restart the session or switch the model.`;
741
+ try {
742
+ (terminalStopWhisper ?? quietWhisper)(text);
743
+ } catch (err) {
744
+ log("warn", `watchdog: terminal-stop whisper delivery failed: ${(err as Error).message}`);
745
+ }
746
+ }
747
+
748
+ function escalateTunnelDown(): void {
749
+ const n = tunnel.failures;
750
+ fireEscalation(
751
+ tunnel.lastMessageEnvelope ??
752
+ `Watchdog: telegram tunnel DOWN (${n} consecutive getUpdates failures). The remote canary is ` +
753
+ `offline — diagnose the tunnel/poller before relying on remote operations.`,
754
+ `[watchdog] tg tunnel down (${n} fetch failures)`,
755
+ );
756
+ }
757
+
758
+ /** Bounded timer-reason rendering for the wake-delivery bark text. */
759
+ function boundReason(reason: string): string {
760
+ return reason.length > 120 ? `${reason.slice(0, 117)}…` : reason;
761
+ }
762
+
763
+ // Wake-delivery feed (timer → watchdog)
764
+
765
+ /** Repeated outcome timeouts for one fire: the loop is not settling wake
766
+ * turns. The queue only arms (and forwards) an outcome timeout when NO
767
+ * agent run is active for the fire — a merely-long run never reaches
768
+ * here (drainDue's long-run grace), and a wedged ACTIVE run pages via
769
+ * turn-stall instead. What reaches this function is a dead delivery:
770
+ * consecutive windows with no settle and no run. One bark per episode;
771
+ * later timeouts of the same episode are absorbed (a wedged loop must
772
+ * not page per retry). */
773
+ function recordWakeOutcomeTimeout(timerId: string, reason: string, timeouts: number): void {
774
+ if (!isEnabled() || wakeDelivery.open) return;
775
+ wakeDelivery.open = true;
776
+ fireEscalation(
777
+ `Watchdog: wake delivery stalling — timer ${timerId} ("${boundReason(reason)}") has ` +
778
+ `${timeouts} consecutive wake outcome timeouts with no turn settle and no agent run active. ` +
779
+ `The wake send likely never started a turn (a pre-flight abort never settles wakes). ` +
780
+ `Check for lost timer fires before relying on timer wakes.`,
781
+ `[watchdog] timer wake not settling (${timeouts}× outcome timeout, no active run) — wake send lost?`,
782
+ );
783
+ }
784
+
785
+ /** A fire dropped after exhausting its redelivery bound: the scheduled
786
+ * content is permanently lost. Barks only when it is the episode's first
787
+ * event — if outcome timeouts already paged, the episode stays one bark. */
788
+ function recordWakeUndelivered(timerId: string, reason: string, attempts: number): void {
789
+ if (!isEnabled() || wakeDelivery.open) return;
790
+ wakeDelivery.open = true;
791
+ fireEscalation(
792
+ `Watchdog: wake delivery died — timer ${timerId} ("${boundReason(reason)}") was permanently ` +
793
+ `undelivered after ${attempts} redeliveries; the scheduled content never reached a turn. ` +
794
+ `Check the agent loop / provider health before relying on timer wakes.`,
795
+ `[watchdog] wake fire permanently undelivered after ${attempts} retries: ${boundReason(reason)}`,
796
+ );
797
+ }
798
+
799
+ /** A tracked wake settled delivered — the loop runs again. Closes the
800
+ * episode with one recovery line. The tunnel recovery precedent only
801
+ * whispers because tg itself was down; here tg is the channel that WORKED
802
+ * (the wedge was the loop, not the tunnel), so the owner who got the tg
803
+ * bark also gets the tg all-clear. */
804
+ function recordWakeDelivered(timerId: string): void {
805
+ if (!isEnabled() || !wakeDelivery.open) return;
806
+ wakeDelivery.open = false;
807
+ quietWhisper(
808
+ `Watchdog: wake delivery recovered — timer wakes are settling again (confirmed by timer ${timerId}).`,
809
+ );
810
+ try {
811
+ tgSignal?.("[watchdog] wake delivery recovered — timer wakes settling again");
812
+ } catch {
813
+ // optional — never fatal
814
+ }
815
+ }
816
+
817
+ // Detect pass
818
+
819
+ // Standalone closure (no `this`) so both the object's check() method and
820
+ // the scheduled timer call it, and any code path (check, tunnel push) can
821
+ // re-cadence immediately after a condition opens.
822
+ const performCheck = (): void => {
823
+ if (!isEnabled()) return;
824
+ evaluateQuota();
825
+ evaluateTunnel();
826
+ evaluateStalls();
827
+ scheduleNextCheck();
828
+ emitTelemetryLine();
829
+ };
830
+
831
+ /**
832
+ * Hook 2: one cheap scalar telemetry line per detect pass so idle
833
+ * processes are covered on the watchdog's wall-clock cadence (the OOM
834
+ * overnight window had idle processes too). No ctx here — the wired
835
+ * emitter (watchdog/index.ts) enriches with sessionId/session size/
836
+ * health mode. Optional dep keeps fixture tests hermetic.
837
+ */
838
+ function emitTelemetryLine(): void {
839
+ if (!deps.telemetryEmit) return;
840
+ try {
841
+ const mem = process.memoryUsage();
842
+ deps.telemetryEmit({
843
+ ts: now(),
844
+ source: "watchdog",
845
+ rssBytes: mem.rss,
846
+ heapUsed: mem.heapUsed,
847
+ cadence: anyOpen() ? "hot" : "base",
848
+ openConditions: openConditions().join(",").slice(0, 120),
849
+ quotaConsecutive,
850
+ tunnelStatus: tunnel.status,
851
+ tunnelFailures: tunnel.failures,
852
+ stalledCount: [...stalls.values()].filter((s) => s.open).length,
853
+ nextCheckInMs: Math.max(0, nextCheckAt - now()),
854
+ });
855
+ } catch {
856
+ // telemetry never fatal
857
+ }
858
+ }
859
+
860
+ /** Soft backoff: hot while ≥1 issue is open, base when clean. */
861
+ const scheduleNextCheck = (): void => {
862
+ const cadence = anyOpen() ? "hot" : "base";
863
+ const intervalMs = cadence === "hot" ? config.hotMs : config.baseMs;
864
+ nextCheckAt = now() + intervalMs;
865
+ if (timerCancel) timerCancel();
866
+ timerCancel = schedule(() => performCheck(), intervalMs);
867
+ };
868
+
869
+ function evaluateQuota(): void {
870
+ const problem = quotaConsecutive >= config.quotaErrors;
871
+ if (problem) {
872
+ quotaHealthyStreak = 0; // any quota failure breaks the success streak
873
+ if (!quota.open) {
874
+ quota.open = true;
875
+ if (quotaLatchArmed && budgetAllows(quota, 0)) {
876
+ // Threshold crossing + latch armed: the FIRST escalation of the
877
+ // open episode always fires (owner-endorsed wake-up feature), and
878
+ // the episode starts with a fresh milestone ladder.
879
+ quotaLatchArmed = false;
880
+ quota.lastMilestone = 0;
881
+ escalateQuotaLoop();
882
+ quota.escalations++;
883
+ quota.lastEscalatedAt = now();
884
+ return;
885
+ }
886
+ // Same episode re-opened after a transient close (flap): NO new
887
+ // wake bark and the ladder keeps its high-water — fall through to
888
+ // the milestone gate. This is the D6 storm fix. (A budget-exhausted
889
+ // session also lands here: only the 500 rung escalates.)
890
+ }
891
+ // Continuously open: sparse milestone re-warn, with the normal
892
+ // cooldown kept as a second gate (strictly-fewer barks, never more).
893
+ if (now() - quota.lastEscalatedAt < cooldownMs) return;
894
+ const m = crossedRewarnMilestone(quotaConsecutive, quota.lastMilestone);
895
+ if (m === undefined) return;
896
+ if (!budgetAllows(quota, m)) return;
897
+ escalateQuotaLoop();
898
+ quota.escalations++;
899
+ quota.lastEscalatedAt = now();
900
+ quota.lastMilestone = m;
901
+ } else if (quota.open) {
902
+ // Silent recovery (already rotating / success). latch: a transient
903
+ // close does NOT reset the milestone ladder nor re-arm the wake bark —
904
+ // re-arm requires the success streak (noteQuotaHealthy).
905
+ quota.open = false;
906
+ } else {
907
+ noteQuotaHealthy();
908
+ }
909
+ }
910
+
911
+ /** Latch re-arm: a consecutive success streak (healthy evaluations or
912
+ * LLM successes — both funnel here) re-arms the first bark and starts a
913
+ * fresh milestone ladder for the next genuine outage. */
914
+ function noteQuotaHealthy(): void {
915
+ if (quotaLatchArmed) return;
916
+ quotaHealthyStreak++;
917
+ if (quotaHealthyStreak >= QUOTA_REARM_SUCCESS_STREAK) {
918
+ quotaLatchArmed = true;
919
+ quota.lastMilestone = 0;
920
+ quotaHealthyStreak = 0;
921
+ }
922
+ }
923
+
924
+ function evaluateTunnel(): void {
925
+ // Snapshot-driven seatbelt: covers a down event emitted before we
926
+ // subscribed (the hub preserves the latest status; the push handler emits
927
+ // the primary escalation, this keeps a missed transition from wedging).
928
+ const snap = getTunnelStatus?.();
929
+ if (snap) {
930
+ tunnel.status = snap.status;
931
+ tunnel.failures = snap.failures;
932
+ }
933
+ const down = tunnel.status === "down" && tunnel.failures >= config.tunnelFailures;
934
+ if (down) {
935
+ escalateTunnelDownGated();
936
+ } else if (tunnel.open) {
937
+ // Genuine up transition = explicit success: full re-arm.
938
+ tunnel.open = false;
939
+ tunnel.lastMilestone = 0; // re-arm the ladder for the next outage
940
+ }
941
+ }
942
+
943
+ function evaluateStalls(): void {
944
+ const threshold = config.stallMult * config.baseMs;
945
+ for (const s of stalls.values()) {
946
+ const age = now() - s.lastActivityAt;
947
+ if (s.streaming && age > threshold) {
948
+ if (s.episodeEnded) continue; // terminal hand-back already surfaced
949
+ const cls = classifyStall(s);
950
+ if (!s.open) {
951
+ // Threshold crossing: fire 1 = rung 1 (notify) + rung 2 (classify).
952
+ s.open = true;
953
+ s.fires = 1;
954
+ s.escalatedAt = now();
955
+ log(
956
+ "warn",
957
+ `watchdog: turn stall first fire (${s.key}) — classification ${cls}` +
958
+ ` (wire silence ${streamSilentForMs(s) ?? "?"}ms, transcript terminal ${s.transcriptTerminal})`,
959
+ );
960
+ escalateTurnStall(s);
961
+ continue;
962
+ }
963
+ if (now() - s.escalatedAt < STALL_REWARN_COOLDOWN_MULT * cooldownMs) continue;
964
+ s.fires++;
965
+ if (cls === "dead" && s.fires >= STALL_SERVICE_FIRE) {
966
+ remediateStall(s);
967
+ continue;
968
+ }
969
+ // Advisory re-warn: the counter-less long cooldown (sparse but
970
+ // periodic), unchanged for episodes that never confirm dead.
971
+ escalateTurnStall(s);
972
+ s.escalatedAt = now();
973
+ } else if (s.open) {
974
+ closeStallEpisode(s);
975
+ }
976
+ }
977
+ }
978
+
979
+ // Public surface
980
+
981
+ return {
982
+ start() {
983
+ if (started) return;
984
+ if (config.mode !== "on") {
985
+ log("info", "watchdog engine disabled (broker.watchdog.mode != on)");
986
+ return;
987
+ }
988
+ started = true;
989
+ stopped = false;
990
+ // Prime the tunnel state from the shared hub so a down event emitted
991
+ // before subscription is not lost.
992
+ const snap = getTunnelStatus?.();
993
+ if (snap) {
994
+ tunnel.status = snap.status;
995
+ tunnel.failures = snap.failures;
996
+ }
997
+ if (subscribeTunnel) {
998
+ disposeTunnel = subscribeTunnel((event) => {
999
+ // The push handler both seeds state and escalates/reports recovery.
1000
+ tunnel.status = event.status;
1001
+ tunnel.failures = event.failures;
1002
+ if (event.status === "down") {
1003
+ if (event.message) tunnel.lastMessageEnvelope = event.message;
1004
+ if (event.failures >= config.tunnelFailures) {
1005
+ const wasOpen = tunnel.open;
1006
+ escalateTunnelDownGated();
1007
+ // Fast recheck while the issue is open (design: soft backoff).
1008
+ if (!wasOpen) scheduleNextCheck();
1009
+ }
1010
+ } else {
1011
+ // Tunnel recovered: close + one quiet recovery whisper.
1012
+ // Genuine up event = explicit success: full ladder re-arm.
1013
+ const wasOpen = tunnel.open;
1014
+ tunnel.open = false;
1015
+ tunnel.lastMilestone = 0; // re-arm the ladder for the next outage
1016
+ if (wasOpen) quietWhisper(event.message || "Telegram tunnel recovered.");
1017
+ }
1018
+ });
1019
+ }
1020
+ scheduleNextCheck();
1021
+ log(
1022
+ "info",
1023
+ `watchdog engine started (${config.mode}, base ${config.baseMs}ms, hot ${config.hotMs}ms)`,
1024
+ );
1025
+ },
1026
+
1027
+ stop() {
1028
+ stopped = true;
1029
+ if (timerCancel) timerCancel();
1030
+ timerCancel = undefined;
1031
+ if (disposeTunnel) disposeTunnel();
1032
+ disposeTunnel = undefined;
1033
+ log("info", "watchdog engine stopped");
1034
+ },
1035
+
1036
+ observeSessionStart(key: string) {
1037
+ stalls.set(key, newStallSession(key));
1038
+ },
1039
+
1040
+ observeProgress(key, kind) {
1041
+ const s = ensureStall(key);
1042
+ s.lastActivityAt = now();
1043
+ if (kind === "assistant") {
1044
+ s.transcriptTerminal = false;
1045
+ s.transcriptTerminalKind = undefined;
1046
+ }
1047
+ if (s.open) closeStallEpisode(s); // progress resolved the stall
1048
+ },
1049
+
1050
+ observeToolCall(key, tool) {
1051
+ const s = ensureStall(key);
1052
+ // "uses last-tool-call, not wall clock" — a fresh tool call resets the
1053
+ // stall clock even if the wall clock is old.
1054
+ s.lastActivityAt = now();
1055
+ s.transcriptTerminal = false;
1056
+ s.transcriptTerminalKind = undefined;
1057
+ if (tool?.toolName) {
1058
+ s.pendingToolCall = {
1059
+ toolName: tool.toolName,
1060
+ toolCallId: tool.toolCallId,
1061
+ argsPreview: boundHead(tool.argsPreview, RESUME_MARKER_ARGS_CAP),
1062
+ };
1063
+ }
1064
+ if (s.open) closeStallEpisode(s);
1065
+ },
1066
+
1067
+ observeStreamActivity(key, partialText) {
1068
+ const s = ensureStall(key);
1069
+ s.lastStreamActivityAt = now();
1070
+ s.transcriptTerminal = false;
1071
+ s.transcriptTerminalKind = undefined;
1072
+ if (partialText) s.partialOutput = boundTail(partialText, RESUME_MARKER_TEXT_CAP);
1073
+ },
1074
+
1075
+ observeToolResult(key, toolCallId) {
1076
+ const s = ensureStall(key);
1077
+ s.lastActivityAt = now();
1078
+ s.transcriptTerminal = true;
1079
+ s.transcriptTerminalKind = "tool-result";
1080
+ // Clear the pending call when ids match, or when either side carries no
1081
+ // id (an unmatchable result is the only candidate).
1082
+ const pendingId = s.pendingToolCall?.toolCallId;
1083
+ if (!toolCallId || !pendingId || pendingId === toolCallId) s.pendingToolCall = undefined;
1084
+ if (s.open) closeStallEpisode(s);
1085
+ },
1086
+
1087
+ observeTranscriptError(key) {
1088
+ const s = ensureStall(key);
1089
+ s.transcriptTerminal = true;
1090
+ s.transcriptTerminalKind = "error";
1091
+ },
1092
+
1093
+ observeTurnStart(key) {
1094
+ const s = ensureStall(key);
1095
+ s.streaming = true;
1096
+ s.lastStreamActivityAt = now(); // the wire clock starts with the new call
1097
+ s.transcriptTerminal = false;
1098
+ s.transcriptTerminalKind = undefined;
1099
+ s.pendingToolCall = undefined;
1100
+ s.partialOutput = undefined;
1101
+ closeStallEpisode(s);
1102
+ },
1103
+
1104
+ observeTurnComplete(key) {
1105
+ const s = ensureStall(key);
1106
+ s.streaming = false;
1107
+ s.lastActivityAt = now();
1108
+ s.transcriptTerminal = false;
1109
+ s.transcriptTerminalKind = undefined;
1110
+ s.pendingToolCall = undefined;
1111
+ s.partialOutput = undefined;
1112
+ closeStallEpisode(s);
1113
+ },
1114
+
1115
+ recordLlmFailure(detail?: string, meta?: { provider?: string; model?: string }): void {
1116
+ // The key ring reports ALL LLM failures (rotation needs them), but only
1117
+ // quota-class outcomes feed the quota loop: rate-limit/balance/auth, or
1118
+ // ring-exhaustion text (which carries no provider status code).
1119
+ // Transient/abort/unknown (sleep timeouts, dropped sockets) must never
1120
+ // bark quota — they get a separate log-only streak instead.
1121
+ const category = classifyLlmError(detail ?? "").category;
1122
+ const ringExhausted = detail !== undefined && RING_EXHAUSTION_PATTERN.test(detail);
1123
+ if (
1124
+ category === "rate_limit" ||
1125
+ category === "balance" ||
1126
+ category === "auth" ||
1127
+ ringExhausted
1128
+ ) {
1129
+ quotaConsecutive++;
1130
+ quotaHealthyStreak = 0; // failures break the success streak
1131
+ // A terminal stop is auth/balance only (NOT rate_limit, NOT ring
1132
+ // exhaustion without a status): a throttled ring keeps waking.
1133
+ if (category === "auth" || category === "balance") {
1134
+ if (terminalStopConsecutive === 0) terminalStopFirstAt = now();
1135
+ terminalStopConsecutive++;
1136
+ terminalStopLastCategory = category;
1137
+ terminalStopLastStatus = detail ? extractHttpCodeFromText(detail) : undefined;
1138
+ if (!terminalStop.open && terminalStopConsecutive >= config.quotaErrors && isEnabled()) {
1139
+ terminalStop.open = true;
1140
+ escalateTerminalStop();
1141
+ }
1142
+ }
1143
+ log(
1144
+ "warn",
1145
+ `watchdog: LLM rate-limit/quota/auth failure (${quotaConsecutive} consecutive)${truncateDetail(detail)}`,
1146
+ );
1147
+ } else {
1148
+ transientConsecutive++;
1149
+ if (category === "unknown") {
1150
+ // An unclassified failure is exactly the case the classifier
1151
+ // failed on — retain the raw evidence (bounded text, provider
1152
+ // identity, extracted HTTP code) in the snapshot ring so
1153
+ // root-causing needs no separate forensic pass. Ring-exhaustion
1154
+ // text is quota-class by definition and never lands here.
1155
+ unknownFailures.push({
1156
+ at: now(),
1157
+ text: truncateDetail(detail).replace(/^: /, ""),
1158
+ provider: meta?.provider,
1159
+ model: meta?.model,
1160
+ statusCode: detail ? extractHttpCodeFromText(detail) : undefined,
1161
+ });
1162
+ if (unknownFailures.length > UNKNOWN_FAILURE_RING_CAP) unknownFailures.shift();
1163
+ log(
1164
+ "warn",
1165
+ `watchdog: LLM unknown failure (transient streak ${transientConsecutive}, ` +
1166
+ `provider ${meta?.provider ?? "?"}, HTTP ${
1167
+ detail ? (extractHttpCodeFromText(detail) ?? "?") : "?"
1168
+ })${truncateDetail(detail)}`,
1169
+ );
1170
+ } else {
1171
+ log(
1172
+ "debug",
1173
+ `watchdog: LLM ${category} failure (transient streak ${transientConsecutive}, not quota)${truncateDetail(detail)}`,
1174
+ );
1175
+ }
1176
+ }
1177
+ },
1178
+
1179
+ recordLlmSuccess() {
1180
+ if (quotaConsecutive > 0) {
1181
+ log("info", `watchdog: LLM quota streak cleared after ${quotaConsecutive} failure(s)`);
1182
+ quotaConsecutive = 0;
1183
+ }
1184
+ if (terminalStopConsecutive > 0) {
1185
+ terminalStopConsecutive = 0;
1186
+ terminalStopFirstAt = undefined;
1187
+ terminalStopLastCategory = undefined;
1188
+ terminalStopLastStatus = undefined;
1189
+ }
1190
+ // End the episode: a recovered route that later stops terminally barks
1191
+ // once more. (No success-streak re-arm latch — see escalateTerminalStop.)
1192
+ terminalStop.open = false;
1193
+ if (transientConsecutive > 0) {
1194
+ log(
1195
+ "debug",
1196
+ `watchdog: LLM transient streak cleared after ${transientConsecutive} failure(s)`,
1197
+ );
1198
+ transientConsecutive = 0;
1199
+ }
1200
+ if (quota.open) {
1201
+ quota.open = false;
1202
+ // Flap latch: do NOT reset the milestone ladder here — a single
1203
+ // success after a long outage is not a new episode. Re-arm requires
1204
+ // the success streak (below).
1205
+ }
1206
+ // An explicit success feeds the re-arm streak (≥3 consecutive
1207
+ // successes re-arm the first bark + fresh ladder, killing the
1208
+ // close→open flap storm while preserving per-episode wake-ups).
1209
+ noteQuotaHealthy();
1210
+ },
1211
+
1212
+ check() {
1213
+ performCheck();
1214
+ },
1215
+
1216
+ recordWakeOutcomeTimeout,
1217
+ recordWakeUndelivered,
1218
+ recordWakeDelivered,
1219
+
1220
+ getSnapshot(): WatchdogSnapshot {
1221
+ return {
1222
+ enabled: isEnabled(),
1223
+ cadence: anyOpen() ? "hot" : "base",
1224
+ openConditions: openConditions(),
1225
+ quotaConsecutive,
1226
+ tunnel: { status: tunnel.status, failures: tunnel.failures },
1227
+ stalledSessions: [...stalls.values()].filter((s) => s.open).map((s) => s.key),
1228
+ stallEpisodes: [...stalls.values()]
1229
+ .filter((s) => s.open || s.episodeEnded)
1230
+ .map((s) => ({
1231
+ key: s.key,
1232
+ open: s.open,
1233
+ classification: classifyStall(s),
1234
+ streamSilentForMs: streamSilentForMs(s),
1235
+ transcriptTerminal: s.transcriptTerminal,
1236
+ fires: s.fires,
1237
+ remediated: s.remediated,
1238
+ ended: s.episodeEnded,
1239
+ })),
1240
+ nextCheckAt,
1241
+ unknownFailures: unknownFailures.map((r) => ({ ...r })),
1242
+ terminalConsecutive: terminalStopConsecutive,
1243
+ };
1244
+ },
1245
+ };
1246
+ }