@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,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
+ }
@@ -0,0 +1,81 @@
1
+ import { statSync, readFileSync } from "node:fs";
2
+ import { isAbsolute, resolve } from "node:path";
3
+ import type { Run } from "./run.ts";
4
+ import { executeQuality } from "./quality.ts";
5
+
6
+ export interface GateCheck { item: string; ok: boolean; note: string }
7
+ export class GateReport {
8
+ readonly gate: string;
9
+ readonly checks: GateCheck[] = [];
10
+ constructor(gate: string) { this.gate = gate; }
11
+ check(item: string, ok: boolean, note: string): this { this.checks.push({ item, ok, note }); return this; }
12
+ get ok(): boolean { return this.checks.length > 0 && this.checks.every(check => check.ok); }
13
+ failures(): GateCheck[] { return this.checks.filter(check => !check.ok); }
14
+ }
15
+
16
+ export type Gate<T = any> = (envelope: T, run: Run) => GateReport | Promise<GateReport>;
17
+
18
+ function artifactPath(path: string, run: Run): string { return isAbsolute(path) ? path : resolve(run.trace.cwd, path); }
19
+
20
+ export const artifactsExist: Gate<{ artifacts?: string[] }> = (envelope, run) => {
21
+ const report = new GateReport("artifactsExist");
22
+ for (const item of envelope.artifacts ?? []) {
23
+ try { const stat = statSync(artifactPath(item, run)); report.check(item, true, `${stat.size} bytes`); }
24
+ catch { report.check(item, false, "declared artifact does not exist"); }
25
+ }
26
+ return envelope.artifacts?.length ? report : report.check("artifacts", true, "no artifacts declared");
27
+ };
28
+
29
+ export const filesNonEmpty: Gate<{ artifacts?: string[] }> = (envelope, run) => {
30
+ const report = new GateReport("filesNonEmpty");
31
+ for (const item of envelope.artifacts ?? []) {
32
+ try { const size = statSync(artifactPath(item, run)).size; report.check(item, size > 0, `${size} bytes`); }
33
+ catch { report.check(item, false, "file cannot be read"); }
34
+ }
35
+ return envelope.artifacts?.length ? report : report.check("artifacts", true, "no artifacts declared");
36
+ };
37
+
38
+ export const jsonParses: Gate<{ artifacts?: string[] }> = (envelope, run) => {
39
+ const report = new GateReport("jsonParses");
40
+ const items = (envelope.artifacts ?? []).filter(item => item.toLowerCase().endsWith(".json"));
41
+ for (const item of items) {
42
+ try { JSON.parse(readFileSync(artifactPath(item, run), "utf8")); report.check(item, true, "JSON.parse succeeded"); }
43
+ catch (error) { report.check(item, false, error instanceof Error ? error.message : String(error)); }
44
+ }
45
+ return items.length ? report : report.check("json artifacts", true, "no JSON artifacts declared");
46
+ };
47
+
48
+ export const diffMatchesClaims: Gate<{ changed_files?: string[] }> = (envelope, run) => {
49
+ const report = new GateReport("diffMatchesClaims");
50
+ for (const item of envelope.changed_files ?? []) {
51
+ try { const stat = statSync(artifactPath(item, run)); report.check(item, true, `${stat.size} bytes on disk`); }
52
+ catch { report.check(item, false, "claimed changed file does not exist"); }
53
+ }
54
+ return envelope.changed_files?.length ? report : report.check("changed_files", true, "no changed files claimed");
55
+ };
56
+
57
+ export function testsPass(argv: string[], options: { cwd?: string; timeoutSeconds?: number } = {}): Gate {
58
+ return async (_envelope, run) => {
59
+ const logPath = resolve(run.trace.directory, `gate-tests-${Date.now()}.log`);
60
+ const result = await executeQuality(argv, { cwd: options.cwd ?? run.trace.cwd, logPath, timeoutSeconds: options.timeoutSeconds, signal: run.signal });
61
+ const evidence = result.passed ? `exit 0; ${logPath}` : `${(result.stderr || result.stdout).slice(-4000)}\n${logPath}`;
62
+ return new GateReport("testsPass").check(argv.join(" "), result.passed, evidence);
63
+ };
64
+ }
65
+
66
+ export const verdictConsistent: Gate<{ approved?: boolean; assertions_failed?: unknown[]; assertions_unproven?: unknown[]; open_risks?: unknown[]; requires_user_decision?: unknown[] }> = envelope => {
67
+ const report = new GateReport("verdictConsistent");
68
+ const failed = envelope.assertions_failed ?? [];
69
+ const unproven = envelope.assertions_unproven ?? [];
70
+ const decisions = envelope.requires_user_decision ?? [];
71
+ const problems = [...failed, ...unproven, ...(envelope.open_risks ?? []), ...decisions];
72
+ report.check("approved vs failed assertions", !envelope.approved || failed.length === 0, envelope.approved && failed.length ? "approved verdict has blocking failed assertions" : "consistent");
73
+ report.check("approved vs unresolved work", !envelope.approved || (unproven.length === 0 && decisions.length === 0), envelope.approved && (unproven.length || decisions.length) ? "approved verdict has unresolved assertions or decisions" : "consistent");
74
+ report.check("rejection names a problem", envelope.approved !== false || problems.length > 0, envelope.approved === false && problems.length === 0 ? "rejected verdict names no problem" : "consistent");
75
+ return report;
76
+ };
77
+
78
+ export function gateCorrectionPrompt(reports: GateReport[]): string {
79
+ const failures = reports.flatMap(report => report.failures().map(check => `- ${report.gate} / ${check.item}: ${check.note}`));
80
+ return `Your previous work failed executable gates:\n${failures.join("\n")}\nCorrect the work in this same session, then re-emit ONLY your Report JSON.`;
81
+ }
@@ -0,0 +1,96 @@
1
+ import { spawnSync } from "node:child_process";
2
+ import { changedPaths, permitted, rollBack, snapshot, type PermissionPolicy, type PermissionSnapshot } from "./permissions.ts";
3
+
4
+ export class StartRefusedError extends Error {
5
+ readonly exitCode = 3;
6
+ }
7
+ export class GitOperationError extends Error {}
8
+
9
+ export interface FlowBranchMetadata {
10
+ branch: string;
11
+ flowName?: string;
12
+ runId?: string;
13
+ baseBranch?: string;
14
+ baseCommit?: string;
15
+ result?: "accepted" | "rejected";
16
+ }
17
+
18
+ function git(cwd: string, args: string[]): string {
19
+ const result = spawnSync("git", args, { cwd, encoding: "utf8" });
20
+ if (result.status !== 0) throw new GitOperationError((result.stderr || result.stdout || `git ${args.join(" ")} failed`).trim());
21
+ return result.stdout.trim();
22
+ }
23
+ function asStartRefusal(action: () => string): string {
24
+ try { return action(); }
25
+ catch (error) { throw new StartRefusedError(error instanceof Error ? error.message : String(error)); }
26
+ }
27
+
28
+ export function isClean(cwd = process.cwd()): boolean {
29
+ return asStartRefusal(() => git(cwd, ["status", "--porcelain", "--untracked-files=all"])) === "";
30
+ }
31
+
32
+ export function requireCleanTree(cwd = process.cwd(), allowDirty = false): void {
33
+ if (!allowDirty && !isClean(cwd)) throw new StartRefusedError("Flow start refused: working tree is dirty; commit/stash it or pass --allow-dirty.");
34
+ }
35
+
36
+ export function flowBranchName(name: string, runId: string): string {
37
+ return `flow/${name}-${runId}`;
38
+ }
39
+
40
+ function configKey(branch: string, name: string): string { return `branch.${branch}.agentFleet${name}`; }
41
+ function optionalGit(cwd: string, args: string[]): string | undefined {
42
+ try { return git(cwd, args); } catch { return undefined; }
43
+ }
44
+ function writeBranchConfig(cwd: string, branch: string, name: string, value: string): void {
45
+ git(cwd, ["config", "--local", "--replace-all", configKey(branch, name), value]);
46
+ }
47
+
48
+ export function readFlowBranchMetadata(branch: string, cwd = process.cwd()): FlowBranchMetadata {
49
+ const value = (name: string) => optionalGit(cwd, ["config", "--local", "--get", configKey(branch, name)]);
50
+ const flowName = value("FlowName"), runId = value("RunId"), baseBranch = value("BaseBranch"), baseCommit = value("BaseCommit"), result = value("Result");
51
+ return {
52
+ branch,
53
+ ...(flowName ? { flowName } : {}), ...(runId ? { runId } : {}), ...(baseBranch ? { baseBranch } : {}), ...(baseCommit ? { baseCommit } : {}),
54
+ ...(result === "accepted" || result === "rejected" ? { result } : {}),
55
+ };
56
+ }
57
+
58
+ export function recordFlowResult(branch: string, result: "accepted" | "rejected", cwd = process.cwd()): void {
59
+ writeBranchConfig(cwd, branch, "Result", result);
60
+ }
61
+
62
+ export function createFlowBranch(name: string, runId: string, cwd = process.cwd()): string {
63
+ const branch = flowBranchName(name, runId);
64
+ const baseBranch = optionalGit(cwd, ["branch", "--show-current"]);
65
+ const baseCommit = asStartRefusal(() => git(cwd, ["rev-parse", "HEAD"]));
66
+ asStartRefusal(() => git(cwd, ["switch", "-c", branch]));
67
+ try {
68
+ writeBranchConfig(cwd, branch, "FlowName", name);
69
+ writeBranchConfig(cwd, branch, "RunId", runId);
70
+ writeBranchConfig(cwd, branch, "BaseCommit", baseCommit);
71
+ if (baseBranch) writeBranchConfig(cwd, branch, "BaseBranch", baseBranch);
72
+ } catch (error) {
73
+ throw new GitOperationError(`Flow branch was created but its metadata could not be recorded: ${error instanceof Error ? error.message : String(error)}`);
74
+ }
75
+ return branch;
76
+ }
77
+
78
+ export function commitAll(message: string, cwd: string, baseline: PermissionSnapshot, policy: PermissionPolicy = {}): string | null {
79
+ let after = snapshot(cwd);
80
+ const changed = changedPaths(baseline, after);
81
+ const preDirtyChanged = changed.filter(path => baseline.paths.has(path));
82
+ if (preDirtyChanged.length) {
83
+ rollBack(baseline, preDirtyChanged);
84
+ after = snapshot(cwd);
85
+ }
86
+ const introduced = changedPaths(baseline, after).filter(path => !baseline.paths.has(path));
87
+ const violations = introduced.filter(path => !permitted(path, policy, cwd));
88
+ if (violations.length) {
89
+ rollBack(baseline, violations);
90
+ throw new GitOperationError(`Flow introduced paths outside the commit policy: ${violations.join(", ")}`);
91
+ }
92
+ if (!introduced.length) return null;
93
+ git(cwd, ["add", "--", ...introduced]);
94
+ git(cwd, ["commit", "--only", "-m", message, "--", ...introduced]);
95
+ return git(cwd, ["rev-parse", "HEAD"]);
96
+ }