@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,103 @@
1
+ import { execFileSync } from "node:child_process";
2
+
3
+ export function snapshotWorktree(cwd) {
4
+ const status = gitStatus(cwd);
5
+ if (status.skipped) return { skipped: true, reason: status.reason, paths: new Set() };
6
+ return { skipped: false, paths: new Set(status.paths) };
7
+ }
8
+
9
+ export function diffAgainst(snapshot, cwd) {
10
+ const current = snapshotWorktree(cwd);
11
+ if (snapshot?.skipped || current.skipped) {
12
+ return { skipped: true, reason: snapshot?.reason || current.reason || "scope gate skipped", paths: [] };
13
+ }
14
+ const before = snapshot?.paths instanceof Set ? snapshot.paths : new Set(snapshot?.paths || []);
15
+ const paths = [...current.paths].filter((p) => !before.has(p)).sort();
16
+ return { skipped: false, paths };
17
+ }
18
+
19
+ export function checkScope(changedPaths, scopeGlobs) {
20
+ const scopes = (scopeGlobs || []).map(normalizePath).filter(Boolean);
21
+ const inScope = [];
22
+ const outOfScope = [];
23
+ for (const rawPath of changedPaths || []) {
24
+ const changed = normalizePath(rawPath);
25
+ if (!changed) continue;
26
+ if (scopes.some((scope) => matchesScope(changed, scope))) inScope.push(changed);
27
+ else outOfScope.push(changed);
28
+ }
29
+ return { inScope: uniqueSorted(inScope), outOfScope: uniqueSorted(outOfScope) };
30
+ }
31
+
32
+ function gitStatus(cwd) {
33
+ try {
34
+ const output = execFileSync("git", ["-C", cwd, "status", "--porcelain", "--untracked-files=all"], {
35
+ encoding: "utf-8",
36
+ stdio: ["ignore", "pipe", "pipe"],
37
+ });
38
+ return { skipped: false, paths: parsePorcelain(output) };
39
+ } catch (err) {
40
+ return { skipped: true, reason: err?.message || "not a git worktree" };
41
+ }
42
+ }
43
+
44
+ function parsePorcelain(output) {
45
+ const paths = [];
46
+ for (const line of String(output || "").split(/\r?\n/)) {
47
+ if (!line.trim()) continue;
48
+ let file = line.slice(3).trim();
49
+ const rename = file.match(/ -> (.+)$/);
50
+ if (rename) file = rename[1];
51
+ paths.push(normalizePath(unquotePorcelainPath(file)));
52
+ }
53
+ return uniqueSorted(paths.filter(Boolean));
54
+ }
55
+
56
+ function matchesScope(changedPath, scope) {
57
+ if (hasGlob(scope)) return globToRegExp(scope).test(changedPath);
58
+ const dir = scope.endsWith("/") ? scope.slice(0, -1) : scope;
59
+ return changedPath === dir || changedPath.startsWith(`${dir}/`);
60
+ }
61
+
62
+ function hasGlob(scope) {
63
+ return /[*?]/.test(scope);
64
+ }
65
+
66
+ function globToRegExp(glob) {
67
+ let out = "^";
68
+ for (let i = 0; i < glob.length; i++) {
69
+ const c = glob[i];
70
+ if (c === "*") {
71
+ if (glob[i + 1] === "*") {
72
+ out += ".*";
73
+ i++;
74
+ } else {
75
+ out += "[^/]*";
76
+ }
77
+ } else {
78
+ out += escapeRegExp(c);
79
+ }
80
+ }
81
+ out += "$";
82
+ return new RegExp(out);
83
+ }
84
+
85
+ function normalizePath(value) {
86
+ return String(value || "").trim().replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+/g, "/");
87
+ }
88
+
89
+ function uniqueSorted(values) {
90
+ return [...new Set(values)].sort();
91
+ }
92
+
93
+ function unquotePorcelainPath(value) {
94
+ const trimmed = String(value || "").trim();
95
+ if (trimmed.length >= 2 && trimmed.startsWith('"') && trimmed.endsWith('"')) {
96
+ try { return JSON.parse(trimmed); } catch { return trimmed.slice(1, -1); }
97
+ }
98
+ return trimmed;
99
+ }
100
+
101
+ function escapeRegExp(value) {
102
+ return value.replace(/[|\\{}()[\]^$+?.]/g, "\\$&");
103
+ }
@@ -0,0 +1,246 @@
1
+ /**
2
+ * spawnPiAgent — the ONE place agent-hub code spawns a headless `pi` child and
3
+ * parses its JSON event stream. Research helpers and read-only delegate children
4
+ * opt into the per-tool watchdog here, rather than trusting an agent-side timer.
5
+ */
6
+
7
+ import { spawn, type ChildProcess } from "child_process";
8
+
9
+ export interface PiUsage {
10
+ input?: number;
11
+ output?: number;
12
+ [k: string]: any;
13
+ }
14
+
15
+ export interface ToolTimeout {
16
+ toolCallId: string;
17
+ toolName: string;
18
+ args: string;
19
+ startedAt: number;
20
+ deadlineAt: number;
21
+ }
22
+
23
+ export interface Termination {
24
+ reason: "tool_timeout" | "turn_timeout" | "drift_stop" | "cancelled";
25
+ confirmed: boolean;
26
+ escalated: boolean;
27
+ tool?: ToolTimeout;
28
+ }
29
+
30
+ /** External run control handed to the caller via onControl (drift watchdog). */
31
+ export interface PiRunControl {
32
+ /** Terminate the child group with the given classification (default "drift_stop"). */
33
+ terminate(reason?: "drift_stop" | "cancelled"): void;
34
+ }
35
+
36
+ export interface ToolWatchdogOptions {
37
+ /** Per read-only tool call deadline. null disables the watchdog. */
38
+ timeoutMs: number | null;
39
+ /** Grace after SIGTERM, followed by SIGKILL. Kept injectable for focused tests. */
40
+ termGraceMs?: number;
41
+ /** Bound on final settlement; never wait forever for close or inherited pipes. */
42
+ settleGraceMs?: number;
43
+ /** Only these tool names are watched (research/delegate read-only surface). */
44
+ tools?: readonly string[];
45
+ }
46
+
47
+ export interface SpawnPiAgentOptions {
48
+ model: string;
49
+ tools: string;
50
+ thinking: string;
51
+ appendSystemPrompt: string;
52
+ sessionFile: string;
53
+ resume?: boolean;
54
+ prompt: string;
55
+ extensions?: string[];
56
+ env?: Record<string, string>;
57
+ /** Own a process group. Required for a watchdog/cancellation kill cascade. */
58
+ detached?: boolean;
59
+ cwd?: string;
60
+ /** Parent tool cancellation; classified separately from a tool timeout. */
61
+ signal?: AbortSignal;
62
+ toolWatchdog?: ToolWatchdogOptions;
63
+ /**
64
+ * Whole-run deadline: one timer from spawn start; on expiry the child group is
65
+ * terminated with reason "turn_timeout" (same SIGTERM→SIGKILL→settle cascade as
66
+ * the per-tool watchdog). null/undefined disables it. Unlike the tool watchdog
67
+ * this bounds the ENTIRE run, thinking and non-watched tools included.
68
+ */
69
+ turnDeadlineMs?: number | null;
70
+ }
71
+
72
+ export interface SpawnPiAgentCallbacks {
73
+ onProcess?(proc: ChildProcess): void;
74
+ /** Receives a terminate handle for parent-side classified stops (drift watchdog). */
75
+ onControl?(control: PiRunControl): void;
76
+ onTextDelta?(delta: string): void;
77
+ onThinkingDelta?(delta: string): void;
78
+ onToolStart?(toolName: string, argStr: string, toolCallId?: string): void;
79
+ /** isError is present only when the event stream carries an error flag. */
80
+ onToolEnd?(toolName: string, toolCallId?: string, isError?: boolean): void;
81
+ onUsage?(usage: PiUsage, source: "message_end" | "agent_end"): void;
82
+ }
83
+
84
+ export interface SpawnPiAgentResult {
85
+ output: string;
86
+ exitCode: number | null;
87
+ stderr: string;
88
+ spawnError?: string;
89
+ /** Present only when parent-side bounded termination was requested. */
90
+ termination?: Termination;
91
+ }
92
+
93
+ const DEFAULT_TERM_GRACE_MS = 1_000;
94
+ const DEFAULT_SETTLE_GRACE_MS = 1_000;
95
+ const WATCHED_TOOLS = new Set(["read", "grep", "find", "ls"]);
96
+
97
+ /** Signal an explicitly owned process group, falling back only for legacy callers. */
98
+ export function killPiTree(proc: ChildProcess, signal: NodeJS.Signals = "SIGTERM"): void {
99
+ const pid = proc.pid;
100
+ if (pid == null) return;
101
+ try {
102
+ process.kill(-pid, signal);
103
+ } catch {
104
+ try { proc.kill(signal); } catch {}
105
+ }
106
+ }
107
+
108
+ export function spawnPiAgent(
109
+ opts: SpawnPiAgentOptions,
110
+ cbs: SpawnPiAgentCallbacks = {},
111
+ ): Promise<SpawnPiAgentResult> {
112
+ const args = [
113
+ "--mode", "json", "-p", "--no-extensions",
114
+ ...(opts.extensions || []).flatMap(e => ["-e", e]),
115
+ "--model", opts.model, "--tools", opts.tools, "--thinking", opts.thinking,
116
+ "--append-system-prompt", opts.appendSystemPrompt, "--session", opts.sessionFile,
117
+ ];
118
+ if (opts.resume) args.push("-c");
119
+
120
+ const watchdog = opts.toolWatchdog;
121
+ const turnDeadlineMs = opts.turnDeadlineMs ?? null;
122
+ // A watchdog or deadline must own its group: group signalling remains valid even
123
+ // after the pi leader exits while an inherited-stdio descendant is still alive.
124
+ const ownsGroup = opts.detached === true || watchdog !== undefined || opts.signal !== undefined || turnDeadlineMs != null || cbs.onControl !== undefined;
125
+ const watchedTools = new Set(watchdog?.tools ?? WATCHED_TOOLS);
126
+ const timeoutMs = watchdog?.timeoutMs ?? null;
127
+ const termGraceMs = watchdog?.termGraceMs ?? DEFAULT_TERM_GRACE_MS;
128
+ const settleGraceMs = watchdog?.settleGraceMs ?? DEFAULT_SETTLE_GRACE_MS;
129
+
130
+ const textChunks: string[] = [];
131
+ const stderrChunks: string[] = [];
132
+ return new Promise((resolve) => {
133
+ const proc = spawn("pi", args, {
134
+ stdio: ["pipe", "pipe", "pipe"],
135
+ env: { ...process.env, ...(opts.env || {}) },
136
+ ...(opts.cwd ? { cwd: opts.cwd } : {}),
137
+ ...(ownsGroup ? { detached: true } : {}),
138
+ });
139
+ cbs.onProcess?.(proc);
140
+ proc.stdin?.on("error", () => {});
141
+ proc.stdin?.end(opts.prompt);
142
+
143
+ let buffer = "";
144
+ let settled = false;
145
+ let closeSeen = false;
146
+ let termination: Termination | undefined;
147
+ let termTimer: ReturnType<typeof setTimeout> | undefined;
148
+ let settleTimer: ReturnType<typeof setTimeout> | undefined;
149
+ let deadlineTimer: ReturnType<typeof setTimeout> | undefined;
150
+ const calls = new Map<string, ToolTimeout & { timer: ReturnType<typeof setTimeout> }>();
151
+
152
+ const clearCalls = () => {
153
+ for (const call of calls.values()) clearTimeout(call.timer);
154
+ calls.clear();
155
+ };
156
+ const cleanup = () => {
157
+ clearCalls();
158
+ if (termTimer) clearTimeout(termTimer);
159
+ if (settleTimer) clearTimeout(settleTimer);
160
+ if (deadlineTimer) clearTimeout(deadlineTimer);
161
+ opts.signal?.removeEventListener("abort", onAbort);
162
+ };
163
+ const settle = (code: number | null, spawnError?: string) => {
164
+ if (settled) return;
165
+ settled = true;
166
+ cleanup();
167
+ if (termination) termination.confirmed = closeSeen;
168
+ // A pipe held by a descendant must not hold the caller forever.
169
+ try { proc.stdin?.destroy(); } catch {}
170
+ try { proc.stdout?.destroy(); } catch {}
171
+ try { proc.stderr?.destroy(); } catch {}
172
+ resolve({ output: textChunks.join(""), exitCode: code, stderr: stderrChunks.join(""), ...(spawnError ? { spawnError } : {}), ...(termination ? { termination } : {}) });
173
+ };
174
+ const terminate = (reason: Termination["reason"], tool?: ToolTimeout) => {
175
+ // The first classification wins; later cancellation/exit events keep it.
176
+ if (termination) return;
177
+ termination = { reason, confirmed: false, escalated: false, ...(tool ? { tool } : {}) };
178
+ clearCalls();
179
+ killPiTree(proc, "SIGTERM");
180
+ termTimer = setTimeout(() => {
181
+ if (settled) return;
182
+ termination!.escalated = true;
183
+ killPiTree(proc, "SIGKILL");
184
+ }, termGraceMs);
185
+ settleTimer = setTimeout(() => settle(null), termGraceMs + settleGraceMs);
186
+ };
187
+ const onAbort = () => terminate("cancelled");
188
+ if (opts.signal?.aborted) onAbort();
189
+ else opts.signal?.addEventListener("abort", onAbort, { once: true });
190
+ // External classified stop (drift watchdog): same first-classification-wins
191
+ // cascade as every other termination path; harmless after settle.
192
+ cbs.onControl?.({ terminate: (reason = "drift_stop") => { if (!settled) terminate(reason); } });
193
+ if (turnDeadlineMs != null) {
194
+ deadlineTimer = setTimeout(() => terminate("turn_timeout"), turnDeadlineMs);
195
+ }
196
+
197
+ const toolId = (event: any) => String(event.toolCallId ?? event.tool_call_id ?? event.id ?? "");
198
+ const handleEvent = (event: any) => {
199
+ if (event.type === "message_update") {
200
+ const delta = event.assistantMessageEvent;
201
+ if (delta?.type === "text_delta") { textChunks.push(delta.delta || ""); cbs.onTextDelta?.(delta.delta || ""); }
202
+ else if (delta?.type === "thinking_delta") cbs.onThinkingDelta?.(delta.delta || "");
203
+ } else if (event.type === "tool_execution_start") {
204
+ let argStr = "";
205
+ try { argStr = event.args != null ? JSON.stringify(event.args) : ""; } catch {}
206
+ const id = toolId(event);
207
+ const name = event.toolName || "tool";
208
+ cbs.onToolStart?.(name, argStr, id || undefined);
209
+ if (timeoutMs != null && id && watchedTools.has(name) && !calls.has(id)) {
210
+ const startedAt = Date.now();
211
+ const call: ToolTimeout = { toolCallId: id, toolName: name, args: argStr, startedAt, deadlineAt: startedAt + timeoutMs };
212
+ calls.set(id, { ...call, timer: setTimeout(() => terminate("tool_timeout", call), timeoutMs) });
213
+ }
214
+ } else if (event.type === "tool_execution_end") {
215
+ const id = toolId(event);
216
+ if (id) {
217
+ const call = calls.get(id);
218
+ if (call) { clearTimeout(call.timer); calls.delete(id); }
219
+ }
220
+ const rawIsError = event.isError ?? event.is_error ?? event.result?.isError ?? event.result?.is_error;
221
+ cbs.onToolEnd?.(event.toolName || "tool", id || undefined, typeof rawIsError === "boolean" ? rawIsError : undefined);
222
+ } else if (event.type === "message_end") {
223
+ if (event.message?.usage) cbs.onUsage?.(event.message.usage, "message_end");
224
+ } else if (event.type === "agent_end") {
225
+ const last = [...(event.messages || [])].reverse().find((m: any) => m.role === "assistant");
226
+ if (last?.usage) cbs.onUsage?.(last.usage, "agent_end");
227
+ }
228
+ };
229
+
230
+ proc.stdout!.setEncoding("utf-8");
231
+ proc.stdout!.on("data", (chunk: string) => {
232
+ buffer += chunk;
233
+ const lines = buffer.split("\n");
234
+ buffer = lines.pop() || "";
235
+ for (const line of lines) { if (line.trim()) try { handleEvent(JSON.parse(line)); } catch {} }
236
+ });
237
+ proc.stderr!.setEncoding("utf-8");
238
+ proc.stderr!.on("data", (chunk: string) => stderrChunks.push(chunk));
239
+ proc.on("close", (code) => {
240
+ closeSeen = true;
241
+ if (buffer.trim()) try { handleEvent(JSON.parse(buffer)); } catch {}
242
+ settle(code);
243
+ });
244
+ proc.on("error", (err) => settle(1, err.message));
245
+ });
246
+ }
@@ -0,0 +1,18 @@
1
+ import { readFileSync } from "node:fs";
2
+
3
+ export const VERSION_STATUS_KEY = "00-agent-fleet-version";
4
+
5
+ function readAdjacentVersion(): string | null {
6
+ try {
7
+ const manifest = JSON.parse(readFileSync(new URL("./package.json", import.meta.url), "utf8"));
8
+ return typeof manifest.version === "string" && manifest.version.length > 0 ? manifest.version : null;
9
+ } catch {
10
+ return null;
11
+ }
12
+ }
13
+
14
+ export const HARNESS_VERSION = readAdjacentVersion();
15
+
16
+ export function registerVersionStatus(ctx: { ui?: { setStatus?: (key: string, text: string) => void } }): void {
17
+ if (HARNESS_VERSION) ctx.ui?.setStatus?.(VERSION_STATUS_KEY, `v${HARNESS_VERSION}`);
18
+ }
@@ -0,0 +1,18 @@
1
+ # ask-user-remote
2
+
3
+ Harness wrapper for `pi-ask-user` that preserves the stock `ask_user` UI and result shape while optionally racing it against the Hermes `user-remote` coms peer.
4
+
5
+ The experimental Codex Remote-Control conductor is **not** an inbound `ask_user` route. It initiates approval-gated outbound delegation from Android; Hermes remains the only phone answer participant in this race. See the [Codex conductor runbook](../../../docs/codex-remote-conductor.md).
6
+
7
+ - The stock `pi-ask-user` extension is loaded through a capture proxy; its `ask_user` tool is not registered directly.
8
+ - If no live `user-remote` peer is present at call time, the wrapper calls stock `execute` with the original arguments and signal unchanged.
9
+ - If `user-remote` is present, the wrapper races local stock UI against the remote coms request using `race-core.js`; first answer wins and local-first emits one best-effort cancel.
10
+ - If another extension already registered `ask_user`, registration failure is caught and logged as a warning instead of crashing the session.
11
+
12
+ ## Double-load protection
13
+
14
+ Do **not** also list `npm:pi-ask-user` in pi settings `packages` (project `.pi/settings.json` or global `~/.pi/agent/settings.json`) — the harness loads the stock extension itself. A settings-listed copy is loaded by pi core outside the harness's control, and if the harness happened to register `ask_user` first, pi core would hard-crash the session with `Tool "ask_user" conflicts` while loading the package (load order between the two is a race).
15
+
16
+ The harness defends against this with a startup preflight: it scans both settings files for a `pi-ask-user` package entry, and if one is found it logs a warning and skips registering its wrapper entirely, so the stock package registers alone and the session survives regardless of load order. The cost is that remote answer racing is disabled until the entry is removed — the warning says so. The try/catch on registration remains as the second layer for the package-first order (or any other extension owning `ask_user`).
17
+
18
+ Tests use fakes for the stock TUI and coms peer. The abort test proves signal propagation and the stock-shaped `{cancelled:true}` result through a fake captured tool; it does not drive a live TUI overlay.
@@ -0,0 +1,293 @@
1
+ // ask-user-remote harness
2
+ //
3
+ // Captures the stock pi-ask-user `ask_user` tool, then registers a wrapper with
4
+ // the same schema/renderers/result shape. With no live `user-remote` coms peer
5
+ // it delegates to stock execute with the original arguments unchanged. When the
6
+ // peer is live, it races the stock local UI against a remote coms round trip.
7
+
8
+ import * as fs from "node:fs";
9
+ import * as os from "node:os";
10
+ import * as path from "node:path";
11
+
12
+ import { raceAskUser } from "./race-core.js";
13
+
14
+ interface ToolRegistration {
15
+ name: string;
16
+ execute?: (...args: any[]) => Promise<any> | any;
17
+ [key: string]: any;
18
+ }
19
+
20
+ interface ExtensionLike {
21
+ registerTool: (tool: ToolRegistration) => void;
22
+ [key: string]: any;
23
+ }
24
+
25
+ interface InstallOptions {
26
+ stockFactory?: (pi: ExtensionLike) => void;
27
+ startRemote?: (params: any, ctx?: any) => Promise<{ qid: string; result: Promise<any> } | null> | { qid: string; result: Promise<any> } | null;
28
+ cancelRemote?: (qid: string, reason: string) => Promise<void> | void;
29
+ warn?: (message: string) => void;
30
+ createAbortController?: () => AbortController;
31
+ settingsPaths?: string[];
32
+ }
33
+
34
+ // A stock `pi-ask-user` package listed in pi settings is loaded by pi core
35
+ // itself, outside this harness's try/catch. If the harness registers `ask_user`
36
+ // first, the package's later registration makes pi core hard-crash the session
37
+ // with a tool-name conflict. The preflight below detects that configuration and
38
+ // skips the wrapper entirely, so the stock package registers alone regardless
39
+ // of load order.
40
+ const STOCK_PACKAGE_PATTERN = /(^|[/:])pi-ask-user(@[^/]*)?$/;
41
+
42
+ export function defaultSettingsPaths(): string[] {
43
+ return [
44
+ path.join(process.cwd(), ".pi", "settings.json"),
45
+ path.join(os.homedir(), ".pi", "agent", "settings.json"),
46
+ ];
47
+ }
48
+
49
+ export function findStockAskUserPackageEntry(settingsPaths: string[]): { entry: string; settingsPath: string } | null {
50
+ for (const settingsPath of settingsPaths) {
51
+ let packages: unknown;
52
+ try {
53
+ packages = JSON.parse(fs.readFileSync(settingsPath, "utf8"))?.packages;
54
+ } catch {
55
+ continue;
56
+ }
57
+ if (!Array.isArray(packages)) continue;
58
+ const entry = packages.find((pkg) => typeof pkg === "string" && STOCK_PACKAGE_PATTERN.test(pkg));
59
+ if (entry) return { entry, settingsPath };
60
+ }
61
+ return null;
62
+ }
63
+
64
+ export function captureAskUserTool(stockFactory: (pi: ExtensionLike) => void, pi: ExtensionLike): ToolRegistration {
65
+ let captured: ToolRegistration | null = null;
66
+ const proxy = new Proxy(pi, {
67
+ get(target, prop, receiver) {
68
+ if (prop === "registerTool") {
69
+ return (tool: ToolRegistration) => {
70
+ if (tool?.name === "ask_user") {
71
+ captured = tool;
72
+ return;
73
+ }
74
+ return target.registerTool(tool);
75
+ };
76
+ }
77
+ return Reflect.get(target, prop, receiver);
78
+ },
79
+ }) as ExtensionLike;
80
+
81
+ stockFactory(proxy);
82
+ if (!captured) throw new Error("ask-user-remote: stock pi-ask-user did not register ask_user");
83
+ return captured;
84
+ }
85
+
86
+ function warn(pi: ExtensionLike, options: InstallOptions, message: string): void {
87
+ if (typeof options.warn === "function") {
88
+ options.warn(message);
89
+ return;
90
+ }
91
+ if (typeof pi.logger?.warn === "function") {
92
+ pi.logger.warn(message);
93
+ return;
94
+ }
95
+ if (typeof pi.log?.warn === "function") {
96
+ pi.log.warn(message);
97
+ return;
98
+ }
99
+ console.warn(message);
100
+ }
101
+
102
+ function linkAbortSignal(parent: AbortSignal | undefined, child: AbortController): void {
103
+ if (!parent) return;
104
+ if (parent.aborted) {
105
+ child.abort();
106
+ return;
107
+ }
108
+ parent.addEventListener("abort", () => child.abort(), { once: true });
109
+ }
110
+
111
+ function stockResultFromRemote(params: any, response: any): any {
112
+ const summary = response?.kind === "selection"
113
+ ? (Array.isArray(response.selections) ? response.selections.join(", ") : "")
114
+ : response?.kind === "freeform"
115
+ ? String(response.text ?? "")
116
+ : typeof response === "string"
117
+ ? response
118
+ : JSON.stringify(response);
119
+ return {
120
+ content: [{ type: "text", text: `User answered: ${summary}` }],
121
+ details: {
122
+ question: params?.question,
123
+ context: params?.context?.trim?.() || params?.context,
124
+ options: normalizeOptions(params?.options ?? []),
125
+ response,
126
+ cancelled: false,
127
+ },
128
+ };
129
+ }
130
+
131
+ function normalizeOptions(options: any[]): Array<{ title: string; description?: string }> {
132
+ return (Array.isArray(options) ? options : [])
133
+ .map((option) => {
134
+ if (typeof option === "string") return { title: option };
135
+ if (option && typeof option === "object" && typeof option.title === "string") {
136
+ return typeof option.description === "string"
137
+ ? { title: option.title, description: option.description }
138
+ : { title: option.title };
139
+ }
140
+ return null;
141
+ })
142
+ .filter(Boolean) as Array<{ title: string; description?: string }>;
143
+ }
144
+
145
+ // Live remote questions started by defaultStartRemote, keyed by qid. A cancel
146
+ // must settle the pending result so the per-question endpoint server is closed;
147
+ // otherwise every locally-answered race leaks a bound socket until process exit.
148
+ const activeRemote = new Map<string, (error: Error) => void>();
149
+
150
+ export function activeRemoteCount(): number {
151
+ return activeRemote.size;
152
+ }
153
+
154
+ async function defaultStartRemote(params: any): Promise<{ qid: string; result: Promise<any> } | null> {
155
+ const coms = await import("../../../scripts/lib/coms-envelope.ts");
156
+ const project = process.env.PI_COMS_PROJECT || "default";
157
+ const peerName = process.env.PI_ASK_USER_REMOTE_PEER || "user-remote";
158
+ const peer = coms.pruneDeadEntries(project).find((entry: any) => entry.name === peerName);
159
+ if (!peer) return null;
160
+
161
+ coms.ensureComsDirs(project);
162
+ const id = {
163
+ session_id: coms.ulid(),
164
+ name: "ask-user-remote",
165
+ endpoint: "",
166
+ cwd: process.cwd(),
167
+ };
168
+ id.endpoint = coms.makeEndpoint(id.session_id);
169
+
170
+ let resolveResult!: (value: any) => void;
171
+ let rejectResult!: (error: Error) => void;
172
+ const rawResult = new Promise<any>((resolve, reject) => {
173
+ resolveResult = resolve;
174
+ rejectResult = reject;
175
+ });
176
+ const server = await coms.bindEndpoint(
177
+ id.endpoint,
178
+ coms.makeConnHandler((env: Record<string, unknown>, socket: any) => {
179
+ if (coms.isResponseEnvelope(env)) {
180
+ coms.writeAck(socket, env.msg_id);
181
+ if (env.error) rejectResult(new Error(String(env.error)));
182
+ else resolveResult(stockResultFromRemote(params, env.response));
183
+ return;
184
+ }
185
+ coms.writeNack(socket, (env as { msg_id?: string }).msg_id ?? "", "ask-user-remote awaits responses only");
186
+ }),
187
+ );
188
+ const cleanup = () => {
189
+ try { server.close(); } catch { /* ignore */ }
190
+ try { fs.unlinkSync(id.endpoint); } catch { /* ignore */ }
191
+ };
192
+
193
+ const promptPayload = JSON.stringify({
194
+ question: params?.question,
195
+ context: params?.context,
196
+ options: params?.options ?? [],
197
+ });
198
+ const env = coms.makePromptEnvelope(id, promptPayload);
199
+ activeRemote.set(env.msg_id, rejectResult);
200
+ const result = rawResult.finally(() => {
201
+ activeRemote.delete(env.msg_id);
202
+ cleanup();
203
+ });
204
+ try {
205
+ await coms.sendEnvelope(peer.endpoint, env);
206
+ } catch (error) {
207
+ rejectResult(error instanceof Error ? error : new Error(String(error)));
208
+ }
209
+ return { qid: env.msg_id, result };
210
+ }
211
+
212
+ async function defaultCancelRemote(qid: string, reason: string): Promise<void> {
213
+ try {
214
+ const coms = await import("../../../scripts/lib/coms-envelope.ts");
215
+ const project = process.env.PI_COMS_PROJECT || "default";
216
+ const peerName = process.env.PI_ASK_USER_REMOTE_PEER || "user-remote";
217
+ const peer = coms.pruneDeadEntries(project).find((entry: any) => entry.name === peerName);
218
+ if (peer) {
219
+ await coms.sendEnvelope(peer.endpoint, coms.makeCancelEnvelope({
220
+ from: "ask-user-remote",
221
+ to: peer.name,
222
+ ref_msg_id: qid,
223
+ }));
224
+ }
225
+ } finally {
226
+ // The bridge sends no response for a cancelled qid, so settle the pending
227
+ // result here to release the per-question endpoint server.
228
+ activeRemote.get(qid)?.(new Error(`ask-user-remote: cancelled (${reason})`));
229
+ }
230
+ }
231
+
232
+ export function wrapAskUserTool(stockTool: ToolRegistration, options: InstallOptions = {}): ToolRegistration {
233
+ return {
234
+ ...stockTool,
235
+ async execute(toolCallId: string, params: any, signal?: AbortSignal, onUpdate?: any, ctx?: any) {
236
+ const startRemote = options.startRemote ?? defaultStartRemote;
237
+ let remoteStart: { qid: string; result: Promise<any> } | null = null;
238
+ try {
239
+ remoteStart = await startRemote(params, ctx);
240
+ } catch {
241
+ remoteStart = null;
242
+ }
243
+
244
+ if (!remoteStart) {
245
+ return await stockTool.execute?.(toolCallId, params, signal, onUpdate, ctx);
246
+ }
247
+
248
+ return await raceAskUser({
249
+ runLocal: (localSignal: AbortSignal) => stockTool.execute?.(toolCallId, params, localSignal, onUpdate, ctx),
250
+ startRemote: () => remoteStart,
251
+ cancelRemote: options.cancelRemote ?? defaultCancelRemote,
252
+ createAbortController: () => {
253
+ const controller = options.createAbortController?.() ?? new AbortController();
254
+ linkAbortSignal(signal, controller);
255
+ return controller;
256
+ },
257
+ signal,
258
+ });
259
+ },
260
+ };
261
+ }
262
+
263
+ export function installAskUserRemote(pi: ExtensionLike, options: InstallOptions = {}): { registered: boolean; tool?: ToolRegistration } {
264
+ if (options.settingsPaths) {
265
+ const listed = findStockAskUserPackageEntry(options.settingsPaths);
266
+ if (listed) {
267
+ warn(pi, options, `ask-user-remote: "${listed.entry}" is listed in ${listed.settingsPath} "packages"; skipping the ask_user wrapper so the stock package registers without a tool conflict (remote answer racing disabled). Remove the entry — this harness loads pi-ask-user itself.`);
268
+ return { registered: false };
269
+ }
270
+ }
271
+ if (!options.stockFactory) throw new Error("ask-user-remote: stockFactory is required for synchronous install");
272
+ const stockTool = captureAskUserTool(options.stockFactory, pi);
273
+ const wrapped = wrapAskUserTool(stockTool, options);
274
+ try {
275
+ pi.registerTool(wrapped);
276
+ return { registered: true, tool: wrapped };
277
+ } catch (error) {
278
+ const message = error instanceof Error ? error.message : String(error);
279
+ warn(pi, options, `ask-user-remote: ask_user already registered; wrapper not installed (${message})`);
280
+ return { registered: false };
281
+ }
282
+ }
283
+
284
+ async function loadStockFactory(): Promise<(pi: ExtensionLike) => void> {
285
+ const mod = await import("../../../node_modules/pi-ask-user/index.ts");
286
+ return mod.default as (pi: ExtensionLike) => void;
287
+ }
288
+
289
+ export default function askUserRemote(pi: ExtensionLike): void {
290
+ void loadStockFactory()
291
+ .then((stockFactory) => installAskUserRemote(pi, { stockFactory, settingsPaths: defaultSettingsPaths() }))
292
+ .catch((error) => warn(pi, {}, `ask-user-remote: failed to load pi-ask-user (${error instanceof Error ? error.message : String(error)})`));
293
+ }