@chankov/agent-fleet 2.0.0 → 2.0.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 (428) hide show
  1. package/.pi/harnesses/agent-hub/package.json +1 -1
  2. package/.pi/harnesses/coms/package.json +1 -1
  3. package/.pi/harnesses/damage-control-continue/package.json +1 -1
  4. package/.versions/2.0.1/.pi/agents/dispatch-policy.yaml +32 -0
  5. package/.versions/2.0.1/.pi/agents/model-profiles.yaml +27 -0
  6. package/.versions/2.0.1/.pi/agents/peers.yaml +142 -0
  7. package/.versions/2.0.1/.pi/agents/teams.yaml +41 -0
  8. package/.versions/2.0.1/.pi/damage-control-rules.yaml +297 -0
  9. package/.versions/2.0.1/.pi/extensions/agent-fleet-update-check/README.md +57 -0
  10. package/.versions/2.0.1/.pi/extensions/agent-fleet-update-check/index.ts +161 -0
  11. package/.versions/2.0.1/.pi/extensions/agent-fleet-update-check/package.json +6 -0
  12. package/.versions/2.0.1/.pi/extensions/btw/README.md +120 -0
  13. package/.versions/2.0.1/.pi/extensions/btw/index.ts +914 -0
  14. package/.versions/2.0.1/.pi/extensions/btw/package.json +6 -0
  15. package/.versions/2.0.1/.pi/extensions/btw/state.js +179 -0
  16. package/.versions/2.0.1/.pi/extensions/chrome-devtools-mcp/README.md +55 -0
  17. package/.versions/2.0.1/.pi/extensions/chrome-devtools-mcp/index.ts +93 -0
  18. package/.versions/2.0.1/.pi/extensions/chrome-devtools-mcp/package.json +6 -0
  19. package/.versions/2.0.1/.pi/extensions/compact-and-continue/README.md +42 -0
  20. package/.versions/2.0.1/.pi/extensions/compact-and-continue/index.ts +120 -0
  21. package/.versions/2.0.1/.pi/extensions/compact-and-continue/package.json +6 -0
  22. package/.versions/2.0.1/.pi/extensions/mcp-bridge/README.md +46 -0
  23. package/.versions/2.0.1/.pi/extensions/mcp-bridge/index.ts +206 -0
  24. package/.versions/2.0.1/.pi/extensions/mcp-bridge/package.json +6 -0
  25. package/.versions/2.0.1/.pi/extensions/package-lock.json +1175 -0
  26. package/.versions/2.0.1/.pi/extensions/package.json +9 -0
  27. package/.versions/2.0.1/.pi/extensions/pi-voice-stt/README.md +205 -0
  28. package/.versions/2.0.1/.pi/extensions/pi-voice-stt/config.ts +198 -0
  29. package/.versions/2.0.1/.pi/extensions/pi-voice-stt/examples/stt.json +35 -0
  30. package/.versions/2.0.1/.pi/extensions/pi-voice-stt/index.ts +248 -0
  31. package/.versions/2.0.1/.pi/extensions/pi-voice-stt/package.json +6 -0
  32. package/.versions/2.0.1/.pi/extensions/pi-voice-stt/providers.ts +214 -0
  33. package/.versions/2.0.1/.pi/extensions/pi-voice-stt/recorder.ts +158 -0
  34. package/.versions/2.0.1/.pi/harnesses/agent-hub/README.md +1161 -0
  35. package/.versions/2.0.1/.pi/harnesses/agent-hub/access-approval.ts +135 -0
  36. package/.versions/2.0.1/.pi/harnesses/agent-hub/artifacts.js +146 -0
  37. package/.versions/2.0.1/.pi/harnesses/agent-hub/assertion-ledger.js +58 -0
  38. package/.versions/2.0.1/.pi/harnesses/agent-hub/backend-policy.js +174 -0
  39. package/.versions/2.0.1/.pi/harnesses/agent-hub/budget-continuation.ts +73 -0
  40. package/.versions/2.0.1/.pi/harnesses/agent-hub/capability-confirmation.ts +47 -0
  41. package/.versions/2.0.1/.pi/harnesses/agent-hub/capability-packs.ts +180 -0
  42. package/.versions/2.0.1/.pi/harnesses/agent-hub/commands/agent-model-thinking.ts +10 -0
  43. package/.versions/2.0.1/.pi/harnesses/agent-hub/commands/agent-model.ts +10 -0
  44. package/.versions/2.0.1/.pi/harnesses/agent-hub/commands/agent-models-substitute.ts +10 -0
  45. package/.versions/2.0.1/.pi/harnesses/agent-hub/commands/agents-add.ts +9 -0
  46. package/.versions/2.0.1/.pi/harnesses/agent-hub/commands/agents-drop.ts +9 -0
  47. package/.versions/2.0.1/.pi/harnesses/agent-hub/commands/agents-history.ts +9 -0
  48. package/.versions/2.0.1/.pi/harnesses/agent-hub/commands/agents-kill.ts +10 -0
  49. package/.versions/2.0.1/.pi/harnesses/agent-hub/commands/agents-list.ts +9 -0
  50. package/.versions/2.0.1/.pi/harnesses/agent-hub/commands/agents-restart.ts +10 -0
  51. package/.versions/2.0.1/.pi/harnesses/agent-hub/commands/agents-save.ts +9 -0
  52. package/.versions/2.0.1/.pi/harnesses/agent-hub/commands/agents-team.ts +9 -0
  53. package/.versions/2.0.1/.pi/harnesses/agent-hub/commands/compound.ts +9 -0
  54. package/.versions/2.0.1/.pi/harnesses/agent-hub/commands/coms.ts +9 -0
  55. package/.versions/2.0.1/.pi/harnesses/agent-hub/commands/context-command.ts +9 -0
  56. package/.versions/2.0.1/.pi/harnesses/agent-hub/commands/context.ts +39 -0
  57. package/.versions/2.0.1/.pi/harnesses/agent-hub/commands/dispatch-policy.ts +9 -0
  58. package/.versions/2.0.1/.pi/harnesses/agent-hub/commands/handoff.ts +10 -0
  59. package/.versions/2.0.1/.pi/harnesses/agent-hub/commands/hub-report.ts +9 -0
  60. package/.versions/2.0.1/.pi/harnesses/agent-hub/commands/models.ts +10 -0
  61. package/.versions/2.0.1/.pi/harnesses/agent-hub/commands/watchdog.ts +9 -0
  62. package/.versions/2.0.1/.pi/harnesses/agent-hub/commands/work-mode.ts +29 -0
  63. package/.versions/2.0.1/.pi/harnesses/agent-hub/commands/zoom.ts +10 -0
  64. package/.versions/2.0.1/.pi/harnesses/agent-hub/config/agents.ts +171 -0
  65. package/.versions/2.0.1/.pi/harnesses/agent-hub/config/overrides.ts +118 -0
  66. package/.versions/2.0.1/.pi/harnesses/agent-hub/context/agent-state.ts +30 -0
  67. package/.versions/2.0.1/.pi/harnesses/agent-hub/context/assertions-artifacts.ts +211 -0
  68. package/.versions/2.0.1/.pi/harnesses/agent-hub/context/budgets.ts +208 -0
  69. package/.versions/2.0.1/.pi/harnesses/agent-hub/context/hub-state.ts +40 -0
  70. package/.versions/2.0.1/.pi/harnesses/agent-hub/context-budget-snapshot.ts +105 -0
  71. package/.versions/2.0.1/.pi/harnesses/agent-hub/context-pressure.ts +191 -0
  72. package/.versions/2.0.1/.pi/harnesses/agent-hub/context-window.js +106 -0
  73. package/.versions/2.0.1/.pi/harnesses/agent-hub/delegate.ts +446 -0
  74. package/.versions/2.0.1/.pi/harnesses/agent-hub/dispatch-coms.ts +232 -0
  75. package/.versions/2.0.1/.pi/harnesses/agent-hub/dispatch-core.ts +27 -0
  76. package/.versions/2.0.1/.pi/harnesses/agent-hub/dispatch-native-complete.ts +135 -0
  77. package/.versions/2.0.1/.pi/harnesses/agent-hub/dispatch-native-prepare.ts +153 -0
  78. package/.versions/2.0.1/.pi/harnesses/agent-hub/dispatch-native-spawn.ts +191 -0
  79. package/.versions/2.0.1/.pi/harnesses/agent-hub/dispatch-native-types.ts +207 -0
  80. package/.versions/2.0.1/.pi/harnesses/agent-hub/dispatch-native.ts +184 -0
  81. package/.versions/2.0.1/.pi/harnesses/agent-hub/dispatch-observability.ts +220 -0
  82. package/.versions/2.0.1/.pi/harnesses/agent-hub/docs-lane.js +122 -0
  83. package/.versions/2.0.1/.pi/harnesses/agent-hub/drift-watchdog.js +218 -0
  84. package/.versions/2.0.1/.pi/harnesses/agent-hub/evidence-rules.js +96 -0
  85. package/.versions/2.0.1/.pi/harnesses/agent-hub/external-blocker.js +85 -0
  86. package/.versions/2.0.1/.pi/harnesses/agent-hub/fixtures/registration-surface.json +53 -0
  87. package/.versions/2.0.1/.pi/harnesses/agent-hub/footer.ts +30 -0
  88. package/.versions/2.0.1/.pi/harnesses/agent-hub/helpers.ts +266 -0
  89. package/.versions/2.0.1/.pi/harnesses/agent-hub/hub-state-audit.js +59 -0
  90. package/.versions/2.0.1/.pi/harnesses/agent-hub/index.ts +1850 -0
  91. package/.versions/2.0.1/.pi/harnesses/agent-hub/input/completions.ts +76 -0
  92. package/.versions/2.0.1/.pi/harnesses/agent-hub/input/shortcuts.ts +47 -0
  93. package/.versions/2.0.1/.pi/harnesses/agent-hub/lifecycle/context-pressure.ts +123 -0
  94. package/.versions/2.0.1/.pi/harnesses/agent-hub/lifecycle/monitor-session.ts +104 -0
  95. package/.versions/2.0.1/.pi/harnesses/agent-hub/lifecycle/session-orchestration.ts +139 -0
  96. package/.versions/2.0.1/.pi/harnesses/agent-hub/lifecycle/turn-handlers.ts +95 -0
  97. package/.versions/2.0.1/.pi/harnesses/agent-hub/monitor-control.ts +9 -0
  98. package/.versions/2.0.1/.pi/harnesses/agent-hub/monitor-invoke-journal.ts +131 -0
  99. package/.versions/2.0.1/.pi/harnesses/agent-hub/monitor-invoke.ts +92 -0
  100. package/.versions/2.0.1/.pi/harnesses/agent-hub/monitor-lifecycle.ts +13 -0
  101. package/.versions/2.0.1/.pi/harnesses/agent-hub/monitor-publisher.ts +59 -0
  102. package/.versions/2.0.1/.pi/harnesses/agent-hub/monitor-recovery.ts +3 -0
  103. package/.versions/2.0.1/.pi/harnesses/agent-hub/monitor-runtime.ts +3 -0
  104. package/.versions/2.0.1/.pi/harnesses/agent-hub/monitor-session-bridge.ts +266 -0
  105. package/.versions/2.0.1/.pi/harnesses/agent-hub/package.json +7 -0
  106. package/.versions/2.0.1/.pi/harnesses/agent-hub/peer-spawn-plan.ts +116 -0
  107. package/.versions/2.0.1/.pi/harnesses/agent-hub/policy/models.ts +126 -0
  108. package/.versions/2.0.1/.pi/harnesses/agent-hub/policy/roster.ts +79 -0
  109. package/.versions/2.0.1/.pi/harnesses/agent-hub/policy/work-mode.ts +118 -0
  110. package/.versions/2.0.1/.pi/harnesses/agent-hub/presentation.ts +48 -0
  111. package/.versions/2.0.1/.pi/harnesses/agent-hub/prompts/context.ts +46 -0
  112. package/.versions/2.0.1/.pi/harnesses/agent-hub/prompts/fragments.ts +115 -0
  113. package/.versions/2.0.1/.pi/harnesses/agent-hub/prompts/session-start.ts +88 -0
  114. package/.versions/2.0.1/.pi/harnesses/agent-hub/prompts/system-prompt.ts +110 -0
  115. package/.versions/2.0.1/.pi/harnesses/agent-hub/provider-semaphore.js +138 -0
  116. package/.versions/2.0.1/.pi/harnesses/agent-hub/research/controls.ts +75 -0
  117. package/.versions/2.0.1/.pi/harnesses/agent-hub/research/runtime.ts +184 -0
  118. package/.versions/2.0.1/.pi/harnesses/agent-hub/research/spawn-run.ts +146 -0
  119. package/.versions/2.0.1/.pi/harnesses/agent-hub/research-retention.js +34 -0
  120. package/.versions/2.0.1/.pi/harnesses/agent-hub/research-watchdog.ts +40 -0
  121. package/.versions/2.0.1/.pi/harnesses/agent-hub/return-contract.js +293 -0
  122. package/.versions/2.0.1/.pi/harnesses/agent-hub/return-extract.js +75 -0
  123. package/.versions/2.0.1/.pi/harnesses/agent-hub/review-findings.js +102 -0
  124. package/.versions/2.0.1/.pi/harnesses/agent-hub/run-budget.js +537 -0
  125. package/.versions/2.0.1/.pi/harnesses/agent-hub/run-namespace.js +87 -0
  126. package/.versions/2.0.1/.pi/harnesses/agent-hub/safety-routing.ts +22 -0
  127. package/.versions/2.0.1/.pi/harnesses/agent-hub/scope-gate.js +103 -0
  128. package/.versions/2.0.1/.pi/harnesses/agent-hub/session-health.js +110 -0
  129. package/.versions/2.0.1/.pi/harnesses/agent-hub/session-start.ts +42 -0
  130. package/.versions/2.0.1/.pi/harnesses/agent-hub/spawn.ts +388 -0
  131. package/.versions/2.0.1/.pi/harnesses/agent-hub/timeline.ts +54 -0
  132. package/.versions/2.0.1/.pi/harnesses/agent-hub/tools/action-executors.ts +146 -0
  133. package/.versions/2.0.1/.pi/harnesses/agent-hub/tools/coms-tools.ts +139 -0
  134. package/.versions/2.0.1/.pi/harnesses/agent-hub/tools/context.ts +132 -0
  135. package/.versions/2.0.1/.pi/harnesses/agent-hub/tools/dispatch-agent.ts +79 -0
  136. package/.versions/2.0.1/.pi/harnesses/agent-hub/tools/dispatch-execution.ts +200 -0
  137. package/.versions/2.0.1/.pi/harnesses/agent-hub/tools/execution-orchestration.ts +22 -0
  138. package/.versions/2.0.1/.pi/harnesses/agent-hub/tools/fleet-tools.ts +202 -0
  139. package/.versions/2.0.1/.pi/harnesses/agent-hub/tools/herdr-executors.ts +82 -0
  140. package/.versions/2.0.1/.pi/harnesses/agent-hub/tools/set-task-tier.ts +29 -0
  141. package/.versions/2.0.1/.pi/harnesses/agent-hub/tools/spawn-research.ts +62 -0
  142. package/.versions/2.0.1/.pi/harnesses/agent-hub/tools/team-adjust.ts +29 -0
  143. package/.versions/2.0.1/.pi/harnesses/agent-hub/tools/verification-contract.ts +77 -0
  144. package/.versions/2.0.1/.pi/harnesses/agent-hub/types.ts +60 -0
  145. package/.versions/2.0.1/.pi/harnesses/agent-hub/ui/context-budget.ts +86 -0
  146. package/.versions/2.0.1/.pi/harnesses/agent-hub/ui/detail-panel.ts +175 -0
  147. package/.versions/2.0.1/.pi/harnesses/agent-hub/ui/fleet-dashboard.ts +130 -0
  148. package/.versions/2.0.1/.pi/harnesses/agent-hub/ui/grid.ts +306 -0
  149. package/.versions/2.0.1/.pi/harnesses/agent-hub/ui/history-store.ts +137 -0
  150. package/.versions/2.0.1/.pi/harnesses/agent-hub/ui/history.ts +234 -0
  151. package/.versions/2.0.1/.pi/harnesses/agent-hub/ui/pool.ts +103 -0
  152. package/.versions/2.0.1/.pi/harnesses/agent-hub/ui/zoom.ts +204 -0
  153. package/.versions/2.0.1/.pi/harnesses/agent-hub/version.ts +42 -0
  154. package/.versions/2.0.1/.pi/harnesses/agent-hub/work-mode-controls.ts +56 -0
  155. package/.versions/2.0.1/.pi/harnesses/agent-hub/work-mode.ts +167 -0
  156. package/.versions/2.0.1/.pi/harnesses/ask-user-remote/README.md +53 -0
  157. package/.versions/2.0.1/.pi/harnesses/ask-user-remote/index.ts +532 -0
  158. package/.versions/2.0.1/.pi/harnesses/ask-user-remote/race-core.js +106 -0
  159. package/.versions/2.0.1/.pi/harnesses/coms/README.md +100 -0
  160. package/.versions/2.0.1/.pi/harnesses/coms/index.ts +276 -0
  161. package/.versions/2.0.1/.pi/harnesses/coms/package.json +7 -0
  162. package/.versions/2.0.1/.pi/harnesses/coms/version.ts +42 -0
  163. package/.versions/2.0.1/.pi/harnesses/damage-control-continue/README.md +124 -0
  164. package/.versions/2.0.1/.pi/harnesses/damage-control-continue/index.ts +536 -0
  165. package/.versions/2.0.1/.pi/harnesses/damage-control-continue/package.json +7 -0
  166. package/.versions/2.0.1/.pi/harnesses/damage-control-continue/version.ts +42 -0
  167. package/.versions/2.0.1/.pi/harnesses/lib/coms-core-io.ts +385 -0
  168. package/.versions/2.0.1/.pi/harnesses/lib/coms-core.ts +577 -0
  169. package/.versions/2.0.1/.pi/harnesses/lib/coms-registry-entry.ts +94 -0
  170. package/.versions/2.0.1/.pi/harnesses/lib/context-budget-child-prompt.ts +179 -0
  171. package/.versions/2.0.1/.pi/harnesses/lib/context-budget-hub-prompt.ts +114 -0
  172. package/.versions/2.0.1/.pi/harnesses/lib/context-budget-view.ts +107 -0
  173. package/.versions/2.0.1/.pi/harnesses/lib/context-budget.ts +114 -0
  174. package/.versions/2.0.1/.pi/harnesses/lib/damage-control-shared.ts +197 -0
  175. package/.versions/2.0.1/.pi/harnesses/lib/fixtures/context-budget-profiles.json +11 -0
  176. package/.versions/2.0.1/.pi/harnesses/lib/fixtures/hub-prompt-operator.legacy.txt +73 -0
  177. package/.versions/2.0.1/.pi/harnesses/lib/fixtures/hub-prompt-orchestrator.legacy.txt +73 -0
  178. package/.versions/2.0.1/.pi/harnesses/lib/fleet-dashboard-ops.ts +155 -0
  179. package/.versions/2.0.1/.pi/harnesses/lib/fleet-dashboard-view.ts +142 -0
  180. package/.versions/2.0.1/.pi/harnesses/lib/fleet-detail-view.ts +247 -0
  181. package/.versions/2.0.1/.pi/harnesses/lib/fleet-overlay.ts +26 -0
  182. package/.versions/2.0.1/.pi/harnesses/lib/fleet-panel.ts +34 -0
  183. package/.versions/2.0.1/.pi/harnesses/lib/fleet-read-model.ts +131 -0
  184. package/.versions/2.0.1/.pi/harnesses/lib/fleet-selection.ts +24 -0
  185. package/.versions/2.0.1/.pi/harnesses/lib/fleet-transcript-store.ts +244 -0
  186. package/.versions/2.0.1/.pi/harnesses/lib/herdr-client.ts +472 -0
  187. package/.versions/2.0.1/.pi/harnesses/lib/herdr-presence.ts +399 -0
  188. package/.versions/2.0.1/.pi/harnesses/lib/hermes-monitor-events.ts +136 -0
  189. package/.versions/2.0.1/.pi/harnesses/lib/hermes-monitor-herdr.ts +28 -0
  190. package/.versions/2.0.1/.pi/harnesses/lib/hermes-monitor-model.ts +18 -0
  191. package/.versions/2.0.1/.pi/harnesses/lib/hermes-monitor-registry.ts +6 -0
  192. package/.versions/2.0.1/.pi/harnesses/lib/hermes-monitor-socket.ts +163 -0
  193. package/.versions/2.0.1/.pi/harnesses/lib/hermes-monitor-store.ts +31 -0
  194. package/.versions/2.0.1/.pi/harnesses/lib/spawned-peers.js +190 -0
  195. package/.versions/2.0.1/.pi/harnesses/package-lock.json +2039 -0
  196. package/.versions/2.0.1/.pi/harnesses/package.json +10 -0
  197. package/.versions/2.0.1/.pi/prompts/af-build.md +24 -0
  198. package/.versions/2.0.1/.pi/prompts/af-code-simplify.md +22 -0
  199. package/.versions/2.0.1/.pi/prompts/af-plan.md +17 -0
  200. package/.versions/2.0.1/.pi/prompts/af-review.md +16 -0
  201. package/.versions/2.0.1/.pi/prompts/af-set-hermes-telegram.md +15 -0
  202. package/.versions/2.0.1/.pi/prompts/af-set-hermes-watchdog.md +6 -0
  203. package/.versions/2.0.1/.pi/prompts/af-ship.md +17 -0
  204. package/.versions/2.0.1/.pi/prompts/af-spec.md +15 -0
  205. package/.versions/2.0.1/.pi/prompts/af-test.md +19 -0
  206. package/.versions/2.0.1/.pi/skills/bowser/SKILL.md +145 -0
  207. package/.versions/2.0.1/.version +1 -0
  208. package/.versions/2.0.1/agents/architect.md +25 -0
  209. package/.versions/2.0.1/agents/bowser.md +28 -0
  210. package/.versions/2.0.1/agents/builder.md +56 -0
  211. package/.versions/2.0.1/agents/code-reviewer.md +210 -0
  212. package/.versions/2.0.1/agents/deep-researcher.md +33 -0
  213. package/.versions/2.0.1/agents/documenter.md +22 -0
  214. package/.versions/2.0.1/agents/orchestrator.md +23 -0
  215. package/.versions/2.0.1/agents/plan-reviewer.md +84 -0
  216. package/.versions/2.0.1/agents/planner.md +73 -0
  217. package/.versions/2.0.1/agents/releaser.md +25 -0
  218. package/.versions/2.0.1/agents/researcher.md +31 -0
  219. package/.versions/2.0.1/agents/security-auditor.md +168 -0
  220. package/.versions/2.0.1/agents/test-engineer.md +154 -0
  221. package/.versions/2.0.1/agents/web-debugger.md +44 -0
  222. package/.versions/2.0.1/agents/web-performance-auditor.md +194 -0
  223. package/.versions/2.0.1/bin/catalog/harness-runtime-closure.json +38 -0
  224. package/.versions/2.0.1/codex/CONDUCTOR.md +148 -0
  225. package/.versions/2.0.1/docs/ARCHITECTURE.md +407 -0
  226. package/.versions/2.0.1/docs/agent-fleet-setup.md +468 -0
  227. package/.versions/2.0.1/docs/claude-code-coms-bridge.md +128 -0
  228. package/.versions/2.0.1/docs/codex-remote-conductor.md +170 -0
  229. package/.versions/2.0.1/docs/coms-hermes-bridge.md +189 -0
  230. package/.versions/2.0.1/docs/getting-started.md +119 -0
  231. package/.versions/2.0.1/docs/npm-install.md +292 -0
  232. package/.versions/2.0.1/docs/pi-extensions.md +439 -0
  233. package/.versions/2.0.1/docs/pi-setup.md +74 -0
  234. package/.versions/2.0.1/docs/skill-anatomy.md +150 -0
  235. package/.versions/2.0.1/hermes/README.md +347 -0
  236. package/.versions/2.0.1/hermes/desktop-plugins/agent-fleet-herdr/plugin.js +1291 -0
  237. package/.versions/2.0.1/hermes/desktop-plugins/agent-fleet-herdr/presentation.js +672 -0
  238. package/.versions/2.0.1/hermes/desktop-plugins/agent-fleet-monitor/plugin.js +19 -0
  239. package/.versions/2.0.1/hermes/desktop-plugins/agent-fleet-monitor/state.js +10 -0
  240. package/.versions/2.0.1/hermes/gates/gate-o-capability.md +8 -0
  241. package/.versions/2.0.1/hermes/gates/gate-o-validator-fixtures.json +1 -0
  242. package/.versions/2.0.1/hermes/plugins/agent-fleet-herdr/dashboard/activity.py +770 -0
  243. package/.versions/2.0.1/hermes/plugins/agent-fleet-herdr/dashboard/coms_registry.py +134 -0
  244. package/.versions/2.0.1/hermes/plugins/agent-fleet-herdr/dashboard/coms_send.py +350 -0
  245. package/.versions/2.0.1/hermes/plugins/agent-fleet-herdr/dashboard/herdr_source.py +193 -0
  246. package/.versions/2.0.1/hermes/plugins/agent-fleet-herdr/dashboard/manifest.json +4 -0
  247. package/.versions/2.0.1/hermes/plugins/agent-fleet-herdr/dashboard/plugin_api.py +444 -0
  248. package/.versions/2.0.1/hermes/plugins/agent-fleet-herdr/dashboard/sessions.py +205 -0
  249. package/.versions/2.0.1/hermes/plugins/agent-fleet-herdr/dashboard/tasks.py +300 -0
  250. package/.versions/2.0.1/hermes/plugins/agent-fleet-herdr/dashboard/watch.py +819 -0
  251. package/.versions/2.0.1/hermes/plugins/agent-fleet-herdr/plugin.yaml +8 -0
  252. package/.versions/2.0.1/hermes/plugins/agent-fleet-monitor/dashboard/adapter.py +139 -0
  253. package/.versions/2.0.1/hermes/plugins/agent-fleet-monitor/dashboard/manifest.json +11 -0
  254. package/.versions/2.0.1/hermes/plugins/agent-fleet-monitor/dashboard/plugin_api.py +50 -0
  255. package/.versions/2.0.1/hermes/skills/hub-conductor/SKILL.md +84 -0
  256. package/.versions/2.0.1/hermes/skills/hub-liaison/SKILL.md +84 -0
  257. package/.versions/2.0.1/hermes/skills/hub-watchdog/SKILL.md +76 -0
  258. package/.versions/2.0.1/hermes/skills/hub-watchdog/manifest.json +1 -0
  259. package/.versions/2.0.1/hermes/skills/hub-watchdog/scripts/watchdog.py +249 -0
  260. package/.versions/2.0.1/hermes/skills/hub-watchdog/scripts/watchdog_actions.py +124 -0
  261. package/.versions/2.0.1/hermes/skills/hub-watchdog/scripts/watchdog_contract.py +76 -0
  262. package/.versions/2.0.1/hermes/skills/hub-watchdog/scripts/watchdog_delivery.py +10 -0
  263. package/.versions/2.0.1/hermes/skills/hub-watchdog/scripts/watchdog_engine.py +128 -0
  264. package/.versions/2.0.1/hermes/skills/hub-watchdog/scripts/watchdog_judgment.py +41 -0
  265. package/.versions/2.0.1/hermes/skills/hub-watchdog/scripts/watchdog_recovery.py +103 -0
  266. package/.versions/2.0.1/hermes/skills/hub-watchdog/scripts/watchdog_state.py +163 -0
  267. package/.versions/2.0.1/hermes/skills/hub-watchdog/scripts/watchdog_transport.py +138 -0
  268. package/.versions/2.0.1/hermes/watchdog-tests/__init__.py +0 -0
  269. package/.versions/2.0.1/hooks/coms-stop-hook.mjs +84 -0
  270. package/.versions/2.0.1/install-manifest.json +2830 -0
  271. package/.versions/2.0.1/justfile +286 -0
  272. package/.versions/2.0.1/manifest-meta.json +913 -0
  273. package/.versions/2.0.1/references/accessibility-checklist.md +160 -0
  274. package/.versions/2.0.1/references/definition-of-done.md +67 -0
  275. package/.versions/2.0.1/references/fleet-coordination-patterns.md +151 -0
  276. package/.versions/2.0.1/references/observability-checklist.md +91 -0
  277. package/.versions/2.0.1/references/orchestration-patterns.md +370 -0
  278. package/.versions/2.0.1/references/performance-checklist.md +153 -0
  279. package/.versions/2.0.1/references/prompting-patterns.md +380 -0
  280. package/.versions/2.0.1/references/security-checklist.md +179 -0
  281. package/.versions/2.0.1/references/testing-patterns.md +236 -0
  282. package/.versions/2.0.1/references/workflow-authoring.md +304 -0
  283. package/.versions/2.0.1/scripts/codex-conductor.ts +41 -0
  284. package/.versions/2.0.1/scripts/codex-remote-control.ts +167 -0
  285. package/.versions/2.0.1/scripts/coms-claude-bridge.ts +411 -0
  286. package/.versions/2.0.1/scripts/coms-cli.ts +484 -0
  287. package/.versions/2.0.1/scripts/coms-hermes-bridge.ts +413 -0
  288. package/.versions/2.0.1/scripts/fleet.ts +198 -0
  289. package/.versions/2.0.1/scripts/flow.ts +121 -0
  290. package/.versions/2.0.1/scripts/hermes-monitor-capability-runner.ts +25 -0
  291. package/.versions/2.0.1/scripts/hermes-monitor-scenario.ts +474 -0
  292. package/.versions/2.0.1/scripts/hermes-watchdog-capability-probe.ts +45 -0
  293. package/.versions/2.0.1/scripts/install-hermes-plugin.sh +180 -0
  294. package/.versions/2.0.1/scripts/lib/claude-bridge-core.ts +210 -0
  295. package/.versions/2.0.1/scripts/lib/codex-conductor.ts +88 -0
  296. package/.versions/2.0.1/scripts/lib/codex-remote-control.ts +480 -0
  297. package/.versions/2.0.1/scripts/lib/coms-envelope.ts +582 -0
  298. package/.versions/2.0.1/scripts/lib/fake-herdr-server.ts +88 -0
  299. package/.versions/2.0.1/scripts/lib/fleet-command.ts +270 -0
  300. package/.versions/2.0.1/scripts/lib/flow-command.ts +77 -0
  301. package/.versions/2.0.1/scripts/lib/flow-maintenance.ts +230 -0
  302. package/.versions/2.0.1/scripts/lib/herdr-layout.ts +281 -0
  303. package/.versions/2.0.1/scripts/lib/hermes-bridge-core.ts +241 -0
  304. package/.versions/2.0.1/scripts/lib/hermes-monitor-events.ts +1 -0
  305. package/.versions/2.0.1/scripts/lib/hermes-monitor-herdr.ts +2 -0
  306. package/.versions/2.0.1/scripts/lib/hermes-monitor-model.ts +3 -0
  307. package/.versions/2.0.1/scripts/lib/hermes-monitor-registry.ts +2 -0
  308. package/.versions/2.0.1/scripts/lib/hermes-monitor-socket.ts +2 -0
  309. package/.versions/2.0.1/scripts/lib/hermes-monitor-store.ts +2 -0
  310. package/.versions/2.0.1/scripts/lib/monitor-env.ts +146 -0
  311. package/.versions/2.0.1/scripts/lib/peer-launch.ts +318 -0
  312. package/.versions/2.0.1/scripts/lib/persona-banner.ts +62 -0
  313. package/.versions/2.0.1/scripts/lib/spawn-stagger.ts +101 -0
  314. package/.versions/2.0.1/scripts/lib/team-project.ts +213 -0
  315. package/.versions/2.0.1/scripts/lib/team-snapshot.ts +147 -0
  316. package/.versions/2.0.1/scripts/peer-banner.ts +40 -0
  317. package/.versions/2.0.1/scripts/peer-launch.ts +259 -0
  318. package/.versions/2.0.1/scripts/team-snapshot.ts +237 -0
  319. package/.versions/2.0.1/scripts/team-up.ts +406 -0
  320. package/.versions/2.0.1/scripts/workflows/lib/agent-phase.ts +118 -0
  321. package/.versions/2.0.1/scripts/workflows/lib/changes.ts +61 -0
  322. package/.versions/2.0.1/scripts/workflows/lib/env.ts +34 -0
  323. package/.versions/2.0.1/scripts/workflows/lib/envelopes.ts +141 -0
  324. package/.versions/2.0.1/scripts/workflows/lib/gates.ts +81 -0
  325. package/.versions/2.0.1/scripts/workflows/lib/git.ts +96 -0
  326. package/.versions/2.0.1/scripts/workflows/lib/permissions.ts +130 -0
  327. package/.versions/2.0.1/scripts/workflows/lib/personas.ts +44 -0
  328. package/.versions/2.0.1/scripts/workflows/lib/quality.ts +64 -0
  329. package/.versions/2.0.1/scripts/workflows/lib/run.ts +106 -0
  330. package/.versions/2.0.1/scripts/workflows/lib/trace.ts +34 -0
  331. package/.versions/2.0.1/scripts/workflows/tsconfig.json +22 -0
  332. package/.versions/2.0.1/scripts/workflows/wf-build-test.ts +61 -0
  333. package/.versions/2.0.1/scripts/workflows/wf-document.ts +50 -0
  334. package/.versions/2.0.1/scripts/workflows/wf-quality.ts +20 -0
  335. package/.versions/2.0.1/scripts/workflows/wf-scout.ts +38 -0
  336. package/.versions/2.0.1/skills/_internal/grilling.md +59 -0
  337. package/.versions/2.0.1/skills/browser-testing-with-devtools/SKILL.md +351 -0
  338. package/.versions/2.0.1/skills/code-review-and-quality/SKILL.md +381 -0
  339. package/.versions/2.0.1/skills/compound-learning/SKILL.md +137 -0
  340. package/.versions/2.0.1/skills/context-engineering/SKILL.md +291 -0
  341. package/.versions/2.0.1/skills/deprecation-and-migration/SKILL.md +206 -0
  342. package/.versions/2.0.1/skills/designing-agents/SKILL.md +394 -0
  343. package/.versions/2.0.1/skills/designing-agents/pi-harness-authoring.md +222 -0
  344. package/.versions/2.0.1/skills/drafting-workflows/SKILL.md +143 -0
  345. package/.versions/2.0.1/skills/drafting-workflows/scripts/make-workflow.ts +177 -0
  346. package/.versions/2.0.1/skills/frontend-ui-engineering/SKILL.md +328 -0
  347. package/.versions/2.0.1/skills/git-workflow-and-versioning/SKILL.md +316 -0
  348. package/.versions/2.0.1/skills/idea-refine/SKILL.md +182 -0
  349. package/.versions/2.0.1/skills/idea-refine/examples.md +238 -0
  350. package/.versions/2.0.1/skills/idea-refine/frameworks.md +99 -0
  351. package/.versions/2.0.1/skills/idea-refine/refinement-criteria.md +113 -0
  352. package/.versions/2.0.1/skills/idea-refine/scripts/idea-refine.sh +15 -0
  353. package/.versions/2.0.1/skills/incremental-implementation/SKILL.md +298 -0
  354. package/.versions/2.0.1/skills/interview-me/SKILL.md +226 -0
  355. package/.versions/2.0.1/skills/orchestration-verification/SKILL.md +181 -0
  356. package/.versions/2.0.1/skills/peer-coms/SKILL.md +90 -0
  357. package/.versions/2.0.1/skills/performance-optimization/SKILL.md +350 -0
  358. package/.versions/2.0.1/skills/planning-and-task-breakdown/SKILL.md +263 -0
  359. package/.versions/2.0.1/skills/security-and-hardening/SKILL.md +461 -0
  360. package/.versions/2.0.1/skills/spec-driven-development/SKILL.md +256 -0
  361. package/.versions/2.0.1/skills/using-agent-skills/SKILL.md +197 -0
  362. package/.versions/2.0.1/systemd/user/agent-fleet-codex-remote-control.service.in +23 -0
  363. package/.versions/2.0.1/vendor/agent-skills-upstream/LICENSE +21 -0
  364. package/.versions/2.0.1/vendor/agent-skills-upstream/README.md +11 -0
  365. package/.versions/2.0.1/vendor/agent-skills-upstream/skills/api-and-interface-design/SKILL.md +294 -0
  366. package/.versions/2.0.1/vendor/agent-skills-upstream/skills/browser-testing-with-devtools/SKILL.md +317 -0
  367. package/.versions/2.0.1/vendor/agent-skills-upstream/skills/ci-cd-and-automation/SKILL.md +390 -0
  368. package/.versions/2.0.1/vendor/agent-skills-upstream/skills/code-review-and-quality/SKILL.md +396 -0
  369. package/.versions/2.0.1/vendor/agent-skills-upstream/skills/code-simplification/SKILL.md +331 -0
  370. package/.versions/2.0.1/vendor/agent-skills-upstream/skills/context-engineering/SKILL.md +289 -0
  371. package/.versions/2.0.1/vendor/agent-skills-upstream/skills/debugging-and-error-recovery/SKILL.md +300 -0
  372. package/.versions/2.0.1/vendor/agent-skills-upstream/skills/deprecation-and-migration/SKILL.md +247 -0
  373. package/.versions/2.0.1/vendor/agent-skills-upstream/skills/documentation-and-adrs/SKILL.md +278 -0
  374. package/.versions/2.0.1/vendor/agent-skills-upstream/skills/doubt-driven-development/SKILL.md +243 -0
  375. package/.versions/2.0.1/vendor/agent-skills-upstream/skills/frontend-ui-engineering/SKILL.md +328 -0
  376. package/.versions/2.0.1/vendor/agent-skills-upstream/skills/git-workflow-and-versioning/SKILL.md +355 -0
  377. package/.versions/2.0.1/vendor/agent-skills-upstream/skills/idea-refine/SKILL.md +178 -0
  378. package/.versions/2.0.1/vendor/agent-skills-upstream/skills/idea-refine/examples.md +238 -0
  379. package/.versions/2.0.1/vendor/agent-skills-upstream/skills/idea-refine/frameworks.md +99 -0
  380. package/.versions/2.0.1/vendor/agent-skills-upstream/skills/idea-refine/refinement-criteria.md +113 -0
  381. package/.versions/2.0.1/vendor/agent-skills-upstream/skills/idea-refine/scripts/idea-refine.sh +15 -0
  382. package/.versions/2.0.1/vendor/agent-skills-upstream/skills/incremental-implementation/SKILL.md +249 -0
  383. package/.versions/2.0.1/vendor/agent-skills-upstream/skills/interview-me/SKILL.md +225 -0
  384. package/.versions/2.0.1/vendor/agent-skills-upstream/skills/observability-and-instrumentation/SKILL.md +203 -0
  385. package/.versions/2.0.1/vendor/agent-skills-upstream/skills/performance-optimization/SKILL.md +350 -0
  386. package/.versions/2.0.1/vendor/agent-skills-upstream/skills/planning-and-task-breakdown/SKILL.md +234 -0
  387. package/.versions/2.0.1/vendor/agent-skills-upstream/skills/security-and-hardening/SKILL.md +467 -0
  388. package/.versions/2.0.1/vendor/agent-skills-upstream/skills/shipping-and-launch/SKILL.md +310 -0
  389. package/.versions/2.0.1/vendor/agent-skills-upstream/skills/source-driven-development/SKILL.md +194 -0
  390. package/.versions/2.0.1/vendor/agent-skills-upstream/skills/spec-driven-development/SKILL.md +206 -0
  391. package/.versions/2.0.1/vendor/agent-skills-upstream/skills/test-driven-development/SKILL.md +383 -0
  392. package/.versions/2.0.1/vendor/agent-skills-upstream/skills/using-agent-skills/SKILL.md +191 -0
  393. package/CHANGELOG.md +7 -0
  394. package/README.md +21 -0
  395. package/agents/code-reviewer.md +1 -0
  396. package/agents/documenter.md +3 -0
  397. package/agents/planner.md +2 -0
  398. package/agents/researcher.md +2 -0
  399. package/docs/ARCHITECTURE.md +3 -0
  400. package/docs/getting-started.md +21 -0
  401. package/docs/workflows.md +136 -0
  402. package/install-manifest.json +86 -1
  403. package/justfile +14 -0
  404. package/manifest-meta.json +32 -1
  405. package/package.json +10 -3
  406. package/references/workflow-authoring.md +304 -0
  407. package/scripts/fleet.ts +13 -0
  408. package/scripts/flow.ts +121 -0
  409. package/scripts/lib/flow-command.ts +77 -0
  410. package/scripts/lib/flow-maintenance.ts +230 -0
  411. package/scripts/workflows/lib/agent-phase.ts +118 -0
  412. package/scripts/workflows/lib/changes.ts +61 -0
  413. package/scripts/workflows/lib/env.ts +34 -0
  414. package/scripts/workflows/lib/envelopes.ts +141 -0
  415. package/scripts/workflows/lib/gates.ts +81 -0
  416. package/scripts/workflows/lib/git.ts +96 -0
  417. package/scripts/workflows/lib/permissions.ts +130 -0
  418. package/scripts/workflows/lib/personas.ts +44 -0
  419. package/scripts/workflows/lib/quality.ts +64 -0
  420. package/scripts/workflows/lib/run.ts +106 -0
  421. package/scripts/workflows/lib/trace.ts +34 -0
  422. package/scripts/workflows/tsconfig.json +22 -0
  423. package/scripts/workflows/wf-build-test.ts +61 -0
  424. package/scripts/workflows/wf-document.ts +50 -0
  425. package/scripts/workflows/wf-quality.ts +20 -0
  426. package/scripts/workflows/wf-scout.ts +38 -0
  427. package/skills/drafting-workflows/SKILL.md +143 -0
  428. package/skills/drafting-workflows/scripts/make-workflow.ts +177 -0
@@ -0,0 +1,230 @@
1
+ import { spawn, spawnSync } from "node:child_process";
2
+ import { existsSync, readdirSync, readFileSync } from "node:fs";
3
+ import { createInterface } from "node:readline/promises";
4
+ import { resolve } from "node:path";
5
+ import { readFlowBranchMetadata, type FlowBranchMetadata } from "../workflows/lib/git.ts";
6
+ import type { FlowMaintenanceCommand } from "./flow-command.ts";
7
+
8
+ export interface FlowBranchInfo {
9
+ branch: string;
10
+ head: string;
11
+ timestamp: number;
12
+ metadata: FlowBranchMetadata;
13
+ runId?: string;
14
+ result: "accepted" | "rejected" | "unknown";
15
+ target?: string;
16
+ worktreePath?: string;
17
+ dirty: boolean;
18
+ ahead?: number;
19
+ behind?: number;
20
+ diffSummary?: string;
21
+ }
22
+
23
+ interface CommandResult { status: number | null; stdout: string; stderr: string; error?: Error; streamed?: boolean }
24
+ type CommandRunner = (command: string, args: string[], cwd: string) => CommandResult | Promise<CommandResult>;
25
+ export interface FlowMaintenanceOptions {
26
+ cwd?: string;
27
+ interactive?: boolean;
28
+ taskRunner?: CommandRunner;
29
+ taskPrompt?: (question: string) => Promise<string>;
30
+ writeOut?: (text: string) => void;
31
+ writeError?: (text: string) => void;
32
+ }
33
+
34
+ export class FlowMaintenanceError extends Error {
35
+ readonly exitCode: number;
36
+ constructor(message: string, exitCode = 3) { super(message); this.exitCode = exitCode; }
37
+ }
38
+
39
+ function run(command: string, args: string[], cwd: string): CommandResult {
40
+ const result = spawnSync(command, args, { cwd, encoding: "utf8" });
41
+ return { status: result.status, stdout: result.stdout ?? "", stderr: result.stderr ?? "", ...(result.error ? { error: result.error } : {}) };
42
+ }
43
+
44
+ function runTask(command: string, args: string[], cwd: string): Promise<CommandResult> {
45
+ return new Promise(resolveTask => {
46
+ const visible = !(command === "wt" && args[0] === "--version");
47
+ let stdout = "", stderr = "", spawnError: Error | undefined;
48
+ const child = spawn(command, args, { cwd, stdio: ["inherit", "pipe", "pipe"] });
49
+ child.stdout.on("data", chunk => { const text = chunk.toString(); stdout += text; if (visible) process.stdout.write(text); });
50
+ child.stderr.on("data", chunk => { const text = chunk.toString(); stderr += text; if (visible) process.stderr.write(text); });
51
+ child.on("error", error => { spawnError = error; });
52
+ child.on("close", status => resolveTask({ status, stdout, stderr, ...(spawnError ? { error: spawnError } : {}), streamed: visible }));
53
+ });
54
+ }
55
+
56
+ function git(cwd: string, args: string[]): string {
57
+ const result = run("git", args, cwd);
58
+ if (result.status !== 0) throw new FlowMaintenanceError((result.stderr || result.stdout || `git ${args.join(" ")} failed`).trim(), 1);
59
+ return result.stdout.trim();
60
+ }
61
+
62
+ function localBranchExists(cwd: string, branch: string): boolean {
63
+ return run("git", ["show-ref", "--verify", "--quiet", `refs/heads/${branch}`], cwd).status === 0;
64
+ }
65
+
66
+ function worktrees(cwd: string): Map<string, string> {
67
+ const output = git(cwd, ["worktree", "list", "--porcelain"]);
68
+ const result = new Map<string, string>();
69
+ let path: string | undefined;
70
+ for (const line of output.split("\n")) {
71
+ if (line.startsWith("worktree ")) path = line.slice("worktree ".length);
72
+ else if (line.startsWith("branch refs/heads/") && path) result.set(line.slice("branch refs/heads/".length), path);
73
+ else if (!line) path = undefined;
74
+ }
75
+ return result;
76
+ }
77
+
78
+ function inferRunId(branch: string, cwd: string): string | undefined {
79
+ const sessions = resolve(cwd, ".pi", "flow-sessions");
80
+ if (!existsSync(sessions)) return undefined;
81
+ return readdirSync(sessions, { withFileTypes: true })
82
+ .filter(entry => entry.isDirectory() && branch.endsWith(`-${entry.name}`))
83
+ .map(entry => entry.name)
84
+ .sort((a, b) => b.length - a.length || a.localeCompare(b))[0];
85
+ }
86
+
87
+ function traceResult(cwd: string, runId?: string): "accepted" | "rejected" | undefined {
88
+ if (!runId) return undefined;
89
+ try {
90
+ const lines = readFileSync(resolve(cwd, ".pi", "flow-sessions", runId, "trace.jsonl"), "utf8").trim().split("\n").filter(Boolean);
91
+ for (let index = lines.length - 1; index >= 0; index--) {
92
+ const event = JSON.parse(lines[index]) as { type?: string; status?: string };
93
+ if (event.type === "run_end" && (event.status === "accepted" || event.status === "rejected")) return event.status;
94
+ }
95
+ } catch {}
96
+ return undefined;
97
+ }
98
+
99
+ function dirtyWorktree(path: string | undefined): boolean {
100
+ if (!path) return false;
101
+ const result = run("git", ["status", "--porcelain", "--untracked-files=all"], path);
102
+ if (result.status !== 0) throw new FlowMaintenanceError(`Could not inspect flow worktree ${path}: ${(result.stderr || result.error?.message || "git status failed").trim()}`);
103
+ return result.stdout.trim() !== "";
104
+ }
105
+
106
+ export function listFlowBranches(cwd = process.cwd()): FlowBranchInfo[] {
107
+ const refs = git(cwd, ["for-each-ref", "--format=%(refname:short)%09%(objectname:short)%09%(committerdate:unix)", "refs/heads/flow/"]);
108
+ if (!refs) return [];
109
+ const paths = worktrees(cwd);
110
+ return refs.split("\n").filter(Boolean).map(line => {
111
+ const [branch, head, rawTimestamp] = line.split("\t");
112
+ const metadata = readFlowBranchMetadata(branch, cwd);
113
+ const runId = metadata.runId ?? inferRunId(branch, cwd);
114
+ const result = metadata.result ?? traceResult(cwd, runId) ?? "unknown";
115
+ const target = metadata.baseBranch;
116
+ const worktreePath = paths.get(branch);
117
+ let ahead: number | undefined, behind: number | undefined, diffSummary: string | undefined;
118
+ if (target && localBranchExists(cwd, target)) {
119
+ const counts = git(cwd, ["rev-list", "--left-right", "--count", `${target}...${branch}`]).split(/\s+/).map(Number);
120
+ behind = counts[0]; ahead = counts[1];
121
+ diffSummary = git(cwd, ["diff", "--shortstat", `${target}...${branch}`]) || "no file changes";
122
+ }
123
+ return {
124
+ branch, head, timestamp: Number(rawTimestamp) || 0, metadata,
125
+ ...(runId ? { runId } : {}), result, ...(target ? { target } : {}), ...(worktreePath ? { worktreePath } : {}),
126
+ dirty: dirtyWorktree(worktreePath), ...(ahead === undefined ? {} : { ahead }), ...(behind === undefined ? {} : { behind }), ...(diffSummary ? { diffSummary } : {}),
127
+ };
128
+ }).sort((a, b) => b.timestamp - a.timestamp || a.branch.localeCompare(b.branch));
129
+ }
130
+
131
+ export function renderFlowBranches(branches: FlowBranchInfo[]): string {
132
+ if (!branches.length) return "No local flow/* branches found.\n";
133
+ const rows = branches.map((info, index) => {
134
+ const relation = info.ahead === undefined ? "relation unknown" : `↑${info.ahead} ↓${info.behind ?? 0}`;
135
+ return ` ${index + 1}. ${info.branch} ${info.result} ${info.dirty ? "dirty" : "clean"} ${relation} target: ${info.target ?? "unknown"}`;
136
+ });
137
+ return `Flow branches:\n${rows.join("\n")}\n\nSelect with a number or full branch name.\n`;
138
+ }
139
+
140
+ export function selectFlowBranch(branches: FlowBranchInfo[], selector: string): FlowBranchInfo {
141
+ if (/^\d+$/.test(selector)) {
142
+ const index = Number(selector) - 1;
143
+ if (!Number.isSafeInteger(index) || index < 0 || index >= branches.length) throw new FlowMaintenanceError(`Flow branch number is out of range: ${selector}`, 2);
144
+ return branches[index];
145
+ }
146
+ const match = branches.find(info => info.branch === selector);
147
+ if (!match) throw new FlowMaintenanceError(`Flow branch was not found: ${selector}`, 2);
148
+ return match;
149
+ }
150
+
151
+ async function defaultPrompt(question: string): Promise<string> {
152
+ const prompt = createInterface({ input: process.stdin, output: process.stdout });
153
+ try { return (await prompt.question(question)).trim(); }
154
+ finally { prompt.close(); }
155
+ }
156
+
157
+ async function requireWorktrunk(cwd: string, taskRunner: CommandRunner): Promise<void> {
158
+ const result = await taskRunner("wt", ["--version"], cwd);
159
+ if (result.status !== 0) throw new FlowMaintenanceError(`Worktrunk is required for flow maintenance: ${(result.error?.message || result.stderr || "wt was not found").trim()}`);
160
+ }
161
+
162
+ function printTaskResult(result: CommandResult, out: (text: string) => void, error: (text: string) => void): void {
163
+ if (result.streamed) return;
164
+ if (result.stdout.trim()) out(`${result.stdout.trim()}\n`);
165
+ if (result.stderr.trim()) error(`${result.stderr.trim()}\n`);
166
+ }
167
+
168
+ function requireClean(info: FlowBranchInfo): void {
169
+ if (info.dirty) throw new FlowMaintenanceError(`Flow branch ${info.branch} has uncommitted changes; commit or stash them before maintenance.`);
170
+ }
171
+
172
+ async function selectedWorktree(info: FlowBranchInfo, cwd: string, taskRunner: CommandRunner): Promise<string> {
173
+ if (info.worktreePath) return info.worktreePath;
174
+ const switched = await taskRunner("wt", ["-C", cwd, "-y", "switch", info.branch, "--no-cd", "--format=json"], cwd);
175
+ if (switched.status !== 0) throw new FlowMaintenanceError((switched.stderr || switched.stdout || `Worktrunk could not create a worktree for ${info.branch}`).trim(), 1);
176
+ const path = worktrees(cwd).get(info.branch);
177
+ if (!path) throw new FlowMaintenanceError(`Worktrunk did not expose a worktree for ${info.branch}.`, 1);
178
+ return path;
179
+ }
180
+
181
+ export async function runFlowMaintenance(command: FlowMaintenanceCommand, options: FlowMaintenanceOptions = {}): Promise<number> {
182
+ const cwd = resolve(options.cwd ?? process.cwd());
183
+ const interactive = options.interactive ?? Boolean(process.stdin.isTTY && process.stdout.isTTY);
184
+ const taskRunner = options.taskRunner ?? runTask;
185
+ const ask = options.taskPrompt ?? defaultPrompt;
186
+ const out = options.writeOut ?? (text => process.stdout.write(text));
187
+ const error = options.writeError ?? (text => process.stderr.write(text));
188
+ const branches = listFlowBranches(cwd);
189
+ out(renderFlowBranches(branches));
190
+ if (!branches.length) return 0;
191
+
192
+ let selector = command.selector;
193
+ if (!selector) {
194
+ if (!interactive) return 0;
195
+ selector = await ask(`${command.action === "cleanup" ? "Clean up" : "Merge"} which flow branch? `);
196
+ if (!selector) return 0;
197
+ }
198
+ let info = selectFlowBranch(branches, selector);
199
+ if (!command.yes) {
200
+ if (!interactive) throw new FlowMaintenanceError("Confirmation requires an interactive terminal; rerun with --yes.");
201
+ const answer = (await ask(`${command.action === "cleanup" ? command.discard ? "Discard" : "Clean up" : "Squash-merge"} ${info.branch}? [y/N] `)).toLowerCase();
202
+ if (answer !== "y" && answer !== "yes") { out("Cancelled.\n"); return 0; }
203
+ }
204
+
205
+ const refreshed = listFlowBranches(cwd).find(candidate => candidate.branch === info.branch);
206
+ if (!refreshed) throw new FlowMaintenanceError(`Flow branch disappeared before ${command.action}: ${info.branch}`, 1);
207
+ info = refreshed;
208
+ requireClean(info);
209
+ if (command.action === "cleanup") {
210
+ await requireWorktrunk(cwd, taskRunner);
211
+ const args = ["-C", cwd, "-y", "remove", info.branch, "--foreground", "--format=json", ...(command.discard ? ["-D"] : [])];
212
+ const result = await taskRunner("wt", args, cwd);
213
+ printTaskResult(result, out, error);
214
+ if (result.status !== 0) throw new FlowMaintenanceError(`Worktrunk did not remove ${info.branch}. Use flow merge, or review before --discard.`, 1);
215
+ return 0;
216
+ }
217
+
218
+ if (info.result !== "accepted") throw new FlowMaintenanceError(`Flow branch ${info.branch} is ${info.result}; only accepted runs may be merged.`);
219
+ const target = command.target ?? info.target;
220
+ if (!target) throw new FlowMaintenanceError(`Flow branch ${info.branch} has no recorded source branch; rerun with --target <branch>.`);
221
+ if (target === info.branch) throw new FlowMaintenanceError("A flow branch cannot be merged into itself.", 2);
222
+ if (!localBranchExists(cwd, target)) throw new FlowMaintenanceError(`Merge target is not a local branch: ${target}`);
223
+ await requireWorktrunk(cwd, taskRunner);
224
+ const path = await selectedWorktree(info, cwd, taskRunner);
225
+ if (dirtyWorktree(path)) throw new FlowMaintenanceError(`Flow worktree ${path} became dirty before merge; merge was refused.`);
226
+ const result = await taskRunner("wt", ["-C", path, "-y", "merge", target, "--format=json"], path);
227
+ printTaskResult(result, out, error);
228
+ if (result.status !== 0) throw new FlowMaintenanceError(`Worktrunk could not merge ${info.branch} into ${target}.`, 1);
229
+ return 0;
230
+ }
@@ -0,0 +1,118 @@
1
+ import type { ChildProcess } from "node:child_process";
2
+ import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
3
+ import { resolve } from "node:path";
4
+
5
+ interface SpawnPiAgentOptions {
6
+ model: string; tools: string; thinking: string; systemPrompt?: string; noSkills?: boolean; noContextFiles?: boolean;
7
+ sessionFile: string; resume?: boolean; prompt: string; cwd?: string; extensions?: string[]; detached?: boolean;
8
+ signal?: AbortSignal; toolWatchdog?: { timeoutMs: number | null }; turnDeadlineMs?: number | null;
9
+ }
10
+ interface SpawnPiAgentResult { output: string; exitCode: number | null; assistantError?: string; spawnError?: string; stderr?: string }
11
+ interface SpawnCallbacks { onProcess?(process: ChildProcess): void; onUsage?(usage: { input?: number; output?: number; cacheRead?: number; cacheWrite?: number }): void }
12
+ type SpawnFallback = (options: SpawnPiAgentOptions, fallbackModel?: string, callbacks?: SpawnCallbacks, fallbackOptions?: { midRun?: boolean }) => Promise<SpawnPiAgentResult>;
13
+ const promptModulePath: string = "../../../.pi/harnesses/lib/context-budget-child-prompt.ts";
14
+ const contextModulePath: string = "../../../.pi/harnesses/agent-hub/context-window.js";
15
+ const spawnModulePath: string = "../../../.pi/harnesses/agent-hub/spawn.ts";
16
+ const { buildSpecialistContextManifest, nativeSpecialistSystemPrompt } = await import(promptModulePath) as {
17
+ buildSpecialistContextManifest(options: Record<string, unknown>): unknown;
18
+ nativeSpecialistSystemPrompt(options: Record<string, unknown>): string;
19
+ };
20
+ const { estimatePromptTokens, resolveContextWindow, shouldRecycleBeforeSpawn } = await import(contextModulePath) as {
21
+ estimatePromptTokens(text: string): number;
22
+ resolveContextWindow(model: string, options: { lookup?: AgentPhaseOptions["modelLookup"]; fallbackWindow?: number }): { window: number };
23
+ shouldRecycleBeforeSpawn(options: { priorTokens: number; promptTokens: number; window: number }): { message: string } | null;
24
+ };
25
+ const { spawnPiAgentWithModelFallback } = await import(spawnModulePath) as { spawnPiAgentWithModelFallback: SpawnFallback };
26
+ import { envelopePrompt, parseWithCorrections, type EnvelopeName } from "./envelopes.ts";
27
+ import { gateCorrectionPrompt, type Gate, type GateReport } from "./gates.ts";
28
+ import { enforce, snapshot, type PermissionPolicy } from "./permissions.ts";
29
+ import type { PersonaDefinition } from "./personas.ts";
30
+ import type { Run } from "./run.ts";
31
+
32
+ export type SpawnAgent = SpawnFallback;
33
+ export interface AgentPhaseOptions<T = unknown> {
34
+ run: Run; persona: PersonaDefinition; task: string; envelope: EnvelopeName; cwd?: string;
35
+ spawn?: SpawnAgent; modelLookup?: (provider: string, modelId: string) => unknown; contextWindow?: number;
36
+ toolWatchdogMs?: number; turnDeadlineMs?: number; rulesPaths?: string[]; docsPaths?: string[];
37
+ gates?: Gate<T>[]; gateRetries?: number; protectedGlobs?: string[]; permissionPolicy?: PermissionPolicy;
38
+ }
39
+
40
+ interface SessionMeta { contextTokens: number }
41
+ function readMeta(path: string): SessionMeta {
42
+ try { const value = JSON.parse(readFileSync(path, "utf8")); return { contextTokens: Number(value.contextTokens) || 0 }; } catch { return { contextTokens: 0 }; }
43
+ }
44
+
45
+ export async function runAgentPhase<T = unknown>(options: AgentPhaseOptions<T>): Promise<T> {
46
+ const cwd = options.cwd ?? process.cwd();
47
+ const agentKey = options.persona.name.toLowerCase();
48
+ const directory = resolve(options.run.trace.directory, agentKey);
49
+ mkdirSync(directory, { recursive: true });
50
+ const sessionFile = resolve(directory, "session.json");
51
+ const metaFile = resolve(directory, "session-meta.json");
52
+ let meta = readMeta(metaFile);
53
+ let runNumber = 0;
54
+ if (options.permissionPolicy === undefined && options.persona.writes === undefined) {
55
+ throw new Error(`Flow agent persona ${options.persona.name} has no writes policy; declare persona writes or pass an explicit permissionPolicy.`);
56
+ }
57
+ let permissionBaseline = snapshot(cwd);
58
+ const permissionPolicy: PermissionPolicy = {
59
+ ...(options.permissionPolicy ?? { writes: options.persona.writes }),
60
+ protectedGlobs: options.protectedGlobs ?? options.permissionPolicy?.protectedGlobs,
61
+ alwaysWritable: [...(options.permissionPolicy?.alwaysWritable ?? []), options.run.trace.directory],
62
+ };
63
+ const spawnAgent = options.spawn ?? spawnPiAgentWithModelFallback;
64
+ const manifest = buildSpecialistContextManifest({
65
+ personaName: options.persona.name, personaPath: options.persona.file, personaPrompt: options.persona.systemPrompt,
66
+ task: options.task, rulesPaths: options.rulesPaths ?? [], docsPaths: options.docsPaths ?? [],
67
+ hasAssertions: /\bA\d+\b/.test(options.task), hasScope: false, hasArtifacts: false, delegateRoles: [],
68
+ });
69
+
70
+ const invoke = async (prompt: string): Promise<string> => {
71
+ runNumber++;
72
+ const replacement = nativeSpecialistSystemPrompt({ manifest, userLanguage: "English", agentKey, runNumber });
73
+ const window = resolveContextWindow(options.persona.model!, { lookup: options.modelLookup, fallbackWindow: options.contextWindow ?? Number(process.env.AGENT_FLEET_CONTEXT_WINDOW ?? 0) });
74
+ let resume = existsSync(sessionFile);
75
+ const overflow = resume ? shouldRecycleBeforeSpawn({ priorTokens: meta.contextTokens, promptTokens: estimatePromptTokens(prompt) + estimatePromptTokens(replacement), window: window.window }) : null;
76
+ if (overflow) {
77
+ try { unlinkSync(sessionFile); } catch {}
78
+ meta = { contextTokens: 0 };
79
+ resume = false;
80
+ options.run.trace.write("log", { phase: options.persona.name, message: `session recycled before spawn — ${overflow.message}` });
81
+ }
82
+ let measuredTokens = meta.contextTokens;
83
+ const result = await spawnAgent({
84
+ model: options.persona.model!, tools: options.persona.tools, thinking: options.persona.thinking ?? "medium",
85
+ systemPrompt: replacement, noSkills: true, noContextFiles: true, sessionFile, resume, prompt, cwd,
86
+ extensions: [".pi/harnesses/damage-control-continue/index.ts"], detached: true, signal: options.run.signal,
87
+ toolWatchdog: { timeoutMs: options.toolWatchdogMs ?? 120_000 }, turnDeadlineMs: options.turnDeadlineMs ?? 1_200_000,
88
+ }, options.persona.fallbackModel, {
89
+ onProcess: process => options.run.registerProcess(process, options.persona.name),
90
+ onUsage: usage => {
91
+ measuredTokens = Math.max(measuredTokens, Number(usage.input ?? 0) + Number(usage.output ?? 0) + Number((usage as any).cacheRead ?? 0) + Number((usage as any).cacheWrite ?? 0));
92
+ },
93
+ }, { midRun: !/(^|,)(write|edit)(,|$)/.test(options.persona.tools) });
94
+ meta = { contextTokens: measuredTokens };
95
+ writeFileSync(metaFile, JSON.stringify(meta), "utf8");
96
+ const after = snapshot(cwd);
97
+ enforce(permissionBaseline, after, permissionPolicy);
98
+ permissionBaseline = after;
99
+ if (result.exitCode !== 0) throw new Error(`Persona ${options.persona.name} failed (exit ${result.exitCode ?? "unknown"}): ${result.assistantError || result.spawnError || result.stderr || "no diagnostic"}`);
100
+ return result.output;
101
+ };
102
+
103
+ const parse = (output: string) => parseWithCorrections<T>(options.envelope, output, prompt => invoke(prompt), (attempt, errors) => {
104
+ options.run.trace.write("error", { phase: options.persona.name, invalidEnvelope: true, attempt: attempt + 1, errors });
105
+ });
106
+ let report = await parse(await invoke(`${options.task}\n\n${envelopePrompt(options.envelope)}`));
107
+ const retries = options.gateRetries ?? 0;
108
+ for (let attempt = 0; ; attempt++) {
109
+ const gateReports: GateReport[] = [];
110
+ for (const gate of options.gates ?? []) gateReports.push(await gate(report, options.run));
111
+ for (const gateReport of gateReports) {
112
+ options.run.trace.write("gate_report", { phase: options.persona.name, gate: gateReport.gate, ok: gateReport.ok, checks: gateReport.checks });
113
+ }
114
+ if (gateReports.every(gate => gate.ok)) return report;
115
+ if (attempt >= retries) throw Object.assign(new Error(`Executable gates failed after ${attempt + 1} attempt(s): ${gateReports.flatMap(gate => gate.failures().map(check => `${gate.gate}/${check.item}: ${check.note}`)).join("; ")}`), { terminal: true });
116
+ report = await parse(await invoke(gateCorrectionPrompt(gateReports)));
117
+ }
118
+ }
@@ -0,0 +1,61 @@
1
+ import { spawnSync } from "node:child_process";
2
+ import type { Run } from "./run.ts";
3
+
4
+ export interface BaseRef { ref: string; diffBase: string; reason: string; scenario: "ahead" | "dirty" | "fallback" }
5
+ export interface ChangeSet { base: BaseRef; changedFiles: string[]; untrackedFiles: string[]; diff: string; hiddenLines: number }
6
+ export interface ChangesEnvelope {
7
+ status: "success";
8
+ summary: string;
9
+ artifacts: string[];
10
+ notes_for_next_agent: string;
11
+ changed_files: string[];
12
+ base: string;
13
+ reason: string;
14
+ }
15
+ function git(cwd: string, args: string[]): string {
16
+ const result = spawnSync("git", args, { cwd, encoding: "utf8" });
17
+ if (result.status !== 0) throw new Error((result.stderr || result.stdout || `git ${args.join(" ")} failed`).trim());
18
+ return result.stdout;
19
+ }
20
+ function lines(value: string): string[] { return value.split(/\r?\n/).map(line => line.trim()).filter(Boolean); }
21
+
22
+ export function resolveBase(ref: string, cwd = process.cwd()): BaseRef {
23
+ git(cwd, ["rev-parse", "--verify", ref]);
24
+ const ahead = Number(git(cwd, ["rev-list", "--count", `${ref}..HEAD`]).trim());
25
+ if (ahead > 0) return { ref, diffBase: ref, reason: `HEAD is ahead of \`${ref}\``, scenario: "ahead" };
26
+ const dirty = git(cwd, ["status", "--porcelain", "--untracked-files=all"]).trim().length > 0;
27
+ if (dirty) return { ref, diffBase: "HEAD", reason: "diffing the uncommitted working tree", scenario: "dirty" };
28
+ const fallback = git(cwd, ["rev-parse", "--verify", "HEAD~1"]).trim();
29
+ return { ref, diffBase: fallback, reason: "clean tree — falling back to the last commit (HEAD~1)", scenario: "fallback" };
30
+ }
31
+
32
+ export function capture(run: Run, params: { ref?: string; cwd?: string; maxDiffLines?: number } = {}): ChangeSet {
33
+ const cwd = params.cwd ?? run.trace.cwd;
34
+ const base = resolveBase(params.ref ?? "main", cwd);
35
+ const runtimePrefix = `.pi/flow-sessions/${run.trace.runId}/`;
36
+ const tracked = lines(git(cwd, ["diff", "--name-only", base.diffBase, "--"])).filter(path => !path.startsWith(runtimePrefix));
37
+ const untrackedFiles = lines(git(cwd, ["ls-files", "--others", "--exclude-standard"])).filter(path => !path.startsWith(runtimePrefix));
38
+ const changedFiles = [...new Set([...tracked, ...untrackedFiles])].sort();
39
+ let diff = git(cwd, ["diff", "--no-ext-diff", "--unified=3", base.diffBase, "--"]);
40
+ if (untrackedFiles.length) diff += `${diff && !diff.endsWith("\n") ? "\n" : ""}Untracked files:\n${untrackedFiles.map(path => `?? ${path}`).join("\n")}\n`;
41
+ const allLines = diff.split(/\r?\n/);
42
+ if (allLines.at(-1) === "") allLines.pop();
43
+ const max = params.maxDiffLines ?? 2000;
44
+ const hiddenLines = Math.max(0, allLines.length - max);
45
+ if (hiddenLines) diff = `${allLines.slice(0, max).join("\n")}\n... ${hiddenLines} diff lines hidden by maxDiffLines ...`;
46
+ else diff = allLines.join("\n");
47
+ run.trace.write("log", { phase: "changes", message: base.reason, base: base.diffBase, ref: base.ref, changedFiles, untrackedFiles, hiddenLines });
48
+ return { base, changedFiles, untrackedFiles, diff, hiddenLines };
49
+ }
50
+
51
+ export function asEnvelope(changes: ChangeSet, notes = ""): ChangesEnvelope {
52
+ return {
53
+ status: "success",
54
+ summary: `${changes.changedFiles.length} changed path(s) captured`,
55
+ artifacts: [],
56
+ notes_for_next_agent: [changes.diff, notes].filter(Boolean).join("\n\n"),
57
+ changed_files: changes.changedFiles,
58
+ base: changes.base.diffBase,
59
+ reason: changes.base.reason,
60
+ };
61
+ }
@@ -0,0 +1,34 @@
1
+ import { existsSync, readFileSync } from "node:fs";
2
+ import { resolve } from "node:path";
3
+
4
+ export function parseEnv(text: string): Record<string, string> {
5
+ const values: Record<string, string> = {};
6
+ for (const raw of text.split(/\r?\n/)) {
7
+ const line = raw.trim();
8
+ if (!line || line.startsWith("#")) continue;
9
+ const match = line.match(/^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/);
10
+ if (!match) continue;
11
+ let value = match[2].trim();
12
+ if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
13
+ const quote = value[0];
14
+ value = value.slice(1, -1);
15
+ if (quote === '"') value = value.replace(/\\n/g, "\n").replace(/\\r/g, "\r").replace(/\\t/g, "\t").replace(/\\"/g, '"').replace(/\\\\/g, "\\");
16
+ } else {
17
+ value = value.replace(/\s+#.*$/, "").trim();
18
+ }
19
+ values[match[1]] = value;
20
+ }
21
+ return values;
22
+ }
23
+
24
+ export function loadEnv(cwd = process.cwd(), env: NodeJS.ProcessEnv = process.env): Record<string, string> {
25
+ const file = resolve(cwd, ".env");
26
+ if (!existsSync(file)) return {};
27
+ const loaded: Record<string, string> = {};
28
+ for (const [key, value] of Object.entries(parseEnv(readFileSync(file, "utf8")))) {
29
+ if (env[key] !== undefined) continue;
30
+ env[key] = value;
31
+ loaded[key] = value;
32
+ }
33
+ return loaded;
34
+ }
@@ -0,0 +1,141 @@
1
+ import { Type, type Static, type TSchema } from "@sinclair/typebox";
2
+ import { Value } from "@sinclair/typebox/value";
3
+ const returnContractPath: string = "../../../.pi/harnesses/agent-hub/return-contract.js";
4
+ const { parseStructuredReturn } = await import(returnContractPath) as { parseStructuredReturn(text: string): Record<string, unknown> | null };
5
+ const StringArray = Type.Array(Type.String());
6
+ const EnvelopeBase = Type.Object({
7
+ status: Type.Union([Type.Literal("success"), Type.Literal("fail")]),
8
+ summary: Type.String(),
9
+ artifacts: StringArray,
10
+ notes_for_next_agent: Type.String(),
11
+ });
12
+ export const PlanEnvelope = Type.Intersect([EnvelopeBase, Type.Object({ commit_message: Type.String() })]);
13
+ export const BuildEnvelope = Type.Intersect([EnvelopeBase, Type.Object({ changed_files: StringArray, commit_message: Type.String() })]);
14
+ export const ReviewEnvelope = Type.Intersect([EnvelopeBase, Type.Object({
15
+ approved: Type.Boolean(), assertions_proven: StringArray, assertions_unproven: StringArray,
16
+ assertions_failed: StringArray, open_risks: StringArray, requires_user_decision: StringArray,
17
+ })]);
18
+ export const ScoutEnvelope = Type.Intersect([EnvelopeBase, Type.Object({ findings: StringArray })]);
19
+ export const DocumentEnvelope = Type.Intersect([EnvelopeBase, Type.Object({ document_path: Type.String(), documented_files: StringArray, commit_message: Type.String() })]);
20
+
21
+ export const ENVELOPES = { plan: PlanEnvelope, build: BuildEnvelope, review: ReviewEnvelope, scout: ScoutEnvelope, document: DocumentEnvelope } as const;
22
+ export type EnvelopeName = keyof typeof ENVELOPES;
23
+ export type ScoutReport = Static<typeof ScoutEnvelope>;
24
+ export const JSON_FIX_ATTEMPTS = 2;
25
+
26
+ export const ENVELOPE_EXAMPLES: Record<EnvelopeName, Record<string, unknown>> = {
27
+ plan: { status: "success", summary: "Plan ready", artifacts: [], notes_for_next_agent: "", commit_message: "docs: add plan" },
28
+ build: { status: "success", summary: "Build complete", artifacts: [], notes_for_next_agent: "", changed_files: ["src/app.ts"], commit_message: "feat: build" },
29
+ review: { status: "success", summary: "Review clean", artifacts: [], notes_for_next_agent: "", approved: true, assertions_proven: [], assertions_unproven: [], assertions_failed: [], open_risks: [], requires_user_decision: [] },
30
+ scout: { status: "success", summary: "Scout complete", artifacts: [], notes_for_next_agent: "", findings: ["X lives in src/x.ts"] },
31
+ document: { status: "success", summary: "Docs complete", artifacts: [], notes_for_next_agent: "", document_path: "docs/x.md", documented_files: ["src/x.ts"], commit_message: "docs: explain x" },
32
+ };
33
+
34
+ export function envelopePrompt(name: EnvelopeName): string {
35
+ return `Finish by emitting ONLY your Report JSON with exactly this shape:\n${JSON.stringify(ENVELOPE_EXAMPLES[name], null, 2)}`;
36
+ }
37
+
38
+ function reportJsonCandidates(text: string): unknown[] {
39
+ const candidates: unknown[] = [];
40
+ for (let start = text.indexOf("{"); start >= 0; start = text.indexOf("{", start + 1)) {
41
+ let depth = 0, inString = false, escaped = false;
42
+ for (let end = start; end < text.length; end++) {
43
+ const char = text[end];
44
+ if (inString) {
45
+ if (escaped) escaped = false;
46
+ else if (char === "\\") escaped = true;
47
+ else if (char === '"') inString = false;
48
+ continue;
49
+ }
50
+ if (char === '"') { inString = true; continue; }
51
+ if (char === "{") { depth++; continue; }
52
+ if (char !== "}" || --depth !== 0) continue;
53
+ try { candidates.push(JSON.parse(text.slice(start, end + 1))); } catch {}
54
+ break;
55
+ }
56
+ }
57
+ return candidates;
58
+ }
59
+
60
+ function explicitlyParsedHubFields(text: string, parsed: Record<string, unknown>): Record<string, unknown> {
61
+ const candidate: Record<string, unknown> = {};
62
+ for (const [field, value] of Object.entries(parsed)) {
63
+ const label = field.replaceAll("_", "[_ -]");
64
+ const declared = new RegExp(`(?:^|\\n)\\s*(?:#{1,6}\\s+)?${label}\\s*:`, "i").test(text)
65
+ || (Array.isArray(value) && value.length > 0);
66
+ if (declared) candidate[field] = value;
67
+ }
68
+ return candidate;
69
+ }
70
+
71
+ const BASE_FIELDS = ["status", "summary", "artifacts", "notes_for_next_agent"];
72
+ const ENVELOPE_FIELDS: Record<EnvelopeName, string[]> = {
73
+ plan: [...BASE_FIELDS, "commit_message"],
74
+ build: [...BASE_FIELDS, "changed_files", "commit_message"],
75
+ review: [...BASE_FIELDS, "approved", "assertions_proven", "assertions_unproven", "assertions_failed", "open_risks", "requires_user_decision"],
76
+ scout: [...BASE_FIELDS, "findings"],
77
+ document: [...BASE_FIELDS, "document_path", "documented_files", "commit_message"],
78
+ };
79
+
80
+ export interface EnvelopeValidation<T = unknown> { ok: boolean; value?: T; errors: string[] }
81
+
82
+ function schemaErrors(name: EnvelopeName, candidate: unknown): string[] {
83
+ if (!candidate || typeof candidate !== "object" || Array.isArray(candidate)) return ["response: expected one complete Report JSON object"];
84
+ const schema: TSchema = ENVELOPES[name];
85
+ const typeErrors = [...Value.Errors(schema, candidate)];
86
+ const specificErrors = typeErrors.filter(error => error.path);
87
+ const errors = [...new Set((specificErrors.length ? specificErrors : typeErrors).map(error => {
88
+ const field = error.path.replace(/^\//, "").replaceAll("/", ".") || "response";
89
+ return error.type === 45 || /required/i.test(error.message) ? `missing required field: ${field}` : `${field}: ${error.message}`;
90
+ }))];
91
+ const allowed = new Set(ENVELOPE_FIELDS[name]);
92
+ for (const field of Object.keys(candidate)) if (!allowed.has(field)) errors.push(`${field}: unexpected field for ${name} envelope`);
93
+ return errors;
94
+ }
95
+
96
+ function selectCandidate(name: EnvelopeName, output: string, hubParsed: Record<string, unknown> | null): unknown {
97
+ const jsonCandidates = reportJsonCandidates(output).filter(candidate => candidate && typeof candidate === "object" && !Array.isArray(candidate));
98
+ for (let index = jsonCandidates.length - 1; index >= 0; index--) {
99
+ if (schemaErrors(name, jsonCandidates[index]).length === 0) return jsonCandidates[index];
100
+ }
101
+ const hubCandidate = hubParsed ? explicitlyParsedHubFields(output, hubParsed) : null;
102
+ const candidates = hubCandidate && Object.keys(hubCandidate).length > 0 ? [...jsonCandidates, hubCandidate] : jsonCandidates;
103
+ const expected = new Set(ENVELOPE_FIELDS[name]);
104
+ return candidates.reduce<unknown>((best, candidate) => {
105
+ if (!best) return candidate;
106
+ const score = Object.keys(candidate as object).filter(field => expected.has(field)).length;
107
+ const bestScore = Object.keys(best as object).filter(field => expected.has(field)).length;
108
+ return score >= bestScore ? candidate : best;
109
+ }, null);
110
+ }
111
+
112
+ export function validateEnvelope<T = unknown>(name: EnvelopeName, output: string): EnvelopeValidation<T> {
113
+ // The shared hub parser is deliberately the first parser. Its normalized result is
114
+ // only an input to selection: required flow fields must still exist in the emitted
115
+ // object and pass the exact TypeBox envelope below.
116
+ const hubParsed = parseStructuredReturn(output);
117
+ const candidate = selectCandidate(name, output, hubParsed);
118
+ if (!candidate || typeof candidate !== "object" || Array.isArray(candidate)) return { ok: false, errors: ["response: expected one complete Report JSON object"] };
119
+ const errors = schemaErrors(name, candidate);
120
+ if (errors.length) return { ok: false, errors };
121
+ const value = candidate as T;
122
+ if ((value as { status: string }).status === "fail") return { ok: false, errors: [`status: agent declared fail${(value as any).summary ? ` — ${(value as any).summary}` : ""}`] };
123
+ return { ok: true, value, errors: [] };
124
+ }
125
+
126
+ export function correctionPrompt(errors: string[]): string {
127
+ return `Your previous response failed validation:\n${errors.map(error => `- ${error}`).join("\n")}\nFix these problems, then re-emit ONLY your Report JSON.`;
128
+ }
129
+
130
+ export async function parseWithCorrections<T>(name: EnvelopeName, initialOutput: string, correct: (prompt: string, attempt: number) => Promise<string>, onInvalid?: (attempt: number, errors: string[]) => void): Promise<T> {
131
+ let output = initialOutput;
132
+ for (let attempt = 0; attempt <= JSON_FIX_ATTEMPTS; attempt++) {
133
+ const result = validateEnvelope<T>(name, output);
134
+ if (result.ok) return result.value!;
135
+ onInvalid?.(attempt, result.errors);
136
+ if (result.errors.some(error => error.startsWith("status: agent declared fail"))) throw Object.assign(new Error(result.errors[0]), { terminal: true });
137
+ if (attempt === JSON_FIX_ATTEMPTS) throw Object.assign(new Error(`${name} envelope invalid after ${attempt + 1} attempts: ${result.errors.join("; ")}`), { terminal: true });
138
+ output = await correct(correctionPrompt(result.errors), attempt + 1);
139
+ }
140
+ throw new Error(`${name} envelope validation exhausted`);
141
+ }