@chankov/agent-fleet 0.0.3 → 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 (329) hide show
  1. package/.claude/commands/setup-agent-fleet.md +1 -1
  2. package/.opencode/commands/af-setup-agent-fleet.md +1 -1
  3. package/.pi/harnesses/agent-hub/README.md +199 -16
  4. package/.pi/harnesses/agent-hub/access-approval.ts +135 -0
  5. package/.pi/harnesses/agent-hub/delegate.ts +32 -9
  6. package/.pi/harnesses/agent-hub/drift-watchdog.js +165 -0
  7. package/.pi/harnesses/agent-hub/footer.ts +29 -0
  8. package/.pi/harnesses/agent-hub/helpers.ts +49 -0
  9. package/.pi/harnesses/agent-hub/index.ts +1033 -242
  10. package/.pi/harnesses/agent-hub/monitor-control.ts +9 -0
  11. package/.pi/harnesses/agent-hub/monitor-lifecycle.ts +13 -0
  12. package/.pi/harnesses/agent-hub/monitor-publisher.ts +59 -0
  13. package/.pi/harnesses/agent-hub/monitor-recovery.ts +3 -0
  14. package/.pi/harnesses/agent-hub/monitor-runtime.ts +3 -0
  15. package/.pi/harnesses/agent-hub/monitor-session-bridge.ts +11 -0
  16. package/.pi/harnesses/agent-hub/package.json +5 -4
  17. package/.pi/harnesses/agent-hub/research-watchdog.ts +40 -0
  18. package/.pi/harnesses/agent-hub/run-budget.js +155 -0
  19. package/.pi/harnesses/agent-hub/safety-routing.ts +22 -0
  20. package/.pi/harnesses/agent-hub/spawn.ts +161 -94
  21. package/.pi/harnesses/agent-hub/version.ts +18 -0
  22. package/.pi/harnesses/coms/README.md +10 -0
  23. package/.pi/harnesses/coms/index.ts +2 -0
  24. package/.pi/harnesses/coms/package.json +5 -4
  25. package/.pi/harnesses/coms/version.ts +18 -0
  26. package/.pi/harnesses/damage-control-continue/README.md +32 -31
  27. package/.pi/harnesses/damage-control-continue/index.ts +23 -9
  28. package/.pi/harnesses/damage-control-continue/package.json +5 -4
  29. package/.pi/harnesses/damage-control-continue/version.ts +18 -0
  30. package/.pi/harnesses/{damage-control/shared.ts → lib/damage-control-shared.ts} +20 -6
  31. package/.pi/prompts/setup-agent-fleet.md +1 -1
  32. package/.versions/0.0.4/.claude/commands/build.md +44 -0
  33. package/.versions/0.0.4/.claude/commands/code-simplify.md +22 -0
  34. package/.versions/0.0.4/.claude/commands/design-agent.md +14 -0
  35. package/.versions/0.0.4/.claude/commands/doctor-agent-fleet.md +17 -0
  36. package/.versions/0.0.4/.claude/commands/orchestrate.md +112 -0
  37. package/.versions/0.0.4/.claude/commands/plan.md +16 -0
  38. package/.versions/0.0.4/.claude/commands/prime.md +22 -0
  39. package/.versions/0.0.4/.claude/commands/review.md +16 -0
  40. package/.versions/0.0.4/.claude/commands/setup-agent-fleet.md +25 -0
  41. package/.versions/0.0.4/.claude/commands/ship.md +72 -0
  42. package/.versions/0.0.4/.claude/commands/spec.md +15 -0
  43. package/.versions/0.0.4/.claude/commands/test.md +19 -0
  44. package/.versions/0.0.4/.claude/commands/webperf.md +32 -0
  45. package/.versions/0.0.4/.claude/orchestrate-teams.yaml +24 -0
  46. package/.versions/0.0.4/.opencode/commands/af-build.md +17 -0
  47. package/.versions/0.0.4/.opencode/commands/af-code-simplify.md +16 -0
  48. package/.versions/0.0.4/.opencode/commands/af-compound.md +16 -0
  49. package/.versions/0.0.4/.opencode/commands/af-design-agent.md +15 -0
  50. package/.versions/0.0.4/.opencode/commands/af-doctor-agent-fleet.md +17 -0
  51. package/.versions/0.0.4/.opencode/commands/af-orchestrate.md +112 -0
  52. package/.versions/0.0.4/.opencode/commands/af-plan.md +16 -0
  53. package/.versions/0.0.4/.opencode/commands/af-prime.md +22 -0
  54. package/.versions/0.0.4/.opencode/commands/af-review.md +15 -0
  55. package/.versions/0.0.4/.opencode/commands/af-setup-agent-fleet.md +15 -0
  56. package/.versions/0.0.4/.opencode/commands/af-ship.md +16 -0
  57. package/.versions/0.0.4/.opencode/commands/af-spec.md +16 -0
  58. package/.versions/0.0.4/.opencode/commands/af-test.md +21 -0
  59. package/.versions/0.0.4/.opencode/commands/af-webperf.md +32 -0
  60. package/.versions/0.0.4/.opencode/orchestrate-teams.yaml +24 -0
  61. package/.versions/0.0.4/.pi/agents/dispatch-policy.yaml +32 -0
  62. package/.versions/0.0.4/.pi/agents/model-profiles.yaml +20 -0
  63. package/.versions/0.0.4/.pi/agents/peers.yaml +146 -0
  64. package/.versions/0.0.4/.pi/agents/teams.yaml +39 -0
  65. package/.versions/0.0.4/.pi/damage-control-rules.yaml +297 -0
  66. package/.versions/0.0.4/.pi/extensions/agent-fleet-update-check/README.md +58 -0
  67. package/.versions/0.0.4/.pi/extensions/agent-fleet-update-check/index.ts +161 -0
  68. package/{.pi/harnesses/damage-control → .versions/0.0.4/.pi/extensions/agent-fleet-update-check}/package.json +1 -1
  69. package/.versions/0.0.4/.pi/extensions/btw/README.md +118 -0
  70. package/.versions/0.0.4/.pi/extensions/btw/index.ts +917 -0
  71. package/.versions/0.0.4/.pi/extensions/btw/package.json +6 -0
  72. package/.versions/0.0.4/.pi/extensions/btw/state.js +179 -0
  73. package/.versions/0.0.4/.pi/extensions/chrome-devtools-mcp/README.md +58 -0
  74. package/.versions/0.0.4/.pi/extensions/chrome-devtools-mcp/index.ts +92 -0
  75. package/.versions/0.0.4/.pi/extensions/chrome-devtools-mcp/package.json +6 -0
  76. package/.versions/0.0.4/.pi/extensions/compact-and-continue/README.md +42 -0
  77. package/.versions/0.0.4/.pi/extensions/compact-and-continue/index.ts +120 -0
  78. package/.versions/0.0.4/.pi/extensions/compact-and-continue/package.json +6 -0
  79. package/.versions/0.0.4/.pi/extensions/mcp-bridge/README.md +46 -0
  80. package/.versions/0.0.4/.pi/extensions/mcp-bridge/index.ts +206 -0
  81. package/.versions/0.0.4/.pi/extensions/mcp-bridge/package.json +6 -0
  82. package/.versions/0.0.4/.pi/extensions/package-lock.json +1143 -0
  83. package/.versions/0.0.4/.pi/extensions/package.json +9 -0
  84. package/.versions/0.0.4/.pi/extensions/pi-voice-stt/README.md +201 -0
  85. package/.versions/0.0.4/.pi/extensions/pi-voice-stt/config.ts +198 -0
  86. package/.versions/0.0.4/.pi/extensions/pi-voice-stt/examples/stt.json +35 -0
  87. package/.versions/0.0.4/.pi/extensions/pi-voice-stt/index.ts +248 -0
  88. package/.versions/0.0.4/.pi/extensions/pi-voice-stt/package.json +6 -0
  89. package/.versions/0.0.4/.pi/extensions/pi-voice-stt/providers.ts +214 -0
  90. package/.versions/0.0.4/.pi/extensions/pi-voice-stt/recorder.ts +158 -0
  91. package/.versions/0.0.4/.pi/harnesses/agent-hub/README.md +798 -0
  92. package/.versions/0.0.4/.pi/harnesses/agent-hub/access-approval.ts +135 -0
  93. package/.versions/0.0.4/.pi/harnesses/agent-hub/artifacts.js +92 -0
  94. package/.versions/0.0.4/.pi/harnesses/agent-hub/backend-policy.js +153 -0
  95. package/.versions/0.0.4/.pi/harnesses/agent-hub/delegate.ts +386 -0
  96. package/.versions/0.0.4/.pi/harnesses/agent-hub/drift-watchdog.js +165 -0
  97. package/.versions/0.0.4/.pi/harnesses/agent-hub/evidence-rules.js +96 -0
  98. package/.versions/0.0.4/.pi/harnesses/agent-hub/footer.ts +29 -0
  99. package/.versions/0.0.4/.pi/harnesses/agent-hub/helpers.ts +214 -0
  100. package/.versions/0.0.4/.pi/harnesses/agent-hub/index.ts +8045 -0
  101. package/.versions/0.0.4/.pi/harnesses/agent-hub/monitor-control.ts +9 -0
  102. package/.versions/0.0.4/.pi/harnesses/agent-hub/monitor-lifecycle.ts +13 -0
  103. package/.versions/0.0.4/.pi/harnesses/agent-hub/monitor-publisher.ts +59 -0
  104. package/.versions/0.0.4/.pi/harnesses/agent-hub/monitor-recovery.ts +3 -0
  105. package/.versions/0.0.4/.pi/harnesses/agent-hub/monitor-runtime.ts +3 -0
  106. package/.versions/0.0.4/.pi/harnesses/agent-hub/monitor-session-bridge.ts +11 -0
  107. package/.versions/0.0.4/.pi/harnesses/agent-hub/package.json +7 -0
  108. package/.versions/0.0.4/.pi/harnesses/agent-hub/research-retention.js +34 -0
  109. package/.versions/0.0.4/.pi/harnesses/agent-hub/research-watchdog.ts +40 -0
  110. package/.versions/0.0.4/.pi/harnesses/agent-hub/return-contract.js +215 -0
  111. package/.versions/0.0.4/.pi/harnesses/agent-hub/run-budget.js +155 -0
  112. package/.versions/0.0.4/.pi/harnesses/agent-hub/safety-routing.ts +22 -0
  113. package/.versions/0.0.4/.pi/harnesses/agent-hub/scope-gate.js +103 -0
  114. package/.versions/0.0.4/.pi/harnesses/agent-hub/spawn.ts +246 -0
  115. package/.versions/0.0.4/.pi/harnesses/agent-hub/version.ts +18 -0
  116. package/.versions/0.0.4/.pi/harnesses/ask-user-remote/README.md +18 -0
  117. package/.versions/0.0.4/.pi/harnesses/ask-user-remote/index.ts +293 -0
  118. package/.versions/0.0.4/.pi/harnesses/ask-user-remote/race-core.js +106 -0
  119. package/.versions/0.0.4/.pi/harnesses/coms/README.md +92 -0
  120. package/.versions/0.0.4/.pi/harnesses/coms/index.ts +1745 -0
  121. package/.versions/0.0.4/.pi/harnesses/coms/package.json +7 -0
  122. package/.versions/0.0.4/.pi/harnesses/coms/version.ts +18 -0
  123. package/.versions/0.0.4/.pi/harnesses/damage-control-continue/README.md +117 -0
  124. package/.versions/0.0.4/.pi/harnesses/damage-control-continue/index.ts +536 -0
  125. package/.versions/0.0.4/.pi/harnesses/damage-control-continue/package.json +7 -0
  126. package/.versions/0.0.4/.pi/harnesses/damage-control-continue/version.ts +18 -0
  127. package/.versions/0.0.4/.pi/harnesses/lib/damage-control-shared.ts +197 -0
  128. package/.versions/0.0.4/.pi/harnesses/lib/herdr-client.ts +458 -0
  129. package/.versions/0.0.4/.pi/harnesses/lib/herdr-presence.ts +288 -0
  130. package/.versions/0.0.4/.pi/harnesses/package-lock.json +35 -0
  131. package/.versions/0.0.4/.pi/harnesses/package.json +9 -0
  132. package/.versions/0.0.4/.pi/prompts/build.md +24 -0
  133. package/.versions/0.0.4/.pi/prompts/code-simplify.md +22 -0
  134. package/.versions/0.0.4/.pi/prompts/doctor-agent-fleet.md +15 -0
  135. package/.versions/0.0.4/.pi/prompts/plan.md +16 -0
  136. package/.versions/0.0.4/.pi/prompts/review.md +16 -0
  137. package/.versions/0.0.4/.pi/prompts/setup-agent-fleet.md +27 -0
  138. package/.versions/0.0.4/.pi/prompts/ship.md +17 -0
  139. package/.versions/0.0.4/.pi/prompts/spec.md +15 -0
  140. package/.versions/0.0.4/.pi/prompts/test.md +19 -0
  141. package/.versions/0.0.4/.pi/skills/bowser/SKILL.md +145 -0
  142. package/.versions/0.0.4/.version +1 -0
  143. package/.versions/0.0.4/agents/architect.md +23 -0
  144. package/.versions/0.0.4/agents/bowser.md +26 -0
  145. package/.versions/0.0.4/agents/builder.md +53 -0
  146. package/.versions/0.0.4/agents/code-reviewer.md +205 -0
  147. package/.versions/0.0.4/agents/deep-researcher.md +31 -0
  148. package/.versions/0.0.4/agents/documenter.md +18 -0
  149. package/.versions/0.0.4/agents/orchestrator.md +54 -0
  150. package/.versions/0.0.4/agents/plan-reviewer.md +60 -0
  151. package/.versions/0.0.4/agents/planner.md +69 -0
  152. package/.versions/0.0.4/agents/releaser.md +24 -0
  153. package/.versions/0.0.4/agents/researcher.md +28 -0
  154. package/.versions/0.0.4/agents/security-auditor.md +166 -0
  155. package/.versions/0.0.4/agents/test-engineer.md +151 -0
  156. package/.versions/0.0.4/agents/web-debugger.md +42 -0
  157. package/.versions/0.0.4/agents/web-performance-auditor.md +192 -0
  158. package/.versions/0.0.4/codex/CONDUCTOR.md +148 -0
  159. package/.versions/0.0.4/docs/ARCHITECTURE.md +210 -0
  160. package/.versions/0.0.4/docs/agent-fleet-setup.md +366 -0
  161. package/.versions/0.0.4/docs/claude-code-coms-bridge.md +103 -0
  162. package/.versions/0.0.4/docs/codex-remote-conductor.md +170 -0
  163. package/.versions/0.0.4/docs/coms-hermes-bridge.md +121 -0
  164. package/.versions/0.0.4/docs/getting-started.md +183 -0
  165. package/.versions/0.0.4/docs/npm-install.md +337 -0
  166. package/.versions/0.0.4/docs/opencode-setup.md +248 -0
  167. package/.versions/0.0.4/docs/pi-extensions.md +288 -0
  168. package/.versions/0.0.4/docs/pi-setup.md +463 -0
  169. package/.versions/0.0.4/docs/skill-anatomy.md +150 -0
  170. package/.versions/0.0.4/hermes/README.md +228 -0
  171. package/.versions/0.0.4/hermes/desktop-plugins/agent-fleet-monitor/plugin.js +19 -0
  172. package/.versions/0.0.4/hermes/desktop-plugins/agent-fleet-monitor/state.js +10 -0
  173. package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/adapter-cap.test.py +15 -0
  174. package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/adapter-discovery.test.py +19 -0
  175. package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/adapter-envelope.test.py +13 -0
  176. package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/adapter-forged-owner.test.py +11 -0
  177. package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/adapter-lease-list.test.py +9 -0
  178. package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/adapter-multihub.test.py +17 -0
  179. package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/adapter-output.test.py +34 -0
  180. package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/adapter.py +151 -0
  181. package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/adapter.test.py +39 -0
  182. package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/manifest.json +11 -0
  183. package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/plugin-api-validation.test.py +12 -0
  184. package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/plugin_api.py +50 -0
  185. package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/review-live-wiring.red.test.py +22 -0
  186. package/.versions/0.0.4/hermes/skills/hub-conductor/SKILL.md +84 -0
  187. package/.versions/0.0.4/hermes/skills/hub-liaison/SKILL.md +84 -0
  188. package/.versions/0.0.4/hooks/SIMPLIFY-IGNORE.md +90 -0
  189. package/.versions/0.0.4/hooks/coms-stop-hook.mjs +73 -0
  190. package/.versions/0.0.4/hooks/hooks.json +14 -0
  191. package/.versions/0.0.4/hooks/session-start.sh +74 -0
  192. package/.versions/0.0.4/hooks/simplify-ignore.sh +302 -0
  193. package/.versions/0.0.4/justfile +256 -0
  194. package/.versions/0.0.4/references/accessibility-checklist.md +160 -0
  195. package/.versions/0.0.4/references/definition-of-done.md +67 -0
  196. package/.versions/0.0.4/references/fleet-coordination-patterns.md +151 -0
  197. package/.versions/0.0.4/references/observability-checklist.md +91 -0
  198. package/.versions/0.0.4/references/orchestration-patterns.md +370 -0
  199. package/.versions/0.0.4/references/performance-checklist.md +153 -0
  200. package/.versions/0.0.4/references/prompting-patterns.md +380 -0
  201. package/.versions/0.0.4/references/security-checklist.md +179 -0
  202. package/.versions/0.0.4/references/testing-patterns.md +236 -0
  203. package/.versions/0.0.4/scripts/codex-conductor.ts +41 -0
  204. package/.versions/0.0.4/scripts/codex-remote-control.ts +167 -0
  205. package/.versions/0.0.4/scripts/coms-claude-bridge.ts +286 -0
  206. package/.versions/0.0.4/scripts/coms-cli.ts +484 -0
  207. package/.versions/0.0.4/scripts/coms-hermes-bridge.ts +403 -0
  208. package/.versions/0.0.4/scripts/hermes-monitor-capability-runner.ts +25 -0
  209. package/.versions/0.0.4/scripts/hermes-monitor-scenario.ts +7 -0
  210. package/.versions/0.0.4/scripts/lib/claude-bridge-core.ts +100 -0
  211. package/.versions/0.0.4/scripts/lib/codex-conductor.ts +88 -0
  212. package/.versions/0.0.4/scripts/lib/codex-remote-control.ts +480 -0
  213. package/.versions/0.0.4/scripts/lib/coms-envelope.ts +539 -0
  214. package/.versions/0.0.4/scripts/lib/fake-herdr-server.ts +88 -0
  215. package/.versions/0.0.4/scripts/lib/herdr-layout.ts +263 -0
  216. package/.versions/0.0.4/scripts/lib/hermes-bridge-core.ts +238 -0
  217. package/.versions/0.0.4/scripts/lib/hermes-monitor-herdr.ts +28 -0
  218. package/.versions/0.0.4/scripts/lib/hermes-monitor-model.ts +9 -0
  219. package/.versions/0.0.4/scripts/lib/hermes-monitor-registry.ts +6 -0
  220. package/.versions/0.0.4/scripts/lib/hermes-monitor-socket.ts +118 -0
  221. package/.versions/0.0.4/scripts/lib/hermes-monitor-store.ts +31 -0
  222. package/.versions/0.0.4/scripts/lib/persona-banner.ts +62 -0
  223. package/.versions/0.0.4/scripts/lib/spawn-stagger.ts +101 -0
  224. package/.versions/0.0.4/scripts/lib/team-project.ts +184 -0
  225. package/.versions/0.0.4/scripts/lib/team-snapshot.ts +147 -0
  226. package/.versions/0.0.4/scripts/peer-banner.ts +40 -0
  227. package/.versions/0.0.4/scripts/team-snapshot.ts +238 -0
  228. package/.versions/0.0.4/scripts/team-up.ts +333 -0
  229. package/.versions/0.0.4/skills/_internal/grilling.md +11 -0
  230. package/.versions/0.0.4/skills/browser-testing-with-devtools/SKILL.md +352 -0
  231. package/.versions/0.0.4/skills/code-review-and-quality/SKILL.md +381 -0
  232. package/.versions/0.0.4/skills/compound-learning/SKILL.md +137 -0
  233. package/.versions/0.0.4/skills/context-engineering/SKILL.md +291 -0
  234. package/.versions/0.0.4/skills/deprecation-and-migration/SKILL.md +206 -0
  235. package/.versions/0.0.4/skills/designing-agents/SKILL.md +394 -0
  236. package/.versions/0.0.4/skills/designing-agents/pi-harness-authoring.md +222 -0
  237. package/.versions/0.0.4/skills/frontend-ui-engineering/SKILL.md +328 -0
  238. package/.versions/0.0.4/skills/git-workflow-and-versioning/SKILL.md +316 -0
  239. package/.versions/0.0.4/skills/guided-workspace-setup/SKILL.md +535 -0
  240. package/.versions/0.0.4/skills/guided-workspace-setup/companion-manifest.json +33 -0
  241. package/.versions/0.0.4/skills/idea-refine/SKILL.md +182 -0
  242. package/.versions/0.0.4/skills/idea-refine/examples.md +238 -0
  243. package/.versions/0.0.4/skills/idea-refine/frameworks.md +99 -0
  244. package/.versions/0.0.4/skills/idea-refine/refinement-criteria.md +113 -0
  245. package/.versions/0.0.4/skills/idea-refine/scripts/idea-refine.sh +15 -0
  246. package/.versions/0.0.4/skills/incremental-implementation/SKILL.md +287 -0
  247. package/.versions/0.0.4/skills/interview-me/SKILL.md +226 -0
  248. package/.versions/0.0.4/skills/orchestration-verification/SKILL.md +181 -0
  249. package/.versions/0.0.4/skills/peer-coms/SKILL.md +90 -0
  250. package/.versions/0.0.4/skills/performance-optimization/SKILL.md +350 -0
  251. package/.versions/0.0.4/skills/planning-and-task-breakdown/SKILL.md +236 -0
  252. package/.versions/0.0.4/skills/security-and-hardening/SKILL.md +461 -0
  253. package/.versions/0.0.4/skills/spec-driven-development/SKILL.md +245 -0
  254. package/.versions/0.0.4/skills/using-agent-skills/SKILL.md +199 -0
  255. package/.versions/0.0.4/systemd/user/agent-fleet-codex-remote-control.service.in +23 -0
  256. package/.versions/0.0.4/vendor/agent-skills-upstream/LICENSE +21 -0
  257. package/.versions/0.0.4/vendor/agent-skills-upstream/README.md +11 -0
  258. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/api-and-interface-design/SKILL.md +294 -0
  259. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/browser-testing-with-devtools/SKILL.md +317 -0
  260. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/ci-cd-and-automation/SKILL.md +390 -0
  261. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/code-review-and-quality/SKILL.md +396 -0
  262. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/code-simplification/SKILL.md +331 -0
  263. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/context-engineering/SKILL.md +289 -0
  264. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/debugging-and-error-recovery/SKILL.md +300 -0
  265. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/deprecation-and-migration/SKILL.md +247 -0
  266. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/documentation-and-adrs/SKILL.md +278 -0
  267. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/doubt-driven-development/SKILL.md +243 -0
  268. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/frontend-ui-engineering/SKILL.md +328 -0
  269. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/git-workflow-and-versioning/SKILL.md +355 -0
  270. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/idea-refine/SKILL.md +178 -0
  271. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/idea-refine/examples.md +238 -0
  272. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/idea-refine/frameworks.md +99 -0
  273. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/idea-refine/refinement-criteria.md +113 -0
  274. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/idea-refine/scripts/idea-refine.sh +15 -0
  275. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/incremental-implementation/SKILL.md +249 -0
  276. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/interview-me/SKILL.md +225 -0
  277. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/observability-and-instrumentation/SKILL.md +203 -0
  278. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/performance-optimization/SKILL.md +350 -0
  279. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/planning-and-task-breakdown/SKILL.md +234 -0
  280. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/security-and-hardening/SKILL.md +467 -0
  281. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/shipping-and-launch/SKILL.md +310 -0
  282. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/source-driven-development/SKILL.md +194 -0
  283. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/spec-driven-development/SKILL.md +206 -0
  284. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/test-driven-development/SKILL.md +383 -0
  285. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/using-agent-skills/SKILL.md +191 -0
  286. package/CHANGELOG.md +53 -0
  287. package/README.md +3 -3
  288. package/agents/builder.md +1 -1
  289. package/agents/code-reviewer.md +1 -1
  290. package/agents/deep-researcher.md +3 -3
  291. package/agents/orchestrator.md +20 -11
  292. package/agents/plan-reviewer.md +3 -3
  293. package/agents/test-engineer.md +11 -4
  294. package/bin/lib/validate-overrides.js +19 -0
  295. package/bin/sync-harness-versions.js +94 -0
  296. package/docs/ARCHITECTURE.md +46 -1
  297. package/docs/agent-fleet-setup.md +10 -0
  298. package/docs/pi-extensions.md +49 -14
  299. package/docs/pi-setup.md +10 -4
  300. package/hermes/README.md +180 -0
  301. package/hermes/desktop-plugins/agent-fleet-monitor/plugin.js +19 -0
  302. package/hermes/desktop-plugins/agent-fleet-monitor/state.js +10 -0
  303. package/hermes/plugins/agent-fleet-monitor/dashboard/adapter-cap.test.py +15 -0
  304. package/hermes/plugins/agent-fleet-monitor/dashboard/adapter-discovery.test.py +19 -0
  305. package/hermes/plugins/agent-fleet-monitor/dashboard/adapter-envelope.test.py +13 -0
  306. package/hermes/plugins/agent-fleet-monitor/dashboard/adapter-forged-owner.test.py +11 -0
  307. package/hermes/plugins/agent-fleet-monitor/dashboard/adapter-lease-list.test.py +9 -0
  308. package/hermes/plugins/agent-fleet-monitor/dashboard/adapter-multihub.test.py +17 -0
  309. package/hermes/plugins/agent-fleet-monitor/dashboard/adapter-output.test.py +34 -0
  310. package/hermes/plugins/agent-fleet-monitor/dashboard/adapter.py +151 -0
  311. package/hermes/plugins/agent-fleet-monitor/dashboard/adapter.test.py +39 -0
  312. package/hermes/plugins/agent-fleet-monitor/dashboard/dist/index.js +10 -0
  313. package/hermes/plugins/agent-fleet-monitor/dashboard/manifest.json +11 -0
  314. package/hermes/plugins/agent-fleet-monitor/dashboard/plugin-api-validation.test.py +12 -0
  315. package/hermes/plugins/agent-fleet-monitor/dashboard/plugin_api.py +50 -0
  316. package/hermes/plugins/agent-fleet-monitor/dashboard/review-live-wiring.red.test.py +22 -0
  317. package/justfile +6 -10
  318. package/package.json +9 -4
  319. package/scripts/lib/fake-herdr-server.ts +88 -0
  320. package/scripts/lib/hermes-monitor-herdr.ts +28 -0
  321. package/scripts/lib/hermes-monitor-model.ts +9 -0
  322. package/scripts/lib/hermes-monitor-registry.ts +6 -0
  323. package/scripts/lib/hermes-monitor-socket.ts +118 -0
  324. package/scripts/lib/hermes-monitor-store.ts +31 -0
  325. package/skills/designing-agents/SKILL.md +2 -2
  326. package/skills/designing-agents/pi-harness-authoring.md +26 -13
  327. package/skills/guided-workspace-setup/SKILL.md +11 -8
  328. package/.pi/harnesses/damage-control/README.md +0 -65
  329. package/.pi/harnesses/damage-control/index.ts +0 -250
@@ -0,0 +1,118 @@
1
+ import * as crypto from "node:crypto";
2
+ import * as fs from "node:fs";
3
+ import * as net from "node:net";
4
+ import * as path from "node:path";
5
+
6
+ import type { MonitorRegistration } from "./hermes-monitor-registry.ts";
7
+
8
+ export const MAX_SOCKET_FRAME_BYTES = 64 * 1024;
9
+ export const MAX_SNAPSHOT_BYTES = 256 * 1024;
10
+ export const MAX_CANCEL_RESPONSE_BYTES = 16 * 1024;
11
+ export const PARTIAL_FRAME_TIMEOUT_MS = 1000;
12
+ export const MAX_SOCKET_CONNECTIONS = 32;
13
+ export const MAX_TASK_ID_LENGTH = 128;
14
+ export const MAX_AFTER_SEQUENCE = 1_000_000_000;
15
+ /** 2 MiB covers the 256 KiB retained UTF-8 output after worst-case JSON escaping plus its envelope. */
16
+ export const MAX_OUTPUT_RESPONSE_BYTES = 2 * 1024 * 1024;
17
+
18
+ interface SnapshotRequest {
19
+ type: "snapshot";
20
+ token: string;
21
+ }
22
+
23
+ function authorized(actual: string, expected: string): boolean {
24
+ const actualBytes = Buffer.from(actual);
25
+ const expectedBytes = Buffer.from(expected);
26
+ return actualBytes.length === expectedBytes.length && crypto.timingSafeEqual(actualBytes, expectedBytes);
27
+ }
28
+
29
+ function validTaskRequest(taskId: unknown, generation: unknown, afterSequence?: unknown): boolean { return typeof taskId === "string" && /^[A-Za-z0-9][A-Za-z0-9._:-]*$/.test(taskId) && taskId.length <= MAX_TASK_ID_LENGTH && Number.isInteger(generation) && (generation as number) >= 1 && (afterSequence === undefined || (Number.isInteger(afterSequence) && (afterSequence as number) >= 0 && (afterSequence as number) <= MAX_AFTER_SEQUENCE)); }
30
+
31
+ function parseRequest(frame: string): SnapshotRequest | null {
32
+ try {
33
+ const value = JSON.parse(frame) as Partial<SnapshotRequest>;
34
+ if (value.type !== "snapshot" || typeof value.token !== "string") return null;
35
+ return { type: "snapshot", token: value.token };
36
+ } catch {
37
+ return null;
38
+ }
39
+ }
40
+
41
+ export class MonitorSocketServer {
42
+ private readonly registration: MonitorRegistration;
43
+ private readonly server: net.Server;
44
+ private connections = 0;
45
+
46
+ constructor(registration: MonitorRegistration) {
47
+ this.registration = registration;
48
+ this.server = net.createServer((socket) => {
49
+ if (this.connections >= MAX_SOCKET_CONNECTIONS) { socket.destroy(); return; }
50
+ this.connections += 1;
51
+ socket.once("close", () => { this.connections -= 1; });
52
+ this.handle(socket);
53
+ });
54
+ }
55
+
56
+ private assertOwnedSocketPath(): void {
57
+ if (!this.registration.socketDir || path.resolve(this.registration.socketPath) !== path.join(path.resolve(this.registration.socketDir), "s")) throw new Error("monitor socket path is not registry-owned");
58
+ if (fs.lstatSync(this.registration.socketDir).isSymbolicLink() || (fs.statSync(this.registration.socketDir).mode & 0o777) !== 0o700) throw new Error("monitor socket directory is unsafe");
59
+ }
60
+ private async removeVerifiedStaleSocket(): Promise<void> {
61
+ this.assertOwnedSocketPath(); if (!fs.existsSync(this.registration.socketPath)) return;
62
+ const active=await new Promise<boolean>(resolve=>{const probe=net.createConnection(this.registration.socketPath);probe.once("connect",()=>{probe.destroy();resolve(true);});probe.once("error",()=>resolve(false));});
63
+ if (active) throw new Error("monitor socket is already active");
64
+ if (fs.lstatSync(this.registration.socketPath).isSymbolicLink()) throw new Error("monitor socket must not be a symlink"); fs.unlinkSync(this.registration.socketPath);
65
+ }
66
+ async listen(): Promise<void> {
67
+ await this.removeVerifiedStaleSocket(); return new Promise((resolve, reject) => { this.server.once("error", reject); this.server.listen(this.registration.socketPath, () => { this.server.off("error", reject); fs.chmodSync(this.registration.socketPath, 0o600); resolve(); }); });
68
+ }
69
+
70
+ async close(): Promise<void> {
71
+ await new Promise<void>((resolve, reject) => this.server.close((error) => error ? reject(error) : resolve()));
72
+ this.assertOwnedSocketPath(); try { fs.unlinkSync(this.registration.socketPath); } catch (error: any) { if (error?.code !== "ENOENT") throw error; }
73
+ }
74
+
75
+ mode(): number {
76
+ return fs.statSync(this.registration.socketPath).mode & 0o777;
77
+ }
78
+
79
+ private handle(socket: net.Socket): void {
80
+ let buffer = "";
81
+ let handled = false;
82
+ const deadline = setTimeout(() => { if (!handled) socket.destroy(); }, PARTIAL_FRAME_TIMEOUT_MS);
83
+ socket.on("data", (chunk) => {
84
+ if (handled) return;
85
+ buffer += chunk.toString("utf8");
86
+ if (Buffer.byteLength(buffer, "utf8") > MAX_SOCKET_FRAME_BYTES) {
87
+ socket.destroy();
88
+ return;
89
+ }
90
+ const newline = buffer.indexOf("\n");
91
+ if (newline < 0) return;
92
+ handled = true;
93
+ const request = parseRequest(buffer.slice(0, newline));
94
+ clearTimeout(deadline);
95
+ let value: { type?: string; token?: string; taskId?: string; generation?: number };
96
+ try { value = JSON.parse(buffer.slice(0, newline)) as typeof value; } catch { socket.destroy(); return; }
97
+ if (value.type === "output") {
98
+ if (!authorized(String(value.token ?? ""), this.registration.token)) { socket.end(JSON.stringify({ ok: false, error: "unauthorized" }) + "\n"); return; }
99
+ if (!this.registration.output || (value as any).afterSequence === undefined || !validTaskRequest(value.taskId, value.generation, (value as any).afterSequence)) { socket.destroy(); return; }
100
+ Promise.resolve().then(()=>this.registration.output!({ taskId: value.taskId!, generation: value.generation!, afterSequence: (value as any).afterSequence })).then((output) => { const body=JSON.stringify({ ok:true, output }); if(Buffer.byteLength(body)>MAX_OUTPUT_RESPONSE_BYTES) socket.end(JSON.stringify({ok:false,error:"response_too_large"})+"\n"); else socket.end(body+"\n"); }).catch(()=>socket.end(JSON.stringify({ok:false,error:"monitor_unavailable"})+"\n")); return;
101
+ }
102
+ if (value.type === "cancel") {
103
+ if (!authorized(String(value.token ?? ""), this.registration.token)) { socket.end(JSON.stringify({ ok: false, error: "unauthorized" }) + "\n"); return; }
104
+ if (!this.registration.cancel || !validTaskRequest(value.taskId, value.generation)) { socket.destroy(); return; }
105
+ Promise.resolve().then(()=>this.registration.cancel!({ taskId: value.taskId!, generation: value.generation! })).then((result) => { const body=JSON.stringify({ ok: true, result }); if (Buffer.byteLength(body, "utf8") > MAX_CANCEL_RESPONSE_BYTES) socket.end(JSON.stringify({ok:false,error:"response_too_large"})+"\n"); else socket.end(body + "\n"); }).catch(()=>socket.end(JSON.stringify({ok:false,error:"monitor_unavailable"})+"\n")); return;
106
+ }
107
+ if (!request || !authorized(request.token, this.registration.token)) {
108
+ if (request) socket.end(JSON.stringify({ ok: false, error: "unauthorized" }) + "\n");
109
+ else socket.destroy();
110
+ return;
111
+ }
112
+ try { const response = JSON.stringify({ ok: true, snapshot: this.registration.snapshot() }); if (Buffer.byteLength(response, "utf8") > MAX_SNAPSHOT_BYTES) socket.end(JSON.stringify({ok:false,error:"response_too_large"})+"\n"); else socket.end(response + "\n"); } catch { socket.end(JSON.stringify({ok:false,error:"monitor_unavailable"})+"\n"); }
113
+ });
114
+ socket.on("end", () => {
115
+ if (!handled) socket.destroy();
116
+ });
117
+ }
118
+ }
@@ -0,0 +1,31 @@
1
+ import { createChildTask, createParentTask, type CreateChildTaskInput, type CreateParentTaskInput, type MonitorTask } from "./hermes-monitor-model.ts";
2
+ export const MAX_OUTPUT_BYTES=256*1024;
3
+ export const MONITOR_RETENTION_MS=7*24*60*60*1000;
4
+ export const MONITOR_RETENTION_MAX=200;
5
+ const terminal=new Set(["completed","blocked","failed","cancelled","orphaned","done"]);
6
+ const active=(state:string)=>state==="starting"||state==="running"||state==="cancelling"||state==="recovering";
7
+ export function pruneMonitorTasks<T extends {state:string;updatedAt?:string}>(options:{now:Date;tasks:T[]}):T[]{const cutoff=options.now.getTime()-MONITOR_RETENTION_MS;const running=options.tasks.filter(t=>active(t.state));const terminalTasks=options.tasks.filter(t=>!active(t.state)&&(!t.updatedAt||new Date(t.updatedAt).getTime()>=cutoff)).sort((a,b)=>new Date(a.updatedAt??0).getTime()-new Date(b.updatedAt??0).getTime()).slice(-MONITOR_RETENTION_MAX);return [...running,...terminalTasks];}
8
+ export interface MonitorOutput{text:string;sequence:number;firstSequence:number;truncated:boolean}
9
+ interface StoredOutput{chunks:{sequence:number;text:string}[];sequence:number;truncated:boolean}
10
+ interface StoredTask{task:MonitorTask;output:StoredOutput;createdAt:string;updatedAt:string}
11
+ function suffix(text:string,limit:number){let bytes=0;const chars:string[]=[];for(const char of Array.from(text).reverse()){const size=Buffer.byteLength(char);if(bytes+size>limit)break;chars.push(char);bytes+=size;}return chars.reverse().join("");}
12
+
13
+ export class MonitorStore {
14
+ private readonly tasks=new Map<string,StoredTask>(); private readonly now:()=>Date;
15
+ constructor(options:{now?:()=>Date}={}){this.now=options.now??(()=>new Date());}
16
+ private key(id:string,generation:number){return `${id}:${generation}`;} private stamp(){return this.now().toISOString();}
17
+ createParent(input:CreateParentTaskInput){return this.add(createParentTask(input));}
18
+ createChild(input:CreateChildTaskInput){if(![...this.tasks.values()].some(s=>s.task.id===input.parentId&&s.task.generation===input.parentGeneration&&s.task.kind==="parent"))throw new Error(`parent task ${input.parentId} was not found`);return this.add(createChildTask(input));}
19
+ patch(id:string,generation:number,values:any){const stored=this.require(id,generation);Object.assign(stored.task,values);stored.updatedAt=this.stamp();return stored.task;}
20
+ transition(id:string,generation:number,state:any){const stored=this.require(id,generation);if(terminal.has(stored.task.state))throw new Error("terminal transition");stored.task.state=state;stored.updatedAt=this.stamp();return stored.task;}
21
+ get(id:string,generation?:number){return generation===undefined?[...this.tasks.values()].find(s=>s.task.id===id)?.task:this.tasks.get(this.key(id,generation))?.task;}
22
+ appendPublicOutput(id:string,generation:number,text:string){const stored=this.require(id,generation);if(terminal.has(stored.task.state))throw new Error("terminal output");const sequence=stored.output.sequence+1, chunk=suffix(text,MAX_OUTPUT_BYTES),chunks=[...stored.output.chunks,{sequence,text:chunk}];let bytes=chunks.reduce((n,c)=>n+Buffer.byteLength(c.text),0),truncated=stored.output.truncated||bytes<Buffer.byteLength(text);while(bytes>MAX_OUTPUT_BYTES&&chunks.length>1){bytes-=Buffer.byteLength(chunks.shift()!.text);truncated=true;}stored.output={chunks,sequence,truncated};stored.updatedAt=this.stamp();return this.outputAfter(stored.output,0);}
23
+ readOutput(id:string,generation:number,afterSequence:number){return this.outputAfter(this.require(id,generation).output,afterSequence);}
24
+ snapshot(){return {tasks:[...this.tasks.values()].map(s=>this.publicTask(s))};} durableSnapshot(){return{tasks:[...this.tasks.values()].map(s=>({...this.publicTask(s),outputChunks:s.output.chunks.map(c=>({...c}),),outputLatestSequence:s.output.sequence,outputFirstSequence:s.output.chunks[0]?.sequence??0,outputTruncated:s.output.truncated}))};} restore(rows:any[]){for(const row of rows){const key=this.key(row.id,row.generation);if(this.tasks.has(key))continue;const output=row.output??"";this.tasks.set(key,{task:{...row},output:{chunks:Array.isArray(row.outputChunks)?row.outputChunks.map((c:any)=>({sequence:c.sequence,text:c.text})):output?[{sequence:row.outputSequence??1,text:output}]:[],sequence:row.outputLatestSequence??row.outputSequence??0,truncated:row.outputTruncated??!!row.truncated},createdAt:row.createdAt??this.stamp(),updatedAt:row.updatedAt??this.stamp()});}}
25
+ prune(now=this.now()){const cutoff=now.getTime()-MONITOR_RETENTION_MS;const values=[...this.tasks.values()];const protectedIds=new Set<string>();for(const s of values)if(active(s.task.state)){protectedIds.add(this.key(s.task.id,s.task.generation));if(s.task.parentId)for(const p of values)if(p.task.id===s.task.parentId)protectedIds.add(this.key(p.task.id,p.task.generation));for(const c of values)if(c.task.parentId===s.task.id)protectedIds.add(this.key(c.task.id,c.task.generation));}const candidates=values.filter(s=>!active(s.task.state)&&!protectedIds.has(this.key(s.task.id,s.task.generation))).sort((a,b)=>Date.parse(a.updatedAt)-Date.parse(b.updatedAt));const expired=candidates.filter(s=>Date.parse(s.updatedAt)<cutoff);for(const s of expired)this.tasks.delete(this.key(s.task.id,s.task.generation));const remaining=[...this.tasks.values()].filter(s=>!active(s.task.state)&&!protectedIds.has(this.key(s.task.id,s.task.generation))).sort((a,b)=>Date.parse(a.updatedAt)-Date.parse(b.updatedAt));while(remaining.length>MONITOR_RETENTION_MAX){const oldest=remaining.shift()!;this.tasks.delete(this.key(oldest.task.id,oldest.task.generation));}return this.snapshot();}
26
+ private add(task:MonitorTask){const key=this.key(task.id,task.generation);if(this.tasks.has(key))throw new Error(`task ${task.id} generation ${task.generation} already exists`);const stamp=this.stamp();this.tasks.set(key,{task,output:{chunks:[],sequence:0,truncated:false},createdAt:stamp,updatedAt:stamp});return task;}
27
+ private publicTask(s:StoredTask){const output=this.outputAfter(s.output,0);return {...s.task,createdAt:s.createdAt,updatedAt:s.updatedAt,outputSequence:output.sequence,firstSequence:output.firstSequence,truncated:output.truncated};}
28
+ private outputAfter(output:StoredOutput,after:number):MonitorOutput{return{text:output.chunks.filter(c=>c.sequence>after).map(c=>c.text).join(""),sequence:output.sequence,firstSequence:output.chunks[0]?.sequence??0,truncated:output.truncated};}
29
+ private require(id:string,generation:number){const stored=this.tasks.get(this.key(id,generation));if(!stored)throw new Error(`task ${id} generation ${generation} was not found`);return stored;}
30
+ }
31
+ export function createMonitorStore(options:{now:()=>Date}){const store=new MonitorStore(options);const baseSnapshot=store.snapshot.bind(store);return Object.assign(store,{snapshot(){const all=(baseSnapshot() as any).tasks;return{tasks:all.filter((t:any)=>t.kind==='parent').map((parent:any)=>({id:parent.id,generation:parent.generation,children:all.filter((child:any)=>child.parentId===parent.id).map((child:any)=>({id:child.id,generation:child.generation,state:child.state,workspaceId:child.workspaceId,hubPaneId:child.hubPaneId,outputSequence:child.outputSequence,updatedAt:child.updatedAt}))}))};}});}
@@ -11,7 +11,7 @@ This repo has three kinds of artifacts that shape how an agent works. Each is au
11
11
 
12
12
  - **Agent personas** live in `agents/<name>.md`. They define a *role* another agent adopts when it needs specialized review, audit, or analysis. Example: `code-reviewer`, `security-auditor`, `test-engineer`.
13
13
  - **Skills** live in `skills/<name>/SKILL.md`. They define a *workflow* — a repeatable process with gated steps, anti-rationalization guardrails, and verification. Example: `spec-driven-development`, `test-driven-development`, `context-engineering`.
14
- - **pi harnesses** live in `.pi/harnesses/<name>/`. They define a *session environment* — a TypeScript pi extension that reshapes the whole session: setting UI surfaces, gating tool calls, registering new tools or commands, or orchestrating sub-agents. Example: `agent-hub`, `damage-control`, `coms`.
14
+ - **pi harnesses** live in `.pi/harnesses/<name>/`. They define a *session environment* — a TypeScript pi extension that reshapes the whole session: setting UI surfaces, gating tool calls, registering new tools or commands, or orchestrating sub-agents. Example: `agent-hub`, `damage-control-continue`, `coms`.
15
15
 
16
16
  Personas and skills are prose that change an agent's *judgment*. A harness is code that changes the agent's *environment* — what it can do and what it sees. All three fail the same way: a persona that reads like general advice gets cited but ignored; a skill that skips its guardrails becomes a suggestion; a harness built without studying the existing ones collides with pi's auto-discovery or fights another extension. This skill is the workflow for authoring any of the three so the result measurably changes behavior.
17
17
 
@@ -316,7 +316,7 @@ A harness is a directory, not a single file. The `ExtensionAPI` surface, the `in
316
316
  | "I'll skip the Output Format section — the agent will figure it out" (persona) | Without a template, outputs drift across invocations and become uncomparable. Reviewers cannot triage findings that don't share a shape. |
317
317
  | "I'll skip the Common Rationalizations table — the steps are obvious" (skill) | Every step that gets skipped had an excuse attached. The table is the only place in the skill that directly blocks those excuses. Skipping it is how skills become suggestions. |
318
318
  | "I'll skip the Verification checklist — the user will know when it's done" (skill) | Without evidence requirements, 'seems right' becomes the completion signal. The checklist is what forces proof. |
319
- | "I'll drop the harness in `.pi/extensions/` so it loads automatically" | pi auto-discovers `.pi/extensions/` and loads everything there at once. Most harnesses are mutually exclusive — footers fight, duplicate CLI flags abort startup. Harnesses live in `.pi/harnesses/` and load explicitly; the supported stack is `damage-control` before `agent-hub`. |
319
+ | "I'll drop the harness in `.pi/extensions/` so it loads automatically" | pi auto-discovers `.pi/extensions/` and loads everything there at once. Most harnesses are mutually exclusive — footers fight, duplicate CLI flags abort startup. Harnesses live in `.pi/harnesses/` and load explicitly; the supported stack loads `damage-control-continue` before `agent-hub`. |
320
320
  | "I'll write the harness `index.ts` from memory — I've seen the pattern" | The `ExtensionAPI` surface is specific and unforgiving; a misspelled event name fails silently. Read `pi-harness-authoring.md` and copy the closest existing harness. |
321
321
  | "I'll skip the harness README and catalog row — `index.ts` is the real artifact" | A harness with no row in `docs/pi-extensions.md` is undiscoverable; no agent will load it. The README is its discovery surface — the same role frontmatter plays for a skill. |
322
322
  | "I'll copy an existing artifact and tweak it" | For prose artifacts, copy-paste creates silent duplication and drift — read the existing files to learn the pattern, then write fresh. For a harness, copying the nearest `index.ts` *is* the recommended start; just rename it cleanly and cut what you don't use. |
@@ -9,8 +9,8 @@ A pi harness is a TypeScript pi extension that reshapes a whole session. The har
9
9
  in `.pi/harnesses/` were ported from `disler/pi-vs-claude-code`; `docs/pi-extensions.md`
10
10
  is their catalog. A harness can:
11
11
 
12
- - set status, widgets, or overlays — `agent-hub`, `damage-control`
13
- - gate every tool call and block or confirm it — `damage-control`
12
+ - set status, widgets, or overlays — `agent-hub`, `damage-control-continue`
13
+ - gate every tool call and block or confirm it — `damage-control-continue`
14
14
  - register a new tool or `/command` — `agent-hub`, `coms`
15
15
  - inject text into the system prompt — `agent-hub`
16
16
  - orchestrate sub-agents — `agent-hub`
@@ -23,37 +23,47 @@ pi auto-discovers and loads **every** directory under `.pi/extensions/`. The thr
23
23
  coexist. Harnesses are different: most are **mutually exclusive** — two that both replace
24
24
  the footer fight, two that register the same CLI flag abort startup. So harnesses live in
25
25
  `.pi/harnesses/`, which pi does **not** auto-discover, and load explicitly via `pi -e <path>`
26
- or the `justfile`. The supported stack is `damage-control` before `agent-hub`; never put a
26
+ or the `justfile`. The supported stack is `damage-control-continue` before `agent-hub`; never put a
27
27
  harness under `.pi/extensions/`.
28
28
 
29
29
  ## Directory anatomy
30
30
 
31
- Every harness is a directory with exactly three files:
31
+ Every harness has these three required baseline files:
32
32
 
33
33
  ```
34
34
  .pi/harnesses/<name>/
35
35
  index.ts # the extension
36
- package.json # four fields, identical shape for every harness
36
+ package.json # shared manifest fields; persistent-UI targets add a version stamp
37
37
  README.md # the discovery surface
38
38
  ```
39
39
 
40
+ Persistent-UI targets may additionally include a local `version.ts` provenance reader beside
41
+ their adjacent stamped `package.json`; do not describe those target harnesses as having exactly
42
+ three files.
43
+
40
44
  ### package.json
41
45
 
42
- Identical shape for every harness — only `name` changes:
46
+ Every harness manifest shares the same base shape (only `name` changes). Persistent-UI targets
47
+ add a root-derived `version` stamp:
43
48
 
44
49
  ```json
45
50
  {
46
51
  "name": "agent-fleet-pi-<name>",
47
52
  "private": true,
48
53
  "type": "module",
49
- "main": "index.ts"
54
+ "main": "index.ts",
55
+ "version": "<root package version>"
50
56
  }
51
57
  ```
52
58
 
53
- Runtime dependencies are **not** declared here. Shared deps (`@sinclair/typebox`, `yaml`)
54
- live in `.pi/harnesses/package.json` and are installed once by `just install`. The
55
- `@mariozechner/pi-*` packages are provided by the pi runtime. If a harness needs a new
56
- dependency, add it to `.pi/harnesses/package.json`, not the per-harness file.
59
+ The root `package.json` is canonical; `bin/sync-harness-versions.js` synchronizes the adjacent
60
+ harness stamps. A persistent-UI harness may keep a local provenance reader beside that manifest
61
+ so a copied or symlinked directory resolves its adjacent stamp, not the launch cwd. This does
62
+ **not** make it dependency-free. Runtime dependencies remain in `.pi/harnesses/package.json` and
63
+ are installed once by `just install`; copied/symlinked target harnesses still need that full
64
+ harness dependency installation. The `@mariozechner/pi-*` packages are provided by the pi runtime.
65
+ If a harness needs a new dependency, add it to `.pi/harnesses/package.json`, not the per-harness
66
+ file.
57
67
 
58
68
  ## The ExtensionAPI surface
59
69
 
@@ -107,7 +117,10 @@ Handlers are `async (event, ctx) => …`.
107
117
  - `ctx.sessionManager.getBranch()` — session entries, for state reconstruction
108
118
  - `ctx.abort()` — abort the current turn
109
119
  - `ctx.hasUI` — false in headless runs; guard UI-only commands with it
110
- - `ctx.ui.setFooter(fn)` / `setWidget(id, fn, opts)` / `setStatus(text, id)` — UI surfaces
120
+ - `ctx.ui.setFooter(fn)` / `setWidget(id, fn, opts)` / `setStatus(key, text)` — UI surfaces.
121
+ Use a stable, namespaced status key per concern. Stack-wide data such as the harness version
122
+ uses one shared key so stacked harnesses deduplicate `v<version>`; mutable status (for example,
123
+ Damage-Control activity or violations) uses its own key and must not overwrite that version.
111
124
  - `ctx.ui.notify(text, level)` — transient message (`info` | `warning` | `error` | `success`)
112
125
  - `ctx.ui.confirm(title, body, opts)` — yes/no dialog
113
126
  - `ctx.ui.select(title, options)` — pick-one dialog
@@ -148,7 +161,7 @@ Do not write from scratch. Pick the nearest pattern and adapt it:
148
161
 
149
162
  | If the harness… | Study | Approx. lines |
150
163
  |---|---|---|
151
- | Blocks tool calls from a rules file | `damage-control` | 200 |
164
+ | Blocks tool calls from a rules file | `damage-control-continue` | ~530 |
152
165
  | Sets widgets/status or registers orchestration commands/tools | `agent-hub` | large |
153
166
  | Orchestrates sub-agents | `agent-hub` | large |
154
167
  | Adds local cross-agent messaging | `coms`, `agent-hub` | large |
@@ -183,7 +183,7 @@ An Express answer other than `Custom` skips all seven group screens and goes str
183
183
 
184
184
  1. **Quick screen** (single-select). Fresh: `Recommended ★ (n)` / `Everything (m)` / `Customise` / `Skip group`. Existing: `Keep as-is (n installed)` / `Apply updates (k changed)` / `Customise` / `Remove some…`. Counts come from the state table; a group with nothing installed and nothing recommended may go straight to its Customise chunks.
185
185
  2. **Customise drill-in** (multi-select, only when picked). The group's items chunked by sub-category, ≤ 9 options per call (`part i/n`; ≤ 4 on `AskUserQuestion`). Titles: `<name> ★ [st]`. Descriptions: the purpose in ≤ ~6 words plus the state in plain words and its consequence (`mod` → "refreshing overwrites your local edits"). Selecting an item installs or refreshes it; **leaving an installed item unselected keeps it as-is — it does not remove it.** `cflt` rows are listed for visibility, but selecting one only queues its diff-then-ask exchange.
186
- 3. **Remove screen** (multi-select, only via `Remove some…` or when the user asks to remove). Lists **only** installed items the removal-scope rule allows (in inventory + recorded / symlinked-to-source). Selecting an item marks it for removal in Step 9/10; an empty selection or cancel removes nothing. Items held by a mandatory pairing (the damage-control variants and `ask-user-remote` while `agent-hub` stays kept) are not listed; explain the pairing if the user asks for them.
186
+ 3. **Remove screen** (multi-select, only via `Remove some…` or when the user asks to remove). Lists **only** installed items the removal-scope rule allows (current inventory + recorded / symlinked-to-source). Selecting an item marks it for removal in Step 9/10; an empty selection or cancel removes nothing. Items held by a mandatory pairing (`damage-control-continue` and `ask-user-remote` while `agent-hub` stays kept) are not listed; explain the pairing if the user asks for them. A source-retired `damage-control` hard-stop harness is a `gone` cleanup, not a selectable inventory item; apply the retired-artifact ownership rule below.
187
187
 
188
188
  **The three-way diff for `conflicting upgrade`.** For each `cflt` row, print the diff as normal agent text, comparing:
189
189
 
@@ -257,10 +257,12 @@ Groups, in order. Groups 1–4 apply to every agent; groups 5–7 are shown **on
257
257
  Record `.ai/stt.json` (and the `.env` keys touched) in `## install-status`. On a later removal of `pi-voice-stt`, delete `.ai/stt.json` **only** if it still matches what setup wrote (unedited; a user-edited config is preserved and listed under "Skipped — user-modified"), and **never** delete `.env`, its values, or the `.gitignore` line. Secrets in `.env` outlive the extension.
258
258
  6. **pi harnesses** *(pi only; sub-category = harness category — install many, load through the explicit recipes; `just hub` stacks `damage-control-continue` + `ask-user-remote` before `agent-hub`)* — one group for all harnesses:
259
259
  - *orchestration* — `agent-hub`, `ask-user-remote`
260
- - *safety* — `damage-control`, `damage-control-continue`
260
+ - *safety* — `damage-control-continue`
261
261
  - *messaging* — `coms`
262
262
 
263
- **Mandatory pairing: `agent-hub` ⇒ `damage-control` + `damage-control-continue` + `ask-user-remote`.** When `agent-hub` is selected (installed or kept), auto-include **both** damage-control variants and `ask-user-remote` in the same pass, state the auto-inclusion in the restate line, and keep all three off the remove screen while `agent-hub` stays selected — explain that the hub's `just hub` main session loads `damage-control-continue` and `ask-user-remote` before `agent-hub` (so recipes pointing at missing harnesses would fail to launch or lose the `ask_user` handoff path), and the hub re-loads a guardrail into every spawned subagent as their only protection: `damage-control` (hard-stop) into specialists, `damage-control-continue` into research helpers. Removing either guardrail leaves part of the session unguarded; removing `ask-user-remote` makes agent-hub's `askUserAvailable` probe omit `ask_user` from the dispatcher tools. These harnesses without `agent-hub` remain freely selectable.
263
+ **Mandatory pairing: `agent-hub` ⇒ `damage-control-continue` + `ask-user-remote`.** When `agent-hub` is selected (installed or kept), auto-include `damage-control-continue` and `ask-user-remote` in the same pass, state the auto-inclusion in the restate line, and keep both off the remove screen while `agent-hub` stays selected. The `just hub` main session loads both before `agent-hub`; the hub then loads `damage-control-continue` into every native specialist, researcher, and nested delegate. Removing it leaves child dispatch fail-closed; removing `ask-user-remote` makes the hub's `askUserAvailable` probe omit `ask_user` from dispatcher tools. Either harness remains freely selectable without `agent-hub`.
264
+
265
+ **Retired hard-stop cleanup.** `damage-control` (the former hard-stop harness) is no longer inventory and must never be installed or offered. On an upgrade, classify an existing `.pi/harnesses/damage-control/` as an upstream-removed (`gone`) artifact. Propose removal only when it is recorded in `## install-status` and still matches the recorded-version snapshot, or is a symlink whose target path is inside the agent-fleet source root (including a now-broken link to the retired source path). Preserve a user-modified regular copy or any unrecorded/unowned copy as `Skipped — user-modified` / `Skipped — not owned`; never delete it silently. Itemise the cleanup in Step 9, and remove its install-status row only when the owned artifact is actually removed.
264
266
 
265
267
  **Harness companions (refreshed with the group, not separate rows).** A harness directory does not run on its own — the launch recipes live in the `justfile`, and several harnesses shell out to support files. So whenever **any** harness in this group is installed, kept, or removed, refresh its companions from source in the same pass — they are not shown as their own menu rows:
266
268
  - Every path in `companion-manifest.json` — the sole list for Codex/Hermes/systemd directories, conductor docs, top-level runtime scripts, and recursive `scripts/lib` imports. Do not recreate a partial hand-maintained list.
@@ -292,10 +294,10 @@ When an external pi package is selected during clone/symlink or manual pi setup
292
294
 
293
295
  **Removal scope — what the remove screen (and `gone`/`brk` cleanup) may touch.** A target item is eligible for removal only when **both** are true:
294
296
 
295
- 1. **It is part of the agent-fleet inventory.** Its name matches an artifact shipped in the source repo's canonical trees (`skills/`, `vendor/agent-skills-upstream/skills/`, `agents/`, `.claude/commands/`, `.pi/prompts/`, `.pi/extensions/`, `.pi/harnesses/`, `.pi/skills/`, `references/`, `hooks/`). External pi packages are governed by the Group 7 ownership rule above. Other out-of-inventory items — user-authored skills, project-specific commands, custom personas, third-party plugins, external pi packages not managed by Group 7 (not setup-owned entries), unrelated dotfiles — are never proposed for removal even if they sit in the same directory.
296
- 2. **It is recorded in this workspace's install record.** The `## install-status` section of `.ai/agent-fleet-setup.md` lists it as previously installed by this skill, *or* it is a symlink whose target resolves into the agent-fleet source root (which is unambiguously ours).
297
+ 1. **It is part of the current agent-fleet inventory, or is an owned artifact removed upstream.** Current inventory names match artifacts shipped in the source repo's canonical trees (`skills/`, `vendor/agent-skills-upstream/skills/`, `agents/`, `.claude/commands/`, `.pi/prompts/`, `.pi/extensions/`, `.pi/harnesses/`, `.pi/skills/`, `references/`, `hooks/`). A source-retired artifact is eligible only as a `gone` cleanup when its old path is present in the recorded-version snapshot; this exception currently covers the retired `.pi/harnesses/damage-control/` hard-stop harness. External pi packages are governed by the Group 7 ownership rule above. Other out-of-inventory items are never proposed for removal.
298
+ 2. **Ownership is proven.** For current inventory, `## install-status` records the item or it is a symlink into the source root. For a source-retired artifact, it must be recorded and byte-match the recorded-version snapshot, or be a symlink whose stored target is inside the source root (a broken symlink caused by retirement still counts). A differing regular copy is user-modified and must be preserved.
297
299
 
298
- If a candidate fails either test, list it once under a "Skipped — not owned by agent-fleet" line in the Step 9 plan and leave it alone. Settings files (`.claude/settings.json`, `.opencode/config*`, env vars, MCP config) are touched **only** to remove agent-fleet' own hook registrations — never other keys, never user env vars, never third-party MCP entries.
300
+ If a candidate fails either test, list it once under `Skipped — user-modified` or `Skipped — not owned by agent-fleet` in the Step 9 plan and leave it alone. Settings files (`.claude/settings.json`, `.opencode/config*`, env vars, MCP config) are touched **only** to remove agent-fleet' own hook registrations — never other keys, never user env vars, never third-party MCP entries.
299
301
 
300
302
  **Tabular fallback rendering (no-widget runtimes only).** When Step 1 resolved to the tabular fallback, render each group as one compact markdown table and take the picks as a text reply — this legacy format keeps the old pre-checked semantics, since a printed table *can* show them:
301
303
 
@@ -474,7 +476,7 @@ Close the report with one line explaining the installer-cleanup outcome:
474
476
  - An existing, differing target file overwritten without asking the user.
475
477
  - A re-run that ignores the existing `## install-status` and reinstalls everything.
476
478
  - A `pi` workspace using `agent-hub` reached Step 7 without being offered the `## agent-hub` / `language: <value>` override, or an existing language value was overwritten instead of preserved.
477
- - `agent-hub` installed or kept without `damage-control` **and** `damage-control-continue` — the mandatory pairing was skipped, or a removal of either damage-control variant was accepted while `agent-hub` stayed selected.
479
+ - `agent-hub` installed or kept without `damage-control-continue` **and** `ask-user-remote` — the mandatory pairing was skipped, or removal of either required companion was accepted while `agent-hub` stayed selected.
478
480
  - The `bowser` runtime-skill installed without checking for the external `playwright-cli` CLI — or a global `@playwright/cli` install run without the user's confirmation.
479
481
  - The overrides file padded with install status, summaries, or prose instead of terse `key: value` sections.
480
482
  - A re-run that detects a non-empty version delta but skips the "Changes since v<recorded> → v<current>" block in Step 9.
@@ -514,7 +516,8 @@ After completing the workflow, confirm:
514
516
  - [ ] Settings-file edits were limited to agent-fleet' own hook entries; no user keys, env vars, or third-party MCP entries were modified.
515
517
  - [ ] `.ai/agent-fleet-overrides.md` holds the agreed override sections as terse `key: value` lines, and nothing else.
516
518
  - [ ] For `pi` workspaces using `agent-hub`, the `## agent-hub` language override was offered (an existing legacy `## agent-team` section kept its name), existing values were preserved, and omitting the section was treated as default English.
517
- - [ ] If `agent-hub` was installed or kept, `damage-control` was installed/kept alongside it (mandatory pairing) and could not be deselected while `agent-hub` remained.
519
+ - [ ] If `agent-hub` was installed or kept, `damage-control-continue` and `ask-user-remote` were installed/kept alongside it (mandatory pairing) and could not be deselected while `agent-hub` remained.
520
+ - [ ] Any retired `.pi/harnesses/damage-control/` copy was removed only when recorded and unchanged (or symlinked into source); user-modified or unowned copies were preserved.
518
521
  - [ ] If the `bowser` runtime-skill was installed or kept, the external `playwright-cli` dependency was checked, and a missing CLI was surfaced with the install offer (`npm install -g @playwright/cli@latest`) rather than silently installed or treated as a hard failure.
519
522
  - [ ] `.ai/agent-fleet-setup.md` holds an up-to-date install record, including at least one `## doctor-runs` entry for this session, and a `version:` line in `## workspace-summary` that matches the package version from Step 2.
520
523
  - [ ] Step 9 was rendered as compact action-grouped lines (Add / Refresh / Remove / Keep-count / Records / Method) printed as agent text, followed by the single `inline` confirm question — not a wide `Target paths` + `Notes` table, and not a plan packed into the question's `context`.
@@ -1,65 +0,0 @@
1
- # damage-control
2
-
3
- Safety auditing — blocks destructive tool calls.
4
-
5
- > Ported from [`pi-vs-claude-code`](https://github.com/disler/pi-vs-claude-code) by [disler](https://github.com/disler) (MIT). See the [extension catalog](../../../docs/pi-extensions.md).
6
-
7
- ## What it does
8
-
9
- Intercepts every tool call and checks it against rules in `.pi/damage-control-rules.yaml`:
10
-
11
- - `bashToolPatterns` — destructive shell commands (`rm -rf`, `git reset --hard`,
12
- `DROP TABLE`, cloud-resource deletes, …); some are hard-blocked, some marked `ask`
13
- - `zeroAccessPaths` — secrets and credentials that must never be read (`.env`, `*.pem`, …)
14
- - `readOnlyPaths` — paths that may be read but not written (lockfiles, build output, …)
15
- - `noDeletePaths` — paths that may be edited but not deleted (`README`, `.git/`, …)
16
-
17
- On a match the tool result is replaced with a block message and the agent's turn is
18
- aborted (`ctx.abort()`). For the softer variant that blocks but feeds back so the agent
19
- adapts and keeps working, see [`damage-control-continue`](../damage-control-continue/README.md)
20
- — the default guardrail for the `just hub` main session and spawned research helpers.
21
-
22
- ## Exemptions (pre-granted only)
23
-
24
- The hard-stop variant honors **pre-granted exemptions** from the shared exemptions
25
- file agent-hub passes down via `AGENT_HUB_EXEMPTIONS_FILE` (written by `/allow
26
- <pattern> session` or an approved escalation in the dispatcher session). Exemptions
27
- apply to the path categories only — `zeroAccessPaths`, `readOnlyPaths`,
28
- `noDeletePaths` — never to the destructive `bashToolPatterns`. There is no
29
- prompting and no escalation here by design: a specialist run never negotiates
30
- access mid-flight; grants happen in the hub before or between dispatches.
31
- Agent-scoped grants (`Allow for <agent>`) only reach the child whose
32
- `AGENT_HUB_AGENT_ID` matches.
33
-
34
- The exemption plumbing (file I/O + escalation protocol types) lives in
35
- [`shared.ts`](./shared.ts), used by both variants and agent-hub.
36
-
37
- ## Commands & tools
38
-
39
- None — it runs passively on the `tool_call` event.
40
-
41
- ## Requires
42
-
43
- - `.pi/damage-control-rules.yaml` — the rule set (shipped in this repo)
44
-
45
- ## Usage
46
-
47
- ```bash
48
- # standalone guardrail session
49
- just ext-damage-control
50
- pi -e .pi/harnesses/damage-control/index.ts
51
-
52
- # the hub recipes load this harness first by default
53
- just hub
54
- just hub-solo
55
-
56
- # direct guarded hub launch
57
- pi -e .pi/harnesses/damage-control/index.ts -e .pi/harnesses/agent-hub/index.ts
58
- ```
59
-
60
- ## Upstream changes
61
-
62
- - Theme integration removed — the `themeMap.ts` import and the `applyExtensionDefaults()`
63
- call were stripped (this repo does not ship pi themes).
64
- - Pre-granted exemptions from the hub session's shared file are honored (not in
65
- upstream) — see the Exemptions section above.