@apralabs/apra-fleet 0.3.5 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (571) hide show
  1. package/README.md +245 -257
  2. package/dist/agents/backlog-groomer.md +287 -0
  3. package/dist/agents/deployer.md +52 -11
  4. package/dist/agents/doer.md +32 -7
  5. package/dist/agents/integ-test-runner.md +151 -61
  6. package/dist/agents/plan-reviewer.md +74 -17
  7. package/dist/agents/planner.md +94 -14
  8. package/dist/agents/regression-test-runner.md +216 -0
  9. package/dist/agents/reviewer.md +21 -6
  10. package/dist/agents/schemas/backlog-groomer-input.json +35 -0
  11. package/dist/agents/schemas/backlog-groomer-output.json +164 -0
  12. package/dist/agents/schemas/integ-test-runner-output.json +34 -0
  13. package/dist/agents/schemas/regression-test-runner-input.json +15 -0
  14. package/dist/agents/schemas/regression-test-runner-output.json +50 -0
  15. package/dist/agents/schemas/reviewer-output.json +4 -0
  16. package/dist/cli/agent-transform.d.ts +1 -0
  17. package/dist/cli/agent-transform.d.ts.map +1 -1
  18. package/dist/cli/agent-transform.js +77 -0
  19. package/dist/cli/agent-transform.js.map +1 -1
  20. package/dist/cli/auth.d.ts +3 -0
  21. package/dist/cli/auth.d.ts.map +1 -1
  22. package/dist/cli/auth.js +181 -5
  23. package/dist/cli/auth.js.map +1 -1
  24. package/dist/cli/config.d.ts +5 -1
  25. package/dist/cli/config.d.ts.map +1 -1
  26. package/dist/cli/config.js +7 -1
  27. package/dist/cli/config.js.map +1 -1
  28. package/dist/cli/dolt-install.d.ts +91 -0
  29. package/dist/cli/dolt-install.d.ts.map +1 -0
  30. package/dist/cli/dolt-install.js +334 -0
  31. package/dist/cli/dolt-install.js.map +1 -0
  32. package/dist/cli/install-guard.d.ts +29 -0
  33. package/dist/cli/install-guard.d.ts.map +1 -0
  34. package/dist/cli/install-guard.js +153 -0
  35. package/dist/cli/install-guard.js.map +1 -0
  36. package/dist/cli/install.d.ts +44 -3
  37. package/dist/cli/install.d.ts.map +1 -1
  38. package/dist/cli/install.js +604 -108
  39. package/dist/cli/install.js.map +1 -1
  40. package/dist/cli/join.d.ts +12 -0
  41. package/dist/cli/join.d.ts.map +1 -0
  42. package/dist/cli/join.js +87 -0
  43. package/dist/cli/join.js.map +1 -0
  44. package/dist/cli/register-member.d.ts +2 -0
  45. package/dist/cli/register-member.d.ts.map +1 -0
  46. package/dist/cli/register-member.js +193 -0
  47. package/dist/cli/register-member.js.map +1 -0
  48. package/dist/cli/restart.d.ts +2 -0
  49. package/dist/cli/restart.d.ts.map +1 -0
  50. package/dist/cli/restart.js +7 -0
  51. package/dist/cli/restart.js.map +1 -0
  52. package/dist/cli/secret.js +8 -2
  53. package/dist/cli/secret.js.map +1 -1
  54. package/dist/cli/spoke.d.ts +35 -0
  55. package/dist/cli/spoke.d.ts.map +1 -0
  56. package/dist/cli/spoke.js +212 -0
  57. package/dist/cli/spoke.js.map +1 -0
  58. package/dist/cli/start.d.ts +2 -0
  59. package/dist/cli/start.d.ts.map +1 -0
  60. package/dist/cli/start.js +92 -0
  61. package/dist/cli/start.js.map +1 -0
  62. package/dist/cli/status.d.ts +2 -0
  63. package/dist/cli/status.d.ts.map +1 -0
  64. package/dist/cli/status.js +83 -0
  65. package/dist/cli/status.js.map +1 -0
  66. package/dist/cli/stop.d.ts +2 -0
  67. package/dist/cli/stop.d.ts.map +1 -0
  68. package/dist/cli/stop.js +51 -0
  69. package/dist/cli/stop.js.map +1 -0
  70. package/dist/cli/uninstall.d.ts.map +1 -1
  71. package/dist/cli/uninstall.js +109 -9
  72. package/dist/cli/uninstall.js.map +1 -1
  73. package/dist/cli/update.d.ts.map +1 -1
  74. package/dist/cli/update.js +10 -1
  75. package/dist/cli/update.js.map +1 -1
  76. package/dist/cli/workflow-assets.d.ts +37 -0
  77. package/dist/cli/workflow-assets.d.ts.map +1 -0
  78. package/dist/cli/workflow-assets.js +144 -0
  79. package/dist/cli/workflow-assets.js.map +1 -0
  80. package/dist/cli/workflow.d.ts +75 -0
  81. package/dist/cli/workflow.d.ts.map +1 -0
  82. package/dist/cli/workflow.js +397 -0
  83. package/dist/cli/workflow.js.map +1 -0
  84. package/dist/hub-service/activity.d.ts +30 -0
  85. package/dist/hub-service/activity.d.ts.map +1 -0
  86. package/dist/hub-service/activity.js +20 -0
  87. package/dist/hub-service/activity.js.map +1 -0
  88. package/dist/hub-service/audit-log.d.ts +19 -0
  89. package/dist/hub-service/audit-log.d.ts.map +1 -0
  90. package/dist/hub-service/audit-log.js +13 -0
  91. package/dist/hub-service/audit-log.js.map +1 -0
  92. package/dist/hub-service/db/pool.d.ts +19 -0
  93. package/dist/hub-service/db/pool.d.ts.map +1 -0
  94. package/dist/hub-service/db/pool.js +53 -0
  95. package/dist/hub-service/db/pool.js.map +1 -0
  96. package/dist/hub-service/enrollment.d.ts +29 -0
  97. package/dist/hub-service/enrollment.d.ts.map +1 -0
  98. package/dist/hub-service/enrollment.js +48 -0
  99. package/dist/hub-service/enrollment.js.map +1 -0
  100. package/dist/hub-service/envelope-routes.d.ts +46 -0
  101. package/dist/hub-service/envelope-routes.d.ts.map +1 -0
  102. package/dist/hub-service/envelope-routes.js +94 -0
  103. package/dist/hub-service/envelope-routes.js.map +1 -0
  104. package/dist/hub-service/handlers/installers.d.ts +14 -0
  105. package/dist/hub-service/handlers/installers.d.ts.map +1 -0
  106. package/dist/hub-service/handlers/installers.js +8 -0
  107. package/dist/hub-service/handlers/installers.js.map +1 -0
  108. package/dist/hub-service/http-server.d.ts +31 -0
  109. package/dist/hub-service/http-server.d.ts.map +1 -0
  110. package/dist/hub-service/http-server.js +711 -0
  111. package/dist/hub-service/http-server.js.map +1 -0
  112. package/dist/hub-service/hub-jwt.d.ts +30 -0
  113. package/dist/hub-service/hub-jwt.d.ts.map +1 -0
  114. package/dist/hub-service/hub-jwt.js +105 -0
  115. package/dist/hub-service/hub-jwt.js.map +1 -0
  116. package/dist/hub-service/jwt-revocation.d.ts +20 -0
  117. package/dist/hub-service/jwt-revocation.d.ts.map +1 -0
  118. package/dist/hub-service/jwt-revocation.js +18 -0
  119. package/dist/hub-service/jwt-revocation.js.map +1 -0
  120. package/dist/hub-service/machines.d.ts +16 -0
  121. package/dist/hub-service/machines.d.ts.map +1 -0
  122. package/dist/hub-service/machines.js +14 -0
  123. package/dist/hub-service/machines.js.map +1 -0
  124. package/dist/hub-service/main.d.ts +3 -0
  125. package/dist/hub-service/main.d.ts.map +1 -0
  126. package/dist/hub-service/main.js +64 -0
  127. package/dist/hub-service/main.js.map +1 -0
  128. package/dist/hub-service/member-tokens.d.ts +11 -0
  129. package/dist/hub-service/member-tokens.d.ts.map +1 -0
  130. package/dist/hub-service/member-tokens.js +49 -0
  131. package/dist/hub-service/member-tokens.js.map +1 -0
  132. package/dist/hub-service/member-view.d.ts +20 -0
  133. package/dist/hub-service/member-view.d.ts.map +1 -0
  134. package/dist/hub-service/member-view.js +76 -0
  135. package/dist/hub-service/member-view.js.map +1 -0
  136. package/dist/hub-service/members.d.ts +44 -0
  137. package/dist/hub-service/members.d.ts.map +1 -0
  138. package/dist/hub-service/members.js +25 -0
  139. package/dist/hub-service/members.js.map +1 -0
  140. package/dist/hub-service/presence.d.ts +40 -0
  141. package/dist/hub-service/presence.d.ts.map +1 -0
  142. package/dist/hub-service/presence.js +44 -0
  143. package/dist/hub-service/presence.js.map +1 -0
  144. package/dist/hub-service/project-view.d.ts +12 -0
  145. package/dist/hub-service/project-view.d.ts.map +1 -0
  146. package/dist/hub-service/project-view.js +34 -0
  147. package/dist/hub-service/project-view.js.map +1 -0
  148. package/dist/hub-service/projects.d.ts +48 -0
  149. package/dist/hub-service/projects.d.ts.map +1 -0
  150. package/dist/hub-service/projects.js +80 -0
  151. package/dist/hub-service/projects.js.map +1 -0
  152. package/dist/hub-service/relay-queue.d.ts +115 -0
  153. package/dist/hub-service/relay-queue.d.ts.map +1 -0
  154. package/dist/hub-service/relay-queue.js +148 -0
  155. package/dist/hub-service/relay-queue.js.map +1 -0
  156. package/dist/hub-service/session-jwt.d.ts +10 -0
  157. package/dist/hub-service/session-jwt.d.ts.map +1 -0
  158. package/dist/hub-service/session-jwt.js +69 -0
  159. package/dist/hub-service/session-jwt.js.map +1 -0
  160. package/dist/hub-service/usage.d.ts +40 -0
  161. package/dist/hub-service/usage.d.ts.map +1 -0
  162. package/dist/hub-service/usage.js +25 -0
  163. package/dist/hub-service/usage.js.map +1 -0
  164. package/dist/hub-service/users.d.ts +56 -0
  165. package/dist/hub-service/users.d.ts.map +1 -0
  166. package/dist/hub-service/users.js +72 -0
  167. package/dist/hub-service/users.js.map +1 -0
  168. package/dist/hub-service/workspaces.d.ts +20 -0
  169. package/dist/hub-service/workspaces.d.ts.map +1 -0
  170. package/dist/hub-service/workspaces.js +10 -0
  171. package/dist/hub-service/workspaces.js.map +1 -0
  172. package/dist/index.js +179 -132
  173. package/dist/index.js.map +1 -1
  174. package/dist/os/linux.d.ts +13 -0
  175. package/dist/os/linux.d.ts.map +1 -1
  176. package/dist/os/linux.js +62 -3
  177. package/dist/os/linux.js.map +1 -1
  178. package/dist/os/os-commands.d.ts +10 -0
  179. package/dist/os/os-commands.d.ts.map +1 -1
  180. package/dist/os/windows.d.ts +1 -0
  181. package/dist/os/windows.d.ts.map +1 -1
  182. package/dist/os/windows.js +21 -1
  183. package/dist/os/windows.js.map +1 -1
  184. package/dist/paths.d.ts +23 -0
  185. package/dist/paths.d.ts.map +1 -1
  186. package/dist/paths.js +29 -0
  187. package/dist/paths.js.map +1 -1
  188. package/dist/providers/agy.d.ts +9 -2
  189. package/dist/providers/agy.d.ts.map +1 -1
  190. package/dist/providers/agy.js +127 -14
  191. package/dist/providers/agy.js.map +1 -1
  192. package/dist/providers/claude.d.ts +6 -2
  193. package/dist/providers/claude.d.ts.map +1 -1
  194. package/dist/providers/claude.js +248 -9
  195. package/dist/providers/claude.js.map +1 -1
  196. package/dist/providers/codex.d.ts +3 -2
  197. package/dist/providers/codex.d.ts.map +1 -1
  198. package/dist/providers/codex.js +7 -0
  199. package/dist/providers/codex.js.map +1 -1
  200. package/dist/providers/copilot.d.ts +3 -2
  201. package/dist/providers/copilot.d.ts.map +1 -1
  202. package/dist/providers/copilot.js +8 -1
  203. package/dist/providers/copilot.js.map +1 -1
  204. package/dist/providers/gemini.d.ts +3 -2
  205. package/dist/providers/gemini.d.ts.map +1 -1
  206. package/dist/providers/gemini.js +11 -1
  207. package/dist/providers/gemini.js.map +1 -1
  208. package/dist/providers/index.d.ts +1 -0
  209. package/dist/providers/index.d.ts.map +1 -1
  210. package/dist/providers/index.js +3 -0
  211. package/dist/providers/index.js.map +1 -1
  212. package/dist/providers/none.d.ts +51 -0
  213. package/dist/providers/none.d.ts.map +1 -0
  214. package/dist/providers/none.js +103 -0
  215. package/dist/providers/none.js.map +1 -0
  216. package/dist/providers/opencode.d.ts +4 -2
  217. package/dist/providers/opencode.d.ts.map +1 -1
  218. package/dist/providers/opencode.js +49 -0
  219. package/dist/providers/opencode.js.map +1 -1
  220. package/dist/providers/provider.d.ts +79 -1
  221. package/dist/providers/provider.d.ts.map +1 -1
  222. package/dist/providers/provider.js +10 -0
  223. package/dist/providers/provider.js.map +1 -1
  224. package/dist/services/agent-provisioner.d.ts +3 -3
  225. package/dist/services/agent-provisioner.d.ts.map +1 -1
  226. package/dist/services/agent-provisioner.js +12 -5
  227. package/dist/services/agent-provisioner.js.map +1 -1
  228. package/dist/services/auth-socket.d.ts.map +1 -1
  229. package/dist/services/auth-socket.js +2 -0
  230. package/dist/services/auth-socket.js.map +1 -1
  231. package/dist/services/budget-awareness.d.ts +130 -0
  232. package/dist/services/budget-awareness.d.ts.map +1 -0
  233. package/dist/services/budget-awareness.js +129 -0
  234. package/dist/services/budget-awareness.js.map +1 -0
  235. package/dist/services/cloud-sync.d.ts +35 -0
  236. package/dist/services/cloud-sync.d.ts.map +1 -0
  237. package/dist/services/cloud-sync.js +90 -0
  238. package/dist/services/cloud-sync.js.map +1 -0
  239. package/dist/services/context-admission.d.ts +82 -0
  240. package/dist/services/context-admission.d.ts.map +1 -0
  241. package/dist/services/context-admission.js +136 -0
  242. package/dist/services/context-admission.js.map +1 -0
  243. package/dist/services/event-bus.d.ts +27 -0
  244. package/dist/services/event-bus.d.ts.map +1 -0
  245. package/dist/services/event-bus.js +20 -0
  246. package/dist/services/event-bus.js.map +1 -0
  247. package/dist/services/file-chunker.d.ts +38 -0
  248. package/dist/services/file-chunker.d.ts.map +1 -0
  249. package/dist/services/file-chunker.js +63 -0
  250. package/dist/services/file-chunker.js.map +1 -0
  251. package/dist/services/file-transfer-relay.d.ts +55 -0
  252. package/dist/services/file-transfer-relay.d.ts.map +1 -0
  253. package/dist/services/file-transfer-relay.js +115 -0
  254. package/dist/services/file-transfer-relay.js.map +1 -0
  255. package/dist/services/github-app.d.ts.map +1 -1
  256. package/dist/services/github-app.js +1 -0
  257. package/dist/services/github-app.js.map +1 -1
  258. package/dist/services/http-transport.d.ts +25 -0
  259. package/dist/services/http-transport.d.ts.map +1 -0
  260. package/dist/services/http-transport.js +371 -0
  261. package/dist/services/http-transport.js.map +1 -0
  262. package/dist/services/hub-client.d.ts +69 -0
  263. package/dist/services/hub-client.d.ts.map +1 -0
  264. package/dist/services/hub-client.js +217 -0
  265. package/dist/services/hub-client.js.map +1 -0
  266. package/dist/services/jwt.d.ts +17 -0
  267. package/dist/services/jwt.d.ts.map +1 -0
  268. package/dist/services/jwt.js +70 -0
  269. package/dist/services/jwt.js.map +1 -0
  270. package/dist/services/known-sessions.d.ts +8 -0
  271. package/dist/services/known-sessions.d.ts.map +1 -0
  272. package/dist/services/known-sessions.js +40 -0
  273. package/dist/services/known-sessions.js.map +1 -0
  274. package/dist/services/model-pricing.d.ts +36 -0
  275. package/dist/services/model-pricing.d.ts.map +1 -0
  276. package/dist/services/model-pricing.js +108 -0
  277. package/dist/services/model-pricing.js.map +1 -0
  278. package/dist/services/orphan-recovery.d.ts +56 -0
  279. package/dist/services/orphan-recovery.d.ts.map +1 -0
  280. package/dist/services/orphan-recovery.js +111 -0
  281. package/dist/services/orphan-recovery.js.map +1 -0
  282. package/dist/services/pending-responses.d.ts +23 -0
  283. package/dist/services/pending-responses.d.ts.map +1 -0
  284. package/dist/services/pending-responses.js +52 -0
  285. package/dist/services/pending-responses.js.map +1 -0
  286. package/dist/services/registry.d.ts +4 -1
  287. package/dist/services/registry.d.ts.map +1 -1
  288. package/dist/services/registry.js +3 -0
  289. package/dist/services/registry.js.map +1 -1
  290. package/dist/services/relay-context.d.ts +23 -0
  291. package/dist/services/relay-context.d.ts.map +1 -0
  292. package/dist/services/relay-context.js +8 -0
  293. package/dist/services/relay-context.js.map +1 -0
  294. package/dist/services/relay-executor.d.ts +68 -0
  295. package/dist/services/relay-executor.d.ts.map +1 -0
  296. package/dist/services/relay-executor.js +70 -0
  297. package/dist/services/relay-executor.js.map +1 -0
  298. package/dist/services/relay-request.d.ts +65 -0
  299. package/dist/services/relay-request.d.ts.map +1 -0
  300. package/dist/services/relay-request.js +129 -0
  301. package/dist/services/relay-request.js.map +1 -0
  302. package/dist/services/relay-strategy.d.ts +19 -0
  303. package/dist/services/relay-strategy.d.ts.map +1 -0
  304. package/dist/services/relay-strategy.js +111 -0
  305. package/dist/services/relay-strategy.js.map +1 -0
  306. package/dist/services/service-manager/index.d.ts +5 -0
  307. package/dist/services/service-manager/index.d.ts.map +1 -0
  308. package/dist/services/service-manager/index.js +66 -0
  309. package/dist/services/service-manager/index.js.map +1 -0
  310. package/dist/services/service-manager/linux.d.ts +10 -0
  311. package/dist/services/service-manager/linux.d.ts.map +1 -0
  312. package/dist/services/service-manager/linux.js +97 -0
  313. package/dist/services/service-manager/linux.js.map +1 -0
  314. package/dist/services/service-manager/macos.d.ts +10 -0
  315. package/dist/services/service-manager/macos.d.ts.map +1 -0
  316. package/dist/services/service-manager/macos.js +94 -0
  317. package/dist/services/service-manager/macos.js.map +1 -0
  318. package/dist/services/service-manager/types.d.ts +18 -0
  319. package/dist/services/service-manager/types.d.ts.map +1 -0
  320. package/dist/services/service-manager/types.js +5 -0
  321. package/dist/services/service-manager/types.js.map +1 -0
  322. package/dist/services/service-manager/windows.d.ts +10 -0
  323. package/dist/services/service-manager/windows.d.ts.map +1 -0
  324. package/dist/services/service-manager/windows.js +73 -0
  325. package/dist/services/service-manager/windows.js.map +1 -0
  326. package/dist/services/session-registry.d.ts +70 -0
  327. package/dist/services/session-registry.d.ts.map +1 -0
  328. package/dist/services/session-registry.js +91 -0
  329. package/dist/services/session-registry.js.map +1 -0
  330. package/dist/services/singleton.d.ts +15 -0
  331. package/dist/services/singleton.d.ts.map +1 -0
  332. package/dist/services/singleton.js +98 -0
  333. package/dist/services/singleton.js.map +1 -0
  334. package/dist/services/sprint-coordination.d.ts +168 -0
  335. package/dist/services/sprint-coordination.d.ts.map +1 -0
  336. package/dist/services/sprint-coordination.js +564 -0
  337. package/dist/services/sprint-coordination.js.map +1 -0
  338. package/dist/services/ssh.d.ts.map +1 -1
  339. package/dist/services/ssh.js +70 -3
  340. package/dist/services/ssh.js.map +1 -1
  341. package/dist/services/stall/log-path-resolver.d.ts.map +1 -1
  342. package/dist/services/stall/log-path-resolver.js +8 -1
  343. package/dist/services/stall/log-path-resolver.js.map +1 -1
  344. package/dist/services/stall/stall-detector.d.ts.map +1 -1
  345. package/dist/services/stall/stall-detector.js +39 -7
  346. package/dist/services/stall/stall-detector.js.map +1 -1
  347. package/dist/services/stall/stall-poller.d.ts +16 -0
  348. package/dist/services/stall/stall-poller.d.ts.map +1 -1
  349. package/dist/services/stall/stall-poller.js +136 -18
  350. package/dist/services/stall/stall-poller.js.map +1 -1
  351. package/dist/services/strategy.d.ts.map +1 -1
  352. package/dist/services/strategy.js +55 -5
  353. package/dist/services/strategy.js.map +1 -1
  354. package/dist/services/substitution-engine.d.ts +20 -0
  355. package/dist/services/substitution-engine.d.ts.map +1 -0
  356. package/dist/services/substitution-engine.js +92 -0
  357. package/dist/services/substitution-engine.js.map +1 -0
  358. package/dist/services/task-cleanup.d.ts.map +1 -1
  359. package/dist/services/task-cleanup.js +1 -9
  360. package/dist/services/task-cleanup.js.map +1 -1
  361. package/dist/services/token-issuer.d.ts +47 -0
  362. package/dist/services/token-issuer.d.ts.map +1 -0
  363. package/dist/services/token-issuer.js +63 -0
  364. package/dist/services/token-issuer.js.map +1 -0
  365. package/dist/services/tool-registry.d.ts +3 -0
  366. package/dist/services/tool-registry.d.ts.map +1 -0
  367. package/dist/services/tool-registry.js +139 -0
  368. package/dist/services/tool-registry.js.map +1 -0
  369. package/dist/services/user-config.d.ts +14 -0
  370. package/dist/services/user-config.d.ts.map +1 -1
  371. package/dist/services/user-config.js +55 -0
  372. package/dist/services/user-config.js.map +1 -1
  373. package/dist/services/vcs/types.d.ts +44 -0
  374. package/dist/services/vcs/types.d.ts.map +1 -1
  375. package/dist/skills/fleet-sprint-cli/SKILL.md +103 -0
  376. package/dist/skills/pm/cost.md +3 -0
  377. package/dist/skills/pm/doer-reviewer-loop.md +3 -0
  378. package/dist/tools/check-status.d.ts.map +1 -1
  379. package/dist/tools/check-status.js +8 -2
  380. package/dist/tools/check-status.js.map +1 -1
  381. package/dist/tools/child-id-allocator.d.ts +45 -0
  382. package/dist/tools/child-id-allocator.d.ts.map +1 -0
  383. package/dist/tools/child-id-allocator.js +62 -0
  384. package/dist/tools/child-id-allocator.js.map +1 -0
  385. package/dist/tools/cloud-control.d.ts +2 -2
  386. package/dist/tools/compose-permissions.d.ts +12 -4
  387. package/dist/tools/compose-permissions.d.ts.map +1 -1
  388. package/dist/tools/compose-permissions.js +55 -4
  389. package/dist/tools/compose-permissions.js.map +1 -1
  390. package/dist/tools/dolt-push-mutex.d.ts +44 -0
  391. package/dist/tools/dolt-push-mutex.d.ts.map +1 -0
  392. package/dist/tools/dolt-push-mutex.js +83 -0
  393. package/dist/tools/dolt-push-mutex.js.map +1 -0
  394. package/dist/tools/execute-command.d.ts +11 -1
  395. package/dist/tools/execute-command.d.ts.map +1 -1
  396. package/dist/tools/execute-command.js +22 -5
  397. package/dist/tools/execute-command.js.map +1 -1
  398. package/dist/tools/execute-prompt.d.ts +72 -12
  399. package/dist/tools/execute-prompt.d.ts.map +1 -1
  400. package/dist/tools/execute-prompt.js +962 -71
  401. package/dist/tools/execute-prompt.js.map +1 -1
  402. package/dist/tools/get-member-model-pricing.d.ts +21 -0
  403. package/dist/tools/get-member-model-pricing.d.ts.map +1 -0
  404. package/dist/tools/get-member-model-pricing.js +29 -0
  405. package/dist/tools/get-member-model-pricing.js.map +1 -0
  406. package/dist/tools/list-members.d.ts.map +1 -1
  407. package/dist/tools/list-members.js +39 -7
  408. package/dist/tools/list-members.js.map +1 -1
  409. package/dist/tools/member-detail.d.ts +1 -1
  410. package/dist/tools/member-detail.d.ts.map +1 -1
  411. package/dist/tools/member-detail.js +8 -2
  412. package/dist/tools/member-detail.js.map +1 -1
  413. package/dist/tools/member-reservation.d.ts +29 -0
  414. package/dist/tools/member-reservation.d.ts.map +1 -0
  415. package/dist/tools/member-reservation.js +71 -0
  416. package/dist/tools/member-reservation.js.map +1 -0
  417. package/dist/tools/provision-vcs-auth.d.ts +7 -7
  418. package/dist/tools/provision-vcs-auth.js +1 -1
  419. package/dist/tools/provision-vcs-auth.js.map +1 -1
  420. package/dist/tools/register-member.d.ts +17 -5
  421. package/dist/tools/register-member.d.ts.map +1 -1
  422. package/dist/tools/register-member.js +144 -5
  423. package/dist/tools/register-member.js.map +1 -1
  424. package/dist/tools/remove-member.d.ts +1 -1
  425. package/dist/tools/report-status.d.ts +33 -0
  426. package/dist/tools/report-status.d.ts.map +1 -0
  427. package/dist/tools/report-status.js +44 -0
  428. package/dist/tools/report-status.js.map +1 -0
  429. package/dist/tools/respond-to-message.d.ts +21 -0
  430. package/dist/tools/respond-to-message.d.ts.map +1 -0
  431. package/dist/tools/respond-to-message.js +23 -0
  432. package/dist/tools/respond-to-message.js.map +1 -0
  433. package/dist/tools/send-files.d.ts +3 -0
  434. package/dist/tools/send-files.d.ts.map +1 -1
  435. package/dist/tools/send-files.js +88 -8
  436. package/dist/tools/send-files.js.map +1 -1
  437. package/dist/tools/send-message.d.ts +27 -0
  438. package/dist/tools/send-message.d.ts.map +1 -0
  439. package/dist/tools/send-message.js +46 -0
  440. package/dist/tools/send-message.js.map +1 -0
  441. package/dist/tools/shutdown-server.d.ts +2 -0
  442. package/dist/tools/shutdown-server.d.ts.map +1 -1
  443. package/dist/tools/shutdown-server.js +19 -0
  444. package/dist/tools/shutdown-server.js.map +1 -1
  445. package/dist/tools/update-member.d.ts +8 -8
  446. package/dist/tools/update-member.d.ts.map +1 -1
  447. package/dist/tools/update-member.js +11 -1
  448. package/dist/tools/update-member.js.map +1 -1
  449. package/dist/types.d.ts +15 -3
  450. package/dist/types.d.ts.map +1 -1
  451. package/dist/utils/agent-helpers.d.ts +2 -1
  452. package/dist/utils/agent-helpers.d.ts.map +1 -1
  453. package/dist/utils/agent-helpers.js +7 -2
  454. package/dist/utils/agent-helpers.js.map +1 -1
  455. package/dist/utils/pid-helpers.d.ts +15 -0
  456. package/dist/utils/pid-helpers.d.ts.map +1 -1
  457. package/dist/utils/pid-helpers.js +23 -0
  458. package/dist/utils/pid-helpers.js.map +1 -1
  459. package/dist/utils/process-utils.d.ts +3 -0
  460. package/dist/utils/process-utils.d.ts.map +1 -0
  461. package/dist/utils/process-utils.js +42 -0
  462. package/dist/utils/process-utils.js.map +1 -0
  463. package/dist/utils/prompt-errors.d.ts +2 -1
  464. package/dist/utils/prompt-errors.d.ts.map +1 -1
  465. package/dist/utils/prompt-errors.js +13 -3
  466. package/dist/utils/prompt-errors.js.map +1 -1
  467. package/dist/utils/workspace-trust.d.ts +24 -0
  468. package/dist/utils/workspace-trust.d.ts.map +1 -0
  469. package/dist/utils/workspace-trust.js +35 -0
  470. package/dist/utils/workspace-trust.js.map +1 -0
  471. package/dist/workflows/auto-sprint.js +450 -87
  472. package/package.json +35 -7
  473. package/packages/apra-fleet-client/package.json +26 -0
  474. package/packages/apra-fleet-client/src/client/api.mjs +396 -0
  475. package/packages/apra-fleet-client/src/client/client.mjs +146 -0
  476. package/packages/apra-fleet-client/src/client/errors.mjs +71 -0
  477. package/packages/apra-fleet-client/src/client/factory.mjs +65 -0
  478. package/packages/apra-fleet-client/src/client/server-resolution.mjs +265 -0
  479. package/packages/apra-fleet-client/src/client/transport.mjs +327 -0
  480. package/packages/apra-fleet-se/apra-pm/agents/backlog-groomer.md +287 -0
  481. package/packages/apra-fleet-se/apra-pm/agents/ci-watcher.md +89 -0
  482. package/packages/apra-fleet-se/apra-pm/agents/deployer.md +139 -0
  483. package/packages/apra-fleet-se/apra-pm/agents/doer.md +225 -0
  484. package/packages/apra-fleet-se/apra-pm/agents/harvester.md +169 -0
  485. package/packages/apra-fleet-se/apra-pm/agents/integ-test-runner.md +316 -0
  486. package/packages/apra-fleet-se/apra-pm/agents/plan-reviewer.md +188 -0
  487. package/packages/apra-fleet-se/apra-pm/agents/planner.md +239 -0
  488. package/packages/apra-fleet-se/apra-pm/agents/regression-test-runner.md +216 -0
  489. package/packages/apra-fleet-se/apra-pm/agents/reviewer.md +174 -0
  490. package/packages/apra-fleet-se/apra-pm/agents/schemas/backlog-groomer-input.json +35 -0
  491. package/packages/apra-fleet-se/apra-pm/agents/schemas/backlog-groomer-output.json +164 -0
  492. package/packages/apra-fleet-se/apra-pm/agents/schemas/ci-watcher-input.json +26 -0
  493. package/packages/apra-fleet-se/apra-pm/agents/schemas/ci-watcher-output.json +18 -0
  494. package/packages/apra-fleet-se/apra-pm/agents/schemas/deployer-input.json +19 -0
  495. package/packages/apra-fleet-se/apra-pm/agents/schemas/deployer-output.json +17 -0
  496. package/packages/apra-fleet-se/apra-pm/agents/schemas/doer-input.json +25 -0
  497. package/packages/apra-fleet-se/apra-pm/agents/schemas/doer-output.json +22 -0
  498. package/packages/apra-fleet-se/apra-pm/agents/schemas/harvester-input.json +31 -0
  499. package/packages/apra-fleet-se/apra-pm/agents/schemas/harvester-output.json +18 -0
  500. package/packages/apra-fleet-se/apra-pm/agents/schemas/integ-test-runner-input.json +20 -0
  501. package/packages/apra-fleet-se/apra-pm/agents/schemas/integ-test-runner-output.json +61 -0
  502. package/packages/apra-fleet-se/apra-pm/agents/schemas/plan-reviewer-input.json +15 -0
  503. package/packages/apra-fleet-se/apra-pm/agents/schemas/plan-reviewer-output.json +30 -0
  504. package/packages/apra-fleet-se/apra-pm/agents/schemas/regression-test-runner-input.json +15 -0
  505. package/packages/apra-fleet-se/apra-pm/agents/schemas/regression-test-runner-output.json +50 -0
  506. package/packages/apra-fleet-se/apra-pm/agents/schemas/reviewer-input.json +25 -0
  507. package/packages/apra-fleet-se/apra-pm/agents/schemas/reviewer-output.json +38 -0
  508. package/packages/apra-fleet-se/apra-pm/skills/pm/SKILL.md +402 -0
  509. package/packages/apra-fleet-se/apra-pm/skills/pm/beads.md +142 -0
  510. package/packages/apra-fleet-se/apra-pm/skills/pm/cost.md +157 -0
  511. package/packages/apra-fleet-se/apra-pm/skills/pm/doer-reviewer-loop.md +300 -0
  512. package/packages/apra-fleet-se/apra-pm/skills/pm/fleet-addendum.md +121 -0
  513. package/packages/apra-fleet-se/apra-pm/skills/pm/simple-sprint.md +65 -0
  514. package/packages/apra-fleet-se/apra-pm/skills/pm/sprint.md +327 -0
  515. package/packages/apra-fleet-se/apra-pm/skills/pm/worktrees.md +92 -0
  516. package/packages/apra-fleet-se/apra-pm/version.json +3 -0
  517. package/packages/apra-fleet-se/bin/cli.mjs +857 -0
  518. package/packages/apra-fleet-se/bin/serve.mjs +383 -0
  519. package/packages/apra-fleet-se/fleet-sprint/conflict-ladder.mjs +178 -0
  520. package/packages/apra-fleet-se/fleet-sprint/contracts.mjs +914 -0
  521. package/packages/apra-fleet-se/fleet-sprint/dispatch-safety-guard.mjs +177 -0
  522. package/packages/apra-fleet-se/fleet-sprint/docs/README.md +191 -0
  523. package/packages/apra-fleet-se/fleet-sprint/docs/coach-role-design.md +151 -0
  524. package/packages/apra-fleet-se/fleet-sprint/docs/dolt-tier2-runbook.md +127 -0
  525. package/packages/apra-fleet-se/fleet-sprint/docs/fleet-sprint-diagram.md +94 -0
  526. package/packages/apra-fleet-se/fleet-sprint/docs/stabilization-log.md +1125 -0
  527. package/packages/apra-fleet-se/fleet-sprint/dolt-literal-guard.mjs +72 -0
  528. package/packages/apra-fleet-se/fleet-sprint/dolt-recovery-path-b.mjs +339 -0
  529. package/packages/apra-fleet-se/fleet-sprint/dolt-recovery-tier2.mjs +360 -0
  530. package/packages/apra-fleet-se/fleet-sprint/dolt-recovery.mjs +363 -0
  531. package/packages/apra-fleet-se/fleet-sprint/dolt-sync.mjs +1244 -0
  532. package/packages/apra-fleet-se/fleet-sprint/errors.mjs +572 -0
  533. package/packages/apra-fleet-se/fleet-sprint/full-db-fetch-guard.mjs +118 -0
  534. package/packages/apra-fleet-se/fleet-sprint/runner.js +9447 -0
  535. package/packages/apra-fleet-se/fleet-sprint/skills/fleet-sprint-cli/SKILL.md +103 -0
  536. package/packages/apra-fleet-se/fleet-sprint/sprint-lock.mjs +140 -0
  537. package/packages/apra-fleet-se/fleet-sprint/vcs-module.mjs +435 -0
  538. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/azure-devops.mjs +68 -0
  539. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/bitbucket.mjs +53 -0
  540. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/dolt.mjs +146 -0
  541. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/generic-git.mjs +176 -0
  542. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/github.mjs +222 -0
  543. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/index.mjs +218 -0
  544. package/packages/apra-fleet-se/fleet-sprint/viewer-extensions.mjs +882 -0
  545. package/packages/apra-fleet-se/package.json +28 -0
  546. package/packages/apra-fleet-se/workflow.json +1 -0
  547. package/packages/apra-fleet-workflow/package.json +30 -0
  548. package/packages/apra-fleet-workflow/src/viewer/command-output-cap.mjs +112 -0
  549. package/packages/apra-fleet-workflow/src/viewer/debounced-writer.mjs +153 -0
  550. package/packages/apra-fleet-workflow/src/viewer/html-utils.mjs +31 -0
  551. package/packages/apra-fleet-workflow/src/viewer/index.mjs +1325 -0
  552. package/packages/apra-fleet-workflow/src/viewer/lean-state.mjs +237 -0
  553. package/packages/apra-fleet-workflow/src/viewer/run-state-paths.mjs +130 -0
  554. package/packages/apra-fleet-workflow/src/viewer/sprint-state-paths.mjs +29 -0
  555. package/packages/apra-fleet-workflow/src/workflow/engine.mjs +200 -0
  556. package/packages/apra-fleet-workflow/src/workflow/errors.mjs +146 -0
  557. package/packages/apra-fleet-workflow/src/workflow/index.mjs +1723 -0
  558. package/packages/apra-fleet-workflow/src/workflow/journal.mjs +291 -0
  559. package/packages/apra-fleet-workflow/src/workflow/pricing.mjs +99 -0
  560. package/packages/apra-fleet-workflow/src/workflow/vetting.mjs +111 -0
  561. package/scripts/agy-transcript-reader.js +1 -0
  562. package/scripts/fleet-statusline.sh +17 -13
  563. package/skills/fleet/SKILL.md +37 -2
  564. package/skills/fleet/beads.md +14 -7
  565. package/skills/fleet/permissions.md +50 -0
  566. package/skills/fleet/profiles/base-dev.json +1 -0
  567. package/skills/fleet/profiles/base-reviewer.json +1 -0
  568. package/skills/fleet/profiles/node.json +2 -2
  569. package/version.json +1 -1
  570. package/scripts/agy-settings-merge.js +0 -27
  571. /package/{dist → packages/apra-fleet-se/apra-pm}/agents/_shared/GRAPH-SEMANTICS.md +0 -0
@@ -0,0 +1,28 @@
1
+ {
2
+ "name": "@apralabs/apra-fleet-se",
3
+ "version": "1.0.0",
4
+ "description": "Apra Fleet Software Engineering (SE) Edition. Contains SE-specific workflows like fleet-sprint.",
5
+ "private": true,
6
+ "license": "Apache-2.0",
7
+ "type": "module",
8
+ "engines": {
9
+ "node": ">=22.0.0"
10
+ },
11
+ "bin": {
12
+ "fleet-sprint": "./bin/cli.mjs",
13
+ "fleet-se-serve": "./bin/serve.mjs"
14
+ },
15
+ "scripts": {
16
+ "test": "node --test --test-reporter=./test/helpers/timestamped-reporter.mjs --test-reporter-destination=stdout --test-concurrency=8 test/*.test.mjs",
17
+ "test:slow": "node --test --test-reporter=./test/helpers/timestamped-reporter.mjs --test-reporter-destination=stdout test/slow/*.test.mjs",
18
+ "test:unit": "node scripts/run-tests.mjs mock",
19
+ "test:integration": "node scripts/run-tests.mjs real",
20
+ "test:record": "node scripts/run-tests.mjs record",
21
+ "update-golden": "node -e \"require('child_process').execFileSync(process.execPath,['--test','test/golden-transcript.test.mjs'],{stdio:'inherit',env:{...process.env,UPDATE_GOLDEN:'1'}})\""
22
+ },
23
+ "dependencies": {
24
+ "@apralabs/apra-fleet-workflow": "*",
25
+ "@apralabs/apra-fleet-client": "*",
26
+ "ajv": "^8.12.0"
27
+ }
28
+ }
@@ -0,0 +1 @@
1
+ {"name":"fleet-sprint","entry":"bin/cli.mjs","description":"Multi-cycle sprint: plan -> develop -> test -> harvest"}
@@ -0,0 +1,30 @@
1
+ {
2
+ "name": "@apralabs/apra-fleet-workflow",
3
+ "version": "1.0.0",
4
+ "description": "Workflow Engine for Apra Fleet",
5
+ "private": true,
6
+ "engines": {
7
+ "node": ">=22.0.0"
8
+ },
9
+ "main": "src/workflow/index.mjs",
10
+ "exports": {
11
+ ".": "./src/workflow/index.mjs",
12
+ "./engine": "./src/workflow/engine.mjs",
13
+ "./viewer": "./src/viewer/index.mjs",
14
+ "./viewer/html-utils": "./src/viewer/html-utils.mjs",
15
+ "./viewer/run-state-paths": "./src/viewer/run-state-paths.mjs",
16
+ "./viewer/sprint-state-paths": "./src/viewer/sprint-state-paths.mjs",
17
+ "./viewer/debounced-writer": "./src/viewer/debounced-writer.mjs",
18
+ "./viewer/lean-state": "./src/viewer/lean-state.mjs"
19
+ },
20
+ "scripts": {
21
+ "test": "node --test --test-timeout=60000 test/*.test.mjs"
22
+ },
23
+ "type": "module",
24
+ "dependencies": {
25
+ "@apralabs/apra-fleet-client": "*",
26
+ "ajv": "^8.12.0"
27
+ },
28
+ "author": "Apra Labs",
29
+ "license": "Apache-2.0"
30
+ }
@@ -0,0 +1,112 @@
1
+ // apra-fleet-eft.27.4: bounds how much of a command activity's captured
2
+ // stdout ever gets STORED into live run state (state.tree in
3
+ // src/viewer/index.mjs), not just how much GET /state serves per poll (that
4
+ // narrower job belongs to lean-state.mjs, applied only to the outgoing
5
+ // /state payload). Without this, the full text of every `command()`
6
+ // activity survives for the whole run in the in-memory `state` object --
7
+ // and therefore in the debounced running/<runId>.json write and the
8
+ // terminal snapshot too.
9
+ //
10
+ // Root cause (apra-fleet-eft.27, measured live): a 449-activity sprint's
11
+ // 188 MB /state payload was dominated by 130 command-activity events at
12
+ // ~1.3 MB each (164 MB) -- every one the full captured stdout of a repeated
13
+ // `bd list --all --limit 0 --json`. lean-state.mjs's closed siblings
14
+ // (eft.27.1/27.2/27.3) never capped this at the point of STORAGE, only at
15
+ // the point GET /state serialized it for the wire.
16
+ //
17
+ // Design: keep a short head+tail excerpt inline on the activity (enough to
18
+ // diagnose most failures at a glance) plus the true original byte count,
19
+ // and stash the full original text in an in-memory, per-activity-id store
20
+ // so it stays retrievable on demand (GET /activities/:id/output, wired in
21
+ // src/viewer/index.mjs) without ever being re-embedded in polled or
22
+ // persisted state. Deliberately command-agnostic: any chatty command is
23
+ // capped, not just `bd list`.
24
+
25
+ export const DEFAULT_HEAD_CHARS = 2000;
26
+ export const DEFAULT_TAIL_CHARS = 1000;
27
+
28
+ /**
29
+ * Caps `text` to a head+tail excerpt when it exceeds headChars+tailChars.
30
+ * Returns `{ value, truncated, byteLength }`: `value` is the (possibly
31
+ * capped) excerpt to store inline, `truncated` is whether capping actually
32
+ * happened, and `byteLength` is the ORIGINAL text's byte length (not the
33
+ * excerpt's), so a caller can always show/report the true size even when
34
+ * capped.
35
+ *
36
+ * @param {string} text
37
+ * @param {object} [opts]
38
+ * @param {number} [opts.headChars]
39
+ * @param {number} [opts.tailChars]
40
+ */
41
+ export function capOutputText(text, opts = {}) {
42
+ const headChars = opts.headChars ?? DEFAULT_HEAD_CHARS;
43
+ const tailChars = opts.tailChars ?? DEFAULT_TAIL_CHARS;
44
+ if (typeof text !== 'string') return { value: text, truncated: false, byteLength: 0 };
45
+ const byteLength = Buffer.byteLength(text, 'utf8');
46
+ if (text.length <= headChars + tailChars) {
47
+ return { value: text, truncated: false, byteLength };
48
+ }
49
+ const head = text.slice(0, headChars);
50
+ const tail = tailChars > 0 ? text.slice(text.length - tailChars) : '';
51
+ const omittedChars = text.length - headChars - tailChars;
52
+ const value = `${head}\n\n... [${omittedChars} chars / ${byteLength} total bytes omitted -- full output available via GET /activities/:id/output] ...\n\n${tail}`;
53
+ return { value, truncated: true, byteLength };
54
+ }
55
+
56
+ // In-memory store of full, un-capped command-activity output/error text,
57
+ // keyed by activity id (see capCommandActivityMeta()). Read by the
58
+ // GET /activities/:id/output route in src/viewer/index.mjs. Deliberately
59
+ // module-level rather than threaded through `state` -- this text must NEVER
60
+ // be serialized into state.tree / GET /state / persisted snapshots, which is
61
+ // the whole point of capping it there in the first place. One dashboard
62
+ // process serves exactly one live workflow run, so an unbounded Map here is
63
+ // server-side memory only (never transmitted-per-poll or persisted-to-disk
64
+ // as a whole), garbage-collected with the process on exit.
65
+ const fullOutputById = new Map();
66
+
67
+ /** Returns `{ output?, error? }` for a capped activity id, or `null` if none was ever capped (or the id is unknown). */
68
+ export function getFullOutput(activityId) {
69
+ return fullOutputById.has(activityId) ? fullOutputById.get(activityId) : null;
70
+ }
71
+
72
+ // Exposed for tests only.
73
+ export function _clearFullOutputStoreForTests() {
74
+ fullOutputById.clear();
75
+ }
76
+
77
+ const CAPPED_FIELDS = ['output', 'error'];
78
+
79
+ /**
80
+ * Returns a shallow copy of a `type: 'command'` activity:end meta object
81
+ * with `output`/`error` capped to a head+tail excerpt (capOutputText()),
82
+ * stashing the full original text in the module's fullOutputById store
83
+ * (keyed by `meta.id`) whenever capping actually happens. Non-`command`
84
+ * activities (e.g. `agent`) and activities with nothing over the cap pass
85
+ * through completely unchanged (the identical `meta` reference is returned).
86
+ *
87
+ * The ORIGINAL `meta` object passed in is never mutated -- other
88
+ * `activity:end` listeners on the same FleetWorkflow event (e.g.
89
+ * journal.mjs's replay cache) depend on seeing the complete, uncapped text.
90
+ *
91
+ * @param {object} meta
92
+ * @param {object} [opts] - forwarded to capOutputText() (headChars/tailChars).
93
+ */
94
+ export function capCommandActivityMeta(meta, opts = {}) {
95
+ if (!meta || meta.type !== 'command') return meta;
96
+ let out = meta;
97
+ let fullForId = null;
98
+ for (const field of CAPPED_FIELDS) {
99
+ const raw = meta[field];
100
+ if (typeof raw !== 'string' || raw.length === 0) continue;
101
+ const { value, truncated, byteLength } = capOutputText(raw, opts);
102
+ if (!truncated) continue;
103
+ if (out === meta) out = { ...meta };
104
+ out[field] = value;
105
+ out[`${field}Truncated`] = true;
106
+ out[`${field}ByteLength`] = byteLength;
107
+ if (!fullForId) fullForId = { ...(fullOutputById.get(meta.id) || {}) };
108
+ fullForId[field] = raw;
109
+ }
110
+ if (fullForId) fullOutputById.set(meta.id, fullForId);
111
+ return out;
112
+ }
@@ -0,0 +1,153 @@
1
+ // apra-fleet-eft.2.1: debounced run-state writer with flush-on-exit.
2
+ //
3
+ // This is additive to (not a replacement for) the existing
4
+ // terminal snapshot's write-once-on-end persistState() in
5
+ // src/viewer/index.mjs, which stays exactly as-is as the child
6
+ // crash-safety net. This writer coalesces bursts of rapid state changes
7
+ // (e.g. one per activity/phase/state event, see apra-fleet-eft.2.2) into a
8
+ // single write per debounce window, and always flushes synchronously
9
+ // before the process actually exits (end, SIGINT, SIGTERM, /stop).
10
+ //
11
+ // The target file path passed in today is a placeholder -- the real
12
+ // running/<runId>.json -> old_runs/<runId>.json layout under the
13
+ // service data directory is wired in a later task (apra-fleet-eft.2.3).
14
+
15
+ import fs from 'fs';
16
+ import path from 'path';
17
+
18
+ export const MIN_DEBOUNCE_MS = 200;
19
+ export const MAX_DEBOUNCE_MS = 500;
20
+ export const DEFAULT_DEBOUNCE_MS = 300;
21
+
22
+ // apra-fleet-eft.20.1: single shared atomic-JSON-write primitive for every
23
+ // run-state persistence path in this package (the debounced writer below
24
+ // AND the terminal-snapshot persistState() in ../viewer/index.mjs). Centralizing
25
+ // this here guarantees two invariants that a hand-rolled/partial-patch writer
26
+ // could otherwise violate:
27
+ // 1. The full object is always serialized in ONE JSON.stringify pass -- no
28
+ // code path ever splices/patches individual fields into previously
29
+ // serialized text (the kind of string surgery that produced the
30
+ // `"phase"":"Develop"` doubled-quote corruption in apra-fleet-eft.20:
31
+ // a stray extra `"` inserted by an in-place field patch rather than a
32
+ // single whole-object serialization). Because the input to
33
+ // fs.writeFileSync is always the direct output of JSON.stringify(), the
34
+ // written bytes are guaranteed to round-trip through JSON.parse().
35
+ // 2. The write is atomic: bytes land in a sibling temp file first, then
36
+ // `fs.renameSync` (a single filesystem operation on POSIX) swaps it into
37
+ // place, so a reader (or a crash mid-write) can never observe a
38
+ // truncated/partial file -- only the old complete file or the new
39
+ // complete one.
40
+ // The temp filename includes both the pid and a monotonic counter (not just
41
+ // Date.now(), which can collide when called faster than the clock's
42
+ // resolution) so concurrent/rapid writers targeting the same filePath never
43
+ // collide on the same temp path.
44
+ let _tmpSeq = 0;
45
+ export function writeJsonFileAtomic(filePath, data) {
46
+ const dir = path.dirname(filePath);
47
+ fs.mkdirSync(dir, { recursive: true });
48
+ const tmpPath = path.join(
49
+ dir,
50
+ `.${path.basename(filePath)}.${process.pid}.${Date.now()}.${_tmpSeq++}.tmp`
51
+ );
52
+ fs.writeFileSync(tmpPath, JSON.stringify(data, null, 2));
53
+ fs.renameSync(tmpPath, filePath);
54
+ }
55
+
56
+ export class DebouncedStateWriter {
57
+ /**
58
+ * @param {object} opts
59
+ * @param {() => any} opts.getState - returns the current state snapshot to serialize.
60
+ * @param {string} opts.filePath - target file path to write to.
61
+ * @param {number} [opts.debounceMs] - coalescing window in ms; must be in
62
+ * [MIN_DEBOUNCE_MS, MAX_DEBOUNCE_MS], defaults to DEFAULT_DEBOUNCE_MS.
63
+ */
64
+ constructor({ getState, filePath, debounceMs = DEFAULT_DEBOUNCE_MS } = {}) {
65
+ if (typeof getState !== 'function') {
66
+ throw new TypeError('DebouncedStateWriter requires a getState() function');
67
+ }
68
+ if (!filePath) {
69
+ throw new TypeError('DebouncedStateWriter requires a filePath');
70
+ }
71
+ if (typeof debounceMs !== 'number' || Number.isNaN(debounceMs) ||
72
+ debounceMs < MIN_DEBOUNCE_MS || debounceMs > MAX_DEBOUNCE_MS) {
73
+ throw new RangeError(
74
+ `debounceMs must be a number between ${MIN_DEBOUNCE_MS} and ${MAX_DEBOUNCE_MS} (got ${debounceMs})`
75
+ );
76
+ }
77
+
78
+ this._getState = getState;
79
+ this._filePath = filePath;
80
+ this._debounceMs = debounceMs;
81
+ this._timer = null;
82
+ this._dirty = false;
83
+ this._writeCount = 0;
84
+ }
85
+
86
+ /** Number of debounce window in ms this writer coalesces bursts into. */
87
+ get debounceMs() {
88
+ return this._debounceMs;
89
+ }
90
+
91
+ /** Total number of times this writer has actually written to disk. */
92
+ get writeCount() {
93
+ return this._writeCount;
94
+ }
95
+
96
+ /**
97
+ * Mark state as dirty and schedule a write in `debounceMs` if one isn't
98
+ * already pending. Rapid repeated calls within the window coalesce into
99
+ * a single write.
100
+ */
101
+ schedule() {
102
+ this._dirty = true;
103
+ if (this._timer) return;
104
+ this._timer = setTimeout(() => {
105
+ this._timer = null;
106
+ this._writeNow();
107
+ }, this._debounceMs);
108
+ // Never let a pending debounce timer keep the process alive on its own.
109
+ if (this._timer && typeof this._timer.unref === 'function') {
110
+ this._timer.unref();
111
+ }
112
+ }
113
+
114
+ /**
115
+ * Synchronously flush any pending (or just-scheduled) write immediately.
116
+ * Cancels any outstanding debounce timer first so this never races a
117
+ * later async write. Safe to call even when nothing is dirty (no-op).
118
+ * Must be called from every process-exit path (end, SIGINT, SIGTERM,
119
+ * cooperative /stop) so a debounce window is never lost on shutdown.
120
+ */
121
+ flushSync() {
122
+ if (this._timer) {
123
+ clearTimeout(this._timer);
124
+ this._timer = null;
125
+ }
126
+ if (!this._dirty) return;
127
+ this._writeNow();
128
+ }
129
+
130
+ _writeNow() {
131
+ this._dirty = false;
132
+ try {
133
+ // Write atomically: a concurrent reader (watchdog/dashboard/
134
+ // history views, or this package's own tests) must never observe
135
+ // a partially-written file, and a SIGKILL landing mid-write must
136
+ // never corrupt the previous, still-valid state on disk. Writing
137
+ // to a sibling temp path and renaming into place is atomic on
138
+ // POSIX (rename is a single filesystem operation), so readers see
139
+ // either the old complete file or the new complete file, never a
140
+ // truncated one. The whole state snapshot is always serialized in
141
+ // one JSON.stringify() pass (see writeJsonFileAtomic above) --
142
+ // never patched field-by-field -- so the written bytes always
143
+ // round-trip through JSON.parse().
144
+ writeJsonFileAtomic(this._filePath, this._getState());
145
+ this._writeCount += 1;
146
+ } catch (e) {
147
+ // A failed write must never crash or block the run's own
148
+ // normal exit behavior -- log and move on, same contract as
149
+ // the existing persistState() in index.mjs.
150
+ console.warn(`[Viewer] Warning: failed to write debounced state file: ${e.message}`);
151
+ }
152
+ }
153
+ }
@@ -0,0 +1,31 @@
1
+ /**
2
+ * Shared browser-side HTML-escaping helper (apra-fleet-unw.10, F9/A7-viewer).
3
+ *
4
+ * Single source of truth for escaping untrusted, LLM/bead-authored text
5
+ * (activity labels/output, bead titles/descriptions, etc.) before it is
6
+ * interpolated into `innerHTML` in the dashboard's client-side JS. Both the
7
+ * core viewer template (`src/viewer/index.mjs`) and dashboard extensions
8
+ * (e.g. `packages/apra-fleet-se/fleet-sprint/viewer-extensions.mjs`) embed
9
+ * this function's *source text* (via `escapeHtml.toString()`) directly into
10
+ * the HTML page they generate -- the extensions run in the browser as plain
11
+ * `<script>` tags, not as ES modules, so they cannot `import` this file at
12
+ * runtime; `.toString()` is how a single implementation is shared without
13
+ * duplicating the escaping logic by hand in every extension.
14
+ *
15
+ * This same function is also imported and unit-tested directly under Node
16
+ * (see test/apra-fleet-workflow-viewer-lifecycle.test.mjs), so the escaping
17
+ * behavior itself is verified independently of any browser/DOM environment.
18
+ *
19
+ * IMPORTANT: keep this as a `function` declaration (not an arrow function) --
20
+ * `Function.prototype.toString()` on a named function declaration reproduces
21
+ * a valid, directly-embeddable function declaration; an arrow function's
22
+ * source text would not declare a hoisted `escapeHtml` binding the same way.
23
+ */
24
+ export function escapeHtml(unsafe) {
25
+ return (unsafe || '').toString()
26
+ .replace(/&/g, '&amp;')
27
+ .replace(/</g, '&lt;')
28
+ .replace(/>/g, '&gt;')
29
+ .replace(/"/g, '&quot;')
30
+ .replace(/'/g, '&#039;');
31
+ }