@chankov/agent-fleet 0.0.4 → 0.0.5

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 (321) hide show
  1. package/.claude/commands/set-hermes-telegram.md +15 -0
  2. package/.opencode/commands/af-set-hermes-telegram.md +15 -0
  3. package/.pi/agents/dispatch-policy.yaml +1 -1
  4. package/.pi/agents/peers.yaml +4 -4
  5. package/.pi/extensions/chrome-devtools-mcp/README.md +1 -1
  6. package/.pi/extensions/mcp-bridge/README.md +1 -1
  7. package/.pi/harnesses/agent-hub/README.md +26 -26
  8. package/.pi/harnesses/agent-hub/index.ts +6 -6
  9. package/.pi/harnesses/agent-hub/monitor-lifecycle.ts +1 -1
  10. package/.pi/harnesses/agent-hub/monitor-publisher.ts +3 -3
  11. package/.pi/harnesses/agent-hub/monitor-session-bridge.ts +1 -1
  12. package/.pi/harnesses/agent-hub/package.json +1 -1
  13. package/.pi/harnesses/ask-user-remote/README.md +1 -0
  14. package/.pi/harnesses/ask-user-remote/index.ts +36 -8
  15. package/.pi/harnesses/coms/README.md +5 -5
  16. package/.pi/harnesses/coms/package.json +1 -1
  17. package/.pi/harnesses/damage-control-continue/README.md +7 -7
  18. package/.pi/harnesses/damage-control-continue/package.json +1 -1
  19. package/.pi/harnesses/lib/hermes-monitor-herdr.ts +28 -0
  20. package/.pi/harnesses/lib/hermes-monitor-model.ts +9 -0
  21. package/.pi/harnesses/lib/hermes-monitor-registry.ts +6 -0
  22. package/.pi/harnesses/lib/hermes-monitor-socket.ts +118 -0
  23. package/.pi/harnesses/lib/hermes-monitor-store.ts +31 -0
  24. package/.pi/prompts/set-hermes-telegram.md +15 -0
  25. package/.versions/0.0.5/.claude/commands/build.md +44 -0
  26. package/.versions/0.0.5/.claude/commands/code-simplify.md +22 -0
  27. package/.versions/0.0.5/.claude/commands/design-agent.md +14 -0
  28. package/.versions/0.0.5/.claude/commands/doctor-agent-fleet.md +17 -0
  29. package/.versions/0.0.5/.claude/commands/orchestrate.md +112 -0
  30. package/.versions/0.0.5/.claude/commands/plan.md +16 -0
  31. package/.versions/0.0.5/.claude/commands/prime.md +22 -0
  32. package/.versions/0.0.5/.claude/commands/review.md +16 -0
  33. package/.versions/0.0.5/.claude/commands/set-hermes-telegram.md +15 -0
  34. package/.versions/0.0.5/.claude/commands/setup-agent-fleet.md +25 -0
  35. package/.versions/0.0.5/.claude/commands/ship.md +72 -0
  36. package/.versions/0.0.5/.claude/commands/spec.md +15 -0
  37. package/.versions/0.0.5/.claude/commands/test.md +19 -0
  38. package/.versions/0.0.5/.claude/commands/webperf.md +32 -0
  39. package/.versions/0.0.5/.claude/orchestrate-teams.yaml +24 -0
  40. package/.versions/0.0.5/.opencode/commands/af-build.md +17 -0
  41. package/.versions/0.0.5/.opencode/commands/af-code-simplify.md +16 -0
  42. package/.versions/0.0.5/.opencode/commands/af-compound.md +16 -0
  43. package/.versions/0.0.5/.opencode/commands/af-design-agent.md +15 -0
  44. package/.versions/0.0.5/.opencode/commands/af-doctor-agent-fleet.md +17 -0
  45. package/.versions/0.0.5/.opencode/commands/af-orchestrate.md +112 -0
  46. package/.versions/0.0.5/.opencode/commands/af-plan.md +16 -0
  47. package/.versions/0.0.5/.opencode/commands/af-prime.md +22 -0
  48. package/.versions/0.0.5/.opencode/commands/af-review.md +15 -0
  49. package/.versions/0.0.5/.opencode/commands/af-set-hermes-telegram.md +15 -0
  50. package/.versions/0.0.5/.opencode/commands/af-setup-agent-fleet.md +15 -0
  51. package/.versions/0.0.5/.opencode/commands/af-ship.md +16 -0
  52. package/.versions/0.0.5/.opencode/commands/af-spec.md +16 -0
  53. package/.versions/0.0.5/.opencode/commands/af-test.md +21 -0
  54. package/.versions/0.0.5/.opencode/commands/af-webperf.md +32 -0
  55. package/.versions/0.0.5/.opencode/orchestrate-teams.yaml +24 -0
  56. package/.versions/0.0.5/.pi/agents/dispatch-policy.yaml +32 -0
  57. package/.versions/0.0.5/.pi/agents/model-profiles.yaml +20 -0
  58. package/.versions/0.0.5/.pi/agents/peers.yaml +146 -0
  59. package/.versions/0.0.5/.pi/agents/teams.yaml +39 -0
  60. package/.versions/0.0.5/.pi/damage-control-rules.yaml +297 -0
  61. package/.versions/0.0.5/.pi/extensions/agent-fleet-update-check/README.md +58 -0
  62. package/.versions/0.0.5/.pi/extensions/agent-fleet-update-check/index.ts +161 -0
  63. package/.versions/0.0.5/.pi/extensions/agent-fleet-update-check/package.json +6 -0
  64. package/.versions/0.0.5/.pi/extensions/btw/README.md +118 -0
  65. package/.versions/0.0.5/.pi/extensions/btw/index.ts +917 -0
  66. package/.versions/0.0.5/.pi/extensions/btw/package.json +6 -0
  67. package/.versions/0.0.5/.pi/extensions/btw/state.js +179 -0
  68. package/.versions/0.0.5/.pi/extensions/chrome-devtools-mcp/README.md +58 -0
  69. package/.versions/0.0.5/.pi/extensions/chrome-devtools-mcp/index.ts +92 -0
  70. package/.versions/0.0.5/.pi/extensions/chrome-devtools-mcp/package.json +6 -0
  71. package/.versions/0.0.5/.pi/extensions/compact-and-continue/README.md +42 -0
  72. package/.versions/0.0.5/.pi/extensions/compact-and-continue/index.ts +120 -0
  73. package/.versions/0.0.5/.pi/extensions/compact-and-continue/package.json +6 -0
  74. package/.versions/0.0.5/.pi/extensions/mcp-bridge/README.md +46 -0
  75. package/.versions/0.0.5/.pi/extensions/mcp-bridge/index.ts +206 -0
  76. package/.versions/0.0.5/.pi/extensions/mcp-bridge/package.json +6 -0
  77. package/.versions/0.0.5/.pi/extensions/package-lock.json +1143 -0
  78. package/.versions/0.0.5/.pi/extensions/package.json +9 -0
  79. package/.versions/0.0.5/.pi/extensions/pi-voice-stt/README.md +201 -0
  80. package/.versions/0.0.5/.pi/extensions/pi-voice-stt/config.ts +198 -0
  81. package/.versions/0.0.5/.pi/extensions/pi-voice-stt/examples/stt.json +35 -0
  82. package/.versions/0.0.5/.pi/extensions/pi-voice-stt/index.ts +248 -0
  83. package/.versions/0.0.5/.pi/extensions/pi-voice-stt/package.json +6 -0
  84. package/.versions/0.0.5/.pi/extensions/pi-voice-stt/providers.ts +214 -0
  85. package/.versions/0.0.5/.pi/extensions/pi-voice-stt/recorder.ts +158 -0
  86. package/.versions/0.0.5/.pi/harnesses/agent-hub/README.md +798 -0
  87. package/.versions/0.0.5/.pi/harnesses/agent-hub/access-approval.ts +135 -0
  88. package/.versions/0.0.5/.pi/harnesses/agent-hub/artifacts.js +92 -0
  89. package/.versions/0.0.5/.pi/harnesses/agent-hub/backend-policy.js +153 -0
  90. package/.versions/0.0.5/.pi/harnesses/agent-hub/delegate.ts +386 -0
  91. package/.versions/0.0.5/.pi/harnesses/agent-hub/drift-watchdog.js +165 -0
  92. package/.versions/0.0.5/.pi/harnesses/agent-hub/evidence-rules.js +96 -0
  93. package/.versions/0.0.5/.pi/harnesses/agent-hub/footer.ts +29 -0
  94. package/.versions/0.0.5/.pi/harnesses/agent-hub/helpers.ts +214 -0
  95. package/.versions/0.0.5/.pi/harnesses/agent-hub/index.ts +8045 -0
  96. package/.versions/0.0.5/.pi/harnesses/agent-hub/monitor-control.ts +9 -0
  97. package/.versions/0.0.5/.pi/harnesses/agent-hub/monitor-lifecycle.ts +13 -0
  98. package/.versions/0.0.5/.pi/harnesses/agent-hub/monitor-publisher.ts +59 -0
  99. package/.versions/0.0.5/.pi/harnesses/agent-hub/monitor-recovery.ts +3 -0
  100. package/.versions/0.0.5/.pi/harnesses/agent-hub/monitor-runtime.ts +3 -0
  101. package/.versions/0.0.5/.pi/harnesses/agent-hub/monitor-session-bridge.ts +11 -0
  102. package/.versions/0.0.5/.pi/harnesses/agent-hub/package.json +7 -0
  103. package/.versions/0.0.5/.pi/harnesses/agent-hub/research-retention.js +34 -0
  104. package/.versions/0.0.5/.pi/harnesses/agent-hub/research-watchdog.ts +40 -0
  105. package/.versions/0.0.5/.pi/harnesses/agent-hub/return-contract.js +215 -0
  106. package/.versions/0.0.5/.pi/harnesses/agent-hub/run-budget.js +155 -0
  107. package/.versions/0.0.5/.pi/harnesses/agent-hub/safety-routing.ts +22 -0
  108. package/.versions/0.0.5/.pi/harnesses/agent-hub/scope-gate.js +103 -0
  109. package/.versions/0.0.5/.pi/harnesses/agent-hub/spawn.ts +246 -0
  110. package/.versions/0.0.5/.pi/harnesses/agent-hub/version.ts +18 -0
  111. package/.versions/0.0.5/.pi/harnesses/ask-user-remote/README.md +19 -0
  112. package/.versions/0.0.5/.pi/harnesses/ask-user-remote/index.ts +321 -0
  113. package/.versions/0.0.5/.pi/harnesses/ask-user-remote/race-core.js +106 -0
  114. package/.versions/0.0.5/.pi/harnesses/coms/README.md +92 -0
  115. package/.versions/0.0.5/.pi/harnesses/coms/index.ts +1745 -0
  116. package/.versions/0.0.5/.pi/harnesses/coms/package.json +7 -0
  117. package/.versions/0.0.5/.pi/harnesses/coms/version.ts +18 -0
  118. package/.versions/0.0.5/.pi/harnesses/damage-control-continue/README.md +117 -0
  119. package/.versions/0.0.5/.pi/harnesses/damage-control-continue/index.ts +536 -0
  120. package/.versions/0.0.5/.pi/harnesses/damage-control-continue/package.json +7 -0
  121. package/.versions/0.0.5/.pi/harnesses/damage-control-continue/version.ts +18 -0
  122. package/.versions/0.0.5/.pi/harnesses/lib/damage-control-shared.ts +197 -0
  123. package/.versions/0.0.5/.pi/harnesses/lib/herdr-client.ts +458 -0
  124. package/.versions/0.0.5/.pi/harnesses/lib/herdr-presence.ts +288 -0
  125. package/.versions/0.0.5/.pi/harnesses/lib/hermes-monitor-herdr.ts +28 -0
  126. package/.versions/0.0.5/.pi/harnesses/lib/hermes-monitor-model.ts +9 -0
  127. package/.versions/0.0.5/.pi/harnesses/lib/hermes-monitor-registry.ts +6 -0
  128. package/.versions/0.0.5/.pi/harnesses/lib/hermes-monitor-socket.ts +118 -0
  129. package/.versions/0.0.5/.pi/harnesses/lib/hermes-monitor-store.ts +31 -0
  130. package/.versions/0.0.5/.pi/harnesses/package-lock.json +35 -0
  131. package/.versions/0.0.5/.pi/harnesses/package.json +9 -0
  132. package/.versions/0.0.5/.pi/prompts/build.md +24 -0
  133. package/.versions/0.0.5/.pi/prompts/code-simplify.md +22 -0
  134. package/.versions/0.0.5/.pi/prompts/doctor-agent-fleet.md +15 -0
  135. package/.versions/0.0.5/.pi/prompts/plan.md +16 -0
  136. package/.versions/0.0.5/.pi/prompts/review.md +16 -0
  137. package/.versions/0.0.5/.pi/prompts/set-hermes-telegram.md +15 -0
  138. package/.versions/0.0.5/.pi/prompts/setup-agent-fleet.md +27 -0
  139. package/.versions/0.0.5/.pi/prompts/ship.md +17 -0
  140. package/.versions/0.0.5/.pi/prompts/spec.md +15 -0
  141. package/.versions/0.0.5/.pi/prompts/test.md +19 -0
  142. package/.versions/0.0.5/.pi/skills/bowser/SKILL.md +145 -0
  143. package/.versions/0.0.5/.version +1 -0
  144. package/.versions/0.0.5/agents/architect.md +23 -0
  145. package/.versions/0.0.5/agents/bowser.md +26 -0
  146. package/.versions/0.0.5/agents/builder.md +53 -0
  147. package/.versions/0.0.5/agents/code-reviewer.md +205 -0
  148. package/.versions/0.0.5/agents/deep-researcher.md +31 -0
  149. package/.versions/0.0.5/agents/documenter.md +18 -0
  150. package/.versions/0.0.5/agents/orchestrator.md +54 -0
  151. package/.versions/0.0.5/agents/plan-reviewer.md +60 -0
  152. package/.versions/0.0.5/agents/planner.md +69 -0
  153. package/.versions/0.0.5/agents/releaser.md +24 -0
  154. package/.versions/0.0.5/agents/researcher.md +28 -0
  155. package/.versions/0.0.5/agents/security-auditor.md +166 -0
  156. package/.versions/0.0.5/agents/test-engineer.md +151 -0
  157. package/.versions/0.0.5/agents/web-debugger.md +42 -0
  158. package/.versions/0.0.5/agents/web-performance-auditor.md +192 -0
  159. package/.versions/0.0.5/codex/CONDUCTOR.md +148 -0
  160. package/.versions/0.0.5/docs/ARCHITECTURE.md +210 -0
  161. package/.versions/0.0.5/docs/agent-fleet-setup.md +366 -0
  162. package/.versions/0.0.5/docs/claude-code-coms-bridge.md +103 -0
  163. package/.versions/0.0.5/docs/codex-remote-conductor.md +170 -0
  164. package/.versions/0.0.5/docs/coms-hermes-bridge.md +179 -0
  165. package/.versions/0.0.5/docs/getting-started.md +183 -0
  166. package/.versions/0.0.5/docs/npm-install.md +337 -0
  167. package/.versions/0.0.5/docs/opencode-setup.md +249 -0
  168. package/.versions/0.0.5/docs/pi-extensions.md +293 -0
  169. package/.versions/0.0.5/docs/pi-setup.md +472 -0
  170. package/.versions/0.0.5/docs/skill-anatomy.md +150 -0
  171. package/.versions/0.0.5/hermes/README.md +231 -0
  172. package/.versions/0.0.5/hermes/skills/hub-conductor/SKILL.md +84 -0
  173. package/.versions/0.0.5/hermes/skills/hub-liaison/SKILL.md +84 -0
  174. package/.versions/0.0.5/hooks/SIMPLIFY-IGNORE.md +90 -0
  175. package/.versions/0.0.5/hooks/coms-stop-hook.mjs +73 -0
  176. package/.versions/0.0.5/hooks/hooks.json +14 -0
  177. package/.versions/0.0.5/hooks/session-start.sh +74 -0
  178. package/.versions/0.0.5/hooks/simplify-ignore.sh +302 -0
  179. package/.versions/0.0.5/justfile +245 -0
  180. package/.versions/0.0.5/references/accessibility-checklist.md +160 -0
  181. package/.versions/0.0.5/references/definition-of-done.md +67 -0
  182. package/.versions/0.0.5/references/fleet-coordination-patterns.md +151 -0
  183. package/.versions/0.0.5/references/observability-checklist.md +91 -0
  184. package/.versions/0.0.5/references/orchestration-patterns.md +370 -0
  185. package/.versions/0.0.5/references/performance-checklist.md +153 -0
  186. package/.versions/0.0.5/references/prompting-patterns.md +380 -0
  187. package/.versions/0.0.5/references/security-checklist.md +179 -0
  188. package/.versions/0.0.5/references/testing-patterns.md +236 -0
  189. package/.versions/0.0.5/scripts/codex-conductor.ts +41 -0
  190. package/.versions/0.0.5/scripts/codex-remote-control.ts +167 -0
  191. package/.versions/0.0.5/scripts/coms-claude-bridge.ts +286 -0
  192. package/.versions/0.0.5/scripts/coms-cli.ts +484 -0
  193. package/.versions/0.0.5/scripts/coms-hermes-bridge.ts +413 -0
  194. package/.versions/0.0.5/scripts/fleet.ts +141 -0
  195. package/.versions/0.0.5/scripts/hermes-monitor-capability-runner.ts +25 -0
  196. package/.versions/0.0.5/scripts/hermes-monitor-scenario.ts +7 -0
  197. package/.versions/0.0.5/scripts/lib/claude-bridge-core.ts +100 -0
  198. package/.versions/0.0.5/scripts/lib/codex-conductor.ts +88 -0
  199. package/.versions/0.0.5/scripts/lib/codex-remote-control.ts +480 -0
  200. package/.versions/0.0.5/scripts/lib/coms-envelope.ts +539 -0
  201. package/.versions/0.0.5/scripts/lib/fake-herdr-server.ts +88 -0
  202. package/.versions/0.0.5/scripts/lib/fleet-command.ts +109 -0
  203. package/.versions/0.0.5/scripts/lib/herdr-layout.ts +263 -0
  204. package/.versions/0.0.5/scripts/lib/hermes-bridge-core.ts +241 -0
  205. package/.versions/0.0.5/scripts/lib/hermes-monitor-herdr.ts +2 -0
  206. package/.versions/0.0.5/scripts/lib/hermes-monitor-model.ts +3 -0
  207. package/.versions/0.0.5/scripts/lib/hermes-monitor-registry.ts +2 -0
  208. package/.versions/0.0.5/scripts/lib/hermes-monitor-socket.ts +2 -0
  209. package/.versions/0.0.5/scripts/lib/hermes-monitor-store.ts +2 -0
  210. package/.versions/0.0.5/scripts/lib/persona-banner.ts +62 -0
  211. package/.versions/0.0.5/scripts/lib/spawn-stagger.ts +101 -0
  212. package/.versions/0.0.5/scripts/lib/team-project.ts +191 -0
  213. package/.versions/0.0.5/scripts/lib/team-snapshot.ts +147 -0
  214. package/.versions/0.0.5/scripts/peer-banner.ts +40 -0
  215. package/.versions/0.0.5/scripts/team-snapshot.ts +237 -0
  216. package/.versions/0.0.5/scripts/team-up.ts +351 -0
  217. package/.versions/0.0.5/skills/_internal/grilling.md +11 -0
  218. package/.versions/0.0.5/skills/browser-testing-with-devtools/SKILL.md +352 -0
  219. package/.versions/0.0.5/skills/code-review-and-quality/SKILL.md +381 -0
  220. package/.versions/0.0.5/skills/compound-learning/SKILL.md +137 -0
  221. package/.versions/0.0.5/skills/context-engineering/SKILL.md +291 -0
  222. package/.versions/0.0.5/skills/deprecation-and-migration/SKILL.md +206 -0
  223. package/.versions/0.0.5/skills/designing-agents/SKILL.md +394 -0
  224. package/.versions/0.0.5/skills/designing-agents/pi-harness-authoring.md +222 -0
  225. package/.versions/0.0.5/skills/frontend-ui-engineering/SKILL.md +328 -0
  226. package/.versions/0.0.5/skills/git-workflow-and-versioning/SKILL.md +316 -0
  227. package/.versions/0.0.5/skills/guided-workspace-setup/SKILL.md +542 -0
  228. package/.versions/0.0.5/skills/guided-workspace-setup/companion-manifest.json +35 -0
  229. package/.versions/0.0.5/skills/idea-refine/SKILL.md +182 -0
  230. package/.versions/0.0.5/skills/idea-refine/examples.md +238 -0
  231. package/.versions/0.0.5/skills/idea-refine/frameworks.md +99 -0
  232. package/.versions/0.0.5/skills/idea-refine/refinement-criteria.md +113 -0
  233. package/.versions/0.0.5/skills/idea-refine/scripts/idea-refine.sh +15 -0
  234. package/.versions/0.0.5/skills/incremental-implementation/SKILL.md +287 -0
  235. package/.versions/0.0.5/skills/interview-me/SKILL.md +226 -0
  236. package/.versions/0.0.5/skills/orchestration-verification/SKILL.md +181 -0
  237. package/.versions/0.0.5/skills/peer-coms/SKILL.md +90 -0
  238. package/.versions/0.0.5/skills/performance-optimization/SKILL.md +350 -0
  239. package/.versions/0.0.5/skills/planning-and-task-breakdown/SKILL.md +236 -0
  240. package/.versions/0.0.5/skills/security-and-hardening/SKILL.md +461 -0
  241. package/.versions/0.0.5/skills/spec-driven-development/SKILL.md +245 -0
  242. package/.versions/0.0.5/skills/using-agent-skills/SKILL.md +199 -0
  243. package/.versions/0.0.5/systemd/user/agent-fleet-codex-remote-control.service.in +23 -0
  244. package/.versions/0.0.5/vendor/agent-skills-upstream/LICENSE +21 -0
  245. package/.versions/0.0.5/vendor/agent-skills-upstream/README.md +11 -0
  246. package/.versions/0.0.5/vendor/agent-skills-upstream/skills/api-and-interface-design/SKILL.md +294 -0
  247. package/.versions/0.0.5/vendor/agent-skills-upstream/skills/browser-testing-with-devtools/SKILL.md +317 -0
  248. package/.versions/0.0.5/vendor/agent-skills-upstream/skills/ci-cd-and-automation/SKILL.md +390 -0
  249. package/.versions/0.0.5/vendor/agent-skills-upstream/skills/code-review-and-quality/SKILL.md +396 -0
  250. package/.versions/0.0.5/vendor/agent-skills-upstream/skills/code-simplification/SKILL.md +331 -0
  251. package/.versions/0.0.5/vendor/agent-skills-upstream/skills/context-engineering/SKILL.md +289 -0
  252. package/.versions/0.0.5/vendor/agent-skills-upstream/skills/debugging-and-error-recovery/SKILL.md +300 -0
  253. package/.versions/0.0.5/vendor/agent-skills-upstream/skills/deprecation-and-migration/SKILL.md +247 -0
  254. package/.versions/0.0.5/vendor/agent-skills-upstream/skills/documentation-and-adrs/SKILL.md +278 -0
  255. package/.versions/0.0.5/vendor/agent-skills-upstream/skills/doubt-driven-development/SKILL.md +243 -0
  256. package/.versions/0.0.5/vendor/agent-skills-upstream/skills/frontend-ui-engineering/SKILL.md +328 -0
  257. package/.versions/0.0.5/vendor/agent-skills-upstream/skills/git-workflow-and-versioning/SKILL.md +355 -0
  258. package/.versions/0.0.5/vendor/agent-skills-upstream/skills/idea-refine/SKILL.md +178 -0
  259. package/.versions/0.0.5/vendor/agent-skills-upstream/skills/idea-refine/examples.md +238 -0
  260. package/.versions/0.0.5/vendor/agent-skills-upstream/skills/idea-refine/frameworks.md +99 -0
  261. package/.versions/0.0.5/vendor/agent-skills-upstream/skills/idea-refine/refinement-criteria.md +113 -0
  262. package/.versions/0.0.5/vendor/agent-skills-upstream/skills/idea-refine/scripts/idea-refine.sh +15 -0
  263. package/.versions/0.0.5/vendor/agent-skills-upstream/skills/incremental-implementation/SKILL.md +249 -0
  264. package/.versions/0.0.5/vendor/agent-skills-upstream/skills/interview-me/SKILL.md +225 -0
  265. package/.versions/0.0.5/vendor/agent-skills-upstream/skills/observability-and-instrumentation/SKILL.md +203 -0
  266. package/.versions/0.0.5/vendor/agent-skills-upstream/skills/performance-optimization/SKILL.md +350 -0
  267. package/.versions/0.0.5/vendor/agent-skills-upstream/skills/planning-and-task-breakdown/SKILL.md +234 -0
  268. package/.versions/0.0.5/vendor/agent-skills-upstream/skills/security-and-hardening/SKILL.md +467 -0
  269. package/.versions/0.0.5/vendor/agent-skills-upstream/skills/shipping-and-launch/SKILL.md +310 -0
  270. package/.versions/0.0.5/vendor/agent-skills-upstream/skills/source-driven-development/SKILL.md +194 -0
  271. package/.versions/0.0.5/vendor/agent-skills-upstream/skills/spec-driven-development/SKILL.md +206 -0
  272. package/.versions/0.0.5/vendor/agent-skills-upstream/skills/test-driven-development/SKILL.md +383 -0
  273. package/.versions/0.0.5/vendor/agent-skills-upstream/skills/using-agent-skills/SKILL.md +191 -0
  274. package/CHANGELOG.md +9 -0
  275. package/README.md +14 -13
  276. package/bin/cli.js +83 -1
  277. package/bin/lib/set-hermes-telegram.js +323 -0
  278. package/docs/ARCHITECTURE.md +4 -4
  279. package/docs/agent-fleet-setup.md +1 -1
  280. package/docs/claude-code-coms-bridge.md +4 -4
  281. package/docs/codex-remote-conductor.md +12 -12
  282. package/docs/coms-hermes-bridge.md +62 -4
  283. package/docs/getting-started.md +4 -4
  284. package/docs/opencode-setup.md +1 -0
  285. package/docs/pi-extensions.md +30 -25
  286. package/docs/pi-setup.md +17 -8
  287. package/hermes/README.md +14 -11
  288. package/justfile +141 -152
  289. package/package.json +6 -3
  290. package/references/fleet-coordination-patterns.md +1 -1
  291. package/scripts/coms-hermes-bridge.ts +18 -8
  292. package/scripts/fleet.ts +141 -0
  293. package/scripts/lib/fleet-command.ts +109 -0
  294. package/scripts/lib/hermes-bridge-core.ts +5 -2
  295. package/scripts/lib/hermes-monitor-herdr.ts +2 -28
  296. package/scripts/lib/hermes-monitor-model.ts +3 -9
  297. package/scripts/lib/hermes-monitor-registry.ts +2 -6
  298. package/scripts/lib/hermes-monitor-socket.ts +2 -118
  299. package/scripts/lib/hermes-monitor-store.ts +2 -31
  300. package/scripts/lib/team-project.ts +10 -3
  301. package/scripts/team-snapshot.ts +4 -5
  302. package/scripts/team-up.ts +24 -6
  303. package/skills/guided-workspace-setup/SKILL.md +13 -6
  304. package/skills/guided-workspace-setup/companion-manifest.json +3 -1
  305. package/skills/peer-coms/SKILL.md +1 -1
  306. package/hermes/plugins/agent-fleet-monitor/dashboard/dist/index.js +0 -10
  307. /package/{hermes → .versions/0.0.5/hermes}/desktop-plugins/agent-fleet-monitor/plugin.js +0 -0
  308. /package/{hermes → .versions/0.0.5/hermes}/desktop-plugins/agent-fleet-monitor/state.js +0 -0
  309. /package/{hermes → .versions/0.0.5/hermes}/plugins/agent-fleet-monitor/dashboard/adapter-cap.test.py +0 -0
  310. /package/{hermes → .versions/0.0.5/hermes}/plugins/agent-fleet-monitor/dashboard/adapter-discovery.test.py +0 -0
  311. /package/{hermes → .versions/0.0.5/hermes}/plugins/agent-fleet-monitor/dashboard/adapter-envelope.test.py +0 -0
  312. /package/{hermes → .versions/0.0.5/hermes}/plugins/agent-fleet-monitor/dashboard/adapter-forged-owner.test.py +0 -0
  313. /package/{hermes → .versions/0.0.5/hermes}/plugins/agent-fleet-monitor/dashboard/adapter-lease-list.test.py +0 -0
  314. /package/{hermes → .versions/0.0.5/hermes}/plugins/agent-fleet-monitor/dashboard/adapter-multihub.test.py +0 -0
  315. /package/{hermes → .versions/0.0.5/hermes}/plugins/agent-fleet-monitor/dashboard/adapter-output.test.py +0 -0
  316. /package/{hermes → .versions/0.0.5/hermes}/plugins/agent-fleet-monitor/dashboard/adapter.py +0 -0
  317. /package/{hermes → .versions/0.0.5/hermes}/plugins/agent-fleet-monitor/dashboard/adapter.test.py +0 -0
  318. /package/{hermes → .versions/0.0.5/hermes}/plugins/agent-fleet-monitor/dashboard/manifest.json +0 -0
  319. /package/{hermes → .versions/0.0.5/hermes}/plugins/agent-fleet-monitor/dashboard/plugin-api-validation.test.py +0 -0
  320. /package/{hermes → .versions/0.0.5/hermes}/plugins/agent-fleet-monitor/dashboard/plugin_api.py +0 -0
  321. /package/{hermes → .versions/0.0.5/hermes}/plugins/agent-fleet-monitor/dashboard/review-live-wiring.red.test.py +0 -0
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@chankov/agent-fleet",
3
- "version": "0.0.4",
3
+ "version": "0.0.5",
4
4
  "description": "Multi-agent fleet orchestration for coding agents. Pi as the primary runtime, Herdr as the workspace control plane, coms as the peer data plane, and Hermes for remote control — plus skills, personas, harnesses, and a guided setup CLI.",
5
5
  "keywords": [
6
6
  "ai",
@@ -64,7 +64,8 @@
64
64
  "!scripts/hermes-monitor-scenario.test.ts",
65
65
  "scripts/lib/*.ts",
66
66
  "codex/",
67
- "hermes/",
67
+ "hermes/README.md",
68
+ "hermes/skills/",
68
69
  "systemd/",
69
70
  "justfile",
70
71
  "references/",
@@ -98,7 +99,7 @@
98
99
  "access": "public"
99
100
  },
100
101
  "scripts": {
101
- "test": "node bin/cli.js --version && node bin/cli.js --help && node bin/cli.js transform-persona --list --agent claude-code && node --test \"bin/test/*.test.js\" scripts/agent-hub-helpers.test.mjs scripts/agent-hub-spawn.test.mjs scripts/agent-hub-delegate.test.mjs scripts/agent-hub-research.test.mjs .pi/harnesses/lib/herdr-client.test.ts .pi/harnesses/lib/herdr-presence.test.ts scripts/coms-cli.test.ts scripts/lib/codex-conductor.test.ts scripts/lib/codex-remote-control.test.ts scripts/lib/team-project.test.ts scripts/lib/herdr-layout.test.ts scripts/lib/spawn-stagger.test.ts scripts/lib/fleet-extras.test.ts scripts/lib/team-snapshot.test.ts scripts/lib/coms-envelope.test.ts scripts/lib/claude-bridge-core.test.ts scripts/lib/hermes-bridge-core.test.ts scripts/coms-hermes-bridge.test.ts .pi/harnesses/ask-user-remote/race-core.test.js .pi/harnesses/ask-user-remote/index.test.ts .pi/extensions/btw/state.test.js .pi/harnesses/agent-hub/footer.test.ts .pi/harnesses/agent-hub/safety-routing.test.ts .pi/harnesses/agent-hub/approval-routing.integration.test.ts .pi/harnesses/agent-hub/run-budget.test.js .pi/harnesses/agent-hub/drift-watchdog.test.js .pi/harnesses/agent-hub/return-contract.test.js .pi/harnesses/agent-hub/backend-policy.test.js .pi/harnesses/agent-hub/artifacts.test.js .pi/harnesses/agent-hub/scope-gate.test.js .pi/harnesses/agent-hub/evidence-rules.test.js .pi/harnesses/agent-hub/research-retention.test.js .pi/harnesses/lib/damage-control-shared.test.ts .pi/harnesses/damage-control-continue/herdr-rules.test.js .pi/harnesses/damage-control-continue/exemptions.test.js scripts/lib/hermes-monitor-model.test.ts scripts/lib/hermes-monitor-store.test.ts scripts/lib/hermes-monitor-retention.integration.test.ts scripts/lib/hermes-monitor-registry.test.ts scripts/lib/hermes-monitor-socket.test.ts scripts/lib/hermes-monitor-data-path.test.ts scripts/lib/hermes-monitor-slice7-9-backend.test.ts scripts/lib/hermes-monitor-control-socket.test.ts scripts/lib/hermes-monitor-e2e.test.ts scripts/hermes-monitor-capability-runner.test.ts scripts/hermes-monitor-scenario.test.ts .pi/harnesses/agent-hub/monitor-control.test.ts .pi/harnesses/agent-hub/monitor-live-bridge-gaps.test.ts .pi/harnesses/agent-hub/monitor-review-live-wiring.red.test.ts .pi/harnesses/agent-hub/monitor-runtime.test.ts .pi/harnesses/agent-hub/monitor-bridge-runtime.test.ts .pi/harnesses/agent-hub/monitor-reconcile.test.ts .pi/harnesses/agent-hub/monitor-recovery.test.ts .pi/harnesses/agent-hub/monitor-lifecycle-lease.test.ts .pi/harnesses/agent-hub/monitor-session-bridge-race.test.ts .pi/harnesses/agent-hub/monitor-session-bridge.test.ts .pi/harnesses/agent-hub/monitor-cancel-race.test.ts .pi/harnesses/agent-hub/monitor-wait-only.test.ts .pi/harnesses/agent-hub/monitor-index.integration.test.ts",
102
+ "test": "node bin/cli.js --version && node bin/cli.js --help && node bin/cli.js transform-persona --list --agent claude-code && node --test \"bin/test/*.test.js\" scripts/agent-hub-helpers.test.mjs scripts/agent-hub-spawn.test.mjs scripts/agent-hub-delegate.test.mjs scripts/agent-hub-research.test.mjs .pi/harnesses/lib/herdr-client.test.ts .pi/harnesses/lib/herdr-presence.test.ts scripts/coms-cli.test.ts scripts/lib/codex-conductor.test.ts scripts/lib/codex-remote-control.test.ts scripts/lib/fleet-command.test.ts scripts/lib/team-project.test.ts scripts/lib/herdr-layout.test.ts scripts/lib/spawn-stagger.test.ts scripts/lib/fleet-extras.test.ts scripts/lib/team-snapshot.test.ts scripts/lib/coms-envelope.test.ts scripts/lib/claude-bridge-core.test.ts scripts/lib/hermes-bridge-core.test.ts scripts/coms-hermes-bridge.test.ts .pi/harnesses/ask-user-remote/race-core.test.js .pi/harnesses/ask-user-remote/index.test.ts .pi/harnesses/agent-hub/extension-loader.test.ts .pi/extensions/btw/state.test.js .pi/harnesses/agent-hub/footer.test.ts .pi/harnesses/agent-hub/safety-routing.test.ts .pi/harnesses/agent-hub/approval-routing.integration.test.ts .pi/harnesses/agent-hub/run-budget.test.js .pi/harnesses/agent-hub/drift-watchdog.test.js .pi/harnesses/agent-hub/return-contract.test.js .pi/harnesses/agent-hub/backend-policy.test.js .pi/harnesses/agent-hub/artifacts.test.js .pi/harnesses/agent-hub/scope-gate.test.js .pi/harnesses/agent-hub/evidence-rules.test.js .pi/harnesses/agent-hub/research-retention.test.js .pi/harnesses/lib/damage-control-shared.test.ts .pi/harnesses/damage-control-continue/herdr-rules.test.js .pi/harnesses/damage-control-continue/exemptions.test.js scripts/lib/hermes-monitor-model.test.ts scripts/lib/hermes-monitor-store.test.ts scripts/lib/hermes-monitor-retention.integration.test.ts scripts/lib/hermes-monitor-registry.test.ts scripts/lib/hermes-monitor-socket.test.ts scripts/lib/hermes-monitor-data-path.test.ts scripts/lib/hermes-monitor-slice7-9-backend.test.ts scripts/lib/hermes-monitor-control-socket.test.ts scripts/lib/hermes-monitor-e2e.test.ts scripts/hermes-monitor-capability-runner.test.ts scripts/hermes-monitor-scenario.test.ts .pi/harnesses/agent-hub/monitor-control.test.ts .pi/harnesses/agent-hub/monitor-live-bridge-gaps.test.ts .pi/harnesses/agent-hub/monitor-review-live-wiring.red.test.ts .pi/harnesses/agent-hub/monitor-runtime.test.ts .pi/harnesses/agent-hub/monitor-bridge-runtime.test.ts .pi/harnesses/agent-hub/monitor-reconcile.test.ts .pi/harnesses/agent-hub/monitor-recovery.test.ts .pi/harnesses/agent-hub/monitor-lifecycle-lease.test.ts .pi/harnesses/agent-hub/monitor-session-bridge-race.test.ts .pi/harnesses/agent-hub/monitor-session-bridge.test.ts .pi/harnesses/agent-hub/monitor-cancel-race.test.ts .pi/harnesses/agent-hub/monitor-wait-only.test.ts .pi/harnesses/agent-hub/monitor-index.integration.test.ts",
102
103
  "pack:dry": "npm pack --dry-run",
103
104
  "changeset": "changeset",
104
105
  "version:changeset": "node bin/force-patch-changesets.js && changeset version && node bin/sync-harness-versions.js && npm install --package-lock-only --ignore-scripts --no-audit --no-fund && node bin/snapshot-version.js",
@@ -108,8 +109,10 @@
108
109
  "@changesets/cli": "^2.27.1"
109
110
  },
110
111
  "dependencies": {
112
+ "@modelcontextprotocol/sdk": "^1.29.0",
111
113
  "@sinclair/typebox": "^0.34.49",
112
114
  "pi-ask-user": "^0.11.1",
115
+ "typebox": "^1.1.33",
113
116
  "yaml": "^2.9.0"
114
117
  },
115
118
  "bundledDependencies": [
@@ -113,7 +113,7 @@ artifacts only where the digest warrants it. Raw dumps never travel upward.
113
113
  previews + paths, never inlined full content.
114
114
  - The delegate `DIGEST:` contract — children return ≤30 digest lines with `path:line`
115
115
  citations plus the result-file path; over-long returns are truncated with a warning.
116
- - `just team-up <team>` is the fleet-level shard step: one pane per peer, each an
116
+ - `just fleet team <team> --no-hub` is the fleet-level shard step: one pane per peer, each an
117
117
  addressable worker.
118
118
 
119
119
  **Failure modes:** digest inflation (cap lines, require citations); merger re-reading
@@ -52,6 +52,7 @@ const DEFAULT_POLL_MS = 1_000;
52
52
  const COLOR = "#38BDF8";
53
53
  const DEFAULT_NAME = "user-remote";
54
54
  const DEFAULT_PURPOSE = "Remote human via Hermes/Telegram";
55
+ const HERMES_PROFILE_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
55
56
 
56
57
  interface PendingQuestion {
57
58
  env: PromptEnvelope;
@@ -67,7 +68,9 @@ interface ParsedPrompt {
67
68
  }
68
69
 
69
70
  function flagValue(argv: string[], flag: string): string | null {
70
- const i = argv.indexOf(flag);
71
+ const positions = argv.flatMap((arg, index) => arg === flag ? [index] : []);
72
+ if (positions.length > 1) die(`${flag} may only be specified once`);
73
+ const i = positions[0] ?? -1;
71
74
  return i >= 0 && i + 1 < argv.length ? argv[i + 1] : null;
72
75
  }
73
76
 
@@ -116,9 +119,10 @@ function appendAnswerRejectLog(logFile: string, qid: string, detail: unknown): v
116
119
  fs.appendFileSync(logFile, JSON.stringify({ at: nowIso(), qid, event: "answer_rejected", detail }) + "\n");
117
120
  }
118
121
 
119
- function hermesSend(to: string, text: string): Promise<void> {
122
+ function hermesSend(to: string, text: string, profile: string | null): Promise<void> {
120
123
  return new Promise((resolve, reject) => {
121
- const child = spawn("hermes", ["send", "--to", to, text], { stdio: ["ignore", "pipe", "pipe"] });
124
+ const args = [...(profile ? ["--profile", profile] : []), "send", "--to", to, text];
125
+ const child = spawn("hermes", args, { stdio: ["ignore", "pipe", "pipe"] });
122
126
  let stderr = "";
123
127
  let stdout = "";
124
128
  child.stdout?.on("data", (chunk) => { stdout += chunk.toString("utf-8"); });
@@ -140,11 +144,13 @@ async function main(): Promise<void> {
140
144
  const requestedName = flagValue(argv, "--name") ?? DEFAULT_NAME;
141
145
  const project = flagValue(argv, "--project") ?? "default";
142
146
  const to = flagValue(argv, "--to") ?? "telegram";
147
+ const hermesProfile = flagValue(argv, "--hermes-profile");
143
148
  const timeoutMs = Number(flagValue(argv, "--timeout") ?? timeoutMsFromEnv());
144
149
  const pollMs = Number(flagValue(argv, "--poll-ms") ?? DEFAULT_POLL_MS);
145
150
  const qDir = flagValue(argv, "--questions-dir") ?? defaultQuestionsDir();
146
151
  const logFile = path.join(path.dirname(qDir), path.basename(defaultLogPath()));
147
152
 
153
+ if (hermesProfile && (!HERMES_PROFILE_RE.test(hermesProfile) || hermesProfile === "." || hermesProfile.includes(".."))) die("--hermes-profile must be a safe profile name");
148
154
  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) die("--timeout must be a positive number");
149
155
  if (!Number.isFinite(pollMs) || pollMs <= 0) die("--poll-ms must be a positive number");
150
156
 
@@ -211,7 +217,7 @@ async function main(): Promise<void> {
211
217
  markClosed(qid, "timeout");
212
218
  appendLogFile(logFile, qid, "timeout", { timeout_ms: timeoutMs });
213
219
  const outcome = timeoutOutcome(qid, timeoutMs);
214
- await hermesSend(to, outcome.telegramNote).catch((err) => {
220
+ await hermesSend(to, outcome.telegramNote, hermesProfile).catch((err) => {
215
221
  appendLogFile(logFile, qid, "delivery_error", { phase: "timeout_note", error: err instanceof Error ? err.message : String(err) });
216
222
  });
217
223
  await sendResponse(item.env, outcome.response, outcome.error).catch((err) => {
@@ -239,10 +245,11 @@ async function main(): Promise<void> {
239
245
  try {
240
246
  await hermesSend(to, formatTelegramQuestion({
241
247
  qid,
248
+ project,
242
249
  question: parsed.question,
243
250
  context: parsed.context,
244
251
  options: parsed.options,
245
- }));
252
+ }), hermesProfile);
246
253
  const item = pending.get(qid);
247
254
  if (!item) return;
248
255
  item.state = "delivered";
@@ -269,14 +276,14 @@ async function main(): Promise<void> {
269
276
  pending.delete(refMsgId);
270
277
  markClosed(refMsgId, "cancelled");
271
278
  appendLogFile(logFile, refMsgId, "cancelled", { reason: "cancel envelope" });
272
- await hermesSend(to, `✖ [HUB-Q:${refMsgId}] The question was cancelled — it was answered from the console.`).catch((err) => {
279
+ await hermesSend(to, `✖ [HUB-Q:${refMsgId}] The question was cancelled — it was answered from the console.`, hermesProfile).catch((err) => {
273
280
  appendLogFile(logFile, refMsgId, "delivery_error", { phase: "cancel_note", error: err instanceof Error ? err.message : String(err) });
274
281
  });
275
282
  }
276
283
 
277
284
  async function handleLateAnswer(qid: string): Promise<void> {
278
285
  appendLogFile(logFile, qid, "late_answer", { state: closed.get(qid) ?? "unknown" });
279
- await hermesSend(to, `ℹ [HUB-Q:${qid}] This question is already closed; the late answer was ignored.`).catch((err) => {
286
+ await hermesSend(to, `ℹ [HUB-Q:${qid}] This question is already closed; the late answer was ignored.`, hermesProfile).catch((err) => {
280
287
  appendLogFile(logFile, qid, "delivery_error", { phase: "late_note", error: err instanceof Error ? err.message : String(err) });
281
288
  });
282
289
  }
@@ -311,8 +318,11 @@ async function main(): Promise<void> {
311
318
  }
312
319
  invalidJsonSeen.delete(file);
313
320
  const logQid = validation.qid && isValidQid(validation.qid) ? validation.qid : (isValidQid(qidFromName) ? qidFromName : "00000000000000000000000000");
314
- appendAnswerRejectLog(logFile, logQid, { reason: validation.reason, file });
321
+ // Remove the rejected file before publishing the event. Consumers use the
322
+ // log as the completion signal and may immediately write a corrected file
323
+ // at the same path; logging first lets this scan delete that replacement.
315
324
  try { fs.unlinkSync(full); } catch { /* ignore */ }
325
+ appendAnswerRejectLog(logFile, logQid, { reason: validation.reason, file });
316
326
  return;
317
327
  }
318
328
 
@@ -0,0 +1,141 @@
1
+ // Unified `just fleet` command dispatcher. Parsing is kept pure and tested in
2
+ // scripts/lib/fleet-command.test.ts; this entrypoint only hands the resolved
3
+ // recipe back to Just so existing compatibility recipes remain one source of truth.
4
+
5
+ import { spawnSync } from "node:child_process";
6
+ import { parseFleetCommand } from "./lib/fleet-command.ts";
7
+
8
+ const HELP = `Agent Fleet — unified Pi runtime
9
+
10
+ QUICK START
11
+ just fleet
12
+ Start the default guarded Pi session with Fleet Core.
13
+
14
+ just fleet hub --project af
15
+ Start Agent Hub with specialists, research, Verification Contract, and coms.
16
+
17
+ just fleet team frontend --project af
18
+ Start a guarded Hub plus the frontend peer team in one Herdr workspace.
19
+
20
+ FLEET CORE — loaded in every Pi mode
21
+ Damage Control Continue · local/remote ask_user · Speech-to-Text (Alt+S)
22
+ Compact & Continue · BTW side sessions · update checker
23
+
24
+ SESSION MODES
25
+ just fleet [PI_ARGS...]
26
+ Safe interactive Pi without Hub or a coms identity.
27
+ Example: just fleet --model openai-codex/gpt-5.6-terra
28
+
29
+ just fleet peer <name> [PI_ARGS...]
30
+ Safe interactive Pi registered as an addressable coms peer.
31
+ Example: just fleet peer architect --project af
32
+
33
+ just fleet hub [--solo] [PI_ARGS...]
34
+ Agent Hub dispatcher. Embedded coms is on unless --solo is supplied.
35
+ Examples:
36
+ just fleet hub --project af
37
+ just fleet hub --solo
38
+
39
+ TEAM MODES — presets: base, full, web, docs, default, debug, frontend,
40
+ security, hotfix, release, info, review, plan
41
+ just fleet team <preset> [TEAM_ARGS...]
42
+ Guarded Hub plus guarded reusable peers in one Herdr workspace.
43
+ Example: just fleet team security --project af
44
+
45
+ just fleet team <preset> --no-hub [TEAM_ARGS...]
46
+ Guarded reusable peers only; no Hub pane.
47
+ Example: just fleet team docs --no-hub --project af
48
+
49
+ just fleet team <preset> [--no-hub] --dry-run [TEAM_ARGS...]
50
+ Print the resolved workspace, panes, and commands without changing Herdr.
51
+ Example: just fleet team frontend --dry-run --project af
52
+
53
+ TEAM LIFECYCLE
54
+ just fleet snapshot <preset> [--project <name>]
55
+ Save session references while the workspace keeps running.
56
+
57
+ just fleet down <preset> [--project <name>]
58
+ Snapshot and cleanly close the workspace.
59
+
60
+ just fleet resume <preset> [--project <name>]
61
+ Rebuild the workspace and resume available Pi/Claude sessions.
62
+
63
+ Examples:
64
+ just fleet snapshot docs --project af
65
+ just fleet down docs --project af
66
+ just fleet resume docs --project af
67
+
68
+ HERMES CONDUCTOR
69
+ just fleet conductor hermes [preset] [--dry-run] [TEAM_ARGS...]
70
+ Start Hermes with a peer team, or preview the layout with --dry-run.
71
+ Example: just fleet conductor hermes docs --project af
72
+
73
+ CODEX REMOTE-CONTROL CONDUCTOR
74
+ just fleet conductor codex <setup|reconfigure> [preset] [ARGS...]
75
+ just fleet conductor codex <pair|start|status|stop|recover|uninstall>
76
+ just fleet conductor codex [preset] [--dry-run] [TEAM_ARGS...]
77
+
78
+ Typical flow:
79
+ just fleet conductor codex setup docs --project af
80
+ just fleet conductor codex pair
81
+ just fleet conductor codex start
82
+ just fleet conductor codex docs --project af
83
+ just fleet conductor codex status
84
+ just fleet conductor codex stop
85
+
86
+ CAPABILITY FLAGS
87
+ --browser
88
+ Add interactive Chrome DevTools MCP tools to the main Pi/Hub process.
89
+ Example: just fleet hub --browser --project af
90
+
91
+ --all-extensions
92
+ Also auto-load arbitrary project/global extensions outside Fleet Core.
93
+ Example: just fleet peer debugger --all-extensions --project af
94
+
95
+ SETUP
96
+ just fleet install
97
+ Install only .pi/extensions and .pi/harnesses Node dependencies.
98
+ Does not launch Pi, configure STT, install ffmpeg/Herdr, or pair Codex.
99
+
100
+ HELP
101
+ just Show this complete command guide.
102
+ just fleet help Show this complete command guide.
103
+ just --list Show the intentionally small public recipe surface.
104
+
105
+ Configuration:
106
+ Teams: .pi/agents/peers.yaml
107
+ Hub teams: .pi/agents/teams.yaml
108
+ Overrides: .ai/agent-fleet-overrides.md
109
+ STT: .ai/stt.json or ~/.pi/agent/stt.json
110
+ Safety: .pi/damage-control-rules.yaml
111
+ Full docs: docs/pi-extensions.md and docs/pi-setup.md
112
+ `;
113
+
114
+ function main(): void {
115
+ const argv = process.argv.slice(2);
116
+ if (argv[0] === "help" || argv[0] === "--help" || argv[0] === "-h") {
117
+ process.stdout.write(HELP);
118
+ return;
119
+ }
120
+ let invocation;
121
+ try {
122
+ invocation = parseFleetCommand(argv);
123
+ } catch (err) {
124
+ console.error(`fleet: ${err instanceof Error ? err.message : String(err)}\n`);
125
+ process.stderr.write(HELP);
126
+ process.exitCode = 2;
127
+ return;
128
+ }
129
+ const result = spawnSync("just", [invocation.recipe, ...invocation.args], {
130
+ stdio: "inherit",
131
+ env: process.env,
132
+ });
133
+ if (result.error) {
134
+ console.error(`fleet: could not run just: ${result.error.message}`);
135
+ process.exitCode = 1;
136
+ return;
137
+ }
138
+ process.exitCode = result.status ?? 1;
139
+ }
140
+
141
+ main();
@@ -0,0 +1,109 @@
1
+ export interface FleetInvocation {
2
+ recipe: string;
3
+ args: string[];
4
+ }
5
+
6
+ interface Capabilities {
7
+ browser: boolean;
8
+ allExtensions: boolean;
9
+ rest: string[];
10
+ }
11
+
12
+ function capabilities(args: string[]): Capabilities {
13
+ const rest: string[] = [];
14
+ let browser = false;
15
+ let allExtensions = false;
16
+ for (const arg of args) {
17
+ if (arg === "--browser") browser = true;
18
+ else if (arg === "--all-extensions") allExtensions = true;
19
+ else rest.push(arg);
20
+ }
21
+ return { browser, allExtensions, rest };
22
+ }
23
+
24
+ function bool(value: boolean): string {
25
+ return value ? "true" : "false";
26
+ }
27
+
28
+ function requireValue(value: string | undefined, message: string): string {
29
+ if (!value || value.startsWith("--")) throw new Error(message);
30
+ return value;
31
+ }
32
+
33
+ function withoutFlag(args: string[], flag: string): { present: boolean; rest: string[] } {
34
+ return { present: args.includes(flag), rest: args.filter((arg) => arg !== flag) };
35
+ }
36
+
37
+ const CODEX_LIFECYCLE = new Set(["setup", "reconfigure", "pair", "start", "status", "stop", "recover", "uninstall"]);
38
+
39
+ export function parseFleetCommand(argv: string[]): FleetInvocation {
40
+ if (argv.length === 0 || argv[0].startsWith("--")) {
41
+ const c = capabilities(argv);
42
+ return { recipe: "_fleet-core", args: [bool(c.browser), bool(c.allExtensions), ...c.rest] };
43
+ }
44
+
45
+ const [mode, ...tail] = argv;
46
+ if (mode === "install") return { recipe: "_fleet-install", args: tail };
47
+
48
+ if (mode === "peer") {
49
+ const name = requireValue(tail[0], "fleet peer requires a peer name");
50
+ const c = capabilities(tail.slice(1));
51
+ return { recipe: "_fleet-peer", args: [name, bool(c.browser), bool(c.allExtensions), ...c.rest] };
52
+ }
53
+
54
+ if (mode === "hub") {
55
+ const solo = withoutFlag(tail, "--solo");
56
+ const c = capabilities(solo.rest);
57
+ return { recipe: "_fleet-hub", args: [bool(solo.present), bool(c.browser), bool(c.allExtensions), ...c.rest] };
58
+ }
59
+
60
+ if (mode === "team") {
61
+ const team = requireValue(tail[0], "fleet team requires a team preset");
62
+ const noHub = withoutFlag(tail.slice(1), "--no-hub");
63
+ const dry = withoutFlag(noHub.rest, "--dry-run");
64
+ const c = capabilities(dry.rest);
65
+ if (noHub.present && (c.browser || c.allExtensions)) {
66
+ throw new Error("--browser/--all-extensions requires the hub; peer capabilities belong in .pi/agents/peers.yaml");
67
+ }
68
+ const recipe = noHub.present
69
+ ? dry.present ? "_fleet-team-up-dry" : "_fleet-team-up"
70
+ : dry.present ? "_fleet-hub-team-dry" : "_fleet-hub-team";
71
+ const forwarded = [...c.rest];
72
+ if (c.browser) forwarded.push("--browser");
73
+ if (c.allExtensions) forwarded.push("--all-extensions");
74
+ return { recipe, args: [team, ...forwarded] };
75
+ }
76
+
77
+ if (mode === "snapshot" || mode === "down" || mode === "resume") {
78
+ const team = requireValue(tail[0], `fleet ${mode} requires a team preset`);
79
+ return { recipe: `_fleet-team-${mode === "snapshot" ? "snapshot" : mode}`, args: [team, ...tail.slice(1)] };
80
+ }
81
+
82
+ if (mode === "conductor") {
83
+ const backend = requireValue(tail[0], "fleet conductor requires hermes or codex");
84
+ if (backend !== "hermes" && backend !== "codex") throw new Error(`Unknown conductor backend: ${backend}`);
85
+ const rest = tail.slice(1);
86
+ if (backend === "hermes") {
87
+ const team = rest[0] && !rest[0].startsWith("--") ? rest[0] : "full";
88
+ const afterTeam = rest[0] === team ? rest.slice(1) : rest;
89
+ const dry = withoutFlag(afterTeam, "--dry-run");
90
+ return { recipe: dry.present ? "_fleet-conductor-dry" : "_fleet-conductor", args: [team, ...dry.rest] };
91
+ }
92
+
93
+ const action = rest[0];
94
+ if (action && CODEX_LIFECYCLE.has(action)) {
95
+ if (action === "setup" || action === "reconfigure") {
96
+ const team = rest[1] && !rest[1].startsWith("--") ? rest[1] : "full";
97
+ const afterTeam = rest[1] === team ? rest.slice(2) : rest.slice(1);
98
+ return { recipe: `_fleet-conductor-codex-${action}`, args: [team, ...afterTeam] };
99
+ }
100
+ return { recipe: `_fleet-conductor-codex-${action}`, args: rest.slice(1) };
101
+ }
102
+ const team = action && !action.startsWith("--") ? action : "full";
103
+ const afterTeam = action === team ? rest.slice(1) : rest;
104
+ const dry = withoutFlag(afterTeam, "--dry-run");
105
+ return { recipe: dry.present ? "_fleet-conductor-codex-dry" : "_fleet-conductor-codex", args: [team, ...dry.rest] };
106
+ }
107
+
108
+ throw new Error(`Unknown fleet mode: ${mode}`);
109
+ }
@@ -33,6 +33,7 @@ export interface QuestionOption {
33
33
 
34
34
  export interface HermesBridgeQuestion {
35
35
  qid: string;
36
+ project: string;
36
37
  question: string;
37
38
  context?: string;
38
39
  options?: QuestionOption[];
@@ -117,13 +118,15 @@ export function formatTelegramQuestion(input: HermesBridgeQuestion, limit = TELE
117
118
  if (!isValidQid(input.qid)) throw new Error("qid must be a 26-character Crockford ULID");
118
119
  const options = input.options ?? [];
119
120
  const header = `❓ [${HUB_Q_PREFIX}:${input.qid}] ${input.question}`;
121
+ const project = truncateUtf16(input.project.replace(/\s+/g, " ").trim() || "default", 128);
122
+ const projectBlock = `\n\n📁 Project: ${project}`;
120
123
  const optionsBlock = options.length > 0 ? `\n\nOptions:\n${formatOptions(options)}` : "";
121
124
  const instruction = `\n\n↩ Reply to this message, or type: ${HUB_Q_PREFIX}:${input.qid}: <answer>`;
122
125
  const contextPrefix = input.context ? "\n\nContext: " : "";
123
- const fixedLength = header.length + contextPrefix.length + optionsBlock.length + instruction.length;
126
+ const fixedLength = header.length + projectBlock.length + contextPrefix.length + optionsBlock.length + instruction.length;
124
127
  const contextBudget = Math.max(0, limit - fixedLength);
125
128
  const context = input.context ? truncateUtf16(input.context, contextBudget) : "";
126
- return truncateUtf16(`${header}${contextPrefix}${context}${optionsBlock}${instruction}`, limit);
129
+ return truncateUtf16(`${header}${projectBlock}${contextPrefix}${context}${optionsBlock}${instruction}`, limit);
127
130
  }
128
131
 
129
132
  export function mapAnswerToAskResponse(answer: string, options: QuestionOption[] = []): AskResponse {
@@ -1,28 +1,2 @@
1
- import { herdr, subscribe, type HerdrClientOptions, type SubscribeHandle } from "../../.pi/harnesses/lib/herdr-client.ts";
2
-
3
- export interface HubCorrelation { workspaceId?: string; hubPaneId?: string; status: "correlated" | "uncorrelated" | "reconnecting"; }
4
-
5
- export async function correlateHubPane(env: NodeJS.ProcessEnv = process.env, opts: HerdrClientOptions = {}): Promise<HubCorrelation> {
6
- const hubPaneId = env.HERDR_PANE_ID;
7
- if (env.HERDR_ENV !== "1" || !hubPaneId) return { status: "uncorrelated" };
8
- try { const { pane } = await herdr.paneGet(hubPaneId, { socketPath: env.HERDR_SOCKET_PATH, ...opts }); return { workspaceId: pane.workspace_id, hubPaneId, status: "correlated" }; }
9
- catch { return { hubPaneId, status: "reconnecting" }; }
10
- }
11
-
12
- export function watchHubMonitor(options: { env?: NodeJS.ProcessEnv; onStatus: (value: HubCorrelation) => void; onOutput?: (output: { sequence: number; text: string }) => void; initialCursor?: number; reconnectDelayMs?: number }): SubscribeHandle | null {
13
- const env = options.env ?? process.env;
14
- const paneId = env.HERDR_PANE_ID;
15
- if (env.HERDR_ENV !== "1" || !paneId) { options.onStatus({ status: "uncorrelated" }); return null; }
16
- let cursor = options.initialCursor ?? 0;
17
- const refresh = async () => {
18
- try {
19
- const { pane } = await herdr.paneGet(paneId, { socketPath: env.HERDR_SOCKET_PATH });
20
- options.onStatus({ workspaceId: pane.workspace_id, hubPaneId: paneId, status: "correlated" });
21
- const output = (pane as { monitor_resync_output?: { sequence?: number; text?: string } }).monitor_resync_output;
22
- if (output && typeof output.sequence === "number" && output.sequence > cursor && typeof output.text === "string") { cursor = output.sequence; options.onOutput?.({ sequence: output.sequence, text: output.text }); }
23
- } catch { options.onStatus({ hubPaneId: paneId, status: "reconnecting" }); }
24
- };
25
- void refresh();
26
- let connected = false;
27
- return subscribe([{ type: "pane.agent_status_changed", pane_id: paneId }], () => void refresh(), { socketPath: env.HERDR_SOCKET_PATH, reconnectDelayMs: options.reconnectDelayMs, onConnect: () => { if (connected) options.onStatus({ hubPaneId: paneId, status: "reconnecting" }); connected = true; void refresh(); }, onError: () => options.onStatus({ hubPaneId: paneId, status: "reconnecting" }) });
28
- }
1
+ // Compatibility surface for monitor scripts and existing imports.
2
+ export * from "../../.pi/harnesses/lib/hermes-monitor-herdr.ts";
@@ -1,9 +1,3 @@
1
- export type MonitorTaskState = "starting" | "running" | "cancelling" | "completed" | "blocked" | "failed" | "cancelled" | "orphaned" | "recovering";
2
- export const TERMINAL_TASK_STATES = new Set<MonitorTaskState>(["completed","blocked","failed","cancelled","orphaned"]);export type MonitorTaskKind="parent"|"child";
3
- export interface MonitorTask{id:string;generation:number;kind:MonitorTaskKind;state:MonitorTaskState;parentId?:string;parentGeneration?:number;hubInstanceId?:string;checkoutId?:string;specialist?:string;workspaceId?:string;hubPaneId?:string;ownerSessionId?:string;ownerLeaseExpiresAt?:string;}
4
- export interface CreateParentTaskInput{id:string;generation:number;hubInstanceId:string;checkoutId:string;ownerSessionId?:string;ownerLeaseExpiresAt?:string;}
5
- export interface CreateChildTaskInput{id:string;generation:number;parentId:string;parentGeneration:number;specialist:string;workspaceId?:string;hubPaneId?:string;ownerSessionId?:string;ownerLeaseExpiresAt?:string;}
6
- function requireStableIdentity(id:string,generation:number){if(!id)throw Error("task id is required");if(!Number.isInteger(generation)||generation<1)throw Error("task generation must be a positive integer");}const owner=(i:any)=>({...((i.ownerSessionId)?{ownerSessionId:i.ownerSessionId}:{}),...((i.ownerLeaseExpiresAt)?{ownerLeaseExpiresAt:i.ownerLeaseExpiresAt}:{})});
7
- export function createParentTask(input:CreateParentTaskInput):MonitorTask{requireStableIdentity(input.id,input.generation);if(!input.hubInstanceId||!input.checkoutId)throw Error("parent correlation is required");return{id:input.id,generation:input.generation,kind:"parent",state:"starting",hubInstanceId:input.hubInstanceId,checkoutId:input.checkoutId,...owner(input)};}
8
- export function createChildTask(input:CreateChildTaskInput):MonitorTask{requireStableIdentity(input.id,input.generation);if(!input.parentId||!Number.isInteger(input.parentGeneration)||input.parentGeneration<1||!input.specialist)throw Error("child hierarchy is required");return{id:input.id,generation:input.generation,kind:"child",state:"starting",parentId:input.parentId,parentGeneration:input.parentGeneration,specialist:input.specialist,...(input.workspaceId?{workspaceId:input.workspaceId}:{}),...(input.hubPaneId?{hubPaneId:input.hubPaneId}:{}),...owner(input)};}
9
- export function transitionTask(task:MonitorTask,state:MonitorTaskState):MonitorTask{if(TERMINAL_TASK_STATES.has(task.state))throw Error(`terminal task ${task.id} cannot mutate`);if(state==="starting")throw Error("tasks cannot transition back to starting");return{...task,state};}export function continueTask(task:MonitorTask):MonitorTask{if(task.state!=="blocked")throw Error(`only blocked task ${task.id} can continue`);return{...task,generation:task.generation+1,state:"starting"};}
1
+ // Canonical monitor runtime code lives with the Agent Hub harness so a
2
+ // symlinked package update refreshes the harness and its dependencies atomically.
3
+ export * from "../../.pi/harnesses/lib/hermes-monitor-model.ts";
@@ -1,6 +1,2 @@
1
- import * as crypto from "node:crypto"; import * as fs from "node:fs"; import * as path from "node:path";
2
- export interface MonitorRegistration {profileKey:string;namespacePath:string;socketPath:string;socketDir:string;token:string;namespaceMode:number;tokenMode:number;discoveryPath:string;snapshot():unknown;cancel?(r:{taskId:string;generation:number}):unknown|Promise<unknown>;output?(r:{taskId:string;generation:number;afterSequence:number}):unknown|Promise<unknown>;cleanup():void;renew():void;leaseMs:number;ownerId?:string;leaseExpiresAt?:string;}
3
- export interface MonitorRegistryOptions {runtimeDir:string;now?:()=>Date;pid?:number;leaseMs?:number;beforeRenewPublish?:()=>void;} export interface RegisterMonitorInput {profilePath:string;profileId?:string;hubInstanceId:string;snapshot:()=>unknown;}
4
- const D=0o700,F=0o600;const validDiscovery=(d:any)=>typeof d?.owner==="string"&&/^[0-9a-f-]{36}$/i.test(d.owner)&&typeof d.token==="string"&&/^token-[0-9a-f-]{36}$/i.test(d.token)&&typeof d.socket==="string"&&/^@runtime\/s\/[a-f0-9]+\/s$/.test(d.socket)&&typeof d.lease?.hub==="string"&&/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(d.lease.hub)&&Number.isInteger(d.lease?.pid)&&d.lease.pid>0&&typeof d.lease?.startedAt==="string"&&!Number.isNaN(Date.parse(d.lease.startedAt))&&typeof d.lease?.expiresAt==="string"&&!Number.isNaN(Date.parse(d.lease.expiresAt));const mode=(p:string)=>fs.statSync(p).mode&0o777;function dir(p:string){if(!path.isAbsolute(p))throw Error("monitor runtime directory must be absolute");fs.mkdirSync(p,{recursive:true,mode:D});if(fs.lstatSync(p).isSymbolicLink())throw Error("monitor runtime directory must not be a symlink");fs.chmodSync(p,D);}export function canonicalMonitorProfileId(id:string){if(!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(id)||id.includes(".."))throw Error("monitor profile id is unsafe");return crypto.createHash("sha256").update(id).digest("hex");}function profile(p:string,id?:string){if(id)return canonicalMonitorProfileId(id);const real=fs.realpathSync(p);if(!fs.statSync(real).isDirectory())throw Error("monitor profile path must be a directory");return crypto.createHash("sha256").update(real).digest("hex");}function hub(id:string){if(!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(id)||id.includes(".."))throw Error("hub instance id is unsafe");return crypto.createHash("sha256").update(id).digest("hex");}function atomic(p:string,s:string){const t=`${p}.${process.pid}.${crypto.randomBytes(4).toString("hex")}.tmp`;fs.writeFileSync(t,s,{mode:F,flag:"wx"});fs.chmodSync(t,F);fs.renameSync(t,p);}
5
- export class MonitorRegistry {private runtimeDir:string;private now:()=>Date;private pid:number;private leaseMs:number;private beforeRenewPublish?:()=>void;constructor(o:MonitorRegistryOptions){this.runtimeDir=o.runtimeDir;this.now=o.now??(()=>new Date());this.pid=o.pid??process.pid;this.leaseMs=o.leaseMs??30_000;this.beforeRenewPublish=o.beforeRenewPublish;dir(this.runtimeDir);}register(input:RegisterMonitorInput):MonitorRegistration{const key=profile(input.profilePath,input.profileId),h=hub(input.hubInstanceId),ns=path.join(this.runtimeDir,key,h);dir(path.join(this.runtimeDir,key));dir(ns);for(const file of fs.readdirSync(ns).filter(x=>x.startsWith("discovery-"))){const discoveryPath=path.join(ns,file);try{const d=JSON.parse(fs.readFileSync(discoveryPath,"utf8"));if(!validDiscovery(d)||d.token!==`token-${d.owner}`||d.socket!==`@runtime/s/${crypto.createHash("sha256").update(`${key}:${h}:${d.owner}`).digest("hex").slice(0,32)}/s`)throw new Error("monitor discovery metadata is malformed");if(new Date(d.lease?.expiresAt).getTime()>this.now().getTime()){const error:any=Error("monitor namespace is owned by an active lease");error.leaseExpiresAt=d.lease.expiresAt;throw error;}const tokenName=d.token;if(typeof tokenName==="string"&&/^token-[0-9a-f-]+$/.test(tokenName))try{fs.unlinkSync(path.join(ns,tokenName))}catch(e:any){if(e?.code!=="ENOENT")throw e;}fs.unlinkSync(discoveryPath);const socket=typeof d.socket==="string"?d.socket:"";if(socket.startsWith("@runtime/s/")&&socket.endsWith("/s")){const socketDir=path.join(this.runtimeDir,socket.slice("@runtime/".length,-2));if(socketDir.startsWith(path.join(this.runtimeDir,"s")+path.sep))try{fs.rmSync(socketDir,{recursive:true,force:true})}catch{}}}catch(e:any){if(/active lease|malformed/.test(String(e)))throw e;if(e instanceof SyntaxError||e instanceof TypeError||e instanceof RangeError)throw new Error("monitor discovery metadata is malformed");}}
6
- const owner=crypto.randomUUID(),socketDir=path.join(this.runtimeDir,"s",crypto.createHash("sha256").update(`${key}:${h}:${owner}`).digest("hex").slice(0,32));dir(socketDir);const tokenPath=path.join(ns,`token-${owner}`),discoveryPath=path.join(ns,`discovery-${owner}.json`),socketPath=path.join(socketDir,"s"),token=crypto.randomBytes(32).toString("hex"),started=this.now();atomic(tokenPath,token);const tokenFd=fs.openSync(tokenPath,"r");const write=(issued:Date)=>atomic(discoveryPath,JSON.stringify({owner,socket:`@runtime/s/${path.basename(socketDir)}/s`,token:path.basename(tokenPath),lease:{hub:input.hubInstanceId,pid:this.pid,startedAt:started.toISOString(),expiresAt:new Date(issued.getTime()+this.leaseMs).toISOString()}}));write(started);const owns=()=>{try{return fs.fstatSync(tokenFd).nlink===1&&fs.readFileSync(tokenPath,"utf8")===token&&JSON.parse(fs.readFileSync(discoveryPath,"utf8")).owner===owner;}catch{return false;}};const cleanup=()=>{if(!owns())return;for(const p of [tokenPath,discoveryPath])try{fs.unlinkSync(p)}catch(e:any){if(e?.code!=="ENOENT")throw e;}finally{try{fs.closeSync(tokenFd)}catch{}}};return{profileKey:key,ownerId:owner,leaseExpiresAt:new Date(started.getTime()+this.leaseMs).toISOString(),namespacePath:ns,socketPath,socketDir,token,namespaceMode:mode(ns),tokenMode:mode(tokenPath),discoveryPath,snapshot:input.snapshot,cleanup,renew:()=>{if(!owns())throw Error("monitor ownership lost");this.beforeRenewPublish?.();if(!owns())throw Error("monitor ownership lost");const renewedAt=this.now();write(renewedAt);if(!owns()){try{if(JSON.parse(fs.readFileSync(discoveryPath,"utf8")).owner===owner)fs.unlinkSync(discoveryPath)}catch{}throw Error("monitor ownership lost");}return{leaseExpiresAt:new Date(renewedAt.getTime()+this.leaseMs).toISOString()};},leaseMs:this.leaseMs};} evidenceForOwner(ownerId:string,hubInstanceId:string){try{if(!/^[0-9a-f-]{36}$/i.test(ownerId))throw Error("malformed");const h=hub(hubInstanceId);for(const profileKey of fs.readdirSync(this.runtimeDir)){const p=path.join(this.runtimeDir,profileKey,h,`discovery-${ownerId}.json`);if(!fs.existsSync(p))continue;const d=JSON.parse(fs.readFileSync(p,"utf8"));if(!validDiscovery(d)||d.owner!==ownerId||d.token!==`token-${ownerId}`)throw Error("malformed");const token=path.join(path.dirname(p),d.token),socket=path.join(this.runtimeDir,d.socket.slice("@runtime/".length));return{owner:fs.existsSync(token),socket:fs.existsSync(socket),session:fs.existsSync(token),expired:new Date(d.lease.expiresAt).getTime()<=this.now().getTime()};}return{owner:false,socket:false,session:false,expired:true};}catch(error){return{transient:true,error};}}}
1
+ // Compatibility surface for monitor scripts and existing imports.
2
+ export * from "../../.pi/harnesses/lib/hermes-monitor-registry.ts";
@@ -1,118 +1,2 @@
1
- import * as crypto from "node:crypto";
2
- import * as fs from "node:fs";
3
- import * as net from "node:net";
4
- import * as path from "node:path";
5
-
6
- import type { MonitorRegistration } from "./hermes-monitor-registry.ts";
7
-
8
- export const MAX_SOCKET_FRAME_BYTES = 64 * 1024;
9
- export const MAX_SNAPSHOT_BYTES = 256 * 1024;
10
- export const MAX_CANCEL_RESPONSE_BYTES = 16 * 1024;
11
- export const PARTIAL_FRAME_TIMEOUT_MS = 1000;
12
- export const MAX_SOCKET_CONNECTIONS = 32;
13
- export const MAX_TASK_ID_LENGTH = 128;
14
- export const MAX_AFTER_SEQUENCE = 1_000_000_000;
15
- /** 2 MiB covers the 256 KiB retained UTF-8 output after worst-case JSON escaping plus its envelope. */
16
- export const MAX_OUTPUT_RESPONSE_BYTES = 2 * 1024 * 1024;
17
-
18
- interface SnapshotRequest {
19
- type: "snapshot";
20
- token: string;
21
- }
22
-
23
- function authorized(actual: string, expected: string): boolean {
24
- const actualBytes = Buffer.from(actual);
25
- const expectedBytes = Buffer.from(expected);
26
- return actualBytes.length === expectedBytes.length && crypto.timingSafeEqual(actualBytes, expectedBytes);
27
- }
28
-
29
- function validTaskRequest(taskId: unknown, generation: unknown, afterSequence?: unknown): boolean { return typeof taskId === "string" && /^[A-Za-z0-9][A-Za-z0-9._:-]*$/.test(taskId) && taskId.length <= MAX_TASK_ID_LENGTH && Number.isInteger(generation) && (generation as number) >= 1 && (afterSequence === undefined || (Number.isInteger(afterSequence) && (afterSequence as number) >= 0 && (afterSequence as number) <= MAX_AFTER_SEQUENCE)); }
30
-
31
- function parseRequest(frame: string): SnapshotRequest | null {
32
- try {
33
- const value = JSON.parse(frame) as Partial<SnapshotRequest>;
34
- if (value.type !== "snapshot" || typeof value.token !== "string") return null;
35
- return { type: "snapshot", token: value.token };
36
- } catch {
37
- return null;
38
- }
39
- }
40
-
41
- export class MonitorSocketServer {
42
- private readonly registration: MonitorRegistration;
43
- private readonly server: net.Server;
44
- private connections = 0;
45
-
46
- constructor(registration: MonitorRegistration) {
47
- this.registration = registration;
48
- this.server = net.createServer((socket) => {
49
- if (this.connections >= MAX_SOCKET_CONNECTIONS) { socket.destroy(); return; }
50
- this.connections += 1;
51
- socket.once("close", () => { this.connections -= 1; });
52
- this.handle(socket);
53
- });
54
- }
55
-
56
- private assertOwnedSocketPath(): void {
57
- if (!this.registration.socketDir || path.resolve(this.registration.socketPath) !== path.join(path.resolve(this.registration.socketDir), "s")) throw new Error("monitor socket path is not registry-owned");
58
- if (fs.lstatSync(this.registration.socketDir).isSymbolicLink() || (fs.statSync(this.registration.socketDir).mode & 0o777) !== 0o700) throw new Error("monitor socket directory is unsafe");
59
- }
60
- private async removeVerifiedStaleSocket(): Promise<void> {
61
- this.assertOwnedSocketPath(); if (!fs.existsSync(this.registration.socketPath)) return;
62
- const active=await new Promise<boolean>(resolve=>{const probe=net.createConnection(this.registration.socketPath);probe.once("connect",()=>{probe.destroy();resolve(true);});probe.once("error",()=>resolve(false));});
63
- if (active) throw new Error("monitor socket is already active");
64
- if (fs.lstatSync(this.registration.socketPath).isSymbolicLink()) throw new Error("monitor socket must not be a symlink"); fs.unlinkSync(this.registration.socketPath);
65
- }
66
- async listen(): Promise<void> {
67
- await this.removeVerifiedStaleSocket(); return new Promise((resolve, reject) => { this.server.once("error", reject); this.server.listen(this.registration.socketPath, () => { this.server.off("error", reject); fs.chmodSync(this.registration.socketPath, 0o600); resolve(); }); });
68
- }
69
-
70
- async close(): Promise<void> {
71
- await new Promise<void>((resolve, reject) => this.server.close((error) => error ? reject(error) : resolve()));
72
- this.assertOwnedSocketPath(); try { fs.unlinkSync(this.registration.socketPath); } catch (error: any) { if (error?.code !== "ENOENT") throw error; }
73
- }
74
-
75
- mode(): number {
76
- return fs.statSync(this.registration.socketPath).mode & 0o777;
77
- }
78
-
79
- private handle(socket: net.Socket): void {
80
- let buffer = "";
81
- let handled = false;
82
- const deadline = setTimeout(() => { if (!handled) socket.destroy(); }, PARTIAL_FRAME_TIMEOUT_MS);
83
- socket.on("data", (chunk) => {
84
- if (handled) return;
85
- buffer += chunk.toString("utf8");
86
- if (Buffer.byteLength(buffer, "utf8") > MAX_SOCKET_FRAME_BYTES) {
87
- socket.destroy();
88
- return;
89
- }
90
- const newline = buffer.indexOf("\n");
91
- if (newline < 0) return;
92
- handled = true;
93
- const request = parseRequest(buffer.slice(0, newline));
94
- clearTimeout(deadline);
95
- let value: { type?: string; token?: string; taskId?: string; generation?: number };
96
- try { value = JSON.parse(buffer.slice(0, newline)) as typeof value; } catch { socket.destroy(); return; }
97
- if (value.type === "output") {
98
- if (!authorized(String(value.token ?? ""), this.registration.token)) { socket.end(JSON.stringify({ ok: false, error: "unauthorized" }) + "\n"); return; }
99
- if (!this.registration.output || (value as any).afterSequence === undefined || !validTaskRequest(value.taskId, value.generation, (value as any).afterSequence)) { socket.destroy(); return; }
100
- Promise.resolve().then(()=>this.registration.output!({ taskId: value.taskId!, generation: value.generation!, afterSequence: (value as any).afterSequence })).then((output) => { const body=JSON.stringify({ ok:true, output }); if(Buffer.byteLength(body)>MAX_OUTPUT_RESPONSE_BYTES) socket.end(JSON.stringify({ok:false,error:"response_too_large"})+"\n"); else socket.end(body+"\n"); }).catch(()=>socket.end(JSON.stringify({ok:false,error:"monitor_unavailable"})+"\n")); return;
101
- }
102
- if (value.type === "cancel") {
103
- if (!authorized(String(value.token ?? ""), this.registration.token)) { socket.end(JSON.stringify({ ok: false, error: "unauthorized" }) + "\n"); return; }
104
- if (!this.registration.cancel || !validTaskRequest(value.taskId, value.generation)) { socket.destroy(); return; }
105
- Promise.resolve().then(()=>this.registration.cancel!({ taskId: value.taskId!, generation: value.generation! })).then((result) => { const body=JSON.stringify({ ok: true, result }); if (Buffer.byteLength(body, "utf8") > MAX_CANCEL_RESPONSE_BYTES) socket.end(JSON.stringify({ok:false,error:"response_too_large"})+"\n"); else socket.end(body + "\n"); }).catch(()=>socket.end(JSON.stringify({ok:false,error:"monitor_unavailable"})+"\n")); return;
106
- }
107
- if (!request || !authorized(request.token, this.registration.token)) {
108
- if (request) socket.end(JSON.stringify({ ok: false, error: "unauthorized" }) + "\n");
109
- else socket.destroy();
110
- return;
111
- }
112
- try { const response = JSON.stringify({ ok: true, snapshot: this.registration.snapshot() }); if (Buffer.byteLength(response, "utf8") > MAX_SNAPSHOT_BYTES) socket.end(JSON.stringify({ok:false,error:"response_too_large"})+"\n"); else socket.end(response + "\n"); } catch { socket.end(JSON.stringify({ok:false,error:"monitor_unavailable"})+"\n"); }
113
- });
114
- socket.on("end", () => {
115
- if (!handled) socket.destroy();
116
- });
117
- }
118
- }
1
+ // Compatibility surface for monitor scripts and existing imports.
2
+ export * from "../../.pi/harnesses/lib/hermes-monitor-socket.ts";