@chankov/agent-fleet 0.0.2 → 0.0.4

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 (362) hide show
  1. package/.claude/commands/doctor-agent-fleet.md +1 -1
  2. package/.claude/commands/setup-agent-fleet.md +5 -5
  3. package/.opencode/commands/af-doctor-agent-fleet.md +2 -0
  4. package/.opencode/commands/af-setup-agent-fleet.md +1 -1
  5. package/.pi/agents/peers.yaml +4 -0
  6. package/.pi/agents/teams.yaml +2 -2
  7. package/.pi/harnesses/agent-hub/README.md +254 -18
  8. package/.pi/harnesses/agent-hub/access-approval.ts +135 -0
  9. package/.pi/harnesses/agent-hub/delegate.ts +32 -9
  10. package/.pi/harnesses/agent-hub/drift-watchdog.js +165 -0
  11. package/.pi/harnesses/agent-hub/footer.ts +29 -0
  12. package/.pi/harnesses/agent-hub/helpers.ts +49 -0
  13. package/.pi/harnesses/agent-hub/index.ts +1269 -322
  14. package/.pi/harnesses/agent-hub/monitor-control.ts +9 -0
  15. package/.pi/harnesses/agent-hub/monitor-lifecycle.ts +13 -0
  16. package/.pi/harnesses/agent-hub/monitor-publisher.ts +59 -0
  17. package/.pi/harnesses/agent-hub/monitor-recovery.ts +3 -0
  18. package/.pi/harnesses/agent-hub/monitor-runtime.ts +3 -0
  19. package/.pi/harnesses/agent-hub/monitor-session-bridge.ts +11 -0
  20. package/.pi/harnesses/agent-hub/package.json +5 -4
  21. package/.pi/harnesses/agent-hub/research-retention.js +34 -0
  22. package/.pi/harnesses/agent-hub/research-watchdog.ts +40 -0
  23. package/.pi/harnesses/agent-hub/run-budget.js +155 -0
  24. package/.pi/harnesses/agent-hub/safety-routing.ts +22 -0
  25. package/.pi/harnesses/agent-hub/spawn.ts +161 -94
  26. package/.pi/harnesses/agent-hub/version.ts +18 -0
  27. package/.pi/harnesses/ask-user-remote/README.md +2 -0
  28. package/.pi/harnesses/coms/README.md +21 -0
  29. package/.pi/harnesses/coms/index.ts +2 -0
  30. package/.pi/harnesses/coms/package.json +5 -4
  31. package/.pi/harnesses/coms/version.ts +18 -0
  32. package/.pi/harnesses/damage-control-continue/README.md +32 -31
  33. package/.pi/harnesses/damage-control-continue/index.ts +23 -9
  34. package/.pi/harnesses/damage-control-continue/package.json +5 -4
  35. package/.pi/harnesses/damage-control-continue/version.ts +18 -0
  36. package/.pi/harnesses/{damage-control/shared.ts → lib/damage-control-shared.ts} +20 -6
  37. package/.pi/prompts/doctor-agent-fleet.md +1 -1
  38. package/.pi/prompts/setup-agent-fleet.md +5 -5
  39. package/.versions/0.0.4/.claude/commands/build.md +44 -0
  40. package/.versions/0.0.4/.claude/commands/code-simplify.md +22 -0
  41. package/.versions/0.0.4/.claude/commands/design-agent.md +14 -0
  42. package/.versions/0.0.4/.claude/commands/doctor-agent-fleet.md +17 -0
  43. package/.versions/0.0.4/.claude/commands/orchestrate.md +112 -0
  44. package/.versions/0.0.4/.claude/commands/plan.md +16 -0
  45. package/.versions/0.0.4/.claude/commands/prime.md +22 -0
  46. package/.versions/0.0.4/.claude/commands/review.md +16 -0
  47. package/.versions/0.0.4/.claude/commands/setup-agent-fleet.md +25 -0
  48. package/.versions/0.0.4/.claude/commands/ship.md +72 -0
  49. package/.versions/0.0.4/.claude/commands/spec.md +15 -0
  50. package/.versions/0.0.4/.claude/commands/test.md +19 -0
  51. package/.versions/0.0.4/.claude/commands/webperf.md +32 -0
  52. package/.versions/0.0.4/.claude/orchestrate-teams.yaml +24 -0
  53. package/.versions/0.0.4/.opencode/commands/af-build.md +17 -0
  54. package/.versions/0.0.4/.opencode/commands/af-code-simplify.md +16 -0
  55. package/.versions/0.0.4/.opencode/commands/af-compound.md +16 -0
  56. package/.versions/0.0.4/.opencode/commands/af-design-agent.md +15 -0
  57. package/.versions/0.0.4/.opencode/commands/af-doctor-agent-fleet.md +17 -0
  58. package/.versions/0.0.4/.opencode/commands/af-orchestrate.md +112 -0
  59. package/.versions/0.0.4/.opencode/commands/af-plan.md +16 -0
  60. package/.versions/0.0.4/.opencode/commands/af-prime.md +22 -0
  61. package/.versions/0.0.4/.opencode/commands/af-review.md +15 -0
  62. package/.versions/0.0.4/.opencode/commands/af-setup-agent-fleet.md +15 -0
  63. package/.versions/0.0.4/.opencode/commands/af-ship.md +16 -0
  64. package/.versions/0.0.4/.opencode/commands/af-spec.md +16 -0
  65. package/.versions/0.0.4/.opencode/commands/af-test.md +21 -0
  66. package/.versions/0.0.4/.opencode/commands/af-webperf.md +32 -0
  67. package/.versions/0.0.4/.opencode/orchestrate-teams.yaml +24 -0
  68. package/.versions/0.0.4/.pi/agents/dispatch-policy.yaml +32 -0
  69. package/.versions/0.0.4/.pi/agents/model-profiles.yaml +20 -0
  70. package/.versions/0.0.4/.pi/agents/peers.yaml +146 -0
  71. package/.versions/0.0.4/.pi/agents/teams.yaml +39 -0
  72. package/.versions/0.0.4/.pi/damage-control-rules.yaml +297 -0
  73. package/.versions/0.0.4/.pi/extensions/agent-fleet-update-check/README.md +58 -0
  74. package/.versions/0.0.4/.pi/extensions/agent-fleet-update-check/index.ts +161 -0
  75. package/{.pi/harnesses/damage-control → .versions/0.0.4/.pi/extensions/agent-fleet-update-check}/package.json +1 -1
  76. package/.versions/0.0.4/.pi/extensions/btw/README.md +118 -0
  77. package/.versions/0.0.4/.pi/extensions/btw/index.ts +917 -0
  78. package/.versions/0.0.4/.pi/extensions/btw/package.json +6 -0
  79. package/.versions/0.0.4/.pi/extensions/btw/state.js +179 -0
  80. package/.versions/0.0.4/.pi/extensions/chrome-devtools-mcp/README.md +58 -0
  81. package/.versions/0.0.4/.pi/extensions/chrome-devtools-mcp/index.ts +92 -0
  82. package/.versions/0.0.4/.pi/extensions/chrome-devtools-mcp/package.json +6 -0
  83. package/.versions/0.0.4/.pi/extensions/compact-and-continue/README.md +42 -0
  84. package/.versions/0.0.4/.pi/extensions/compact-and-continue/index.ts +120 -0
  85. package/.versions/0.0.4/.pi/extensions/compact-and-continue/package.json +6 -0
  86. package/.versions/0.0.4/.pi/extensions/mcp-bridge/README.md +46 -0
  87. package/.versions/0.0.4/.pi/extensions/mcp-bridge/index.ts +206 -0
  88. package/.versions/0.0.4/.pi/extensions/mcp-bridge/package.json +6 -0
  89. package/.versions/0.0.4/.pi/extensions/package-lock.json +1143 -0
  90. package/.versions/0.0.4/.pi/extensions/package.json +9 -0
  91. package/.versions/0.0.4/.pi/extensions/pi-voice-stt/README.md +201 -0
  92. package/.versions/0.0.4/.pi/extensions/pi-voice-stt/config.ts +198 -0
  93. package/.versions/0.0.4/.pi/extensions/pi-voice-stt/examples/stt.json +35 -0
  94. package/.versions/0.0.4/.pi/extensions/pi-voice-stt/index.ts +248 -0
  95. package/.versions/0.0.4/.pi/extensions/pi-voice-stt/package.json +6 -0
  96. package/.versions/0.0.4/.pi/extensions/pi-voice-stt/providers.ts +214 -0
  97. package/.versions/0.0.4/.pi/extensions/pi-voice-stt/recorder.ts +158 -0
  98. package/.versions/0.0.4/.pi/harnesses/agent-hub/README.md +798 -0
  99. package/.versions/0.0.4/.pi/harnesses/agent-hub/access-approval.ts +135 -0
  100. package/.versions/0.0.4/.pi/harnesses/agent-hub/artifacts.js +92 -0
  101. package/.versions/0.0.4/.pi/harnesses/agent-hub/backend-policy.js +153 -0
  102. package/.versions/0.0.4/.pi/harnesses/agent-hub/delegate.ts +386 -0
  103. package/.versions/0.0.4/.pi/harnesses/agent-hub/drift-watchdog.js +165 -0
  104. package/.versions/0.0.4/.pi/harnesses/agent-hub/evidence-rules.js +96 -0
  105. package/.versions/0.0.4/.pi/harnesses/agent-hub/footer.ts +29 -0
  106. package/.versions/0.0.4/.pi/harnesses/agent-hub/helpers.ts +214 -0
  107. package/.versions/0.0.4/.pi/harnesses/agent-hub/index.ts +8045 -0
  108. package/.versions/0.0.4/.pi/harnesses/agent-hub/monitor-control.ts +9 -0
  109. package/.versions/0.0.4/.pi/harnesses/agent-hub/monitor-lifecycle.ts +13 -0
  110. package/.versions/0.0.4/.pi/harnesses/agent-hub/monitor-publisher.ts +59 -0
  111. package/.versions/0.0.4/.pi/harnesses/agent-hub/monitor-recovery.ts +3 -0
  112. package/.versions/0.0.4/.pi/harnesses/agent-hub/monitor-runtime.ts +3 -0
  113. package/.versions/0.0.4/.pi/harnesses/agent-hub/monitor-session-bridge.ts +11 -0
  114. package/.versions/0.0.4/.pi/harnesses/agent-hub/package.json +7 -0
  115. package/.versions/0.0.4/.pi/harnesses/agent-hub/research-retention.js +34 -0
  116. package/.versions/0.0.4/.pi/harnesses/agent-hub/research-watchdog.ts +40 -0
  117. package/.versions/0.0.4/.pi/harnesses/agent-hub/return-contract.js +215 -0
  118. package/.versions/0.0.4/.pi/harnesses/agent-hub/run-budget.js +155 -0
  119. package/.versions/0.0.4/.pi/harnesses/agent-hub/safety-routing.ts +22 -0
  120. package/.versions/0.0.4/.pi/harnesses/agent-hub/scope-gate.js +103 -0
  121. package/.versions/0.0.4/.pi/harnesses/agent-hub/spawn.ts +246 -0
  122. package/.versions/0.0.4/.pi/harnesses/agent-hub/version.ts +18 -0
  123. package/.versions/0.0.4/.pi/harnesses/ask-user-remote/README.md +18 -0
  124. package/.versions/0.0.4/.pi/harnesses/ask-user-remote/index.ts +293 -0
  125. package/.versions/0.0.4/.pi/harnesses/ask-user-remote/race-core.js +106 -0
  126. package/.versions/0.0.4/.pi/harnesses/coms/README.md +92 -0
  127. package/.versions/0.0.4/.pi/harnesses/coms/index.ts +1745 -0
  128. package/.versions/0.0.4/.pi/harnesses/coms/package.json +7 -0
  129. package/.versions/0.0.4/.pi/harnesses/coms/version.ts +18 -0
  130. package/.versions/0.0.4/.pi/harnesses/damage-control-continue/README.md +117 -0
  131. package/.versions/0.0.4/.pi/harnesses/damage-control-continue/index.ts +536 -0
  132. package/.versions/0.0.4/.pi/harnesses/damage-control-continue/package.json +7 -0
  133. package/.versions/0.0.4/.pi/harnesses/damage-control-continue/version.ts +18 -0
  134. package/.versions/0.0.4/.pi/harnesses/lib/damage-control-shared.ts +197 -0
  135. package/.versions/0.0.4/.pi/harnesses/lib/herdr-client.ts +458 -0
  136. package/.versions/0.0.4/.pi/harnesses/lib/herdr-presence.ts +288 -0
  137. package/.versions/0.0.4/.pi/harnesses/package-lock.json +35 -0
  138. package/.versions/0.0.4/.pi/harnesses/package.json +9 -0
  139. package/.versions/0.0.4/.pi/prompts/build.md +24 -0
  140. package/.versions/0.0.4/.pi/prompts/code-simplify.md +22 -0
  141. package/.versions/0.0.4/.pi/prompts/doctor-agent-fleet.md +15 -0
  142. package/.versions/0.0.4/.pi/prompts/plan.md +16 -0
  143. package/.versions/0.0.4/.pi/prompts/review.md +16 -0
  144. package/.versions/0.0.4/.pi/prompts/setup-agent-fleet.md +27 -0
  145. package/.versions/0.0.4/.pi/prompts/ship.md +17 -0
  146. package/.versions/0.0.4/.pi/prompts/spec.md +15 -0
  147. package/.versions/0.0.4/.pi/prompts/test.md +19 -0
  148. package/.versions/0.0.4/.pi/skills/bowser/SKILL.md +145 -0
  149. package/.versions/0.0.4/.version +1 -0
  150. package/.versions/0.0.4/agents/architect.md +23 -0
  151. package/.versions/0.0.4/agents/bowser.md +26 -0
  152. package/.versions/0.0.4/agents/builder.md +53 -0
  153. package/.versions/0.0.4/agents/code-reviewer.md +205 -0
  154. package/.versions/0.0.4/agents/deep-researcher.md +31 -0
  155. package/.versions/0.0.4/agents/documenter.md +18 -0
  156. package/.versions/0.0.4/agents/orchestrator.md +54 -0
  157. package/.versions/0.0.4/agents/plan-reviewer.md +60 -0
  158. package/.versions/0.0.4/agents/planner.md +69 -0
  159. package/.versions/0.0.4/agents/releaser.md +24 -0
  160. package/.versions/0.0.4/agents/researcher.md +28 -0
  161. package/.versions/0.0.4/agents/security-auditor.md +166 -0
  162. package/.versions/0.0.4/agents/test-engineer.md +151 -0
  163. package/.versions/0.0.4/agents/web-debugger.md +42 -0
  164. package/.versions/0.0.4/agents/web-performance-auditor.md +192 -0
  165. package/.versions/0.0.4/codex/CONDUCTOR.md +148 -0
  166. package/.versions/0.0.4/docs/ARCHITECTURE.md +210 -0
  167. package/.versions/0.0.4/docs/agent-fleet-setup.md +366 -0
  168. package/.versions/0.0.4/docs/claude-code-coms-bridge.md +103 -0
  169. package/.versions/0.0.4/docs/codex-remote-conductor.md +170 -0
  170. package/.versions/0.0.4/docs/coms-hermes-bridge.md +121 -0
  171. package/.versions/0.0.4/docs/getting-started.md +183 -0
  172. package/.versions/0.0.4/docs/npm-install.md +337 -0
  173. package/.versions/0.0.4/docs/opencode-setup.md +248 -0
  174. package/.versions/0.0.4/docs/pi-extensions.md +288 -0
  175. package/.versions/0.0.4/docs/pi-setup.md +463 -0
  176. package/.versions/0.0.4/docs/skill-anatomy.md +150 -0
  177. package/.versions/0.0.4/hermes/README.md +228 -0
  178. package/.versions/0.0.4/hermes/desktop-plugins/agent-fleet-monitor/plugin.js +19 -0
  179. package/.versions/0.0.4/hermes/desktop-plugins/agent-fleet-monitor/state.js +10 -0
  180. package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/adapter-cap.test.py +15 -0
  181. package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/adapter-discovery.test.py +19 -0
  182. package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/adapter-envelope.test.py +13 -0
  183. package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/adapter-forged-owner.test.py +11 -0
  184. package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/adapter-lease-list.test.py +9 -0
  185. package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/adapter-multihub.test.py +17 -0
  186. package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/adapter-output.test.py +34 -0
  187. package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/adapter.py +151 -0
  188. package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/adapter.test.py +39 -0
  189. package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/manifest.json +11 -0
  190. package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/plugin-api-validation.test.py +12 -0
  191. package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/plugin_api.py +50 -0
  192. package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/review-live-wiring.red.test.py +22 -0
  193. package/.versions/0.0.4/hermes/skills/hub-conductor/SKILL.md +84 -0
  194. package/.versions/0.0.4/hermes/skills/hub-liaison/SKILL.md +84 -0
  195. package/.versions/0.0.4/hooks/SIMPLIFY-IGNORE.md +90 -0
  196. package/.versions/0.0.4/hooks/coms-stop-hook.mjs +73 -0
  197. package/.versions/0.0.4/hooks/hooks.json +14 -0
  198. package/.versions/0.0.4/hooks/session-start.sh +74 -0
  199. package/.versions/0.0.4/hooks/simplify-ignore.sh +302 -0
  200. package/.versions/0.0.4/justfile +256 -0
  201. package/.versions/0.0.4/references/accessibility-checklist.md +160 -0
  202. package/.versions/0.0.4/references/definition-of-done.md +67 -0
  203. package/.versions/0.0.4/references/fleet-coordination-patterns.md +151 -0
  204. package/.versions/0.0.4/references/observability-checklist.md +91 -0
  205. package/.versions/0.0.4/references/orchestration-patterns.md +370 -0
  206. package/.versions/0.0.4/references/performance-checklist.md +153 -0
  207. package/.versions/0.0.4/references/prompting-patterns.md +380 -0
  208. package/.versions/0.0.4/references/security-checklist.md +179 -0
  209. package/.versions/0.0.4/references/testing-patterns.md +236 -0
  210. package/.versions/0.0.4/scripts/codex-conductor.ts +41 -0
  211. package/.versions/0.0.4/scripts/codex-remote-control.ts +167 -0
  212. package/.versions/0.0.4/scripts/coms-claude-bridge.ts +286 -0
  213. package/.versions/0.0.4/scripts/coms-cli.ts +484 -0
  214. package/.versions/0.0.4/scripts/coms-hermes-bridge.ts +403 -0
  215. package/.versions/0.0.4/scripts/hermes-monitor-capability-runner.ts +25 -0
  216. package/.versions/0.0.4/scripts/hermes-monitor-scenario.ts +7 -0
  217. package/.versions/0.0.4/scripts/lib/claude-bridge-core.ts +100 -0
  218. package/.versions/0.0.4/scripts/lib/codex-conductor.ts +88 -0
  219. package/.versions/0.0.4/scripts/lib/codex-remote-control.ts +480 -0
  220. package/.versions/0.0.4/scripts/lib/coms-envelope.ts +539 -0
  221. package/.versions/0.0.4/scripts/lib/fake-herdr-server.ts +88 -0
  222. package/.versions/0.0.4/scripts/lib/herdr-layout.ts +263 -0
  223. package/.versions/0.0.4/scripts/lib/hermes-bridge-core.ts +238 -0
  224. package/.versions/0.0.4/scripts/lib/hermes-monitor-herdr.ts +28 -0
  225. package/.versions/0.0.4/scripts/lib/hermes-monitor-model.ts +9 -0
  226. package/.versions/0.0.4/scripts/lib/hermes-monitor-registry.ts +6 -0
  227. package/.versions/0.0.4/scripts/lib/hermes-monitor-socket.ts +118 -0
  228. package/.versions/0.0.4/scripts/lib/hermes-monitor-store.ts +31 -0
  229. package/.versions/0.0.4/scripts/lib/persona-banner.ts +62 -0
  230. package/.versions/0.0.4/scripts/lib/spawn-stagger.ts +101 -0
  231. package/.versions/0.0.4/scripts/lib/team-project.ts +184 -0
  232. package/.versions/0.0.4/scripts/lib/team-snapshot.ts +147 -0
  233. package/.versions/0.0.4/scripts/peer-banner.ts +40 -0
  234. package/.versions/0.0.4/scripts/team-snapshot.ts +238 -0
  235. package/.versions/0.0.4/scripts/team-up.ts +333 -0
  236. package/.versions/0.0.4/skills/_internal/grilling.md +11 -0
  237. package/.versions/0.0.4/skills/browser-testing-with-devtools/SKILL.md +352 -0
  238. package/.versions/0.0.4/skills/code-review-and-quality/SKILL.md +381 -0
  239. package/.versions/0.0.4/skills/compound-learning/SKILL.md +137 -0
  240. package/.versions/0.0.4/skills/context-engineering/SKILL.md +291 -0
  241. package/.versions/0.0.4/skills/deprecation-and-migration/SKILL.md +206 -0
  242. package/.versions/0.0.4/skills/designing-agents/SKILL.md +394 -0
  243. package/.versions/0.0.4/skills/designing-agents/pi-harness-authoring.md +222 -0
  244. package/.versions/0.0.4/skills/frontend-ui-engineering/SKILL.md +328 -0
  245. package/.versions/0.0.4/skills/git-workflow-and-versioning/SKILL.md +316 -0
  246. package/.versions/0.0.4/skills/guided-workspace-setup/SKILL.md +535 -0
  247. package/.versions/0.0.4/skills/guided-workspace-setup/companion-manifest.json +33 -0
  248. package/.versions/0.0.4/skills/idea-refine/SKILL.md +182 -0
  249. package/.versions/0.0.4/skills/idea-refine/examples.md +238 -0
  250. package/.versions/0.0.4/skills/idea-refine/frameworks.md +99 -0
  251. package/.versions/0.0.4/skills/idea-refine/refinement-criteria.md +113 -0
  252. package/.versions/0.0.4/skills/idea-refine/scripts/idea-refine.sh +15 -0
  253. package/.versions/0.0.4/skills/incremental-implementation/SKILL.md +287 -0
  254. package/.versions/0.0.4/skills/interview-me/SKILL.md +226 -0
  255. package/.versions/0.0.4/skills/orchestration-verification/SKILL.md +181 -0
  256. package/.versions/0.0.4/skills/peer-coms/SKILL.md +90 -0
  257. package/.versions/0.0.4/skills/performance-optimization/SKILL.md +350 -0
  258. package/.versions/0.0.4/skills/planning-and-task-breakdown/SKILL.md +236 -0
  259. package/.versions/0.0.4/skills/security-and-hardening/SKILL.md +461 -0
  260. package/.versions/0.0.4/skills/spec-driven-development/SKILL.md +245 -0
  261. package/.versions/0.0.4/skills/using-agent-skills/SKILL.md +199 -0
  262. package/.versions/0.0.4/systemd/user/agent-fleet-codex-remote-control.service.in +23 -0
  263. package/.versions/0.0.4/vendor/agent-skills-upstream/LICENSE +21 -0
  264. package/.versions/0.0.4/vendor/agent-skills-upstream/README.md +11 -0
  265. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/api-and-interface-design/SKILL.md +294 -0
  266. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/browser-testing-with-devtools/SKILL.md +317 -0
  267. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/ci-cd-and-automation/SKILL.md +390 -0
  268. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/code-review-and-quality/SKILL.md +396 -0
  269. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/code-simplification/SKILL.md +331 -0
  270. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/context-engineering/SKILL.md +289 -0
  271. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/debugging-and-error-recovery/SKILL.md +300 -0
  272. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/deprecation-and-migration/SKILL.md +247 -0
  273. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/documentation-and-adrs/SKILL.md +278 -0
  274. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/doubt-driven-development/SKILL.md +243 -0
  275. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/frontend-ui-engineering/SKILL.md +328 -0
  276. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/git-workflow-and-versioning/SKILL.md +355 -0
  277. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/idea-refine/SKILL.md +178 -0
  278. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/idea-refine/examples.md +238 -0
  279. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/idea-refine/frameworks.md +99 -0
  280. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/idea-refine/refinement-criteria.md +113 -0
  281. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/idea-refine/scripts/idea-refine.sh +15 -0
  282. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/incremental-implementation/SKILL.md +249 -0
  283. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/interview-me/SKILL.md +225 -0
  284. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/observability-and-instrumentation/SKILL.md +203 -0
  285. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/performance-optimization/SKILL.md +350 -0
  286. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/planning-and-task-breakdown/SKILL.md +234 -0
  287. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/security-and-hardening/SKILL.md +467 -0
  288. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/shipping-and-launch/SKILL.md +310 -0
  289. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/source-driven-development/SKILL.md +194 -0
  290. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/spec-driven-development/SKILL.md +206 -0
  291. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/test-driven-development/SKILL.md +383 -0
  292. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/using-agent-skills/SKILL.md +191 -0
  293. package/CHANGELOG.md +53 -0
  294. package/README.md +103 -541
  295. package/agents/architect.md +1 -1
  296. package/agents/builder.md +1 -1
  297. package/agents/code-reviewer.md +1 -1
  298. package/agents/deep-researcher.md +3 -3
  299. package/agents/orchestrator.md +20 -11
  300. package/agents/plan-reviewer.md +3 -3
  301. package/agents/planner.md +1 -1
  302. package/agents/security-auditor.md +1 -1
  303. package/agents/test-engineer.md +11 -4
  304. package/bin/lib/validate-overrides.js +19 -0
  305. package/bin/snapshot-version.js +17 -1
  306. package/bin/sync-harness-versions.js +94 -0
  307. package/codex/CONDUCTOR.md +148 -0
  308. package/docs/ARCHITECTURE.md +210 -0
  309. package/docs/agent-fleet-setup.md +11 -0
  310. package/docs/claude-code-coms-bridge.md +10 -0
  311. package/docs/codex-remote-conductor.md +170 -0
  312. package/docs/coms-hermes-bridge.md +121 -0
  313. package/docs/getting-started.md +14 -0
  314. package/docs/npm-install.md +2 -0
  315. package/docs/pi-extensions.md +49 -14
  316. package/docs/pi-setup.md +12 -4
  317. package/hermes/README.md +228 -0
  318. package/hermes/desktop-plugins/agent-fleet-monitor/plugin.js +19 -0
  319. package/hermes/desktop-plugins/agent-fleet-monitor/state.js +10 -0
  320. package/hermes/plugins/agent-fleet-monitor/dashboard/adapter-cap.test.py +15 -0
  321. package/hermes/plugins/agent-fleet-monitor/dashboard/adapter-discovery.test.py +19 -0
  322. package/hermes/plugins/agent-fleet-monitor/dashboard/adapter-envelope.test.py +13 -0
  323. package/hermes/plugins/agent-fleet-monitor/dashboard/adapter-forged-owner.test.py +11 -0
  324. package/hermes/plugins/agent-fleet-monitor/dashboard/adapter-lease-list.test.py +9 -0
  325. package/hermes/plugins/agent-fleet-monitor/dashboard/adapter-multihub.test.py +17 -0
  326. package/hermes/plugins/agent-fleet-monitor/dashboard/adapter-output.test.py +34 -0
  327. package/hermes/plugins/agent-fleet-monitor/dashboard/adapter.py +151 -0
  328. package/hermes/plugins/agent-fleet-monitor/dashboard/adapter.test.py +39 -0
  329. package/hermes/plugins/agent-fleet-monitor/dashboard/dist/index.js +10 -0
  330. package/hermes/plugins/agent-fleet-monitor/dashboard/manifest.json +11 -0
  331. package/hermes/plugins/agent-fleet-monitor/dashboard/plugin-api-validation.test.py +12 -0
  332. package/hermes/plugins/agent-fleet-monitor/dashboard/plugin_api.py +50 -0
  333. package/hermes/plugins/agent-fleet-monitor/dashboard/review-live-wiring.red.test.py +22 -0
  334. package/hermes/skills/hub-conductor/SKILL.md +84 -0
  335. package/hermes/skills/hub-liaison/SKILL.md +84 -0
  336. package/justfile +106 -23
  337. package/package.json +17 -5
  338. package/scripts/codex-conductor.ts +41 -0
  339. package/scripts/codex-remote-control.ts +167 -0
  340. package/scripts/coms-cli.ts +311 -199
  341. package/scripts/coms-hermes-bridge.ts +2 -2
  342. package/scripts/lib/codex-conductor.ts +88 -0
  343. package/scripts/lib/codex-remote-control.ts +480 -0
  344. package/scripts/lib/coms-envelope.ts +51 -6
  345. package/scripts/lib/fake-herdr-server.ts +88 -0
  346. package/scripts/lib/herdr-layout.ts +18 -3
  347. package/scripts/lib/hermes-bridge-core.ts +4 -4
  348. package/scripts/lib/hermes-monitor-herdr.ts +28 -0
  349. package/scripts/lib/hermes-monitor-model.ts +9 -0
  350. package/scripts/lib/hermes-monitor-registry.ts +6 -0
  351. package/scripts/lib/hermes-monitor-socket.ts +118 -0
  352. package/scripts/lib/hermes-monitor-store.ts +31 -0
  353. package/scripts/lib/team-project.ts +85 -1
  354. package/scripts/team-up.ts +77 -18
  355. package/skills/designing-agents/SKILL.md +2 -2
  356. package/skills/designing-agents/pi-harness-authoring.md +26 -13
  357. package/skills/guided-workspace-setup/SKILL.md +131 -102
  358. package/skills/guided-workspace-setup/companion-manifest.json +33 -0
  359. package/skills/peer-coms/SKILL.md +9 -0
  360. package/systemd/user/agent-fleet-codex-remote-control.service.in +23 -0
  361. package/.pi/harnesses/damage-control/README.md +0 -65
  362. package/.pi/harnesses/damage-control/index.ts +0 -250
@@ -0,0 +1,263 @@
1
+ // scripts/lib/herdr-layout.ts
2
+ //
3
+ // Pure logic for the herdr fleet recipes: peers.yaml parsing, peer→command
4
+ // construction, and peers.yaml team → herdr declarative layout tree (BSP
5
+ // splits, one pane per peer). No pi imports, no sockets, no process.exit —
6
+ // everything throws plain Errors so callers decide how to die. Testable
7
+ // under node --test; the wiring (requireHerdr, workspace.create,
8
+ // layout.apply) lives in scripts/team-up.ts.
9
+
10
+ import { resolve as resolvePath } from "node:path";
11
+
12
+ import type { LayoutNode } from "../../.pi/harnesses/lib/herdr-client.ts";
13
+ import { STAGGER_ENV_VAR } from "./spawn-stagger.ts";
14
+ import { DEFAULT_PROJECT, validateProject } from "./team-project.ts";
15
+
16
+ export type { LayoutNode };
17
+
18
+ // Safe charset for any value spliced into a command line or layout — the
19
+ // peers.yaml file is user-edited, so every manifest value is validated.
20
+ export const SAFE = /^[A-Za-z0-9._/,-]+$/;
21
+
22
+ export interface Peer {
23
+ name?: string;
24
+ persona?: string;
25
+ model?: string;
26
+ // Optional comma-separated extension names under .pi/extensions/ to load into
27
+ // this peer (routes it through `just _peer-plus` instead of `just _peer`).
28
+ extensions?: string;
29
+ // Optional repo-relative KEY=VALUE file injected as the pane's env at spawn
30
+ // (herdr injects it before the command runs — no shell `source`).
31
+ env_file?: string;
32
+ // Optional runner. Default (absent) is a pi peer via `_peer`/`_peer-plus`;
33
+ // "claude-code" spawns an interactive Claude Code plus its coms bridge in
34
+ // the pane via `_claude-peer` (model → `claude --model`).
35
+ runner?: string;
36
+ }
37
+
38
+ function stripQuotes(v: string): string {
39
+ if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) {
40
+ return v.slice(1, -1);
41
+ }
42
+ return v;
43
+ }
44
+
45
+ // Minimal parser for the specific peers.yaml shape (team → list of {name,persona,model}).
46
+ // Not a general YAML parser; tolerant of comments and blank lines only.
47
+ export function parsePeersYaml(raw: string): Record<string, Peer[]> {
48
+ const teams: Record<string, Peer[]> = {};
49
+ let currentTeam: string | null = null;
50
+ let currentPeer: Peer | null = null;
51
+
52
+ for (const rawLine of raw.split("\n")) {
53
+ const line = rawLine.replace(/\s+$/, "");
54
+ if (line.trim() === "" || /^\s*#/.test(line)) continue;
55
+ const indent = line.length - line.trimStart().length;
56
+ const content = line.trim();
57
+
58
+ if (indent === 0) {
59
+ const m = content.match(/^([A-Za-z0-9_-]+):\s*$/);
60
+ if (m) {
61
+ currentTeam = m[1];
62
+ teams[currentTeam] = [];
63
+ currentPeer = null;
64
+ }
65
+ continue;
66
+ }
67
+ if (!currentTeam) continue;
68
+
69
+ const itemM = content.match(/^-\s*([A-Za-z0-9_]+):\s*(.+)$/);
70
+ if (itemM) {
71
+ currentPeer = {};
72
+ teams[currentTeam].push(currentPeer);
73
+ (currentPeer as Record<string, string>)[itemM[1]] = stripQuotes(itemM[2]);
74
+ continue;
75
+ }
76
+ const fieldM = content.match(/^([A-Za-z0-9_]+):\s*(.+)$/);
77
+ if (fieldM && currentPeer) {
78
+ (currentPeer as Record<string, string>)[fieldM[1]] = stripQuotes(fieldM[2]);
79
+ }
80
+ }
81
+ return teams;
82
+ }
83
+
84
+ // Validate a peer's fields and build its launch argv. `just` recipe params are
85
+ // POSITIONAL (persona name model session) — bare positional args, never
86
+ // key=value. A peer with `extensions:` routes through `_peer-plus
87
+ // <extensions> <persona> <name> [<model>] [<session>]`; otherwise plain
88
+ // `_peer <persona> <name> [<model>] [<session>]`. `resumeRef` (a pi session
89
+ // path for `pi --session`) fills the trailing session positional — when the
90
+ // peer has no model, an empty-string placeholder keeps the positions aligned.
91
+ export function peerCommand(p: Peer, team: string, resumeRef?: string, project = DEFAULT_PROJECT): string[] {
92
+ validateProject(project);
93
+ if (p.runner !== undefined && p.runner !== "claude-code") {
94
+ throw new Error(`Unknown runner "${p.runner}" for peer "${p.name}" in team "${team}" (supported: claude-code).`);
95
+ }
96
+ if (!p.persona && p.runner !== "claude-code") {
97
+ throw new Error(`Peer "${p.name ?? "(unnamed)"}" in team "${team}" is missing a persona.`);
98
+ }
99
+ if (!p.name) {
100
+ throw new Error(`Peer with persona "${p.persona}" in team "${team}" is missing a name.`);
101
+ }
102
+ for (const [k, v] of Object.entries(p)) {
103
+ // Only string fields can reach a command line; extra non-string fields
104
+ // (e.g. a snapshot's `resume` object) are never spliced into argv.
105
+ if (typeof v === "string" && !SAFE.test(v)) {
106
+ throw new Error(`Unsafe value for ${k} in team "${team}": ${JSON.stringify(v)} (allowed: ${SAFE})`);
107
+ }
108
+ }
109
+ if (resumeRef !== undefined && !SAFE.test(resumeRef)) {
110
+ throw new Error(`Unsafe resume ref for ${p.name}: ${JSON.stringify(resumeRef)} (allowed: ${SAFE})`);
111
+ }
112
+ if (p.runner === "claude-code" && p.extensions) {
113
+ throw new Error(`Peer "${p.name}": extensions: are pi-only and cannot combine with runner: claude-code.`);
114
+ }
115
+ const parts =
116
+ p.runner === "claude-code"
117
+ ? ["just", "_claude-peer", p.name]
118
+ : p.extensions
119
+ ? ["just", "_peer-plus", p.extensions, p.persona, p.name]
120
+ : ["just", "_peer", p.persona, p.name];
121
+ if (p.model) parts.push(p.model);
122
+ if (resumeRef !== undefined) {
123
+ if (!p.model) parts.push(""); // keep the model positional aligned
124
+ parts.push(resumeRef);
125
+ }
126
+ if (project !== DEFAULT_PROJECT) {
127
+ if (!p.model && resumeRef === undefined) parts.push("");
128
+ if (resumeRef === undefined) parts.push("");
129
+ parts.push(project);
130
+ }
131
+ return parts;
132
+ }
133
+
134
+ // Parse a KEY=VALUE env file (B3): no shell evaluation, no expansion.
135
+ // Blank lines and #-comments are skipped; values may be single- or
136
+ // double-quoted (quotes stripped, contents taken literally).
137
+ export function parseEnvFile(raw: string, sourceName = "env file"): Record<string, string> {
138
+ const env: Record<string, string> = {};
139
+ const lines = raw.split("\n");
140
+ for (let i = 0; i < lines.length; i++) {
141
+ const line = lines[i].trim();
142
+ if (line === "" || line.startsWith("#")) continue;
143
+ const m = line.match(/^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
144
+ if (!m) {
145
+ throw new Error(`${sourceName}:${i + 1}: not a KEY=VALUE line: ${JSON.stringify(line)}`);
146
+ }
147
+ env[m[1]] = stripQuotes(m[2].trim());
148
+ }
149
+ return env;
150
+ }
151
+
152
+ // Resolve a peer's env_file to an absolute path inside the repo. The SAFE
153
+ // charset (enforced on every peer field) already excludes shell metacharacters;
154
+ // this adds the traversal guard: repo-relative, no escaping the repo root.
155
+ export function resolveEnvFilePath(envFile: string, repoRoot: string): string {
156
+ if (!SAFE.test(envFile)) {
157
+ throw new Error(`Unsafe env_file path: ${JSON.stringify(envFile)} (allowed: ${SAFE})`);
158
+ }
159
+ if (envFile.startsWith("/")) {
160
+ throw new Error(`env_file must be repo-relative, got absolute path: ${envFile}`);
161
+ }
162
+ const abs = resolvePath(repoRoot, envFile);
163
+ if (abs !== repoRoot && !abs.startsWith(repoRoot + "/")) {
164
+ throw new Error(`env_file escapes the repo root: ${envFile}`);
165
+ }
166
+ return abs;
167
+ }
168
+
169
+ export interface TeamLayoutOptions {
170
+ team: string;
171
+ peers: Peer[];
172
+ repoRoot: string;
173
+ // B3 hook: resolve a peer's extra env (e.g. from its env_file). Returning
174
+ // undefined means no extra env for that peer.
175
+ envForPeer?: (peer: Peer) => Record<string, string> | undefined;
176
+ // B5 hook: resume ref (pi session path) for a peer being restored from a
177
+ // team snapshot. Returning undefined starts the peer fresh.
178
+ resumeForPeer?: (peer: Peer) => string | undefined;
179
+ // Pre-warm/stagger hook (see spawn-stagger.ts): seconds this pane should
180
+ // sleep before launching pi, injected as AGENT_FLEET_SPAWN_DELAY in the
181
+ // pane env. undefined or 0 launches immediately.
182
+ delayForPeer?: (peer: Peer) => number | undefined;
183
+ // B2 hook: when set, the hub occupies a larger root pane (ratio of the
184
+ // horizontal split) and the team tiles in the remaining space.
185
+ // Coms project scope shared by all panes in this layout. The default keeps
186
+ // existing argv shapes; non-default projects are appended to hidden recipe
187
+ // positional args after model/session.
188
+ project?: string;
189
+ hub?: { command: string[]; label: string; ratio?: number; cwd?: string; env?: Record<string, string> };
190
+ }
191
+
192
+ function paneNode(
193
+ peer: Peer,
194
+ team: string,
195
+ repoRoot: string,
196
+ envForPeer?: TeamLayoutOptions["envForPeer"],
197
+ resumeForPeer?: TeamLayoutOptions["resumeForPeer"],
198
+ project = DEFAULT_PROJECT,
199
+ delayForPeer?: TeamLayoutOptions["delayForPeer"],
200
+ ): LayoutNode {
201
+ validateProject(project);
202
+ const env = { ...envForPeer?.(peer) };
203
+ const delay = delayForPeer?.(peer);
204
+ if (delay !== undefined) {
205
+ if (!Number.isFinite(delay) || delay < 0) {
206
+ throw new Error(`Invalid spawn delay for peer "${peer.name}": ${delay}`);
207
+ }
208
+ if (delay > 0) env[STAGGER_ENV_VAR] = String(Math.round(delay));
209
+ }
210
+ return {
211
+ type: "pane",
212
+ command: peerCommand(peer, team, resumeForPeer?.(peer), project),
213
+ cwd: repoRoot,
214
+ label: peer.name as string,
215
+ ...(Object.keys(env).length > 0 ? { env } : {}),
216
+ };
217
+ }
218
+
219
+ // Balanced BSP over a list of panes: split the list in half, alternating
220
+ // split direction by depth — the herdr equivalent of tmux's tiled layout.
221
+ function bsp(nodes: LayoutNode[], depth: number): LayoutNode {
222
+ if (nodes.length === 1) return nodes[0];
223
+ const mid = Math.ceil(nodes.length / 2);
224
+ return {
225
+ type: "split",
226
+ direction: depth % 2 === 0 ? "right" : "down",
227
+ ratio: mid / nodes.length,
228
+ first: bsp(nodes.slice(0, mid), depth + 1),
229
+ second: bsp(nodes.slice(mid), depth + 1),
230
+ };
231
+ }
232
+
233
+ // peers.yaml team → herdr layout tree for layout.apply.
234
+ export function buildTeamLayout(opts: TeamLayoutOptions): LayoutNode {
235
+ const { team, peers, repoRoot, envForPeer, resumeForPeer, delayForPeer, hub, project = DEFAULT_PROJECT } = opts;
236
+ validateProject(project);
237
+ if (peers.length === 0) {
238
+ if (!hub) throw new Error(`Team "${team}" has no peers.`);
239
+ return {
240
+ type: "pane",
241
+ command: hub.command,
242
+ cwd: hub.cwd ?? repoRoot,
243
+ label: hub.label,
244
+ ...(hub.env && Object.keys(hub.env).length > 0 ? { env: hub.env } : {}),
245
+ };
246
+ }
247
+ const panes = peers.map((p) => paneNode(p, team, repoRoot, envForPeer, resumeForPeer, project, delayForPeer));
248
+ const grid = bsp(panes, hub ? 1 : 0);
249
+ if (!hub) return grid;
250
+ return {
251
+ type: "split",
252
+ direction: "right",
253
+ ratio: hub.ratio ?? 0.4,
254
+ first: {
255
+ type: "pane",
256
+ command: hub.command,
257
+ cwd: hub.cwd ?? repoRoot,
258
+ label: hub.label,
259
+ ...(hub.env && Object.keys(hub.env).length > 0 ? { env: hub.env } : {}),
260
+ },
261
+ second: grid,
262
+ };
263
+ }
@@ -0,0 +1,238 @@
1
+ // scripts/lib/hermes-bridge-core.ts
2
+ //
3
+ // Pure logic for the Hermes ⇄ coms bridge: qid correlation, Telegram
4
+ // formatting, answer-file validation, answer mapping, timeout outcomes,
5
+ // state transitions, and ndjson log records. No sockets, no fs, no Hermes CLI.
6
+
7
+ import * as os from "node:os";
8
+ import * as path from "node:path";
9
+
10
+ export const QID_RE = /^[0-9A-HJKMNP-TV-Z]{26}$/;
11
+ export const TELEGRAM_TEXT_LIMIT = 4096;
12
+ export const DEFAULT_REMOTE_TIMEOUT_MS = 1_800_000;
13
+ export const HUB_Q_PREFIX = "HUB-Q";
14
+ export const ANSWER_FILE_SUFFIX = ".answer.json";
15
+
16
+ export const BRIDGE_EVENT_NAMES = [
17
+ "question_received",
18
+ "delivered",
19
+ "delivery_error",
20
+ "answered",
21
+ "cancelled",
22
+ "timeout",
23
+ "late_answer",
24
+ ] as const;
25
+
26
+ export type BridgeEventName = (typeof BRIDGE_EVENT_NAMES)[number];
27
+ export type QuestionState = "pending" | "delivered" | "answered" | "cancelled" | "timeout";
28
+
29
+ export interface QuestionOption {
30
+ title: string;
31
+ description?: string;
32
+ }
33
+
34
+ export interface HermesBridgeQuestion {
35
+ qid: string;
36
+ question: string;
37
+ context?: string;
38
+ options?: QuestionOption[];
39
+ }
40
+
41
+ export interface HermesAnswerFile {
42
+ qid: string;
43
+ answer: string;
44
+ answered_by: string;
45
+ at: string;
46
+ }
47
+
48
+ export type AskResponse =
49
+ | { kind: "selection"; selections: string[]; comment?: string }
50
+ | { kind: "freeform"; text: string };
51
+
52
+ export type AnswerRejectReason =
53
+ | "invalid_path"
54
+ | "invalid_qid"
55
+ | "foreign_qid"
56
+ | "invalid_json"
57
+ | "invalid_schema"
58
+ | "qid_mismatch";
59
+
60
+ export type AnswerFileValidation =
61
+ | { ok: true; qid: string; answer: HermesAnswerFile }
62
+ | { ok: false; reason: AnswerRejectReason; qid?: string; detail?: string };
63
+
64
+ export type StateTransition =
65
+ | { ok: true; state: QuestionState | null }
66
+ | { ok: false; reason: "unsupported_transition"; state: QuestionState | null; event: BridgeEventName };
67
+
68
+ export interface LogRecord {
69
+ at: string;
70
+ qid: string;
71
+ event: BridgeEventName;
72
+ detail?: unknown;
73
+ }
74
+
75
+ export function hermesBridgeDir(home = os.homedir()): string {
76
+ return path.join(home, ".pi", "coms", "hermes-bridge");
77
+ }
78
+
79
+ export function questionsDir(home = os.homedir()): string {
80
+ return path.join(hermesBridgeDir(home), "questions");
81
+ }
82
+
83
+ export function logPath(home = os.homedir()): string {
84
+ return path.join(hermesBridgeDir(home), "log.ndjson");
85
+ }
86
+
87
+ export function answerFilePath(qid: string, dir = questionsDir()): string {
88
+ return path.join(dir, `${qid}${ANSWER_FILE_SUFFIX}`);
89
+ }
90
+
91
+ export function isValidQid(qid: unknown): qid is string {
92
+ return typeof qid === "string" && QID_RE.test(qid);
93
+ }
94
+
95
+ export function qidFromPromptEnvelope(env: { msg_id?: unknown }): string {
96
+ if (!isValidQid(env.msg_id)) throw new Error("prompt msg_id must be a 26-character Crockford ULID qid");
97
+ return env.msg_id;
98
+ }
99
+
100
+ function truncateUtf16(text: string, limit: number): string {
101
+ if (text.length <= limit) return text;
102
+ if (limit <= 0) return "";
103
+ if (limit === 1) return "…";
104
+ return `${text.slice(0, limit - 1)}…`;
105
+ }
106
+
107
+ function formatOptions(options: QuestionOption[]): string {
108
+ return options
109
+ .map((option, index) => {
110
+ const desc = option.description ? ` — ${option.description}` : "";
111
+ return `${index + 1}. ${option.title}${desc}`;
112
+ })
113
+ .join("\n");
114
+ }
115
+
116
+ export function formatTelegramQuestion(input: HermesBridgeQuestion, limit = TELEGRAM_TEXT_LIMIT): string {
117
+ if (!isValidQid(input.qid)) throw new Error("qid must be a 26-character Crockford ULID");
118
+ const options = input.options ?? [];
119
+ const header = `❓ [${HUB_Q_PREFIX}:${input.qid}] ${input.question}`;
120
+ const optionsBlock = options.length > 0 ? `\n\nOptions:\n${formatOptions(options)}` : "";
121
+ const instruction = `\n\n↩ Reply to this message, or type: ${HUB_Q_PREFIX}:${input.qid}: <answer>`;
122
+ const contextPrefix = input.context ? "\n\nContext: " : "";
123
+ const fixedLength = header.length + contextPrefix.length + optionsBlock.length + instruction.length;
124
+ const contextBudget = Math.max(0, limit - fixedLength);
125
+ const context = input.context ? truncateUtf16(input.context, contextBudget) : "";
126
+ return truncateUtf16(`${header}${contextPrefix}${context}${optionsBlock}${instruction}`, limit);
127
+ }
128
+
129
+ export function mapAnswerToAskResponse(answer: string, options: QuestionOption[] = []): AskResponse {
130
+ const text = answer.trim();
131
+ if (options.length > 0) {
132
+ if (/^\d+$/.test(text)) {
133
+ const index = Number(text) - 1;
134
+ const option = options[index];
135
+ if (option) return { kind: "selection", selections: [option.title] };
136
+ }
137
+ const byTitle = options.find((option) => option.title.toLowerCase() === text.toLowerCase());
138
+ if (byTitle) return { kind: "selection", selections: [byTitle.title] };
139
+ }
140
+ return { kind: "freeform", text };
141
+ }
142
+
143
+ function qidFromAnswerPath(filePath: string): { ok: true; qid: string } | { ok: false; reason: AnswerRejectReason } {
144
+ const base = path.basename(filePath);
145
+ if (!base.endsWith(ANSWER_FILE_SUFFIX)) return { ok: false, reason: "invalid_path" };
146
+ const qid = base.slice(0, -ANSWER_FILE_SUFFIX.length);
147
+ if (!isValidQid(qid)) return { ok: false, reason: "invalid_qid" };
148
+ return { ok: true, qid };
149
+ }
150
+
151
+ function isIsoTimestamp(value: string): boolean {
152
+ return !Number.isNaN(Date.parse(value));
153
+ }
154
+
155
+ function schemaValid(value: unknown): value is HermesAnswerFile {
156
+ const rec = value as HermesAnswerFile;
157
+ return (
158
+ !!rec &&
159
+ typeof rec === "object" &&
160
+ isValidQid(rec.qid) &&
161
+ typeof rec.answer === "string" &&
162
+ typeof rec.answered_by === "string" &&
163
+ rec.answered_by.length > 0 &&
164
+ typeof rec.at === "string" &&
165
+ isIsoTimestamp(rec.at)
166
+ );
167
+ }
168
+
169
+ export function validateAnswerFile(
170
+ raw: string,
171
+ filePath: string,
172
+ livePendingQids: Iterable<string>,
173
+ ): AnswerFileValidation {
174
+ const pathQid = qidFromAnswerPath(filePath);
175
+ if (!pathQid.ok) return { ok: false, reason: pathQid.reason };
176
+ const pending = new Set(livePendingQids);
177
+ if (!pending.has(pathQid.qid)) return { ok: false, reason: "foreign_qid", qid: pathQid.qid };
178
+
179
+ let parsed: unknown;
180
+ try {
181
+ parsed = JSON.parse(raw);
182
+ } catch (err) {
183
+ return { ok: false, reason: "invalid_json", qid: pathQid.qid, detail: err instanceof Error ? err.message : String(err) };
184
+ }
185
+ if (!schemaValid(parsed)) return { ok: false, reason: "invalid_schema", qid: pathQid.qid };
186
+ if (parsed.qid !== pathQid.qid) return { ok: false, reason: "qid_mismatch", qid: pathQid.qid };
187
+ return { ok: true, qid: pathQid.qid, answer: parsed };
188
+ }
189
+
190
+ export function timeoutMsFromEnv(env: Pick<NodeJS.ProcessEnv, "PI_COMS_TIMEOUT_MS"> = process.env): number {
191
+ const raw = env.PI_COMS_TIMEOUT_MS;
192
+ if (!raw) return DEFAULT_REMOTE_TIMEOUT_MS;
193
+ const n = Number(raw);
194
+ return Number.isFinite(n) && n > 0 ? n : DEFAULT_REMOTE_TIMEOUT_MS;
195
+ }
196
+
197
+ export function timeoutErrorMessage(timeoutMs: number): string {
198
+ return `no remote answer within ${timeoutMs}ms`;
199
+ }
200
+
201
+ export function timeoutTelegramNote(qid: string, timeoutMs: number): string {
202
+ return `⌛ [${HUB_Q_PREFIX}:${qid}] The question timed out after ${timeoutMs}ms.`;
203
+ }
204
+
205
+ export function timeoutOutcome(qid: string, timeoutMs = timeoutMsFromEnv()): {
206
+ response: null;
207
+ error: string;
208
+ telegramNote: string;
209
+ } {
210
+ return {
211
+ response: null,
212
+ error: timeoutErrorMessage(timeoutMs),
213
+ telegramNote: timeoutTelegramNote(qid, timeoutMs),
214
+ };
215
+ }
216
+
217
+ export function transitionState(state: QuestionState | null, event: BridgeEventName): StateTransition {
218
+ if (state === null && event === "question_received") return { ok: true, state: "pending" };
219
+ if (state === "pending" && event === "delivered") return { ok: true, state: "delivered" };
220
+ if (state === "pending" && event === "delivery_error") return { ok: true, state: null };
221
+ if ((state === "pending" || state === "delivered") && event === "cancelled") return { ok: true, state: "cancelled" };
222
+ if ((state === "pending" || state === "delivered") && event === "timeout") return { ok: true, state: "timeout" };
223
+ if (state === "delivered" && event === "answered") return { ok: true, state: "answered" };
224
+ if ((state === "answered" || state === "cancelled" || state === "timeout") && event === "late_answer") {
225
+ return { ok: true, state };
226
+ }
227
+ return { ok: false, reason: "unsupported_transition", state, event };
228
+ }
229
+
230
+ export function makeLogRecord(qid: string, event: BridgeEventName, detail?: unknown, at = new Date().toISOString()): LogRecord {
231
+ if (!isValidQid(qid)) throw new Error("qid must be a 26-character Crockford ULID");
232
+ if (!BRIDGE_EVENT_NAMES.includes(event)) throw new Error(`unsupported bridge event: ${event}`);
233
+ return detail === undefined ? { at, qid, event } : { at, qid, event, detail };
234
+ }
235
+
236
+ export function renderLogRecord(record: LogRecord): string {
237
+ return `${JSON.stringify(record)}\n`;
238
+ }
@@ -0,0 +1,28 @@
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
+ }
@@ -0,0 +1,9 @@
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"};}
@@ -0,0 +1,6 @@
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};}}}