@chankov/agent-fleet 1.0.2 → 1.0.3

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 (325) hide show
  1. package/.pi/harnesses/agent-hub/README.md +60 -60
  2. package/.pi/harnesses/agent-hub/context-window.js +1 -1
  3. package/.pi/harnesses/agent-hub/drift-watchdog.js +11 -4
  4. package/.pi/harnesses/agent-hub/execution-profile.ts +69 -0
  5. package/.pi/harnesses/agent-hub/footer.ts +3 -2
  6. package/.pi/harnesses/agent-hub/hub-state-audit.js +0 -14
  7. package/.pi/harnesses/agent-hub/index.ts +351 -261
  8. package/.pi/harnesses/agent-hub/package.json +1 -1
  9. package/.pi/harnesses/agent-hub/provider-semaphore.js +1 -1
  10. package/.pi/harnesses/agent-hub/run-budget.js +67 -69
  11. package/.pi/harnesses/coms/package.json +1 -1
  12. package/.pi/harnesses/damage-control-continue/package.json +1 -1
  13. package/.pi/harnesses/lib/fleet-dashboard-view.ts +3 -1
  14. package/.pi/harnesses/lib/fleet-detail-view.ts +39 -4
  15. package/.versions/1.0.3/.pi/agents/dispatch-policy.yaml +32 -0
  16. package/.versions/1.0.3/.pi/agents/model-profiles.yaml +27 -0
  17. package/.versions/1.0.3/.pi/agents/peers.yaml +142 -0
  18. package/.versions/1.0.3/.pi/agents/teams.yaml +41 -0
  19. package/.versions/1.0.3/.pi/damage-control-rules.yaml +297 -0
  20. package/.versions/1.0.3/.pi/extensions/agent-fleet-update-check/README.md +57 -0
  21. package/.versions/1.0.3/.pi/extensions/agent-fleet-update-check/index.ts +161 -0
  22. package/.versions/1.0.3/.pi/extensions/agent-fleet-update-check/package.json +6 -0
  23. package/.versions/1.0.3/.pi/extensions/btw/README.md +120 -0
  24. package/.versions/1.0.3/.pi/extensions/btw/index.ts +914 -0
  25. package/.versions/1.0.3/.pi/extensions/btw/package.json +6 -0
  26. package/.versions/1.0.3/.pi/extensions/btw/state.js +179 -0
  27. package/.versions/1.0.3/.pi/extensions/chrome-devtools-mcp/README.md +55 -0
  28. package/.versions/1.0.3/.pi/extensions/chrome-devtools-mcp/index.ts +93 -0
  29. package/.versions/1.0.3/.pi/extensions/chrome-devtools-mcp/package.json +6 -0
  30. package/.versions/1.0.3/.pi/extensions/compact-and-continue/README.md +42 -0
  31. package/.versions/1.0.3/.pi/extensions/compact-and-continue/index.ts +120 -0
  32. package/.versions/1.0.3/.pi/extensions/compact-and-continue/package.json +6 -0
  33. package/.versions/1.0.3/.pi/extensions/mcp-bridge/README.md +46 -0
  34. package/.versions/1.0.3/.pi/extensions/mcp-bridge/index.ts +206 -0
  35. package/.versions/1.0.3/.pi/extensions/mcp-bridge/package.json +6 -0
  36. package/.versions/1.0.3/.pi/extensions/package-lock.json +1175 -0
  37. package/.versions/1.0.3/.pi/extensions/package.json +9 -0
  38. package/.versions/1.0.3/.pi/extensions/pi-voice-stt/README.md +205 -0
  39. package/.versions/1.0.3/.pi/extensions/pi-voice-stt/config.ts +198 -0
  40. package/.versions/1.0.3/.pi/extensions/pi-voice-stt/examples/stt.json +35 -0
  41. package/.versions/1.0.3/.pi/extensions/pi-voice-stt/index.ts +248 -0
  42. package/.versions/1.0.3/.pi/extensions/pi-voice-stt/package.json +6 -0
  43. package/.versions/1.0.3/.pi/extensions/pi-voice-stt/providers.ts +214 -0
  44. package/.versions/1.0.3/.pi/extensions/pi-voice-stt/recorder.ts +158 -0
  45. package/.versions/1.0.3/.pi/harnesses/agent-hub/README.md +1156 -0
  46. package/.versions/1.0.3/.pi/harnesses/agent-hub/access-approval.ts +135 -0
  47. package/.versions/1.0.3/.pi/harnesses/agent-hub/artifacts.js +146 -0
  48. package/.versions/1.0.3/.pi/harnesses/agent-hub/assertion-ledger.js +58 -0
  49. package/.versions/1.0.3/.pi/harnesses/agent-hub/backend-policy.js +174 -0
  50. package/.versions/1.0.3/.pi/harnesses/agent-hub/budget-continuation.ts +73 -0
  51. package/.versions/1.0.3/.pi/harnesses/agent-hub/capability-confirmation.ts +47 -0
  52. package/.versions/1.0.3/.pi/harnesses/agent-hub/capability-packs.ts +180 -0
  53. package/.versions/1.0.3/.pi/harnesses/agent-hub/context-budget-snapshot.ts +105 -0
  54. package/.versions/1.0.3/.pi/harnesses/agent-hub/context-pressure.ts +191 -0
  55. package/.versions/1.0.3/.pi/harnesses/agent-hub/context-window.js +106 -0
  56. package/.versions/1.0.3/.pi/harnesses/agent-hub/delegate.ts +435 -0
  57. package/.versions/1.0.3/.pi/harnesses/agent-hub/docs-lane.js +122 -0
  58. package/.versions/1.0.3/.pi/harnesses/agent-hub/drift-watchdog.js +218 -0
  59. package/.versions/1.0.3/.pi/harnesses/agent-hub/evidence-rules.js +96 -0
  60. package/.versions/1.0.3/.pi/harnesses/agent-hub/execution-profile.ts +69 -0
  61. package/.versions/1.0.3/.pi/harnesses/agent-hub/external-blocker.js +85 -0
  62. package/.versions/1.0.3/.pi/harnesses/agent-hub/footer.ts +36 -0
  63. package/.versions/1.0.3/.pi/harnesses/agent-hub/helpers.ts +266 -0
  64. package/.versions/1.0.3/.pi/harnesses/agent-hub/hub-state-audit.js +59 -0
  65. package/.versions/1.0.3/.pi/harnesses/agent-hub/index.ts +9999 -0
  66. package/.versions/1.0.3/.pi/harnesses/agent-hub/monitor-control.ts +9 -0
  67. package/.versions/1.0.3/.pi/harnesses/agent-hub/monitor-invoke-journal.ts +131 -0
  68. package/.versions/1.0.3/.pi/harnesses/agent-hub/monitor-invoke.ts +92 -0
  69. package/.versions/1.0.3/.pi/harnesses/agent-hub/monitor-lifecycle.ts +13 -0
  70. package/.versions/1.0.3/.pi/harnesses/agent-hub/monitor-publisher.ts +59 -0
  71. package/.versions/1.0.3/.pi/harnesses/agent-hub/monitor-recovery.ts +3 -0
  72. package/.versions/1.0.3/.pi/harnesses/agent-hub/monitor-runtime.ts +3 -0
  73. package/.versions/1.0.3/.pi/harnesses/agent-hub/monitor-session-bridge.ts +266 -0
  74. package/.versions/1.0.3/.pi/harnesses/agent-hub/package.json +7 -0
  75. package/.versions/1.0.3/.pi/harnesses/agent-hub/peer-spawn-plan.ts +116 -0
  76. package/.versions/1.0.3/.pi/harnesses/agent-hub/posture.ts +158 -0
  77. package/.versions/1.0.3/.pi/harnesses/agent-hub/provider-semaphore.js +138 -0
  78. package/.versions/1.0.3/.pi/harnesses/agent-hub/research-retention.js +34 -0
  79. package/.versions/1.0.3/.pi/harnesses/agent-hub/research-watchdog.ts +40 -0
  80. package/.versions/1.0.3/.pi/harnesses/agent-hub/return-contract.js +293 -0
  81. package/.versions/1.0.3/.pi/harnesses/agent-hub/return-extract.js +75 -0
  82. package/.versions/1.0.3/.pi/harnesses/agent-hub/review-findings.js +102 -0
  83. package/.versions/1.0.3/.pi/harnesses/agent-hub/run-budget.js +537 -0
  84. package/.versions/1.0.3/.pi/harnesses/agent-hub/run-namespace.js +87 -0
  85. package/.versions/1.0.3/.pi/harnesses/agent-hub/safety-routing.ts +22 -0
  86. package/.versions/1.0.3/.pi/harnesses/agent-hub/scope-gate.js +103 -0
  87. package/.versions/1.0.3/.pi/harnesses/agent-hub/session-health.js +110 -0
  88. package/.versions/1.0.3/.pi/harnesses/agent-hub/spawn.ts +366 -0
  89. package/.versions/1.0.3/.pi/harnesses/agent-hub/version.ts +42 -0
  90. package/.versions/1.0.3/.pi/harnesses/ask-user-remote/README.md +53 -0
  91. package/.versions/1.0.3/.pi/harnesses/ask-user-remote/index.ts +532 -0
  92. package/.versions/1.0.3/.pi/harnesses/ask-user-remote/race-core.js +106 -0
  93. package/.versions/1.0.3/.pi/harnesses/coms/README.md +100 -0
  94. package/.versions/1.0.3/.pi/harnesses/coms/index.ts +1767 -0
  95. package/.versions/1.0.3/.pi/harnesses/coms/package.json +7 -0
  96. package/.versions/1.0.3/.pi/harnesses/coms/version.ts +42 -0
  97. package/.versions/1.0.3/.pi/harnesses/damage-control-continue/README.md +124 -0
  98. package/.versions/1.0.3/.pi/harnesses/damage-control-continue/index.ts +536 -0
  99. package/.versions/1.0.3/.pi/harnesses/damage-control-continue/package.json +7 -0
  100. package/.versions/1.0.3/.pi/harnesses/damage-control-continue/version.ts +42 -0
  101. package/.versions/1.0.3/.pi/harnesses/lib/coms-registry-entry.ts +94 -0
  102. package/.versions/1.0.3/.pi/harnesses/lib/context-budget-child-prompt.ts +179 -0
  103. package/.versions/1.0.3/.pi/harnesses/lib/context-budget-hub-prompt.ts +116 -0
  104. package/.versions/1.0.3/.pi/harnesses/lib/context-budget-view.ts +107 -0
  105. package/.versions/1.0.3/.pi/harnesses/lib/context-budget.ts +114 -0
  106. package/.versions/1.0.3/.pi/harnesses/lib/damage-control-shared.ts +197 -0
  107. package/.versions/1.0.3/.pi/harnesses/lib/fixtures/context-budget-profiles.json +11 -0
  108. package/.versions/1.0.3/.pi/harnesses/lib/fixtures/hub-prompt-operator.legacy.txt +73 -0
  109. package/.versions/1.0.3/.pi/harnesses/lib/fixtures/hub-prompt-orchestrator.legacy.txt +73 -0
  110. package/.versions/1.0.3/.pi/harnesses/lib/fleet-dashboard-ops.ts +155 -0
  111. package/.versions/1.0.3/.pi/harnesses/lib/fleet-dashboard-view.ts +142 -0
  112. package/.versions/1.0.3/.pi/harnesses/lib/fleet-detail-view.ts +168 -0
  113. package/.versions/1.0.3/.pi/harnesses/lib/fleet-overlay.ts +26 -0
  114. package/.versions/1.0.3/.pi/harnesses/lib/fleet-panel.ts +34 -0
  115. package/.versions/1.0.3/.pi/harnesses/lib/fleet-read-model.ts +131 -0
  116. package/.versions/1.0.3/.pi/harnesses/lib/fleet-selection.ts +24 -0
  117. package/.versions/1.0.3/.pi/harnesses/lib/herdr-client.ts +472 -0
  118. package/.versions/1.0.3/.pi/harnesses/lib/herdr-presence.ts +399 -0
  119. package/.versions/1.0.3/.pi/harnesses/lib/hermes-monitor-events.ts +136 -0
  120. package/.versions/1.0.3/.pi/harnesses/lib/hermes-monitor-herdr.ts +28 -0
  121. package/.versions/1.0.3/.pi/harnesses/lib/hermes-monitor-model.ts +18 -0
  122. package/.versions/1.0.3/.pi/harnesses/lib/hermes-monitor-registry.ts +6 -0
  123. package/.versions/1.0.3/.pi/harnesses/lib/hermes-monitor-socket.ts +163 -0
  124. package/.versions/1.0.3/.pi/harnesses/lib/hermes-monitor-store.ts +31 -0
  125. package/.versions/1.0.3/.pi/harnesses/lib/spawned-peers.js +190 -0
  126. package/.versions/1.0.3/.pi/harnesses/package-lock.json +2039 -0
  127. package/.versions/1.0.3/.pi/harnesses/package.json +10 -0
  128. package/.versions/1.0.3/.pi/prompts/af-build.md +24 -0
  129. package/.versions/1.0.3/.pi/prompts/af-code-simplify.md +22 -0
  130. package/.versions/1.0.3/.pi/prompts/af-plan.md +16 -0
  131. package/.versions/1.0.3/.pi/prompts/af-review.md +16 -0
  132. package/.versions/1.0.3/.pi/prompts/af-set-hermes-telegram.md +15 -0
  133. package/.versions/1.0.3/.pi/prompts/af-set-hermes-watchdog.md +6 -0
  134. package/.versions/1.0.3/.pi/prompts/af-ship.md +17 -0
  135. package/.versions/1.0.3/.pi/prompts/af-spec.md +15 -0
  136. package/.versions/1.0.3/.pi/prompts/af-test.md +19 -0
  137. package/.versions/1.0.3/.pi/skills/bowser/SKILL.md +145 -0
  138. package/.versions/1.0.3/.version +1 -0
  139. package/.versions/1.0.3/agents/architect.md +25 -0
  140. package/.versions/1.0.3/agents/bowser.md +28 -0
  141. package/.versions/1.0.3/agents/builder.md +55 -0
  142. package/.versions/1.0.3/agents/code-reviewer.md +209 -0
  143. package/.versions/1.0.3/agents/deep-researcher.md +33 -0
  144. package/.versions/1.0.3/agents/documenter.md +19 -0
  145. package/.versions/1.0.3/agents/orchestrator.md +21 -0
  146. package/.versions/1.0.3/agents/plan-reviewer.md +84 -0
  147. package/.versions/1.0.3/agents/planner.md +71 -0
  148. package/.versions/1.0.3/agents/releaser.md +25 -0
  149. package/.versions/1.0.3/agents/researcher.md +29 -0
  150. package/.versions/1.0.3/agents/security-auditor.md +168 -0
  151. package/.versions/1.0.3/agents/test-engineer.md +154 -0
  152. package/.versions/1.0.3/agents/web-debugger.md +44 -0
  153. package/.versions/1.0.3/agents/web-performance-auditor.md +194 -0
  154. package/.versions/1.0.3/bin/catalog/harness-runtime-closure.json +38 -0
  155. package/.versions/1.0.3/codex/CONDUCTOR.md +148 -0
  156. package/.versions/1.0.3/docs/ARCHITECTURE.md +375 -0
  157. package/.versions/1.0.3/docs/agent-fleet-setup.md +468 -0
  158. package/.versions/1.0.3/docs/claude-code-coms-bridge.md +128 -0
  159. package/.versions/1.0.3/docs/codex-remote-conductor.md +170 -0
  160. package/.versions/1.0.3/docs/coms-hermes-bridge.md +189 -0
  161. package/.versions/1.0.3/docs/getting-started.md +98 -0
  162. package/.versions/1.0.3/docs/npm-install.md +292 -0
  163. package/.versions/1.0.3/docs/pi-extensions.md +441 -0
  164. package/.versions/1.0.3/docs/pi-setup.md +74 -0
  165. package/.versions/1.0.3/docs/skill-anatomy.md +150 -0
  166. package/.versions/1.0.3/hermes/README.md +347 -0
  167. package/.versions/1.0.3/hermes/desktop-plugins/agent-fleet-herdr/plugin.js +1291 -0
  168. package/.versions/1.0.3/hermes/desktop-plugins/agent-fleet-herdr/presentation.js +672 -0
  169. package/.versions/1.0.3/hermes/desktop-plugins/agent-fleet-monitor/plugin.js +19 -0
  170. package/.versions/1.0.3/hermes/desktop-plugins/agent-fleet-monitor/state.js +10 -0
  171. package/.versions/1.0.3/hermes/gates/gate-o-capability.md +8 -0
  172. package/.versions/1.0.3/hermes/gates/gate-o-validator-fixtures.json +1 -0
  173. package/.versions/1.0.3/hermes/plugins/agent-fleet-herdr/dashboard/activity.py +770 -0
  174. package/.versions/1.0.3/hermes/plugins/agent-fleet-herdr/dashboard/coms_registry.py +134 -0
  175. package/.versions/1.0.3/hermes/plugins/agent-fleet-herdr/dashboard/coms_send.py +350 -0
  176. package/.versions/1.0.3/hermes/plugins/agent-fleet-herdr/dashboard/herdr_source.py +193 -0
  177. package/.versions/1.0.3/hermes/plugins/agent-fleet-herdr/dashboard/manifest.json +4 -0
  178. package/.versions/1.0.3/hermes/plugins/agent-fleet-herdr/dashboard/plugin_api.py +444 -0
  179. package/.versions/1.0.3/hermes/plugins/agent-fleet-herdr/dashboard/sessions.py +205 -0
  180. package/.versions/1.0.3/hermes/plugins/agent-fleet-herdr/dashboard/tasks.py +300 -0
  181. package/.versions/1.0.3/hermes/plugins/agent-fleet-herdr/dashboard/watch.py +819 -0
  182. package/.versions/1.0.3/hermes/plugins/agent-fleet-herdr/plugin.yaml +8 -0
  183. package/.versions/1.0.3/hermes/plugins/agent-fleet-monitor/dashboard/adapter.py +139 -0
  184. package/.versions/1.0.3/hermes/plugins/agent-fleet-monitor/dashboard/manifest.json +11 -0
  185. package/.versions/1.0.3/hermes/plugins/agent-fleet-monitor/dashboard/plugin_api.py +50 -0
  186. package/.versions/1.0.3/hermes/skills/hub-conductor/SKILL.md +84 -0
  187. package/.versions/1.0.3/hermes/skills/hub-liaison/SKILL.md +84 -0
  188. package/.versions/1.0.3/hermes/skills/hub-watchdog/SKILL.md +76 -0
  189. package/.versions/1.0.3/hermes/skills/hub-watchdog/manifest.json +1 -0
  190. package/.versions/1.0.3/hermes/skills/hub-watchdog/scripts/watchdog.py +249 -0
  191. package/.versions/1.0.3/hermes/skills/hub-watchdog/scripts/watchdog_actions.py +124 -0
  192. package/.versions/1.0.3/hermes/skills/hub-watchdog/scripts/watchdog_contract.py +76 -0
  193. package/.versions/1.0.3/hermes/skills/hub-watchdog/scripts/watchdog_delivery.py +10 -0
  194. package/.versions/1.0.3/hermes/skills/hub-watchdog/scripts/watchdog_engine.py +128 -0
  195. package/.versions/1.0.3/hermes/skills/hub-watchdog/scripts/watchdog_judgment.py +41 -0
  196. package/.versions/1.0.3/hermes/skills/hub-watchdog/scripts/watchdog_recovery.py +103 -0
  197. package/.versions/1.0.3/hermes/skills/hub-watchdog/scripts/watchdog_state.py +163 -0
  198. package/.versions/1.0.3/hermes/skills/hub-watchdog/scripts/watchdog_transport.py +138 -0
  199. package/.versions/1.0.3/hermes/watchdog-tests/__init__.py +0 -0
  200. package/.versions/1.0.3/hooks/coms-stop-hook.mjs +84 -0
  201. package/.versions/1.0.3/install-manifest.json +2745 -0
  202. package/.versions/1.0.3/justfile +272 -0
  203. package/.versions/1.0.3/manifest-meta.json +882 -0
  204. package/.versions/1.0.3/references/accessibility-checklist.md +160 -0
  205. package/.versions/1.0.3/references/definition-of-done.md +67 -0
  206. package/.versions/1.0.3/references/fleet-coordination-patterns.md +151 -0
  207. package/.versions/1.0.3/references/observability-checklist.md +91 -0
  208. package/.versions/1.0.3/references/orchestration-patterns.md +370 -0
  209. package/.versions/1.0.3/references/performance-checklist.md +153 -0
  210. package/.versions/1.0.3/references/prompting-patterns.md +380 -0
  211. package/.versions/1.0.3/references/security-checklist.md +179 -0
  212. package/.versions/1.0.3/references/testing-patterns.md +236 -0
  213. package/.versions/1.0.3/scripts/codex-conductor.ts +41 -0
  214. package/.versions/1.0.3/scripts/codex-remote-control.ts +167 -0
  215. package/.versions/1.0.3/scripts/coms-claude-bridge.ts +411 -0
  216. package/.versions/1.0.3/scripts/coms-cli.ts +484 -0
  217. package/.versions/1.0.3/scripts/coms-hermes-bridge.ts +413 -0
  218. package/.versions/1.0.3/scripts/fleet.ts +185 -0
  219. package/.versions/1.0.3/scripts/hermes-monitor-capability-runner.ts +25 -0
  220. package/.versions/1.0.3/scripts/hermes-monitor-scenario.ts +474 -0
  221. package/.versions/1.0.3/scripts/hermes-watchdog-capability-probe.ts +45 -0
  222. package/.versions/1.0.3/scripts/install-hermes-plugin.sh +180 -0
  223. package/.versions/1.0.3/scripts/lib/claude-bridge-core.ts +210 -0
  224. package/.versions/1.0.3/scripts/lib/codex-conductor.ts +88 -0
  225. package/.versions/1.0.3/scripts/lib/codex-remote-control.ts +480 -0
  226. package/.versions/1.0.3/scripts/lib/coms-envelope.ts +582 -0
  227. package/.versions/1.0.3/scripts/lib/fake-herdr-server.ts +88 -0
  228. package/.versions/1.0.3/scripts/lib/fleet-command.ts +266 -0
  229. package/.versions/1.0.3/scripts/lib/herdr-layout.ts +281 -0
  230. package/.versions/1.0.3/scripts/lib/hermes-bridge-core.ts +241 -0
  231. package/.versions/1.0.3/scripts/lib/hermes-monitor-events.ts +1 -0
  232. package/.versions/1.0.3/scripts/lib/hermes-monitor-herdr.ts +2 -0
  233. package/.versions/1.0.3/scripts/lib/hermes-monitor-model.ts +3 -0
  234. package/.versions/1.0.3/scripts/lib/hermes-monitor-registry.ts +2 -0
  235. package/.versions/1.0.3/scripts/lib/hermes-monitor-socket.ts +2 -0
  236. package/.versions/1.0.3/scripts/lib/hermes-monitor-store.ts +2 -0
  237. package/.versions/1.0.3/scripts/lib/monitor-env.ts +146 -0
  238. package/.versions/1.0.3/scripts/lib/peer-launch.ts +318 -0
  239. package/.versions/1.0.3/scripts/lib/persona-banner.ts +62 -0
  240. package/.versions/1.0.3/scripts/lib/spawn-stagger.ts +101 -0
  241. package/.versions/1.0.3/scripts/lib/team-project.ts +213 -0
  242. package/.versions/1.0.3/scripts/lib/team-snapshot.ts +147 -0
  243. package/.versions/1.0.3/scripts/peer-banner.ts +40 -0
  244. package/.versions/1.0.3/scripts/peer-launch.ts +259 -0
  245. package/.versions/1.0.3/scripts/team-snapshot.ts +237 -0
  246. package/.versions/1.0.3/scripts/team-up.ts +406 -0
  247. package/.versions/1.0.3/skills/_internal/grilling.md +11 -0
  248. package/.versions/1.0.3/skills/browser-testing-with-devtools/SKILL.md +351 -0
  249. package/.versions/1.0.3/skills/code-review-and-quality/SKILL.md +381 -0
  250. package/.versions/1.0.3/skills/compound-learning/SKILL.md +137 -0
  251. package/.versions/1.0.3/skills/context-engineering/SKILL.md +291 -0
  252. package/.versions/1.0.3/skills/deprecation-and-migration/SKILL.md +206 -0
  253. package/.versions/1.0.3/skills/designing-agents/SKILL.md +394 -0
  254. package/.versions/1.0.3/skills/designing-agents/pi-harness-authoring.md +222 -0
  255. package/.versions/1.0.3/skills/frontend-ui-engineering/SKILL.md +328 -0
  256. package/.versions/1.0.3/skills/git-workflow-and-versioning/SKILL.md +316 -0
  257. package/.versions/1.0.3/skills/idea-refine/SKILL.md +182 -0
  258. package/.versions/1.0.3/skills/idea-refine/examples.md +238 -0
  259. package/.versions/1.0.3/skills/idea-refine/frameworks.md +99 -0
  260. package/.versions/1.0.3/skills/idea-refine/refinement-criteria.md +113 -0
  261. package/.versions/1.0.3/skills/idea-refine/scripts/idea-refine.sh +15 -0
  262. package/.versions/1.0.3/skills/incremental-implementation/SKILL.md +287 -0
  263. package/.versions/1.0.3/skills/interview-me/SKILL.md +226 -0
  264. package/.versions/1.0.3/skills/orchestration-verification/SKILL.md +181 -0
  265. package/.versions/1.0.3/skills/peer-coms/SKILL.md +90 -0
  266. package/.versions/1.0.3/skills/performance-optimization/SKILL.md +350 -0
  267. package/.versions/1.0.3/skills/planning-and-task-breakdown/SKILL.md +254 -0
  268. package/.versions/1.0.3/skills/security-and-hardening/SKILL.md +461 -0
  269. package/.versions/1.0.3/skills/spec-driven-development/SKILL.md +257 -0
  270. package/.versions/1.0.3/skills/using-agent-skills/SKILL.md +199 -0
  271. package/.versions/1.0.3/systemd/user/agent-fleet-codex-remote-control.service.in +23 -0
  272. package/.versions/1.0.3/vendor/agent-skills-upstream/LICENSE +21 -0
  273. package/.versions/1.0.3/vendor/agent-skills-upstream/README.md +11 -0
  274. package/.versions/1.0.3/vendor/agent-skills-upstream/skills/api-and-interface-design/SKILL.md +294 -0
  275. package/.versions/1.0.3/vendor/agent-skills-upstream/skills/browser-testing-with-devtools/SKILL.md +317 -0
  276. package/.versions/1.0.3/vendor/agent-skills-upstream/skills/ci-cd-and-automation/SKILL.md +390 -0
  277. package/.versions/1.0.3/vendor/agent-skills-upstream/skills/code-review-and-quality/SKILL.md +396 -0
  278. package/.versions/1.0.3/vendor/agent-skills-upstream/skills/code-simplification/SKILL.md +331 -0
  279. package/.versions/1.0.3/vendor/agent-skills-upstream/skills/context-engineering/SKILL.md +289 -0
  280. package/.versions/1.0.3/vendor/agent-skills-upstream/skills/debugging-and-error-recovery/SKILL.md +300 -0
  281. package/.versions/1.0.3/vendor/agent-skills-upstream/skills/deprecation-and-migration/SKILL.md +247 -0
  282. package/.versions/1.0.3/vendor/agent-skills-upstream/skills/documentation-and-adrs/SKILL.md +278 -0
  283. package/.versions/1.0.3/vendor/agent-skills-upstream/skills/doubt-driven-development/SKILL.md +243 -0
  284. package/.versions/1.0.3/vendor/agent-skills-upstream/skills/frontend-ui-engineering/SKILL.md +328 -0
  285. package/.versions/1.0.3/vendor/agent-skills-upstream/skills/git-workflow-and-versioning/SKILL.md +355 -0
  286. package/.versions/1.0.3/vendor/agent-skills-upstream/skills/idea-refine/SKILL.md +178 -0
  287. package/.versions/1.0.3/vendor/agent-skills-upstream/skills/idea-refine/examples.md +238 -0
  288. package/.versions/1.0.3/vendor/agent-skills-upstream/skills/idea-refine/frameworks.md +99 -0
  289. package/.versions/1.0.3/vendor/agent-skills-upstream/skills/idea-refine/refinement-criteria.md +113 -0
  290. package/.versions/1.0.3/vendor/agent-skills-upstream/skills/idea-refine/scripts/idea-refine.sh +15 -0
  291. package/.versions/1.0.3/vendor/agent-skills-upstream/skills/incremental-implementation/SKILL.md +249 -0
  292. package/.versions/1.0.3/vendor/agent-skills-upstream/skills/interview-me/SKILL.md +225 -0
  293. package/.versions/1.0.3/vendor/agent-skills-upstream/skills/observability-and-instrumentation/SKILL.md +203 -0
  294. package/.versions/1.0.3/vendor/agent-skills-upstream/skills/performance-optimization/SKILL.md +350 -0
  295. package/.versions/1.0.3/vendor/agent-skills-upstream/skills/planning-and-task-breakdown/SKILL.md +234 -0
  296. package/.versions/1.0.3/vendor/agent-skills-upstream/skills/security-and-hardening/SKILL.md +467 -0
  297. package/.versions/1.0.3/vendor/agent-skills-upstream/skills/shipping-and-launch/SKILL.md +310 -0
  298. package/.versions/1.0.3/vendor/agent-skills-upstream/skills/source-driven-development/SKILL.md +194 -0
  299. package/.versions/1.0.3/vendor/agent-skills-upstream/skills/spec-driven-development/SKILL.md +206 -0
  300. package/.versions/1.0.3/vendor/agent-skills-upstream/skills/test-driven-development/SKILL.md +383 -0
  301. package/.versions/1.0.3/vendor/agent-skills-upstream/skills/using-agent-skills/SKILL.md +191 -0
  302. package/CHANGELOG.md +6 -0
  303. package/README.md +5 -4
  304. package/agents/architect.md +1 -0
  305. package/agents/bowser.md +1 -0
  306. package/agents/builder.md +1 -0
  307. package/agents/code-reviewer.md +1 -0
  308. package/agents/deep-researcher.md +1 -0
  309. package/agents/documenter.md +1 -0
  310. package/agents/orchestrator.md +1 -0
  311. package/agents/plan-reviewer.md +1 -0
  312. package/agents/planner.md +1 -0
  313. package/agents/releaser.md +1 -0
  314. package/agents/researcher.md +1 -0
  315. package/agents/security-auditor.md +1 -0
  316. package/agents/test-engineer.md +1 -0
  317. package/agents/web-debugger.md +1 -0
  318. package/agents/web-performance-auditor.md +1 -0
  319. package/bin/lib/validate-overrides.js +1 -1
  320. package/docs/ARCHITECTURE.md +25 -19
  321. package/docs/agent-fleet-setup.md +8 -8
  322. package/docs/pi-extensions.md +4 -2
  323. package/install-manifest.json +1 -1
  324. package/package.json +2 -2
  325. package/scripts/fleet.ts +1 -1
@@ -0,0 +1,150 @@
1
+ # Skill Anatomy
2
+
3
+ This document describes the structure and format of agent-fleet skill files. Use this as a guide when contributing new skills or understanding existing ones.
4
+
5
+ ## File Location
6
+
7
+ Every skill lives in its own directory under `skills/`:
8
+
9
+ ```
10
+ skills/
11
+ skill-name/
12
+ SKILL.md # Required: The skill definition
13
+ scripts/ # Optional: Runnable helpers used by the skill workflow
14
+ supporting-file.md # Optional: Reference material loaded on demand
15
+ ```
16
+
17
+ `SKILL.md` is the only required file. Add `scripts/` only when the skill actually ships runnable helpers, and omit the directory entirely for markdown-only skills.
18
+
19
+ ## SKILL.md Format
20
+
21
+ ### Frontmatter (Required)
22
+
23
+ ```yaml
24
+ ---
25
+ name: skill-name-with-hyphens
26
+ description: Guides agents through [task/workflow]. Use when [specific trigger conditions].
27
+ ---
28
+ ```
29
+
30
+ **Rules:**
31
+ - `name`: Lowercase, hyphen-separated. Must match the directory name.
32
+ - `description`: Start with what the skill does in third person, then include one or more clear "Use when" trigger conditions. Include both *what* and *when*. Maximum 1024 characters.
33
+
34
+ **Why this matters:** Agents discover skills by reading descriptions. The description is injected into the system prompt, so it must tell the agent both what the skill provides and when to activate it. Do not summarize the workflow — if the description contains process steps, the agent may follow the summary instead of reading the full skill.
35
+
36
+ ### Standard Sections (Recommended Pattern)
37
+
38
+ The frontmatter contract above is required. The section layout below is a recommended pattern, not a rigid template: equivalent headings are acceptable when they serve the same purpose clearly.
39
+
40
+ ```markdown
41
+ # Skill Title
42
+
43
+ ## Overview
44
+ One-two sentences explaining what this skill does and why it matters.
45
+
46
+ ## When to Use
47
+ - Bullet list of triggering conditions (symptoms, task types)
48
+ - When NOT to use (exclusions)
49
+
50
+ ## [Core Process / The Workflow / Steps]
51
+ The main workflow, broken into numbered steps or phases.
52
+ Include code examples where they help.
53
+ Use flowcharts (ASCII) where decision points exist.
54
+
55
+ ## [Specific Techniques / Patterns]
56
+ Detailed guidance for specific scenarios.
57
+ Code examples, templates, configuration.
58
+
59
+ ## Common Rationalizations
60
+ | Rationalization | Reality |
61
+ |---|---|
62
+ | Excuse agents use to skip steps | Why the excuse is wrong |
63
+
64
+ ## Red Flags
65
+ - Behavioral patterns indicating the skill is being violated
66
+ - Things to watch for during review
67
+
68
+ ## Verification
69
+ After completing the skill's process, confirm:
70
+ - [ ] Checklist of exit criteria
71
+ - [ ] Evidence requirements
72
+ ```
73
+
74
+ ## Section Purposes
75
+
76
+ ### Overview
77
+ The "elevator pitch" for the skill. Should answer: What does this skill do, and why should an agent follow it?
78
+
79
+ ### When to Use
80
+ Helps agents and humans decide if this skill applies to the current task. Include both positive triggers ("Use when X") and negative exclusions ("NOT for Y").
81
+
82
+ ### Core Process
83
+ The heart of the skill. This is the step-by-step workflow the agent follows. Must be specific and actionable — not vague advice.
84
+
85
+ **Good:** "Run `npm test` and verify all tests pass"
86
+ **Bad:** "Make sure the tests work"
87
+
88
+ ### Common Rationalizations
89
+ The most distinctive feature of well-crafted skills. These are excuses agents use to skip important steps, paired with rebuttals. They prevent the agent from rationalizing its way out of following the process.
90
+
91
+ Think of every time an agent has said "I'll add tests later" or "This is simple enough to skip the spec" — those go here with a factual counter-argument.
92
+
93
+ ### Red Flags
94
+ Observable signs that the skill is being violated. Useful during code review and self-monitoring.
95
+
96
+ ### Verification
97
+ The exit criteria. A checklist the agent uses to confirm the skill's process is complete. Every checkbox should be verifiable with evidence (test output, build result, screenshot, etc.).
98
+
99
+ ## Supporting Files
100
+
101
+ Create supporting files only when:
102
+ - Reference material exceeds 100 lines (keep the main SKILL.md focused)
103
+ - Code tools or scripts are needed
104
+ - Checklists are long enough to justify separate files
105
+
106
+ Keep patterns and principles inline when under 50 lines.
107
+
108
+ If a skill does not need runnable helpers, do not create an empty `scripts/` directory just to mirror other skills. Empty directories add noise without changing how the skill works.
109
+
110
+ ## Writing Principles
111
+
112
+ 1. **Process over knowledge.** Skills are workflows, not reference docs. Steps, not facts.
113
+ 2. **Specific over general.** "Run `npm test`" beats "verify the tests".
114
+ 3. **Evidence over assumption.** Every verification checkbox requires proof.
115
+ 4. **Anti-rationalization.** Every skip-worthy step needs a counter-argument in the rationalizations table.
116
+ 5. **Progressive disclosure.** Main SKILL.md is the entry point. Supporting files are loaded only when needed.
117
+ 6. **Token-conscious.** Every section must justify its inclusion. If removing it wouldn't change agent behavior, remove it.
118
+ 7. **Prompting-patterns applied.** Before finalizing a skill, verify its language against `references/prompting-patterns.md` — positive instructions over prohibitions, explain *why* behind non-obvious rules, no ALL-CAPS or reward/punishment language.
119
+
120
+ ## Naming Conventions
121
+
122
+ - Skill directories: `lowercase-hyphen-separated`
123
+ - Skill files: `SKILL.md` (always uppercase)
124
+ - Supporting files: `lowercase-hyphen-separated.md`
125
+ - References: stored in `references/` at the project root, not inside skill directories
126
+
127
+ ## Cross-Skill References
128
+
129
+ Reference other skills by name:
130
+
131
+ ```markdown
132
+ Follow the `test-driven-development` skill for writing tests.
133
+ If the build breaks, use the `debugging-and-error-recovery` skill.
134
+ ```
135
+
136
+ Don't duplicate content between skills — reference and link instead.
137
+
138
+ ## Required vs Recommended
139
+
140
+ Required:
141
+
142
+ - A `skills/<skill-name>/SKILL.md` file
143
+ - Valid YAML frontmatter with `name` and `description`
144
+ - A description that includes both what the skill does and when to use it
145
+
146
+ Recommended:
147
+
148
+ - The standard section flow shown above
149
+ - Equivalent headings such as `How It Works`, `Core Process`, or `Workflow` when they read more naturally for the skill
150
+ - Supporting files only when they keep the main `SKILL.md` focused
@@ -0,0 +1,347 @@
1
+ # Hermes artifacts
2
+
3
+ This directory holds the in-repository Hermes surfaces of Agent Fleet: the
4
+ **Desktop plugin** that shows the live fleet, and the **skills** behind the
5
+ coms ⇄ Hermes question bridge. They are source artifacts, installed into a
6
+ profile explicitly — nothing here is published to npm and nothing writes to
7
+ `~/.hermes` unless you run an installer.
8
+
9
+ Two distinct integrations, easy to conflate:
10
+
11
+ | | What it does | Direction | Entry point |
12
+ |---|---|---|---|
13
+ | **Desktop plugin** (`agent-fleet-herdr`) | Shows every live Agent Fleet session, its state, what it is doing, and which agent is blocked on you | Hermes reads the fleet | [docs/hermes-desktop-plugins.md](../docs/hermes-desktop-plugins.md) |
14
+ | **Question bridge** (`hub-liaison`) | Relays an agent's `ask_user` question to Telegram and races your answer against a local one | The fleet asks you | [docs/coms-hermes-bridge.md](../docs/coms-hermes-bridge.md) |
15
+
16
+ ## Desktop plugins
17
+
18
+ `desktop-plugins/<id>/` and `plugins/<id>/` are the two halves of a Hermes
19
+ plugin — the Electron pane and the FastAPI backend it calls. They are installed
20
+ into a profile with `scripts/install-hermes-plugin.sh`, never published to npm.
21
+ The contract, the install runbook, and the failure modes that look identical
22
+ from the outside are documented in
23
+ [docs/hermes-desktop-plugins.md](../docs/hermes-desktop-plugins.md).
24
+
25
+ - `agent-fleet-herdr` — read-only panel of live Agent Fleet sessions grouped by
26
+ project, flagging the ones waiting for a human.
27
+ - `agent-fleet-monitor` — the separate agent-hub task view (leases, generations,
28
+ output cursors) over the local monitor transport described below. Its own
29
+ Desktop panel is deliberately left uninstalled: the subagent tree is rendered
30
+ inside `agent-fleet-herdr`'s session modal instead, so a human never has to
31
+ know which pane to open.
32
+
33
+ ### Install the fleet panel
34
+
35
+ Needs Hermes v0.19.0+ with the Desktop app, this checkout, and a fleet that has
36
+ run at least once (so `~/.pi/coms/projects/` exists). herdr is optional —
37
+ without it rows read `unknown` instead of a live state.
38
+
39
+ ```bash
40
+ scripts/install-hermes-plugin.sh agent-fleet-herdr # --profile / --copy / --dry-run / --uninstall
41
+ # then restart the Hermes DESKTOP APP (its gateway is the one that mounts the routes),
42
+ # start a fleet, and open the "Agent Fleet" tab:
43
+ just fleet team default
44
+ ```
45
+
46
+ ![The Agent Fleet panel in Hermes Desktop, listing seven live sessions in one project beside the chat that started them](../docs/assets/hermes-desktop-agent-fleet-panel.png)
47
+
48
+ Selecting a row opens a modal with that agent's purpose, model, context, queue,
49
+ uptime and heartbeat, a live tail of what it is doing read from its own
50
+ transcript, the subagents it is running with their stdout and a Cancel each, and
51
+ `Focus pane` to bring its workspace to the front.
52
+
53
+ ![The session modal for an orchestrator, showing its live activity tail and the Focus pane action](../docs/assets/hermes-desktop-session-modal.png)
54
+
55
+ Prerequisites in full, the API, the join rules, the failure modes and the
56
+ deliberate limits: [docs/hermes-desktop-plugins.md](../docs/hermes-desktop-plugins.md).
57
+
58
+ `skills/hub-watchdog/` is an optional foreground, fail-closed monitor consumer. It is packaged source, not an installed or enabled profile skill. Its profile-aware lifecycle is documented in [the watchdog runbook](../docs/hermes-watchdog-supervisor.md): no installer starts/stops a gateway or changes tools, and Gate O has no checked-in live origin proof. The supported posture is journal-only/dormant; it must not deliver, steer, cancel, recover, wake a chat, or choose a fallback route.
59
+
60
+ ## Skills
61
+
62
+ - `skills/hub-liaison/` — gateway-side Telegram liaison. It writes `~/.pi/coms/hermes-bridge/questions/<qid>.answer.json` answer files for `[HUB-Q:<qid>]` questions consumed by `scripts/coms-hermes-bridge.ts`.
63
+ - `skills/hub-conductor/` — dev-profile conductor. It uses `scripts/coms-cli.ts list` and `scripts/coms-cli.ts send --await --timeout` to delegate to live pi hub-team peers, while preserving the no-herdr damage-control boundary.
64
+
65
+ ## Install
66
+
67
+ For `hub-liaison`, use Agent Fleet's deterministic profile-aware installer rather than a raw copy:
68
+
69
+ ```bash
70
+ agent-fleet set-hermes-telegram status --profile default
71
+ agent-fleet set-hermes-telegram install --profile default
72
+ # Only when status reports a differing local tree:
73
+ agent-fleet set-hermes-telegram install --profile default --force
74
+ # Restart a currently running gateway only by explicit request:
75
+ agent-fleet set-hermes-telegram install --profile default --force --restart
76
+ ```
77
+
78
+ The command is `/af-set-hermes-telegram`. The installer resolves the real profile path via `hermes profile show`, refuses drift without `--force`, backs up forced replacements, copies atomically, and verifies skill/tool/gateway readiness. It never sends a test Telegram message and never starts a stopped gateway. See [the bridge runbook](../docs/coms-hermes-bridge.md#telegram-bridge-control-command).
79
+
80
+ The current `hermes skills install` CLI documents registry identifiers and direct HTTP(S) `SKILL.md` URLs, not local directories, so `hermes skills install hermes/skills/hub-liaison` is not the supported local installation path.
81
+
82
+ `hub-conductor` remains a source artifact for the human's dev/conductor profile. Install it by a reviewed local copy into the path reported by `hermes profile show <profile>`, or publish/install it through a pinned Hermes skill source; it is intentionally not managed by the Telegram bridge command.
83
+
84
+ Use `hub-liaison` in the gateway-owning Telegram profile and `hub-conductor` in the human's dev/conductor profile. Verify availability with `hermes --profile <profile> skills list --enabled-only` before relying on them.
85
+
86
+ ## Local agent-hub monitor integration
87
+
88
+ Agent Fleet exposes an optional **local monitor transport** for Hermes-facing tools. This is
89
+ separate from the Telegram/coms bridge:
90
+
91
+ - `hub-liaison` and `hub-conductor` handle human questions and delegation through coms.
92
+ - The monitor transport exposes dispatcher and specialist state through owner-only discovery,
93
+ a token file, and a Unix domain socket (UDS).
94
+
95
+ A Hermes UI, operator tool, or other local client may consume the transport contract described
96
+ below, but it owns its own presentation and lifecycle. The hub remains the source of truth for
97
+ task state and cancellation. Source artifacts being present in this repository or its package do
98
+ not install, enable, or prove a live Hermes client. In particular, monitor cursor/discovery
99
+ fields and local tests are not proof of a Hermes origin identity or watcher delivery route.
100
+
101
+ ### Integration in action
102
+
103
+ The hub can surface an `ask_user` decision in Hermes Desktop while the specialist workflow keeps
104
+ running. The prompt preserves the question and its choices instead of flattening them into an
105
+ unstructured message:
106
+
107
+ ![Hermes Desktop displaying a multiple-choice question piped from agent-hub](../docs/assets/hermes-question-in-desktop.png)
108
+
109
+ The side-by-side view shows the same live question in the Pi hub and Hermes Desktop. This is the
110
+ question-piping path used for remote human input; task monitoring remains the separate local
111
+ transport described below.
112
+
113
+ ![Pi agent-hub and Hermes Desktop showing the same piped question side by side](../docs/assets/hermes-pi-question-piping.png)
114
+
115
+ ### Start a monitored hub
116
+
117
+ Nothing to set up. A Herdr-backed hub is required because the stable hub identity includes
118
+ `HERDR_WORKSPACE_ID` and `HERDR_PANE_ID`, so use a team recipe:
119
+
120
+ ```bash
121
+ just fleet team default
122
+ ```
123
+
124
+ [scripts/lib/monitor-env.ts](../scripts/lib/monitor-env.ts) picks the profile ID (`dev`) and the
125
+ runtime directory (`$XDG_RUNTIME_DIR/agent-fleet-monitor`, created mode 0700) and the launchers
126
+ export both. Watch the tasks in the **agent-fleet-herdr** pane: select the hub's row, and its
127
+ subagents are a section of the modal with their live output and a Cancel each.
128
+
129
+ To point a hub at a different profile, or to turn the monitor off, set the variables yourself —
130
+ an existing value is never overwritten:
131
+
132
+ ```bash
133
+ AGENT_FLEET_PROFILE_ID=prod just fleet team default # a different Hermes profile
134
+ AGENT_FLEET_MONITOR=0 just fleet team default # unmonitored
135
+ ```
136
+
137
+ If either monitor variable is invalid, if the runtime directory cannot be made mode 0700, or if
138
+ the hub lacks stable Herdr identity, the monitor stays disabled while normal agent-hub
139
+ orchestration continues. The profile ID must start with an alphanumeric character and may contain
140
+ only alphanumerics, `.`, `_`, or `-`; `..` is rejected — the same class
141
+ `hermes/plugins/agent-fleet-monitor/dashboard/adapter.py` enforces when it reads the directory
142
+ back, because a value one end accepts and the other rejects is an empty listing with no error
143
+ anywhere.
144
+
145
+ ### Discover the local endpoint
146
+
147
+ The hub creates mode `0700` namespaces under the runtime root. Each active registration contains
148
+ one mode `0600` discovery file and token file, plus a mode `0600` socket:
149
+
150
+ ```text
151
+ <runtime>/<profile-sha256>/<hub-sha256>/discovery-<owner-id>.json
152
+ <runtime>/<profile-sha256>/<hub-sha256>/token-<owner-id>
153
+ <runtime>/s/<registration-sha256>/s
154
+ ```
155
+
156
+ You can list discovery paths without reading or printing their tokens:
157
+
158
+ ```bash
159
+ find "$AGENT_FLEET_MONITOR_RUNTIME_DIR" -type f -name 'discovery-*.json' -print
160
+ ```
161
+
162
+ A discovery record has this shape:
163
+
164
+ ```json
165
+ {
166
+ "owner": "9db4478e-ef6e-4d5d-930b-6d637f5de4d1",
167
+ "socket": "@runtime/s/0123456789abcdef0123456789abcdef/s",
168
+ "token": "token-9db4478e-ef6e-4d5d-930b-6d637f5de4d1",
169
+ "lease": {
170
+ "hub": "<stable-hub-id>",
171
+ "pid": 12345,
172
+ "startedAt": "2026-07-21T09:00:00.000Z",
173
+ "expiresAt": "2026-07-21T09:00:30.000Z"
174
+ }
175
+ }
176
+ ```
177
+
178
+ A consumer must reject expired or malformed discovery, paths outside the configured runtime root,
179
+ symlinks, unsafe modes, and socket/token names that do not match the discovery schema. It should
180
+ re-discover after reconnect instead of caching a token or absolute socket path. Never put the token
181
+ in a URL, log, Desktop storage, or command-line argument.
182
+
183
+ ### Request snapshot, output, and cancellation
184
+
185
+ The UDS protocol is newline-delimited JSON with one request per connection. Read the token from the
186
+ discovery record's sibling token file, use it only in memory, and terminate every request with
187
+ `\n`.
188
+
189
+ ```js
190
+ import net from "node:net";
191
+
192
+ export function monitorRequest(socketPath, request) {
193
+ return new Promise((resolve, reject) => {
194
+ const client = net.createConnection(socketPath);
195
+ let body = "";
196
+ client.setTimeout(1_000, () => client.destroy(new Error("monitor timeout")));
197
+ client.on("connect", () => client.end(`${JSON.stringify(request)}\n`));
198
+ client.on("data", chunk => { body += chunk; });
199
+ client.on("error", reject);
200
+ client.on("close", () => resolve(body ? JSON.parse(body) : null));
201
+ });
202
+ }
203
+
204
+ // `token` and `socketPath` were resolved and validated from live discovery.
205
+ const current = await monitorRequest(socketPath, { type: "snapshot", token });
206
+ const delta = await monitorRequest(socketPath, {
207
+ type: "output",
208
+ token,
209
+ taskId: "builder:1",
210
+ generation: 1,
211
+ afterSequence: 0
212
+ });
213
+ ```
214
+
215
+ Example snapshot response:
216
+
217
+ ```json
218
+ {
219
+ "ok": true,
220
+ "snapshot": {
221
+ "tasks": [
222
+ {
223
+ "id": "builder:1",
224
+ "generation": 1,
225
+ "kind": "child",
226
+ "state": "running",
227
+ "outputLatestSequence": 4
228
+ }
229
+ ]
230
+ }
231
+ }
232
+ ```
233
+
234
+ Continue incremental output from the returned sequence to avoid duplicates:
235
+
236
+ ```js
237
+ const next = await monitorRequest(socketPath, {
238
+ type: "output",
239
+ token,
240
+ taskId: "builder:1",
241
+ generation: 1,
242
+ afterSequence: delta.output.sequence
243
+ });
244
+ ```
245
+
246
+ Cancellation is an explicit operator action and must use the exact displayed task ID and
247
+ generation:
248
+
249
+ ```js
250
+ const cancelled = await monitorRequest(socketPath, {
251
+ type: "cancel",
252
+ token,
253
+ taskId: "builder:1",
254
+ generation: 1
255
+ });
256
+ ```
257
+
258
+ A native specialist cancellation targets only the hub-owned process generation and validates its
259
+ process identity before signalling it. Cancelling a coms-backed run abandons the hub's local wait;
260
+ the remote peer may continue, so it is never an automatic recovery target and the watchdog must not
261
+ retry or re-dispatch it. Neither operation creates, focuses, closes, or otherwise controls a
262
+ Herdr pane or workspace.
263
+
264
+ ### Additive `events` and `invoke` requests
265
+
266
+ Two request types extend the same socket. A hub that does not implement them answers `unsupported`,
267
+ so a snapshot/output/cancel consumer keeps working unchanged.
268
+
269
+ `events` replays a bounded journal from a cursor the consumer holds. Set a read timeout that covers
270
+ the `waitMs` window you ask the hub to hold, or every quiet poll expires locally and looks like an
271
+ outage:
272
+
273
+ ```js
274
+ const batch = await monitorRequest(socketPath, {
275
+ type: "events",
276
+ token,
277
+ afterSequence: 0,
278
+ limit: 50, // 1–100
279
+ waitMs: 2000 // 0–25000 long-poll window
280
+ });
281
+ // { ok: true, events: { firstAvailableSequence, latestSequence, items: [...], timedOut } }
282
+ ```
283
+
284
+ A cursor older than the retained window is refused rather than silently skipped. Reconcile from a
285
+ fresh snapshot and resume from sequence 0:
286
+
287
+ ```json
288
+ {"ok": false, "error": "cursor_too_old", "snapshotRequired": true, "firstAvailableSequence": 9, "latestSequence": 12}
289
+ ```
290
+
291
+ `invoke` submits one typed request and returns an admission status — never a result of work:
292
+
293
+ ```js
294
+ const admitted = await monitorRequest(socketPath, {
295
+ type: "invoke",
296
+ token,
297
+ requestId: "request-a",
298
+ taskId: "builder:1",
299
+ generation: 1,
300
+ action: "request_status",
301
+ parameters: { assertionIds: [], evidenceEventIds: ["hub:1"] },
302
+ basis: { deviation: "stalled_progress", judgment: "confirmed" }
303
+ });
304
+ // { ok: true, result: { status: "accepted" } }
305
+ ```
306
+
307
+ `status` is one of `accepted`, `duplicate`, `queue_full`, `stale_generation`, `owner_changed`,
308
+ `already_terminal`, `idempotency_conflict`, `unsupported`, or `rejected`. `accepted` means the hub
309
+ queued a visible follow-up for its operator; it does not mean anything ran. Reusing a `requestId`
310
+ returns `duplicate` and adds no second follow-up; reusing it with different parameters returns
311
+ `idempotency_conflict`. The action set is closed — there is no shell, tool, Herdr, or free-text
312
+ surface.
313
+
314
+ ### Failure and reconnect behavior
315
+
316
+ - `{"ok":false,"error":"unauthorized"}` means the token does not match current ownership.
317
+ - `monitor_unavailable` means the hub-side snapshot/output/cancel handler failed closed.
318
+ - `response_too_large` means the consumer must fall back to a fresh bounded snapshot or cursor.
319
+ - An empty response indicates malformed or out-of-contract input; do not retry it unchanged.
320
+ - When the lease expires, the socket closes, or ownership changes, discard the token and repeat
321
+ discovery. Never fall back to public TCP, a gateway endpoint, or Herdr pane control.
322
+
323
+ Stopping the hub removes its owned discovery, token, and socket. Historical monitor journals under
324
+ the configured runtime root are separate from this live registration and should be removed only by
325
+ an operator who has identified the exact profile/runtime scope.
326
+
327
+ ## Usage notes
328
+
329
+ For `hub-liaison`, ensure the Telegram-capable profile has terminal/file-write tools enabled so it can create exactly `~/.pi/coms/hermes-bridge/questions/<qid>.answer.json` and nothing outside that questions directory.
330
+
331
+ For `hub-conductor`, either start the pi team/pool outside Hermes first, or use the repo recipe to create a visible conductor workspace:
332
+
333
+ ```bash
334
+ just conductor docs # conductor pane (`hermes -p dev`) + docs team panes
335
+ just fleet conductor hermes docs --dry-run # preview, no Herdr calls
336
+ ```
337
+
338
+ Inside Hermes, discover and delegate only through coms:
339
+
340
+ ```bash
341
+ node --experimental-strip-types /home/nchankov/repos/agent-fleet/scripts/coms-cli.ts list
342
+ node --experimental-strip-types /home/nchankov/repos/agent-fleet/scripts/coms-cli.ts send <peer> "<task>" --await --timeout 300000
343
+ ```
344
+
345
+ Hermes must not drive herdr panes or workspaces; the `just conductor` recipe creates the pane before Hermes starts. The no-herdr boundary is documented in `docs/coms-hermes-bridge.md` and governed by `.pi/damage-control-rules.yaml`.
346
+
347
+ Hermes/Telegram remains the inbound `ask_user` path beside the experimental Codex remote-control conductor. Codex is outbound-initiated, approval-gated, and serialized through the validated wrapper; both Hermes and Codex contracts remain advisory outside Pi damage-control, and neither external process has an OS command allowlist. See the [Codex operator runbook](../docs/codex-remote-conductor.md).