@chankov/agent-fleet 0.0.10 → 0.0.11

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 (316) hide show
  1. package/.pi/extensions/btw/README.md +3 -2
  2. package/.pi/extensions/pi-voice-stt/README.md +3 -0
  3. package/.pi/harnesses/agent-hub/README.md +3 -0
  4. package/.pi/harnesses/agent-hub/package.json +1 -1
  5. package/.pi/harnesses/coms/package.json +1 -1
  6. package/.pi/harnesses/damage-control-continue/package.json +1 -1
  7. package/.versions/0.0.11/.claude/commands/build.md +44 -0
  8. package/.versions/0.0.11/.claude/commands/code-simplify.md +22 -0
  9. package/.versions/0.0.11/.claude/commands/design-agent.md +14 -0
  10. package/.versions/0.0.11/.claude/commands/doctor-agent-fleet.md +22 -0
  11. package/.versions/0.0.11/.claude/commands/orchestrate.md +112 -0
  12. package/.versions/0.0.11/.claude/commands/plan.md +16 -0
  13. package/.versions/0.0.11/.claude/commands/prime.md +22 -0
  14. package/.versions/0.0.11/.claude/commands/review.md +16 -0
  15. package/.versions/0.0.11/.claude/commands/set-hermes-telegram.md +15 -0
  16. package/.versions/0.0.11/.claude/commands/set-hermes-watchdog.md +6 -0
  17. package/.versions/0.0.11/.claude/commands/setup-agent-fleet.md +17 -0
  18. package/.versions/0.0.11/.claude/commands/ship.md +72 -0
  19. package/.versions/0.0.11/.claude/commands/spec.md +15 -0
  20. package/.versions/0.0.11/.claude/commands/test.md +19 -0
  21. package/.versions/0.0.11/.claude/commands/webperf.md +32 -0
  22. package/.versions/0.0.11/.claude/orchestrate-teams.yaml +24 -0
  23. package/.versions/0.0.11/.opencode/commands/af-build.md +17 -0
  24. package/.versions/0.0.11/.opencode/commands/af-code-simplify.md +16 -0
  25. package/.versions/0.0.11/.opencode/commands/af-compound.md +16 -0
  26. package/.versions/0.0.11/.opencode/commands/af-design-agent.md +15 -0
  27. package/.versions/0.0.11/.opencode/commands/af-doctor-agent-fleet.md +22 -0
  28. package/.versions/0.0.11/.opencode/commands/af-orchestrate.md +112 -0
  29. package/.versions/0.0.11/.opencode/commands/af-plan.md +16 -0
  30. package/.versions/0.0.11/.opencode/commands/af-prime.md +22 -0
  31. package/.versions/0.0.11/.opencode/commands/af-review.md +15 -0
  32. package/.versions/0.0.11/.opencode/commands/af-set-hermes-telegram.md +15 -0
  33. package/.versions/0.0.11/.opencode/commands/af-set-hermes-watchdog.md +6 -0
  34. package/.versions/0.0.11/.opencode/commands/af-setup-agent-fleet.md +17 -0
  35. package/.versions/0.0.11/.opencode/commands/af-ship.md +16 -0
  36. package/.versions/0.0.11/.opencode/commands/af-spec.md +16 -0
  37. package/.versions/0.0.11/.opencode/commands/af-test.md +21 -0
  38. package/.versions/0.0.11/.opencode/commands/af-webperf.md +32 -0
  39. package/.versions/0.0.11/.opencode/orchestrate-teams.yaml +24 -0
  40. package/.versions/0.0.11/.pi/agents/dispatch-policy.yaml +32 -0
  41. package/.versions/0.0.11/.pi/agents/model-profiles.yaml +27 -0
  42. package/.versions/0.0.11/.pi/agents/peers.yaml +142 -0
  43. package/.versions/0.0.11/.pi/agents/teams.yaml +41 -0
  44. package/.versions/0.0.11/.pi/damage-control-rules.yaml +297 -0
  45. package/.versions/0.0.11/.pi/extensions/agent-fleet-update-check/README.md +57 -0
  46. package/.versions/0.0.11/.pi/extensions/agent-fleet-update-check/index.ts +161 -0
  47. package/.versions/0.0.11/.pi/extensions/agent-fleet-update-check/package.json +6 -0
  48. package/.versions/0.0.11/.pi/extensions/btw/README.md +119 -0
  49. package/.versions/0.0.11/.pi/extensions/btw/index.ts +917 -0
  50. package/.versions/0.0.11/.pi/extensions/btw/package.json +6 -0
  51. package/.versions/0.0.11/.pi/extensions/btw/state.js +179 -0
  52. package/.versions/0.0.11/.pi/extensions/chrome-devtools-mcp/README.md +55 -0
  53. package/.versions/0.0.11/.pi/extensions/chrome-devtools-mcp/index.ts +93 -0
  54. package/.versions/0.0.11/.pi/extensions/chrome-devtools-mcp/package.json +6 -0
  55. package/.versions/0.0.11/.pi/extensions/compact-and-continue/README.md +42 -0
  56. package/.versions/0.0.11/.pi/extensions/compact-and-continue/index.ts +120 -0
  57. package/.versions/0.0.11/.pi/extensions/compact-and-continue/package.json +6 -0
  58. package/.versions/0.0.11/.pi/extensions/mcp-bridge/README.md +46 -0
  59. package/.versions/0.0.11/.pi/extensions/mcp-bridge/index.ts +206 -0
  60. package/.versions/0.0.11/.pi/extensions/mcp-bridge/package.json +6 -0
  61. package/.versions/0.0.11/.pi/extensions/package-lock.json +1143 -0
  62. package/.versions/0.0.11/.pi/extensions/package.json +9 -0
  63. package/.versions/0.0.11/.pi/extensions/pi-voice-stt/README.md +204 -0
  64. package/.versions/0.0.11/.pi/extensions/pi-voice-stt/config.ts +198 -0
  65. package/.versions/0.0.11/.pi/extensions/pi-voice-stt/examples/stt.json +35 -0
  66. package/.versions/0.0.11/.pi/extensions/pi-voice-stt/index.ts +248 -0
  67. package/.versions/0.0.11/.pi/extensions/pi-voice-stt/package.json +6 -0
  68. package/.versions/0.0.11/.pi/extensions/pi-voice-stt/providers.ts +214 -0
  69. package/.versions/0.0.11/.pi/extensions/pi-voice-stt/recorder.ts +158 -0
  70. package/.versions/0.0.11/.pi/harnesses/agent-hub/README.md +1004 -0
  71. package/.versions/0.0.11/.pi/harnesses/agent-hub/access-approval.ts +135 -0
  72. package/.versions/0.0.11/.pi/harnesses/agent-hub/artifacts.js +146 -0
  73. package/.versions/0.0.11/.pi/harnesses/agent-hub/assertion-ledger.js +58 -0
  74. package/.versions/0.0.11/.pi/harnesses/agent-hub/backend-policy.js +153 -0
  75. package/.versions/0.0.11/.pi/harnesses/agent-hub/context-window.js +106 -0
  76. package/.versions/0.0.11/.pi/harnesses/agent-hub/delegate.ts +435 -0
  77. package/.versions/0.0.11/.pi/harnesses/agent-hub/docs-lane.js +122 -0
  78. package/.versions/0.0.11/.pi/harnesses/agent-hub/drift-watchdog.js +211 -0
  79. package/.versions/0.0.11/.pi/harnesses/agent-hub/evidence-rules.js +96 -0
  80. package/.versions/0.0.11/.pi/harnesses/agent-hub/external-blocker.js +85 -0
  81. package/.versions/0.0.11/.pi/harnesses/agent-hub/footer.ts +31 -0
  82. package/.versions/0.0.11/.pi/harnesses/agent-hub/helpers.ts +248 -0
  83. package/.versions/0.0.11/.pi/harnesses/agent-hub/index.ts +9111 -0
  84. package/.versions/0.0.11/.pi/harnesses/agent-hub/monitor-control.ts +9 -0
  85. package/.versions/0.0.11/.pi/harnesses/agent-hub/monitor-invoke-journal.ts +131 -0
  86. package/.versions/0.0.11/.pi/harnesses/agent-hub/monitor-invoke.ts +92 -0
  87. package/.versions/0.0.11/.pi/harnesses/agent-hub/monitor-lifecycle.ts +13 -0
  88. package/.versions/0.0.11/.pi/harnesses/agent-hub/monitor-publisher.ts +59 -0
  89. package/.versions/0.0.11/.pi/harnesses/agent-hub/monitor-recovery.ts +3 -0
  90. package/.versions/0.0.11/.pi/harnesses/agent-hub/monitor-runtime.ts +3 -0
  91. package/.versions/0.0.11/.pi/harnesses/agent-hub/monitor-session-bridge.ts +257 -0
  92. package/.versions/0.0.11/.pi/harnesses/agent-hub/package.json +7 -0
  93. package/.versions/0.0.11/.pi/harnesses/agent-hub/provider-semaphore.js +138 -0
  94. package/.versions/0.0.11/.pi/harnesses/agent-hub/research-retention.js +34 -0
  95. package/.versions/0.0.11/.pi/harnesses/agent-hub/research-watchdog.ts +40 -0
  96. package/.versions/0.0.11/.pi/harnesses/agent-hub/return-contract.js +293 -0
  97. package/.versions/0.0.11/.pi/harnesses/agent-hub/return-extract.js +75 -0
  98. package/.versions/0.0.11/.pi/harnesses/agent-hub/review-findings.js +102 -0
  99. package/.versions/0.0.11/.pi/harnesses/agent-hub/run-budget.js +479 -0
  100. package/.versions/0.0.11/.pi/harnesses/agent-hub/run-namespace.js +87 -0
  101. package/.versions/0.0.11/.pi/harnesses/agent-hub/safety-routing.ts +22 -0
  102. package/.versions/0.0.11/.pi/harnesses/agent-hub/scope-gate.js +103 -0
  103. package/.versions/0.0.11/.pi/harnesses/agent-hub/session-health.js +110 -0
  104. package/.versions/0.0.11/.pi/harnesses/agent-hub/spawn.ts +354 -0
  105. package/.versions/0.0.11/.pi/harnesses/agent-hub/version.ts +42 -0
  106. package/.versions/0.0.11/.pi/harnesses/ask-user-remote/README.md +19 -0
  107. package/.versions/0.0.11/.pi/harnesses/ask-user-remote/index.ts +321 -0
  108. package/.versions/0.0.11/.pi/harnesses/ask-user-remote/race-core.js +106 -0
  109. package/.versions/0.0.11/.pi/harnesses/coms/README.md +100 -0
  110. package/.versions/0.0.11/.pi/harnesses/coms/index.ts +1767 -0
  111. package/.versions/0.0.11/.pi/harnesses/coms/package.json +7 -0
  112. package/.versions/0.0.11/.pi/harnesses/coms/version.ts +42 -0
  113. package/.versions/0.0.11/.pi/harnesses/damage-control-continue/README.md +124 -0
  114. package/.versions/0.0.11/.pi/harnesses/damage-control-continue/index.ts +536 -0
  115. package/.versions/0.0.11/.pi/harnesses/damage-control-continue/package.json +7 -0
  116. package/.versions/0.0.11/.pi/harnesses/damage-control-continue/version.ts +42 -0
  117. package/.versions/0.0.11/.pi/harnesses/lib/coms-registry-entry.ts +94 -0
  118. package/.versions/0.0.11/.pi/harnesses/lib/damage-control-shared.ts +197 -0
  119. package/.versions/0.0.11/.pi/harnesses/lib/herdr-client.ts +472 -0
  120. package/.versions/0.0.11/.pi/harnesses/lib/herdr-presence.ts +399 -0
  121. package/.versions/0.0.11/.pi/harnesses/lib/hermes-monitor-events.ts +136 -0
  122. package/.versions/0.0.11/.pi/harnesses/lib/hermes-monitor-herdr.ts +28 -0
  123. package/.versions/0.0.11/.pi/harnesses/lib/hermes-monitor-model.ts +18 -0
  124. package/.versions/0.0.11/.pi/harnesses/lib/hermes-monitor-registry.ts +6 -0
  125. package/.versions/0.0.11/.pi/harnesses/lib/hermes-monitor-socket.ts +163 -0
  126. package/.versions/0.0.11/.pi/harnesses/lib/hermes-monitor-store.ts +31 -0
  127. package/.versions/0.0.11/.pi/harnesses/lib/spawned-peers.js +190 -0
  128. package/.versions/0.0.11/.pi/harnesses/package-lock.json +35 -0
  129. package/.versions/0.0.11/.pi/harnesses/package.json +9 -0
  130. package/.versions/0.0.11/.pi/prompts/af-build.md +24 -0
  131. package/.versions/0.0.11/.pi/prompts/af-code-simplify.md +22 -0
  132. package/.versions/0.0.11/.pi/prompts/af-doctor-agent-fleet.md +22 -0
  133. package/.versions/0.0.11/.pi/prompts/af-plan.md +16 -0
  134. package/.versions/0.0.11/.pi/prompts/af-review.md +16 -0
  135. package/.versions/0.0.11/.pi/prompts/af-set-hermes-telegram.md +15 -0
  136. package/.versions/0.0.11/.pi/prompts/af-set-hermes-watchdog.md +6 -0
  137. package/.versions/0.0.11/.pi/prompts/af-setup-agent-fleet.md +19 -0
  138. package/.versions/0.0.11/.pi/prompts/af-ship.md +17 -0
  139. package/.versions/0.0.11/.pi/prompts/af-spec.md +15 -0
  140. package/.versions/0.0.11/.pi/prompts/af-test.md +19 -0
  141. package/.versions/0.0.11/.pi/skills/bowser/SKILL.md +145 -0
  142. package/.versions/0.0.11/.version +1 -0
  143. package/.versions/0.0.11/agents/architect.md +24 -0
  144. package/.versions/0.0.11/agents/bowser.md +27 -0
  145. package/.versions/0.0.11/agents/builder.md +54 -0
  146. package/.versions/0.0.11/agents/code-reviewer.md +208 -0
  147. package/.versions/0.0.11/agents/deep-researcher.md +32 -0
  148. package/.versions/0.0.11/agents/documenter.md +18 -0
  149. package/.versions/0.0.11/agents/orchestrator.md +72 -0
  150. package/.versions/0.0.11/agents/plan-reviewer.md +83 -0
  151. package/.versions/0.0.11/agents/planner.md +70 -0
  152. package/.versions/0.0.11/agents/releaser.md +24 -0
  153. package/.versions/0.0.11/agents/researcher.md +28 -0
  154. package/.versions/0.0.11/agents/security-auditor.md +167 -0
  155. package/.versions/0.0.11/agents/test-engineer.md +153 -0
  156. package/.versions/0.0.11/agents/web-debugger.md +43 -0
  157. package/.versions/0.0.11/agents/web-performance-auditor.md +193 -0
  158. package/.versions/0.0.11/codex/CONDUCTOR.md +148 -0
  159. package/.versions/0.0.11/docs/ARCHITECTURE.md +303 -0
  160. package/.versions/0.0.11/docs/agent-fleet-setup.md +377 -0
  161. package/.versions/0.0.11/docs/claude-code-coms-bridge.md +109 -0
  162. package/.versions/0.0.11/docs/codex-remote-conductor.md +170 -0
  163. package/.versions/0.0.11/docs/coms-hermes-bridge.md +189 -0
  164. package/.versions/0.0.11/docs/getting-started.md +254 -0
  165. package/.versions/0.0.11/docs/npm-install.md +514 -0
  166. package/.versions/0.0.11/docs/opencode-setup.md +281 -0
  167. package/.versions/0.0.11/docs/pi-extensions.md +368 -0
  168. package/.versions/0.0.11/docs/pi-setup.md +571 -0
  169. package/.versions/0.0.11/docs/skill-anatomy.md +150 -0
  170. package/.versions/0.0.11/hermes/README.md +347 -0
  171. package/.versions/0.0.11/hermes/desktop-plugins/agent-fleet-herdr/plugin.js +1291 -0
  172. package/.versions/0.0.11/hermes/desktop-plugins/agent-fleet-herdr/presentation.js +672 -0
  173. package/.versions/0.0.11/hermes/desktop-plugins/agent-fleet-monitor/plugin.js +19 -0
  174. package/.versions/0.0.11/hermes/desktop-plugins/agent-fleet-monitor/state.js +10 -0
  175. package/.versions/0.0.11/hermes/gates/gate-o-capability.md +8 -0
  176. package/.versions/0.0.11/hermes/gates/gate-o-validator-fixtures.json +1 -0
  177. package/.versions/0.0.11/hermes/plugins/agent-fleet-herdr/dashboard/activity.py +770 -0
  178. package/.versions/0.0.11/hermes/plugins/agent-fleet-herdr/dashboard/coms_registry.py +134 -0
  179. package/.versions/0.0.11/hermes/plugins/agent-fleet-herdr/dashboard/coms_send.py +350 -0
  180. package/.versions/0.0.11/hermes/plugins/agent-fleet-herdr/dashboard/herdr_source.py +193 -0
  181. package/.versions/0.0.11/hermes/plugins/agent-fleet-herdr/dashboard/manifest.json +4 -0
  182. package/.versions/0.0.11/hermes/plugins/agent-fleet-herdr/dashboard/plugin_api.py +444 -0
  183. package/.versions/0.0.11/hermes/plugins/agent-fleet-herdr/dashboard/sessions.py +205 -0
  184. package/.versions/0.0.11/hermes/plugins/agent-fleet-herdr/dashboard/tasks.py +300 -0
  185. package/.versions/0.0.11/hermes/plugins/agent-fleet-herdr/dashboard/watch.py +819 -0
  186. package/.versions/0.0.11/hermes/plugins/agent-fleet-herdr/plugin.yaml +8 -0
  187. package/.versions/0.0.11/hermes/plugins/agent-fleet-monitor/dashboard/adapter.py +139 -0
  188. package/.versions/0.0.11/hermes/plugins/agent-fleet-monitor/dashboard/manifest.json +11 -0
  189. package/.versions/0.0.11/hermes/plugins/agent-fleet-monitor/dashboard/plugin_api.py +50 -0
  190. package/.versions/0.0.11/hermes/skills/hub-conductor/SKILL.md +84 -0
  191. package/.versions/0.0.11/hermes/skills/hub-liaison/SKILL.md +84 -0
  192. package/.versions/0.0.11/hermes/skills/hub-watchdog/SKILL.md +76 -0
  193. package/.versions/0.0.11/hermes/skills/hub-watchdog/manifest.json +1 -0
  194. package/.versions/0.0.11/hermes/skills/hub-watchdog/scripts/watchdog.py +249 -0
  195. package/.versions/0.0.11/hermes/skills/hub-watchdog/scripts/watchdog_actions.py +124 -0
  196. package/.versions/0.0.11/hermes/skills/hub-watchdog/scripts/watchdog_contract.py +76 -0
  197. package/.versions/0.0.11/hermes/skills/hub-watchdog/scripts/watchdog_delivery.py +10 -0
  198. package/.versions/0.0.11/hermes/skills/hub-watchdog/scripts/watchdog_engine.py +128 -0
  199. package/.versions/0.0.11/hermes/skills/hub-watchdog/scripts/watchdog_judgment.py +41 -0
  200. package/.versions/0.0.11/hermes/skills/hub-watchdog/scripts/watchdog_recovery.py +103 -0
  201. package/.versions/0.0.11/hermes/skills/hub-watchdog/scripts/watchdog_state.py +163 -0
  202. package/.versions/0.0.11/hermes/skills/hub-watchdog/scripts/watchdog_transport.py +138 -0
  203. package/.versions/0.0.11/hermes/watchdog-tests/__init__.py +0 -0
  204. package/.versions/0.0.11/hooks/SIMPLIFY-IGNORE.md +90 -0
  205. package/.versions/0.0.11/hooks/coms-stop-hook.mjs +84 -0
  206. package/.versions/0.0.11/hooks/hooks.json +14 -0
  207. package/.versions/0.0.11/hooks/session-start.sh +74 -0
  208. package/.versions/0.0.11/hooks/simplify-ignore.sh +302 -0
  209. package/.versions/0.0.11/install-manifest.json +3615 -0
  210. package/.versions/0.0.11/justfile +254 -0
  211. package/.versions/0.0.11/manifest-meta.json +472 -0
  212. package/.versions/0.0.11/references/accessibility-checklist.md +160 -0
  213. package/.versions/0.0.11/references/definition-of-done.md +67 -0
  214. package/.versions/0.0.11/references/fleet-coordination-patterns.md +151 -0
  215. package/.versions/0.0.11/references/observability-checklist.md +91 -0
  216. package/.versions/0.0.11/references/orchestration-patterns.md +370 -0
  217. package/.versions/0.0.11/references/performance-checklist.md +153 -0
  218. package/.versions/0.0.11/references/prompting-patterns.md +380 -0
  219. package/.versions/0.0.11/references/security-checklist.md +179 -0
  220. package/.versions/0.0.11/references/testing-patterns.md +236 -0
  221. package/.versions/0.0.11/scripts/codex-conductor.ts +41 -0
  222. package/.versions/0.0.11/scripts/codex-remote-control.ts +167 -0
  223. package/.versions/0.0.11/scripts/coms-claude-bridge.ts +401 -0
  224. package/.versions/0.0.11/scripts/coms-cli.ts +484 -0
  225. package/.versions/0.0.11/scripts/coms-hermes-bridge.ts +413 -0
  226. package/.versions/0.0.11/scripts/fleet.ts +168 -0
  227. package/.versions/0.0.11/scripts/hermes-monitor-capability-runner.ts +25 -0
  228. package/.versions/0.0.11/scripts/hermes-monitor-scenario.ts +474 -0
  229. package/.versions/0.0.11/scripts/hermes-watchdog-capability-probe.ts +45 -0
  230. package/.versions/0.0.11/scripts/install-hermes-plugin.sh +180 -0
  231. package/.versions/0.0.11/scripts/lib/claude-bridge-core.ts +165 -0
  232. package/.versions/0.0.11/scripts/lib/codex-conductor.ts +88 -0
  233. package/.versions/0.0.11/scripts/lib/codex-remote-control.ts +480 -0
  234. package/.versions/0.0.11/scripts/lib/coms-envelope.ts +582 -0
  235. package/.versions/0.0.11/scripts/lib/fake-herdr-server.ts +88 -0
  236. package/.versions/0.0.11/scripts/lib/fleet-command.ts +111 -0
  237. package/.versions/0.0.11/scripts/lib/herdr-layout.ts +281 -0
  238. package/.versions/0.0.11/scripts/lib/hermes-bridge-core.ts +241 -0
  239. package/.versions/0.0.11/scripts/lib/hermes-monitor-events.ts +1 -0
  240. package/.versions/0.0.11/scripts/lib/hermes-monitor-herdr.ts +2 -0
  241. package/.versions/0.0.11/scripts/lib/hermes-monitor-model.ts +3 -0
  242. package/.versions/0.0.11/scripts/lib/hermes-monitor-registry.ts +2 -0
  243. package/.versions/0.0.11/scripts/lib/hermes-monitor-socket.ts +2 -0
  244. package/.versions/0.0.11/scripts/lib/hermes-monitor-store.ts +2 -0
  245. package/.versions/0.0.11/scripts/lib/monitor-env.ts +134 -0
  246. package/.versions/0.0.11/scripts/lib/peer-launch.ts +314 -0
  247. package/.versions/0.0.11/scripts/lib/persona-banner.ts +62 -0
  248. package/.versions/0.0.11/scripts/lib/spawn-stagger.ts +101 -0
  249. package/.versions/0.0.11/scripts/lib/team-project.ts +193 -0
  250. package/.versions/0.0.11/scripts/lib/team-snapshot.ts +147 -0
  251. package/.versions/0.0.11/scripts/peer-banner.ts +40 -0
  252. package/.versions/0.0.11/scripts/peer-launch.ts +259 -0
  253. package/.versions/0.0.11/scripts/team-snapshot.ts +237 -0
  254. package/.versions/0.0.11/scripts/team-up.ts +360 -0
  255. package/.versions/0.0.11/skills/_internal/grilling.md +11 -0
  256. package/.versions/0.0.11/skills/browser-testing-with-devtools/SKILL.md +351 -0
  257. package/.versions/0.0.11/skills/code-review-and-quality/SKILL.md +381 -0
  258. package/.versions/0.0.11/skills/compound-learning/SKILL.md +137 -0
  259. package/.versions/0.0.11/skills/context-engineering/SKILL.md +291 -0
  260. package/.versions/0.0.11/skills/deprecation-and-migration/SKILL.md +206 -0
  261. package/.versions/0.0.11/skills/designing-agents/SKILL.md +394 -0
  262. package/.versions/0.0.11/skills/designing-agents/pi-harness-authoring.md +222 -0
  263. package/.versions/0.0.11/skills/frontend-ui-engineering/SKILL.md +328 -0
  264. package/.versions/0.0.11/skills/git-workflow-and-versioning/SKILL.md +316 -0
  265. package/.versions/0.0.11/skills/guided-workspace-setup/SKILL.md +226 -0
  266. package/.versions/0.0.11/skills/guided-workspace-setup/companion-manifest.json +38 -0
  267. package/.versions/0.0.11/skills/idea-refine/SKILL.md +182 -0
  268. package/.versions/0.0.11/skills/idea-refine/examples.md +238 -0
  269. package/.versions/0.0.11/skills/idea-refine/frameworks.md +99 -0
  270. package/.versions/0.0.11/skills/idea-refine/refinement-criteria.md +113 -0
  271. package/.versions/0.0.11/skills/idea-refine/scripts/idea-refine.sh +15 -0
  272. package/.versions/0.0.11/skills/incremental-implementation/SKILL.md +287 -0
  273. package/.versions/0.0.11/skills/interview-me/SKILL.md +226 -0
  274. package/.versions/0.0.11/skills/orchestration-verification/SKILL.md +181 -0
  275. package/.versions/0.0.11/skills/peer-coms/SKILL.md +90 -0
  276. package/.versions/0.0.11/skills/performance-optimization/SKILL.md +350 -0
  277. package/.versions/0.0.11/skills/planning-and-task-breakdown/SKILL.md +254 -0
  278. package/.versions/0.0.11/skills/security-and-hardening/SKILL.md +461 -0
  279. package/.versions/0.0.11/skills/spec-driven-development/SKILL.md +257 -0
  280. package/.versions/0.0.11/skills/using-agent-skills/SKILL.md +199 -0
  281. package/.versions/0.0.11/systemd/user/agent-fleet-codex-remote-control.service.in +23 -0
  282. package/.versions/0.0.11/vendor/agent-skills-upstream/LICENSE +21 -0
  283. package/.versions/0.0.11/vendor/agent-skills-upstream/README.md +11 -0
  284. package/.versions/0.0.11/vendor/agent-skills-upstream/skills/api-and-interface-design/SKILL.md +294 -0
  285. package/.versions/0.0.11/vendor/agent-skills-upstream/skills/browser-testing-with-devtools/SKILL.md +317 -0
  286. package/.versions/0.0.11/vendor/agent-skills-upstream/skills/ci-cd-and-automation/SKILL.md +390 -0
  287. package/.versions/0.0.11/vendor/agent-skills-upstream/skills/code-review-and-quality/SKILL.md +396 -0
  288. package/.versions/0.0.11/vendor/agent-skills-upstream/skills/code-simplification/SKILL.md +331 -0
  289. package/.versions/0.0.11/vendor/agent-skills-upstream/skills/context-engineering/SKILL.md +289 -0
  290. package/.versions/0.0.11/vendor/agent-skills-upstream/skills/debugging-and-error-recovery/SKILL.md +300 -0
  291. package/.versions/0.0.11/vendor/agent-skills-upstream/skills/deprecation-and-migration/SKILL.md +247 -0
  292. package/.versions/0.0.11/vendor/agent-skills-upstream/skills/documentation-and-adrs/SKILL.md +278 -0
  293. package/.versions/0.0.11/vendor/agent-skills-upstream/skills/doubt-driven-development/SKILL.md +243 -0
  294. package/.versions/0.0.11/vendor/agent-skills-upstream/skills/frontend-ui-engineering/SKILL.md +328 -0
  295. package/.versions/0.0.11/vendor/agent-skills-upstream/skills/git-workflow-and-versioning/SKILL.md +355 -0
  296. package/.versions/0.0.11/vendor/agent-skills-upstream/skills/idea-refine/SKILL.md +178 -0
  297. package/.versions/0.0.11/vendor/agent-skills-upstream/skills/idea-refine/examples.md +238 -0
  298. package/.versions/0.0.11/vendor/agent-skills-upstream/skills/idea-refine/frameworks.md +99 -0
  299. package/.versions/0.0.11/vendor/agent-skills-upstream/skills/idea-refine/refinement-criteria.md +113 -0
  300. package/.versions/0.0.11/vendor/agent-skills-upstream/skills/idea-refine/scripts/idea-refine.sh +15 -0
  301. package/.versions/0.0.11/vendor/agent-skills-upstream/skills/incremental-implementation/SKILL.md +249 -0
  302. package/.versions/0.0.11/vendor/agent-skills-upstream/skills/interview-me/SKILL.md +225 -0
  303. package/.versions/0.0.11/vendor/agent-skills-upstream/skills/observability-and-instrumentation/SKILL.md +203 -0
  304. package/.versions/0.0.11/vendor/agent-skills-upstream/skills/performance-optimization/SKILL.md +350 -0
  305. package/.versions/0.0.11/vendor/agent-skills-upstream/skills/planning-and-task-breakdown/SKILL.md +234 -0
  306. package/.versions/0.0.11/vendor/agent-skills-upstream/skills/security-and-hardening/SKILL.md +467 -0
  307. package/.versions/0.0.11/vendor/agent-skills-upstream/skills/shipping-and-launch/SKILL.md +310 -0
  308. package/.versions/0.0.11/vendor/agent-skills-upstream/skills/source-driven-development/SKILL.md +194 -0
  309. package/.versions/0.0.11/vendor/agent-skills-upstream/skills/spec-driven-development/SKILL.md +206 -0
  310. package/.versions/0.0.11/vendor/agent-skills-upstream/skills/test-driven-development/SKILL.md +383 -0
  311. package/.versions/0.0.11/vendor/agent-skills-upstream/skills/using-agent-skills/SKILL.md +191 -0
  312. package/CHANGELOG.md +7 -0
  313. package/docs/pi-extensions.md +5 -0
  314. package/install-manifest.json +1 -1
  315. package/package.json +1 -1
  316. package/scripts/lib/monitor-env.ts +15 -1
@@ -0,0 +1,321 @@
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
+ import { fileURLToPath, pathToFileURL } from "node:url";
12
+
13
+ import { raceAskUser } from "./race-core.js";
14
+
15
+ interface ToolRegistration {
16
+ name: string;
17
+ execute?: (...args: any[]) => Promise<any> | any;
18
+ [key: string]: any;
19
+ }
20
+
21
+ interface ExtensionLike {
22
+ registerTool: (tool: ToolRegistration) => void;
23
+ [key: string]: any;
24
+ }
25
+
26
+ interface InstallOptions {
27
+ stockFactory?: (pi: ExtensionLike) => void;
28
+ startRemote?: (params: any, ctx?: any) => Promise<{ qid: string; result: Promise<any> } | null> | { qid: string; result: Promise<any> } | null;
29
+ cancelRemote?: (qid: string, reason: string) => Promise<void> | void;
30
+ warn?: (message: string) => void;
31
+ createAbortController?: () => AbortController;
32
+ settingsPaths?: string[];
33
+ remoteProject?: string | (() => string);
34
+ }
35
+
36
+ // A stock `pi-ask-user` package listed in pi settings is loaded by pi core
37
+ // itself, outside this harness's try/catch. If the harness registers `ask_user`
38
+ // first, the package's later registration makes pi core hard-crash the session
39
+ // with a tool-name conflict. The preflight below detects that configuration and
40
+ // skips the wrapper entirely, so the stock package registers alone regardless
41
+ // of load order.
42
+ const STOCK_PACKAGE_PATTERN = /(^|[/:])pi-ask-user(@[^/]*)?$/;
43
+
44
+ export function defaultSettingsPaths(): string[] {
45
+ return [
46
+ path.join(process.cwd(), ".pi", "settings.json"),
47
+ path.join(os.homedir(), ".pi", "agent", "settings.json"),
48
+ ];
49
+ }
50
+
51
+ export function findStockAskUserPackageEntry(settingsPaths: string[]): { entry: string; settingsPath: string } | null {
52
+ for (const settingsPath of settingsPaths) {
53
+ let packages: unknown;
54
+ try {
55
+ packages = JSON.parse(fs.readFileSync(settingsPath, "utf8"))?.packages;
56
+ } catch {
57
+ continue;
58
+ }
59
+ if (!Array.isArray(packages)) continue;
60
+ const entry = packages.find((pkg) => typeof pkg === "string" && STOCK_PACKAGE_PATTERN.test(pkg));
61
+ if (entry) return { entry, settingsPath };
62
+ }
63
+ return null;
64
+ }
65
+
66
+ export function captureAskUserTool(stockFactory: (pi: ExtensionLike) => void, pi: ExtensionLike): ToolRegistration {
67
+ let captured: ToolRegistration | null = null;
68
+ const proxy = new Proxy(pi, {
69
+ get(target, prop, receiver) {
70
+ if (prop === "registerTool") {
71
+ return (tool: ToolRegistration) => {
72
+ if (tool?.name === "ask_user") {
73
+ captured = tool;
74
+ return;
75
+ }
76
+ return target.registerTool(tool);
77
+ };
78
+ }
79
+ return Reflect.get(target, prop, receiver);
80
+ },
81
+ }) as ExtensionLike;
82
+
83
+ stockFactory(proxy);
84
+ if (!captured) throw new Error("ask-user-remote: stock pi-ask-user did not register ask_user");
85
+ return captured;
86
+ }
87
+
88
+ function warn(pi: ExtensionLike, options: InstallOptions, message: string): void {
89
+ if (typeof options.warn === "function") {
90
+ options.warn(message);
91
+ return;
92
+ }
93
+ if (typeof pi.logger?.warn === "function") {
94
+ pi.logger.warn(message);
95
+ return;
96
+ }
97
+ if (typeof pi.log?.warn === "function") {
98
+ pi.log.warn(message);
99
+ return;
100
+ }
101
+ console.warn(message);
102
+ }
103
+
104
+ export function resolveRemoteProject(pi: ExtensionLike, argv: string[] = process.argv): string {
105
+ for (let i = argv.length - 2; i >= 0; i--) {
106
+ if (argv[i] === "--project" && typeof argv[i + 1] === "string" && argv[i + 1].trim()) {
107
+ return argv[i + 1].trim();
108
+ }
109
+ }
110
+ const inlineProject = [...argv].reverse().find((arg) => arg.startsWith("--project="))?.slice("--project=".length).trim();
111
+ if (inlineProject) return inlineProject;
112
+ const cliProject = typeof pi.getFlag === "function" ? pi.getFlag("project") : undefined;
113
+ if (typeof cliProject === "string" && cliProject.trim()) return cliProject.trim();
114
+ const envProject = process.env.PI_COMS_PROJECT;
115
+ return envProject?.trim() || "default";
116
+ }
117
+
118
+ function linkAbortSignal(parent: AbortSignal | undefined, child: AbortController): void {
119
+ if (!parent) return;
120
+ if (parent.aborted) {
121
+ child.abort();
122
+ return;
123
+ }
124
+ parent.addEventListener("abort", () => child.abort(), { once: true });
125
+ }
126
+
127
+ function stockResultFromRemote(params: any, response: any): any {
128
+ const summary = response?.kind === "selection"
129
+ ? (Array.isArray(response.selections) ? response.selections.join(", ") : "")
130
+ : response?.kind === "freeform"
131
+ ? String(response.text ?? "")
132
+ : typeof response === "string"
133
+ ? response
134
+ : JSON.stringify(response);
135
+ return {
136
+ content: [{ type: "text", text: `User answered: ${summary}` }],
137
+ details: {
138
+ question: params?.question,
139
+ context: params?.context?.trim?.() || params?.context,
140
+ options: normalizeOptions(params?.options ?? []),
141
+ response,
142
+ cancelled: false,
143
+ },
144
+ };
145
+ }
146
+
147
+ function normalizeOptions(options: any[]): Array<{ title: string; description?: string }> {
148
+ return (Array.isArray(options) ? options : [])
149
+ .map((option) => {
150
+ if (typeof option === "string") return { title: option };
151
+ if (option && typeof option === "object" && typeof option.title === "string") {
152
+ return typeof option.description === "string"
153
+ ? { title: option.title, description: option.description }
154
+ : { title: option.title };
155
+ }
156
+ return null;
157
+ })
158
+ .filter(Boolean) as Array<{ title: string; description?: string }>;
159
+ }
160
+
161
+ // Live remote questions started by defaultStartRemote, keyed by qid. A cancel
162
+ // must settle the pending result so the per-question endpoint server is closed;
163
+ // otherwise every locally-answered race leaks a bound socket until process exit.
164
+ const activeRemote = new Map<string, (error: Error) => void>();
165
+
166
+ export function activeRemoteCount(): number {
167
+ return activeRemote.size;
168
+ }
169
+
170
+ async function defaultStartRemote(params: any, project: string): Promise<{ qid: string; result: Promise<any> } | null> {
171
+ const coms = await import("../../../scripts/lib/coms-envelope.ts");
172
+ const peerName = process.env.PI_ASK_USER_REMOTE_PEER || "user-remote";
173
+ const peer = coms.pruneDeadEntries(project).find((entry: any) => entry.name === peerName);
174
+ if (!peer) return null;
175
+
176
+ coms.ensureComsDirs(project);
177
+ const id = {
178
+ session_id: coms.ulid(),
179
+ name: "ask-user-remote",
180
+ endpoint: "",
181
+ cwd: process.cwd(),
182
+ };
183
+ id.endpoint = coms.makeEndpoint(id.session_id);
184
+
185
+ let resolveResult!: (value: any) => void;
186
+ let rejectResult!: (error: Error) => void;
187
+ const rawResult = new Promise<any>((resolve, reject) => {
188
+ resolveResult = resolve;
189
+ rejectResult = reject;
190
+ });
191
+ const server = await coms.bindEndpoint(
192
+ id.endpoint,
193
+ coms.makeConnHandler((env: Record<string, unknown>, socket: any) => {
194
+ if (coms.isResponseEnvelope(env)) {
195
+ coms.writeAck(socket, env.msg_id);
196
+ if (env.error) rejectResult(new Error(String(env.error)));
197
+ else resolveResult(stockResultFromRemote(params, env.response));
198
+ return;
199
+ }
200
+ coms.writeNack(socket, (env as { msg_id?: string }).msg_id ?? "", "ask-user-remote awaits responses only");
201
+ }),
202
+ );
203
+ const cleanup = () => {
204
+ try { server.close(); } catch { /* ignore */ }
205
+ try { fs.unlinkSync(id.endpoint); } catch { /* ignore */ }
206
+ };
207
+
208
+ const promptPayload = JSON.stringify({
209
+ question: params?.question,
210
+ context: params?.context,
211
+ options: params?.options ?? [],
212
+ });
213
+ const env = coms.makePromptEnvelope(id, promptPayload);
214
+ activeRemote.set(env.msg_id, rejectResult);
215
+ const result = rawResult.finally(() => {
216
+ activeRemote.delete(env.msg_id);
217
+ cleanup();
218
+ });
219
+ try {
220
+ await coms.sendEnvelope(peer.endpoint, env);
221
+ } catch (error) {
222
+ rejectResult(error instanceof Error ? error : new Error(String(error)));
223
+ }
224
+ return { qid: env.msg_id, result };
225
+ }
226
+
227
+ async function defaultCancelRemote(qid: string, reason: string, project: string): Promise<void> {
228
+ try {
229
+ const coms = await import("../../../scripts/lib/coms-envelope.ts");
230
+ const peerName = process.env.PI_ASK_USER_REMOTE_PEER || "user-remote";
231
+ const peer = coms.pruneDeadEntries(project).find((entry: any) => entry.name === peerName);
232
+ if (peer) {
233
+ await coms.sendEnvelope(peer.endpoint, coms.makeCancelEnvelope({
234
+ from: "ask-user-remote",
235
+ to: peer.name,
236
+ ref_msg_id: qid,
237
+ }));
238
+ }
239
+ } finally {
240
+ // The bridge sends no response for a cancelled qid, so settle the pending
241
+ // result here to release the per-question endpoint server.
242
+ activeRemote.get(qid)?.(new Error(`ask-user-remote: cancelled (${reason})`));
243
+ }
244
+ }
245
+
246
+ export function wrapAskUserTool(stockTool: ToolRegistration, options: InstallOptions = {}): ToolRegistration {
247
+ return {
248
+ ...stockTool,
249
+ async execute(toolCallId: string, params: any, signal?: AbortSignal, onUpdate?: any, ctx?: any) {
250
+ const configuredProject = typeof options.remoteProject === "function" ? options.remoteProject() : options.remoteProject;
251
+ const remoteProject = configuredProject ?? process.env.PI_COMS_PROJECT?.trim() ?? "default";
252
+ const startRemote = options.startRemote ?? ((remoteParams: any) => defaultStartRemote(remoteParams, remoteProject));
253
+ let remoteStart: { qid: string; result: Promise<any> } | null = null;
254
+ try {
255
+ remoteStart = await startRemote(params, ctx);
256
+ } catch {
257
+ remoteStart = null;
258
+ }
259
+
260
+ if (!remoteStart) {
261
+ return await stockTool.execute?.(toolCallId, params, signal, onUpdate, ctx);
262
+ }
263
+
264
+ return await raceAskUser({
265
+ runLocal: (localSignal: AbortSignal) => stockTool.execute?.(toolCallId, params, localSignal, onUpdate, ctx),
266
+ startRemote: () => remoteStart,
267
+ cancelRemote: options.cancelRemote ?? ((qid: string, reason: string) => defaultCancelRemote(qid, reason, remoteProject)),
268
+ createAbortController: () => {
269
+ const controller = options.createAbortController?.() ?? new AbortController();
270
+ linkAbortSignal(signal, controller);
271
+ return controller;
272
+ },
273
+ signal,
274
+ });
275
+ },
276
+ };
277
+ }
278
+
279
+ export function installAskUserRemote(pi: ExtensionLike, options: InstallOptions = {}): { registered: boolean; tool?: ToolRegistration } {
280
+ if (options.settingsPaths) {
281
+ const listed = findStockAskUserPackageEntry(options.settingsPaths);
282
+ if (listed) {
283
+ 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.`);
284
+ return { registered: false };
285
+ }
286
+ }
287
+ if (!options.stockFactory) throw new Error("ask-user-remote: stockFactory is required for synchronous install");
288
+ const stockTool = captureAskUserTool(options.stockFactory, pi);
289
+ const wrapped = wrapAskUserTool(stockTool, {
290
+ ...options,
291
+ remoteProject: options.remoteProject ?? (() => resolveRemoteProject(pi)),
292
+ });
293
+ try {
294
+ pi.registerTool(wrapped);
295
+ return { registered: true, tool: wrapped };
296
+ } catch (error) {
297
+ const message = error instanceof Error ? error.message : String(error);
298
+ warn(pi, options, `ask-user-remote: ask_user already registered; wrapper not installed (${message})`);
299
+ return { registered: false };
300
+ }
301
+ }
302
+
303
+ export function resolveStockAskUserModule(moduleUrl: string = import.meta.url): string {
304
+ // Pi's jiti loader preserves the workspace-facing path of a symlinked
305
+ // harness. Canonicalize this module first so the bundled dependency is
306
+ // resolved beside the actual Agent Fleet package, not at workspace root.
307
+ const realModulePath = fs.realpathSync(fileURLToPath(moduleUrl));
308
+ const stockModulePath = path.resolve(path.dirname(realModulePath), "../../../node_modules/pi-ask-user/index.ts");
309
+ return pathToFileURL(stockModulePath).href;
310
+ }
311
+
312
+ async function loadStockFactory(): Promise<(pi: ExtensionLike) => void> {
313
+ const mod = await import(resolveStockAskUserModule());
314
+ return mod.default as (pi: ExtensionLike) => void;
315
+ }
316
+
317
+ export default function askUserRemote(pi: ExtensionLike): void {
318
+ void loadStockFactory()
319
+ .then((stockFactory) => installAskUserRemote(pi, { stockFactory, settingsPaths: defaultSettingsPaths() }))
320
+ .catch((error) => warn(pi, {}, `ask-user-remote: failed to load pi-ask-user (${error instanceof Error ? error.message : String(error)})`));
321
+ }
@@ -0,0 +1,106 @@
1
+ // Pure race arbitration for the ask-user-remote harness.
2
+ //
3
+ // The wrapper supplies the side-effecting pieces:
4
+ // - runLocal(signal): stock pi-ask-user execute with an AbortSignal
5
+ // - startRemote(): starts a user-remote coms request and returns
6
+ // { qid, result: Promise<stock-shaped ask_user result> }, or null when no peer
7
+ // - cancelRemote(qid, reason): best-effort cancel envelope for local-first wins
8
+ //
9
+ // This module owns only the first-answer-wins latch and exactly-once cancel/
10
+ // abort decisions; it has no pi, socket, or filesystem imports.
11
+
12
+ export async function raceAskUser({
13
+ runLocal,
14
+ startRemote,
15
+ cancelRemote,
16
+ createAbortController = () => new AbortController(),
17
+ signal,
18
+ }) {
19
+ if (typeof runLocal !== "function") throw new TypeError("runLocal is required");
20
+
21
+ const controller = createAbortController();
22
+ let settled = false;
23
+ let remotePending = false;
24
+ let remoteQid = null;
25
+ let cancelSent = false;
26
+
27
+ async function emitCancel(reason) {
28
+ if (cancelSent || !remotePending || !remoteQid || typeof cancelRemote !== "function") return;
29
+ cancelSent = true;
30
+ try {
31
+ await cancelRemote(remoteQid, reason);
32
+ } catch {
33
+ // Cancel is best-effort; the winning local answer must not fail because
34
+ // the losing remote channel is already unhealthy.
35
+ }
36
+ }
37
+
38
+ const localPromise = Promise.resolve().then(() => runLocal(controller.signal));
39
+
40
+ let remoteStart = null;
41
+ if (typeof startRemote === "function") {
42
+ try {
43
+ remoteStart = await Promise.resolve().then(() => startRemote());
44
+ } catch {
45
+ remoteStart = null;
46
+ }
47
+ }
48
+
49
+ // No live user-remote peer, or remote startup failed before a qid existed:
50
+ // preserve stock pi-ask-user behavior exactly by returning the local result.
51
+ if (!remoteStart) return await localPromise;
52
+
53
+ remoteQid = typeof remoteStart.qid === "string" ? remoteStart.qid : null;
54
+ remotePending = !!remoteQid;
55
+ const remotePromise = Promise.resolve(remoteStart.result);
56
+
57
+ // If the whole tool call is aborted (turn cancelled), withdraw the remote
58
+ // question instead of leaving it live on the phone until timeout.
59
+ if (signal) {
60
+ if (signal.aborted) void emitCancel("aborted");
61
+ else signal.addEventListener("abort", () => { void emitCancel("aborted"); }, { once: true });
62
+ }
63
+
64
+ return await new Promise((resolve, reject) => {
65
+ let localRejected = false;
66
+ let localError;
67
+ let remoteRejected = false;
68
+
69
+ localPromise.then(
70
+ async (result) => {
71
+ if (settled) return;
72
+ settled = true;
73
+ await emitCancel("local_answered");
74
+ resolve(result);
75
+ },
76
+ (error) => {
77
+ if (settled) return;
78
+ localRejected = true;
79
+ localError = error;
80
+ if (remoteRejected) {
81
+ settled = true;
82
+ reject(localError);
83
+ }
84
+ },
85
+ );
86
+
87
+ remotePromise.then(
88
+ (result) => {
89
+ remotePending = false;
90
+ if (settled) return;
91
+ settled = true;
92
+ controller.abort?.();
93
+ resolve(result);
94
+ },
95
+ () => {
96
+ remotePending = false;
97
+ remoteRejected = true;
98
+ // Remote errors are non-fatal: keep waiting for stock local behavior.
99
+ if (localRejected) {
100
+ settled = true;
101
+ reject(localError);
102
+ }
103
+ },
104
+ );
105
+ });
106
+ }
@@ -0,0 +1,100 @@
1
+ # coms
2
+
3
+ Peer-to-peer messaging between pi agents on the same machine.
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
+ Lets multiple pi agents running on the same machine talk to each other. Each agent listens
10
+ on a single endpoint — a unix socket on POSIX, a named pipe on Windows — and discovers
11
+ peers through per-project registry files under `~/.pi/coms/projects/<project>/agents/`.
12
+
13
+ Surfaces a live "pool" widget of connected peers, with ping and keepalive cycles and a
14
+ clean shutdown lifecycle.
15
+
16
+ ## Version footer and provenance
17
+
18
+ This persistent-UI harness shows `agent fleet v<version>` below the prompt. It shares one common-key
19
+ status with `agent-hub` and `damage-control-continue`, so a stack renders the
20
+ version once. The root `package.json` is canonical; `bin/sync-harness-versions.js` synchronizes
21
+ its value into this adjacent manifest. The local `version.ts` reader is retained so a copied or
22
+ symlinked harness resolves its own adjacent stamp, not the launch directory. That provenance
23
+ pair does not carry dependencies: copy/symlink targets still require the existing full
24
+ `.pi/harnesses/` dependency installation.
25
+
26
+ The `agent fleet` half of the label is an OSC 8 terminal hyperlink to the project homepage —
27
+ clickable in terminals that support hyperlinks, ignored (rendered as plain text) elsewhere, and
28
+ free of footer columns because pi strips OSC sequences before measuring width. It opens the
29
+ repository in a browser, not a TUI panel: pi has no mouse tracking, so a click never reaches the
30
+ harness. `AGENT_FLEET_NO_LINKS=1` restores the plain label on multiplexers that mangle OSC 8
31
+ (GNU screen, tmux before 3.4).
32
+
33
+ ## Presence backends: herdr vs files
34
+
35
+ Presence (who's alive, what state they're in) is pluggable; the **envelope transport,
36
+ tools, and pool-scope boundary are identical in both**:
37
+
38
+ - **herdr** — active automatically when the session runs inside a [herdr](https://herdr.dev)
39
+ pane (`HERDR_ENV=1`) and the server answers ping. Presence goes push: this peer reports
40
+ itself via `pane.report_agent` + `pane.report_metadata` (`tokens` = `coms`/`proj`/
41
+ `ctx`/`q` on herdr >= 0.7.4, one latched fallback to the legacy 32-char
42
+ `custom_status` = `<name> <pct>% q<depth>`), and the pool widget populates
43
+ from `agent.list` + `events.subscribe` — **no periodic ping traffic**; peer state
44
+ changes arrive within ~1s and dead panes disappear on `pane.exited`. Turn state
45
+ (idle/working) in the herdr sidebar comes from herdr's own pi integration when
46
+ installed (`herdr integration install`); coms adds the name/context/queue annotation.
47
+ - **files** — everywhere else: the original 10s ping cycle over the peer endpoints,
48
+ byte-for-byte today's behavior.
49
+
50
+ The file registry keeps being written in BOTH backends (it carries the full agent card
51
+ that a pane annotation cannot, and keeps this peer discoverable to peers
52
+ running outside herdr panes). Peers outside herdr panes appear as dimmed "pending" rows
53
+ when you are on the herdr backend.
54
+
55
+ ## Commands & tools
56
+
57
+ - `/af-coms` — open the coms control surface; `--project <name>` retargets the pool (use `*` for
58
+ every project) and `--all` toggles private (`--explicit`) peers into view
59
+ - `coms_list` / `coms_send` / `coms_get` / `coms_await` tools — discover peers and
60
+ exchange messages
61
+
62
+ ## External conductors
63
+
64
+ Two optional phone-facing conductors use this same pool without becoming pane owners:
65
+
66
+ - **Hermes/Telegram** is the inbound `ask_user` route and can also perform bounded coms delegation.
67
+ - **Codex Remote Control** is an experimental outbound-only Android route. Its user-systemd service loads a managed contract from an external user-state workspace, and `scripts/codex-conductor.ts` permits only scoped `list` plus one serialized `send --await`. See the [operator runbook](../../../docs/codex-remote-conductor.md).
68
+
69
+ Both must use the same validated project as the peers they target. Neither conductor may drive Herdr lifecycle.
70
+
71
+ Standalone `coms-cli` queues are project-scoped under `~/.pi/coms/cli/projects/<project>/<name>/`. Legacy name-only queues fail closed until an operator assigns and moves the complete queue; `projects` is a reserved identity name.
72
+
73
+ ## Pool scope is the reach boundary
74
+
75
+ The pool widget defines who you can reach: `coms_list` and `coms_send` resolve targets through one
76
+ `peersInScope()` helper, so a peer is reachable only if it is in the pool. By default the
77
+ pool is your own project and excludes `--explicit` peers. **Widening is a human-only action** — the
78
+ `coms_list` tool cannot widen scope; only `/af-coms --project` / `/af-coms --all` can. This prevents an
79
+ agent from messaging a cross-project peer that the widget never showed.
80
+
81
+ ## Requires
82
+
83
+ Nothing in-repo — the peer registry lives at `~/.pi/coms/` and is created at runtime.
84
+
85
+ ## Usage
86
+
87
+ ```bash
88
+ pi -e .pi/harnesses/coms/index.ts
89
+ ```
90
+
91
+ For a guarded coms node, use `just fleet peer <name>`. It loads Fleet Core plus `coms`
92
+ with deterministic extension discovery. Add `--browser` for Chrome DevTools or
93
+ `--all-extensions` when the peer intentionally needs arbitrary project/global extensions;
94
+ those tools stay scoped to that process and never leak into Agent Hub's
95
+ `--no-extensions` specialists.
96
+
97
+ ## Upstream changes
98
+
99
+ - Theme integration removed — the `themeMap.ts` import and the `applyExtensionDefaults()`
100
+ call were stripped (this repo does not ship pi themes).