@chankov/agent-fleet 0.0.1

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 (419) hide show
  1. package/.claude/commands/build.md +44 -0
  2. package/.claude/commands/code-simplify.md +22 -0
  3. package/.claude/commands/design-agent.md +14 -0
  4. package/.claude/commands/doctor-agent-fleet.md +17 -0
  5. package/.claude/commands/orchestrate.md +112 -0
  6. package/.claude/commands/plan.md +16 -0
  7. package/.claude/commands/prime.md +22 -0
  8. package/.claude/commands/review.md +16 -0
  9. package/.claude/commands/setup-agent-fleet.md +25 -0
  10. package/.claude/commands/ship.md +72 -0
  11. package/.claude/commands/spec.md +15 -0
  12. package/.claude/commands/test.md +19 -0
  13. package/.claude/commands/webperf.md +32 -0
  14. package/.claude/orchestrate-teams.yaml +24 -0
  15. package/.opencode/commands/af-build.md +17 -0
  16. package/.opencode/commands/af-code-simplify.md +16 -0
  17. package/.opencode/commands/af-compound.md +16 -0
  18. package/.opencode/commands/af-design-agent.md +15 -0
  19. package/.opencode/commands/af-doctor-agent-fleet.md +15 -0
  20. package/.opencode/commands/af-orchestrate.md +112 -0
  21. package/.opencode/commands/af-plan.md +16 -0
  22. package/.opencode/commands/af-prime.md +22 -0
  23. package/.opencode/commands/af-review.md +15 -0
  24. package/.opencode/commands/af-setup-agent-fleet.md +15 -0
  25. package/.opencode/commands/af-ship.md +16 -0
  26. package/.opencode/commands/af-spec.md +16 -0
  27. package/.opencode/commands/af-test.md +21 -0
  28. package/.opencode/commands/af-webperf.md +32 -0
  29. package/.opencode/orchestrate-teams.yaml +24 -0
  30. package/.pi/agents/dispatch-policy.yaml +32 -0
  31. package/.pi/agents/model-profiles.yaml +20 -0
  32. package/.pi/agents/peers.yaml +142 -0
  33. package/.pi/agents/teams.yaml +39 -0
  34. package/.pi/damage-control-rules.yaml +297 -0
  35. package/.pi/extensions/agent-fleet-update-check/README.md +58 -0
  36. package/.pi/extensions/agent-fleet-update-check/index.ts +161 -0
  37. package/.pi/extensions/agent-fleet-update-check/package.json +6 -0
  38. package/.pi/extensions/btw/README.md +118 -0
  39. package/.pi/extensions/btw/index.ts +917 -0
  40. package/.pi/extensions/btw/package.json +6 -0
  41. package/.pi/extensions/btw/state.js +179 -0
  42. package/.pi/extensions/chrome-devtools-mcp/README.md +58 -0
  43. package/.pi/extensions/chrome-devtools-mcp/index.ts +92 -0
  44. package/.pi/extensions/chrome-devtools-mcp/package.json +6 -0
  45. package/.pi/extensions/compact-and-continue/README.md +42 -0
  46. package/.pi/extensions/compact-and-continue/index.ts +120 -0
  47. package/.pi/extensions/compact-and-continue/package.json +6 -0
  48. package/.pi/extensions/mcp-bridge/README.md +46 -0
  49. package/.pi/extensions/mcp-bridge/index.ts +206 -0
  50. package/.pi/extensions/mcp-bridge/package.json +6 -0
  51. package/.pi/extensions/package-lock.json +1143 -0
  52. package/.pi/extensions/package.json +9 -0
  53. package/.pi/extensions/pi-voice-stt/README.md +201 -0
  54. package/.pi/extensions/pi-voice-stt/config.ts +198 -0
  55. package/.pi/extensions/pi-voice-stt/examples/stt.json +35 -0
  56. package/.pi/extensions/pi-voice-stt/index.ts +248 -0
  57. package/.pi/extensions/pi-voice-stt/package.json +6 -0
  58. package/.pi/extensions/pi-voice-stt/providers.ts +214 -0
  59. package/.pi/extensions/pi-voice-stt/recorder.ts +158 -0
  60. package/.pi/harnesses/agent-hub/README.md +562 -0
  61. package/.pi/harnesses/agent-hub/artifacts.js +92 -0
  62. package/.pi/harnesses/agent-hub/backend-policy.js +153 -0
  63. package/.pi/harnesses/agent-hub/delegate.ts +363 -0
  64. package/.pi/harnesses/agent-hub/evidence-rules.js +96 -0
  65. package/.pi/harnesses/agent-hub/helpers.ts +165 -0
  66. package/.pi/harnesses/agent-hub/index.ts +7098 -0
  67. package/.pi/harnesses/agent-hub/package.json +6 -0
  68. package/.pi/harnesses/agent-hub/return-contract.js +215 -0
  69. package/.pi/harnesses/agent-hub/scope-gate.js +103 -0
  70. package/.pi/harnesses/agent-hub/spawn.ts +179 -0
  71. package/.pi/harnesses/ask-user-remote/README.md +10 -0
  72. package/.pi/harnesses/ask-user-remote/index.ts +253 -0
  73. package/.pi/harnesses/ask-user-remote/race-core.js +106 -0
  74. package/.pi/harnesses/coms/README.md +71 -0
  75. package/.pi/harnesses/coms/index.ts +1743 -0
  76. package/.pi/harnesses/coms/package.json +6 -0
  77. package/.pi/harnesses/damage-control/README.md +65 -0
  78. package/.pi/harnesses/damage-control/index.ts +250 -0
  79. package/.pi/harnesses/damage-control/package.json +6 -0
  80. package/.pi/harnesses/damage-control/shared.ts +183 -0
  81. package/.pi/harnesses/damage-control-continue/README.md +116 -0
  82. package/.pi/harnesses/damage-control-continue/index.ts +522 -0
  83. package/.pi/harnesses/damage-control-continue/package.json +6 -0
  84. package/.pi/harnesses/lib/herdr-client.ts +458 -0
  85. package/.pi/harnesses/lib/herdr-presence.ts +288 -0
  86. package/.pi/harnesses/package-lock.json +35 -0
  87. package/.pi/harnesses/package.json +9 -0
  88. package/.pi/prompts/build.md +24 -0
  89. package/.pi/prompts/code-simplify.md +22 -0
  90. package/.pi/prompts/doctor-agent-fleet.md +15 -0
  91. package/.pi/prompts/plan.md +16 -0
  92. package/.pi/prompts/review.md +16 -0
  93. package/.pi/prompts/setup-agent-fleet.md +27 -0
  94. package/.pi/prompts/ship.md +17 -0
  95. package/.pi/prompts/spec.md +15 -0
  96. package/.pi/prompts/test.md +19 -0
  97. package/.pi/skills/bowser/SKILL.md +145 -0
  98. package/.versions/0.0.1/.claude/commands/build.md +44 -0
  99. package/.versions/0.0.1/.claude/commands/code-simplify.md +22 -0
  100. package/.versions/0.0.1/.claude/commands/design-agent.md +14 -0
  101. package/.versions/0.0.1/.claude/commands/doctor-agent-fleet.md +17 -0
  102. package/.versions/0.0.1/.claude/commands/orchestrate.md +112 -0
  103. package/.versions/0.0.1/.claude/commands/plan.md +16 -0
  104. package/.versions/0.0.1/.claude/commands/prime.md +22 -0
  105. package/.versions/0.0.1/.claude/commands/review.md +16 -0
  106. package/.versions/0.0.1/.claude/commands/setup-agent-fleet.md +25 -0
  107. package/.versions/0.0.1/.claude/commands/ship.md +72 -0
  108. package/.versions/0.0.1/.claude/commands/spec.md +15 -0
  109. package/.versions/0.0.1/.claude/commands/test.md +19 -0
  110. package/.versions/0.0.1/.claude/commands/webperf.md +32 -0
  111. package/.versions/0.0.1/.claude/orchestrate-teams.yaml +24 -0
  112. package/.versions/0.0.1/.opencode/commands/af-build.md +17 -0
  113. package/.versions/0.0.1/.opencode/commands/af-code-simplify.md +16 -0
  114. package/.versions/0.0.1/.opencode/commands/af-compound.md +16 -0
  115. package/.versions/0.0.1/.opencode/commands/af-design-agent.md +15 -0
  116. package/.versions/0.0.1/.opencode/commands/af-doctor-agent-fleet.md +15 -0
  117. package/.versions/0.0.1/.opencode/commands/af-orchestrate.md +112 -0
  118. package/.versions/0.0.1/.opencode/commands/af-plan.md +16 -0
  119. package/.versions/0.0.1/.opencode/commands/af-prime.md +22 -0
  120. package/.versions/0.0.1/.opencode/commands/af-review.md +15 -0
  121. package/.versions/0.0.1/.opencode/commands/af-setup-agent-fleet.md +15 -0
  122. package/.versions/0.0.1/.opencode/commands/af-ship.md +16 -0
  123. package/.versions/0.0.1/.opencode/commands/af-spec.md +16 -0
  124. package/.versions/0.0.1/.opencode/commands/af-test.md +21 -0
  125. package/.versions/0.0.1/.opencode/commands/af-webperf.md +32 -0
  126. package/.versions/0.0.1/.opencode/orchestrate-teams.yaml +24 -0
  127. package/.versions/0.0.1/.pi/agents/dispatch-policy.yaml +32 -0
  128. package/.versions/0.0.1/.pi/agents/model-profiles.yaml +20 -0
  129. package/.versions/0.0.1/.pi/agents/peers.yaml +142 -0
  130. package/.versions/0.0.1/.pi/agents/teams.yaml +39 -0
  131. package/.versions/0.0.1/.pi/damage-control-rules.yaml +297 -0
  132. package/.versions/0.0.1/.pi/extensions/agent-fleet-update-check/README.md +58 -0
  133. package/.versions/0.0.1/.pi/extensions/agent-fleet-update-check/index.ts +161 -0
  134. package/.versions/0.0.1/.pi/extensions/agent-fleet-update-check/package.json +6 -0
  135. package/.versions/0.0.1/.pi/extensions/btw/README.md +118 -0
  136. package/.versions/0.0.1/.pi/extensions/btw/index.ts +917 -0
  137. package/.versions/0.0.1/.pi/extensions/btw/package.json +6 -0
  138. package/.versions/0.0.1/.pi/extensions/btw/state.js +179 -0
  139. package/.versions/0.0.1/.pi/extensions/chrome-devtools-mcp/README.md +58 -0
  140. package/.versions/0.0.1/.pi/extensions/chrome-devtools-mcp/index.ts +92 -0
  141. package/.versions/0.0.1/.pi/extensions/chrome-devtools-mcp/package.json +6 -0
  142. package/.versions/0.0.1/.pi/extensions/compact-and-continue/README.md +42 -0
  143. package/.versions/0.0.1/.pi/extensions/compact-and-continue/index.ts +120 -0
  144. package/.versions/0.0.1/.pi/extensions/compact-and-continue/package.json +6 -0
  145. package/.versions/0.0.1/.pi/extensions/mcp-bridge/README.md +46 -0
  146. package/.versions/0.0.1/.pi/extensions/mcp-bridge/index.ts +206 -0
  147. package/.versions/0.0.1/.pi/extensions/mcp-bridge/package.json +6 -0
  148. package/.versions/0.0.1/.pi/extensions/package-lock.json +1143 -0
  149. package/.versions/0.0.1/.pi/extensions/package.json +9 -0
  150. package/.versions/0.0.1/.pi/extensions/pi-voice-stt/README.md +201 -0
  151. package/.versions/0.0.1/.pi/extensions/pi-voice-stt/config.ts +198 -0
  152. package/.versions/0.0.1/.pi/extensions/pi-voice-stt/examples/stt.json +35 -0
  153. package/.versions/0.0.1/.pi/extensions/pi-voice-stt/index.ts +248 -0
  154. package/.versions/0.0.1/.pi/extensions/pi-voice-stt/package.json +6 -0
  155. package/.versions/0.0.1/.pi/extensions/pi-voice-stt/providers.ts +214 -0
  156. package/.versions/0.0.1/.pi/extensions/pi-voice-stt/recorder.ts +158 -0
  157. package/.versions/0.0.1/.pi/harnesses/agent-hub/README.md +562 -0
  158. package/.versions/0.0.1/.pi/harnesses/agent-hub/artifacts.js +92 -0
  159. package/.versions/0.0.1/.pi/harnesses/agent-hub/backend-policy.js +153 -0
  160. package/.versions/0.0.1/.pi/harnesses/agent-hub/delegate.ts +363 -0
  161. package/.versions/0.0.1/.pi/harnesses/agent-hub/evidence-rules.js +96 -0
  162. package/.versions/0.0.1/.pi/harnesses/agent-hub/helpers.ts +165 -0
  163. package/.versions/0.0.1/.pi/harnesses/agent-hub/index.ts +7098 -0
  164. package/.versions/0.0.1/.pi/harnesses/agent-hub/package.json +6 -0
  165. package/.versions/0.0.1/.pi/harnesses/agent-hub/return-contract.js +215 -0
  166. package/.versions/0.0.1/.pi/harnesses/agent-hub/scope-gate.js +103 -0
  167. package/.versions/0.0.1/.pi/harnesses/agent-hub/spawn.ts +179 -0
  168. package/.versions/0.0.1/.pi/harnesses/ask-user-remote/README.md +10 -0
  169. package/.versions/0.0.1/.pi/harnesses/ask-user-remote/index.ts +253 -0
  170. package/.versions/0.0.1/.pi/harnesses/ask-user-remote/race-core.js +106 -0
  171. package/.versions/0.0.1/.pi/harnesses/coms/README.md +71 -0
  172. package/.versions/0.0.1/.pi/harnesses/coms/index.ts +1743 -0
  173. package/.versions/0.0.1/.pi/harnesses/coms/package.json +6 -0
  174. package/.versions/0.0.1/.pi/harnesses/damage-control/README.md +65 -0
  175. package/.versions/0.0.1/.pi/harnesses/damage-control/index.ts +250 -0
  176. package/.versions/0.0.1/.pi/harnesses/damage-control/package.json +6 -0
  177. package/.versions/0.0.1/.pi/harnesses/damage-control/shared.ts +183 -0
  178. package/.versions/0.0.1/.pi/harnesses/damage-control-continue/README.md +116 -0
  179. package/.versions/0.0.1/.pi/harnesses/damage-control-continue/index.ts +522 -0
  180. package/.versions/0.0.1/.pi/harnesses/damage-control-continue/package.json +6 -0
  181. package/.versions/0.0.1/.pi/harnesses/lib/herdr-client.ts +458 -0
  182. package/.versions/0.0.1/.pi/harnesses/lib/herdr-presence.ts +288 -0
  183. package/.versions/0.0.1/.pi/harnesses/package-lock.json +35 -0
  184. package/.versions/0.0.1/.pi/harnesses/package.json +9 -0
  185. package/.versions/0.0.1/.pi/prompts/build.md +24 -0
  186. package/.versions/0.0.1/.pi/prompts/code-simplify.md +22 -0
  187. package/.versions/0.0.1/.pi/prompts/doctor-agent-fleet.md +15 -0
  188. package/.versions/0.0.1/.pi/prompts/plan.md +16 -0
  189. package/.versions/0.0.1/.pi/prompts/review.md +16 -0
  190. package/.versions/0.0.1/.pi/prompts/setup-agent-fleet.md +27 -0
  191. package/.versions/0.0.1/.pi/prompts/ship.md +17 -0
  192. package/.versions/0.0.1/.pi/prompts/spec.md +15 -0
  193. package/.versions/0.0.1/.pi/prompts/test.md +19 -0
  194. package/.versions/0.0.1/.pi/skills/bowser/SKILL.md +145 -0
  195. package/.versions/0.0.1/.version +1 -0
  196. package/.versions/0.0.1/agents/architect.md +21 -0
  197. package/.versions/0.0.1/agents/bowser.md +25 -0
  198. package/.versions/0.0.1/agents/builder.md +52 -0
  199. package/.versions/0.0.1/agents/code-reviewer.md +205 -0
  200. package/.versions/0.0.1/agents/deep-researcher.md +31 -0
  201. package/.versions/0.0.1/agents/documenter.md +16 -0
  202. package/.versions/0.0.1/agents/orchestrator.md +43 -0
  203. package/.versions/0.0.1/agents/plan-reviewer.md +60 -0
  204. package/.versions/0.0.1/agents/planner.md +69 -0
  205. package/.versions/0.0.1/agents/releaser.md +22 -0
  206. package/.versions/0.0.1/agents/researcher.md +28 -0
  207. package/.versions/0.0.1/agents/security-auditor.md +166 -0
  208. package/.versions/0.0.1/agents/test-engineer.md +144 -0
  209. package/.versions/0.0.1/agents/web-debugger.md +42 -0
  210. package/.versions/0.0.1/agents/web-performance-auditor.md +192 -0
  211. package/.versions/0.0.1/hooks/SIMPLIFY-IGNORE.md +90 -0
  212. package/.versions/0.0.1/hooks/coms-stop-hook.mjs +73 -0
  213. package/.versions/0.0.1/hooks/hooks.json +14 -0
  214. package/.versions/0.0.1/hooks/session-start.sh +74 -0
  215. package/.versions/0.0.1/hooks/simplify-ignore.sh +302 -0
  216. package/.versions/0.0.1/justfile +143 -0
  217. package/.versions/0.0.1/references/accessibility-checklist.md +160 -0
  218. package/.versions/0.0.1/references/definition-of-done.md +67 -0
  219. package/.versions/0.0.1/references/fleet-coordination-patterns.md +151 -0
  220. package/.versions/0.0.1/references/observability-checklist.md +91 -0
  221. package/.versions/0.0.1/references/orchestration-patterns.md +370 -0
  222. package/.versions/0.0.1/references/performance-checklist.md +153 -0
  223. package/.versions/0.0.1/references/prompting-patterns.md +380 -0
  224. package/.versions/0.0.1/references/security-checklist.md +179 -0
  225. package/.versions/0.0.1/references/testing-patterns.md +236 -0
  226. package/.versions/0.0.1/scripts/coms-claude-bridge.ts +286 -0
  227. package/.versions/0.0.1/scripts/coms-cli.ts +372 -0
  228. package/.versions/0.0.1/scripts/coms-hermes-bridge.ts +399 -0
  229. package/.versions/0.0.1/scripts/lib/claude-bridge-core.ts +100 -0
  230. package/.versions/0.0.1/scripts/lib/coms-envelope.ts +494 -0
  231. package/.versions/0.0.1/scripts/lib/herdr-layout.ts +235 -0
  232. package/.versions/0.0.1/scripts/lib/hermes-bridge-core.ts +238 -0
  233. package/.versions/0.0.1/scripts/lib/persona-banner.ts +62 -0
  234. package/.versions/0.0.1/scripts/lib/team-project.ts +75 -0
  235. package/.versions/0.0.1/scripts/lib/team-snapshot.ts +146 -0
  236. package/.versions/0.0.1/scripts/peer-banner.ts +40 -0
  237. package/.versions/0.0.1/scripts/team-snapshot.ts +221 -0
  238. package/.versions/0.0.1/scripts/team-up.ts +245 -0
  239. package/.versions/0.0.1/skills/_internal/grilling.md +11 -0
  240. package/.versions/0.0.1/skills/browser-testing-with-devtools/SKILL.md +352 -0
  241. package/.versions/0.0.1/skills/code-review-and-quality/SKILL.md +381 -0
  242. package/.versions/0.0.1/skills/compound-learning/SKILL.md +137 -0
  243. package/.versions/0.0.1/skills/context-engineering/SKILL.md +291 -0
  244. package/.versions/0.0.1/skills/deprecation-and-migration/SKILL.md +206 -0
  245. package/.versions/0.0.1/skills/designing-agents/SKILL.md +394 -0
  246. package/.versions/0.0.1/skills/designing-agents/pi-harness-authoring.md +209 -0
  247. package/.versions/0.0.1/skills/frontend-ui-engineering/SKILL.md +328 -0
  248. package/.versions/0.0.1/skills/git-workflow-and-versioning/SKILL.md +316 -0
  249. package/.versions/0.0.1/skills/guided-workspace-setup/SKILL.md +506 -0
  250. package/.versions/0.0.1/skills/idea-refine/SKILL.md +182 -0
  251. package/.versions/0.0.1/skills/idea-refine/examples.md +238 -0
  252. package/.versions/0.0.1/skills/idea-refine/frameworks.md +99 -0
  253. package/.versions/0.0.1/skills/idea-refine/refinement-criteria.md +113 -0
  254. package/.versions/0.0.1/skills/idea-refine/scripts/idea-refine.sh +15 -0
  255. package/.versions/0.0.1/skills/incremental-implementation/SKILL.md +287 -0
  256. package/.versions/0.0.1/skills/interview-me/SKILL.md +226 -0
  257. package/.versions/0.0.1/skills/orchestration-verification/SKILL.md +181 -0
  258. package/.versions/0.0.1/skills/peer-coms/SKILL.md +81 -0
  259. package/.versions/0.0.1/skills/performance-optimization/SKILL.md +350 -0
  260. package/.versions/0.0.1/skills/planning-and-task-breakdown/SKILL.md +236 -0
  261. package/.versions/0.0.1/skills/security-and-hardening/SKILL.md +461 -0
  262. package/.versions/0.0.1/skills/spec-driven-development/SKILL.md +245 -0
  263. package/.versions/0.0.1/skills/using-agent-skills/SKILL.md +199 -0
  264. package/.versions/0.0.1/vendor/agent-skills-upstream/LICENSE +21 -0
  265. package/.versions/0.0.1/vendor/agent-skills-upstream/README.md +11 -0
  266. package/.versions/0.0.1/vendor/agent-skills-upstream/skills/api-and-interface-design/SKILL.md +294 -0
  267. package/.versions/0.0.1/vendor/agent-skills-upstream/skills/browser-testing-with-devtools/SKILL.md +317 -0
  268. package/.versions/0.0.1/vendor/agent-skills-upstream/skills/ci-cd-and-automation/SKILL.md +390 -0
  269. package/.versions/0.0.1/vendor/agent-skills-upstream/skills/code-review-and-quality/SKILL.md +396 -0
  270. package/.versions/0.0.1/vendor/agent-skills-upstream/skills/code-simplification/SKILL.md +331 -0
  271. package/.versions/0.0.1/vendor/agent-skills-upstream/skills/context-engineering/SKILL.md +289 -0
  272. package/.versions/0.0.1/vendor/agent-skills-upstream/skills/debugging-and-error-recovery/SKILL.md +300 -0
  273. package/.versions/0.0.1/vendor/agent-skills-upstream/skills/deprecation-and-migration/SKILL.md +247 -0
  274. package/.versions/0.0.1/vendor/agent-skills-upstream/skills/documentation-and-adrs/SKILL.md +278 -0
  275. package/.versions/0.0.1/vendor/agent-skills-upstream/skills/doubt-driven-development/SKILL.md +243 -0
  276. package/.versions/0.0.1/vendor/agent-skills-upstream/skills/frontend-ui-engineering/SKILL.md +328 -0
  277. package/.versions/0.0.1/vendor/agent-skills-upstream/skills/git-workflow-and-versioning/SKILL.md +355 -0
  278. package/.versions/0.0.1/vendor/agent-skills-upstream/skills/idea-refine/SKILL.md +178 -0
  279. package/.versions/0.0.1/vendor/agent-skills-upstream/skills/idea-refine/examples.md +238 -0
  280. package/.versions/0.0.1/vendor/agent-skills-upstream/skills/idea-refine/frameworks.md +99 -0
  281. package/.versions/0.0.1/vendor/agent-skills-upstream/skills/idea-refine/refinement-criteria.md +113 -0
  282. package/.versions/0.0.1/vendor/agent-skills-upstream/skills/idea-refine/scripts/idea-refine.sh +15 -0
  283. package/.versions/0.0.1/vendor/agent-skills-upstream/skills/incremental-implementation/SKILL.md +249 -0
  284. package/.versions/0.0.1/vendor/agent-skills-upstream/skills/interview-me/SKILL.md +225 -0
  285. package/.versions/0.0.1/vendor/agent-skills-upstream/skills/observability-and-instrumentation/SKILL.md +203 -0
  286. package/.versions/0.0.1/vendor/agent-skills-upstream/skills/performance-optimization/SKILL.md +350 -0
  287. package/.versions/0.0.1/vendor/agent-skills-upstream/skills/planning-and-task-breakdown/SKILL.md +234 -0
  288. package/.versions/0.0.1/vendor/agent-skills-upstream/skills/security-and-hardening/SKILL.md +467 -0
  289. package/.versions/0.0.1/vendor/agent-skills-upstream/skills/shipping-and-launch/SKILL.md +310 -0
  290. package/.versions/0.0.1/vendor/agent-skills-upstream/skills/source-driven-development/SKILL.md +194 -0
  291. package/.versions/0.0.1/vendor/agent-skills-upstream/skills/spec-driven-development/SKILL.md +206 -0
  292. package/.versions/0.0.1/vendor/agent-skills-upstream/skills/test-driven-development/SKILL.md +383 -0
  293. package/.versions/0.0.1/vendor/agent-skills-upstream/skills/using-agent-skills/SKILL.md +191 -0
  294. package/CHANGELOG.md +65 -0
  295. package/LICENSE +21 -0
  296. package/README.md +458 -0
  297. package/agents/architect.md +21 -0
  298. package/agents/bowser.md +25 -0
  299. package/agents/builder.md +52 -0
  300. package/agents/code-reviewer.md +205 -0
  301. package/agents/deep-researcher.md +31 -0
  302. package/agents/documenter.md +16 -0
  303. package/agents/orchestrator.md +43 -0
  304. package/agents/plan-reviewer.md +60 -0
  305. package/agents/planner.md +69 -0
  306. package/agents/releaser.md +22 -0
  307. package/agents/researcher.md +28 -0
  308. package/agents/security-auditor.md +166 -0
  309. package/agents/test-engineer.md +144 -0
  310. package/agents/web-debugger.md +42 -0
  311. package/agents/web-performance-auditor.md +192 -0
  312. package/bin/cli.js +633 -0
  313. package/bin/force-patch-changesets.js +44 -0
  314. package/bin/lib/bootstrap.js +323 -0
  315. package/bin/lib/detect-agent.js +49 -0
  316. package/bin/lib/doctor.js +302 -0
  317. package/bin/lib/transform-persona.js +180 -0
  318. package/bin/lib/update-notifier.js +195 -0
  319. package/bin/lib/validate-overrides.js +229 -0
  320. package/bin/snapshot-version.js +91 -0
  321. package/docs/agent-fleet-setup.md +355 -0
  322. package/docs/claude-code-coms-bridge.md +93 -0
  323. package/docs/getting-started.md +169 -0
  324. package/docs/npm-install.md +335 -0
  325. package/docs/opencode-setup.md +248 -0
  326. package/docs/pi-extensions.md +237 -0
  327. package/docs/pi-setup.md +455 -0
  328. package/docs/skill-anatomy.md +150 -0
  329. package/hooks/SIMPLIFY-IGNORE.md +90 -0
  330. package/hooks/coms-stop-hook.mjs +73 -0
  331. package/hooks/hooks.json +14 -0
  332. package/hooks/session-start.sh +74 -0
  333. package/hooks/simplify-ignore.sh +302 -0
  334. package/justfile +143 -0
  335. package/node_modules/pi-ask-user/LICENSE +21 -0
  336. package/node_modules/pi-ask-user/README.md +156 -0
  337. package/node_modules/pi-ask-user/index.ts +1795 -0
  338. package/node_modules/pi-ask-user/package.json +51 -0
  339. package/node_modules/pi-ask-user/single-select-layout.ts +203 -0
  340. package/node_modules/pi-ask-user/skills/ask-user/SKILL.md +162 -0
  341. package/node_modules/pi-ask-user/skills/ask-user/references/ask-user-skill-extension-spec.md +96 -0
  342. package/package.json +121 -0
  343. package/references/accessibility-checklist.md +160 -0
  344. package/references/definition-of-done.md +67 -0
  345. package/references/fleet-coordination-patterns.md +151 -0
  346. package/references/observability-checklist.md +91 -0
  347. package/references/orchestration-patterns.md +370 -0
  348. package/references/performance-checklist.md +153 -0
  349. package/references/prompting-patterns.md +380 -0
  350. package/references/security-checklist.md +179 -0
  351. package/references/testing-patterns.md +236 -0
  352. package/scripts/coms-claude-bridge.ts +286 -0
  353. package/scripts/coms-cli.ts +372 -0
  354. package/scripts/coms-hermes-bridge.ts +399 -0
  355. package/scripts/lib/claude-bridge-core.ts +100 -0
  356. package/scripts/lib/coms-envelope.ts +494 -0
  357. package/scripts/lib/herdr-layout.ts +235 -0
  358. package/scripts/lib/hermes-bridge-core.ts +238 -0
  359. package/scripts/lib/persona-banner.ts +62 -0
  360. package/scripts/lib/team-project.ts +75 -0
  361. package/scripts/lib/team-snapshot.ts +146 -0
  362. package/scripts/peer-banner.ts +40 -0
  363. package/scripts/team-snapshot.ts +221 -0
  364. package/scripts/team-up.ts +245 -0
  365. package/skills/_internal/grilling.md +11 -0
  366. package/skills/browser-testing-with-devtools/SKILL.md +352 -0
  367. package/skills/code-review-and-quality/SKILL.md +381 -0
  368. package/skills/compound-learning/SKILL.md +137 -0
  369. package/skills/context-engineering/SKILL.md +291 -0
  370. package/skills/deprecation-and-migration/SKILL.md +206 -0
  371. package/skills/designing-agents/SKILL.md +394 -0
  372. package/skills/designing-agents/pi-harness-authoring.md +209 -0
  373. package/skills/frontend-ui-engineering/SKILL.md +328 -0
  374. package/skills/git-workflow-and-versioning/SKILL.md +316 -0
  375. package/skills/guided-workspace-setup/SKILL.md +506 -0
  376. package/skills/idea-refine/SKILL.md +182 -0
  377. package/skills/idea-refine/examples.md +238 -0
  378. package/skills/idea-refine/frameworks.md +99 -0
  379. package/skills/idea-refine/refinement-criteria.md +113 -0
  380. package/skills/idea-refine/scripts/idea-refine.sh +15 -0
  381. package/skills/incremental-implementation/SKILL.md +287 -0
  382. package/skills/interview-me/SKILL.md +226 -0
  383. package/skills/orchestration-verification/SKILL.md +181 -0
  384. package/skills/peer-coms/SKILL.md +81 -0
  385. package/skills/performance-optimization/SKILL.md +350 -0
  386. package/skills/planning-and-task-breakdown/SKILL.md +236 -0
  387. package/skills/security-and-hardening/SKILL.md +461 -0
  388. package/skills/spec-driven-development/SKILL.md +245 -0
  389. package/skills/using-agent-skills/SKILL.md +199 -0
  390. package/vendor/agent-skills-upstream/LICENSE +21 -0
  391. package/vendor/agent-skills-upstream/README.md +11 -0
  392. package/vendor/agent-skills-upstream/skills/api-and-interface-design/SKILL.md +294 -0
  393. package/vendor/agent-skills-upstream/skills/browser-testing-with-devtools/SKILL.md +317 -0
  394. package/vendor/agent-skills-upstream/skills/ci-cd-and-automation/SKILL.md +390 -0
  395. package/vendor/agent-skills-upstream/skills/code-review-and-quality/SKILL.md +396 -0
  396. package/vendor/agent-skills-upstream/skills/code-simplification/SKILL.md +331 -0
  397. package/vendor/agent-skills-upstream/skills/context-engineering/SKILL.md +289 -0
  398. package/vendor/agent-skills-upstream/skills/debugging-and-error-recovery/SKILL.md +300 -0
  399. package/vendor/agent-skills-upstream/skills/deprecation-and-migration/SKILL.md +247 -0
  400. package/vendor/agent-skills-upstream/skills/documentation-and-adrs/SKILL.md +278 -0
  401. package/vendor/agent-skills-upstream/skills/doubt-driven-development/SKILL.md +243 -0
  402. package/vendor/agent-skills-upstream/skills/frontend-ui-engineering/SKILL.md +328 -0
  403. package/vendor/agent-skills-upstream/skills/git-workflow-and-versioning/SKILL.md +355 -0
  404. package/vendor/agent-skills-upstream/skills/idea-refine/SKILL.md +178 -0
  405. package/vendor/agent-skills-upstream/skills/idea-refine/examples.md +238 -0
  406. package/vendor/agent-skills-upstream/skills/idea-refine/frameworks.md +99 -0
  407. package/vendor/agent-skills-upstream/skills/idea-refine/refinement-criteria.md +113 -0
  408. package/vendor/agent-skills-upstream/skills/idea-refine/scripts/idea-refine.sh +15 -0
  409. package/vendor/agent-skills-upstream/skills/incremental-implementation/SKILL.md +249 -0
  410. package/vendor/agent-skills-upstream/skills/interview-me/SKILL.md +225 -0
  411. package/vendor/agent-skills-upstream/skills/observability-and-instrumentation/SKILL.md +203 -0
  412. package/vendor/agent-skills-upstream/skills/performance-optimization/SKILL.md +350 -0
  413. package/vendor/agent-skills-upstream/skills/planning-and-task-breakdown/SKILL.md +234 -0
  414. package/vendor/agent-skills-upstream/skills/security-and-hardening/SKILL.md +467 -0
  415. package/vendor/agent-skills-upstream/skills/shipping-and-launch/SKILL.md +310 -0
  416. package/vendor/agent-skills-upstream/skills/source-driven-development/SKILL.md +194 -0
  417. package/vendor/agent-skills-upstream/skills/spec-driven-development/SKILL.md +206 -0
  418. package/vendor/agent-skills-upstream/skills/test-driven-development/SKILL.md +383 -0
  419. package/vendor/agent-skills-upstream/skills/using-agent-skills/SKILL.md +191 -0
@@ -0,0 +1,562 @@
1
+ # agent-hub
2
+
3
+ A multi-agent dispatcher with [`coms`](../coms/README.md) **embedded** — so the dispatcher is
4
+ *also* a peer-to-peer node. The bundled `just hub` recipes load
5
+ [`damage-control-continue`](../damage-control-continue/README.md) first, then
6
+ [`ask-user-remote`](../ask-user-remote/README.md), so the dispatcher has guardrails and an
7
+ `ask_user` handoff tool before `agent-hub` starts. It combines local specialist
8
+ orchestration (fixed specialist grid, read-only research helpers, `/zoom`, kill/restart, per-agent
9
+ model, dispatcher persona gate) with peer-to-peer collaboration: it can **hand a session off to
10
+ another main agent** and **use a coms peer as a subagent**.
11
+
12
+ > Consolidates the retired `agent-team` dispatcher into this harness and embeds the ported `coms`
13
+ > P2P layer from [`pi-vs-claude-code`](https://github.com/disler/pi-vs-claude-code) by
14
+ > [disler](https://github.com/disler) (MIT). See the
15
+ > [extension catalog](../../../docs/pi-extensions.md) and the
16
+ > [design plan](../../../docs/plans/agent-hub-multi-agent-harness.md).
17
+
18
+ ## What it does
19
+
20
+ `agent-hub` is the supported home for the former standalone dispatcher features:
21
+
22
+ - **Dispatcher grid** — a live dashboard of fixed specialists from `.pi/agents/teams.yaml`.
23
+ - **Specialist delegation** — `dispatch_agent` sends writable tasks to configured specialists.
24
+ - **Research helpers** — `spawn_research` and `/research` launch read-only helper agents. Two
25
+ `kind: research` personas ship by default: `researcher` (fast `gpt-5.3-codex-spark`) for simple
26
+ reads and `deep-researcher` (`gpt-5.5` / xhigh) for hard, cross-cutting investigation. The
27
+ orchestrator routes by persona; each persona's model + thinking level is shown in its catalog.
28
+ - **Human handoff path** — `ask_user` is exposed by the `ask-user-remote` wrapper (capturing stock
29
+ `pi-ask-user` and optionally racing a `user-remote` bridge), so specialists can bubble decisions
30
+ back through the dispatcher.
31
+ - **Auto-research pipe (`NEEDS_RESEARCH:`)** — a specialist that lacks information pauses by ending
32
+ its turn with `NEEDS_RESEARCH: <question>` lines (mirror of the `ASK_USER:` protocol). The hub
33
+ intercepts them **in code**: it fans out read-only research helpers (max 4 questions per pause,
34
+ 2 pauses per dispatch), writes each helper's findings to `.pi/agent-sessions/findings/*.md`, and
35
+ resumes the specialist's session with the file paths. The dispatcher LLM sees only a one-line
36
+ notice — raw findings never enter its context. Findings files are wiped at session start.
37
+ - **Verification Contract (assertion ledger)** — the dispatcher owns a ledger of checkable
38
+ acceptance assertions built from the request *before* any builder runs, so a clearly stated
39
+ requirement is never silently dropped. `set_assertions` records the numbered, tagged assertions
40
+ (`test` | `runtime-ui` | `code-grep` | `manual`, one pass condition each) and rebuilds the whole
41
+ ledger on a "wrong again" regression reset; `update_assertion` marks each one proven (named
42
+ evidence required), unproven, or failed after a verification gate; `get_assertions` reads the
43
+ full ledger (ids, tags, pass conditions, evidence) back. The hub persists the ledger to
44
+ `.pi/agent-sessions/assertions.json` (wiped at session start like `findings/`) and renders a
45
+ one-line status (`Assertions: 2✓ 1○ 1✗ · open: A4`) so the contract survives compaction without
46
+ re-flooding the dispatcher LLM context — after a compaction the dispatcher calls `get_assertions`
47
+ to recover the full text the status line omits. The `orchestrator` persona drives it — a deep-researcher
48
+ parity inventory for "behave like" requests, runtime proof for UI/visibility assertions, the
49
+ regression reset on a re-ask — per
50
+ [`orchestration-verification`](../../../skills/orchestration-verification/SKILL.md). The hub also
51
+ machine-parses each assertion-carrying specialist's structured return, writes the full raw output
52
+ to `.pi/agent-sessions/artifacts/returns/<agentKey>-run<N>.md`, surfaces only a compact
53
+ `details.structuredReturn` digest plus `details.returnPath`, and marks contract notices such as
54
+ missing assertion ids or evidence-less `assertions_proven` entries (demoted to unproven in the
55
+ tool text). `details.fullOutput` remains for `/zoom`/compatibility, but dispatcher-visible text is
56
+ digest + path oriented. `update_assertion(status: "proven")` validates evidence by assertion tag:
57
+ test evidence needs a command/test and outcome, `code-grep` needs pattern plus result sample,
58
+ manual needs user/`ask_user` confirmation, and `runtime-ui` needs an existing artifact path under
59
+ `.pi/agent-sessions/artifacts/evidence/`. **Advisory by design** (PRD open question 2): status is
60
+ surfaced and "proven" requires named evidence, but a dispatch is never hard-refused on an unproven
61
+ assertion — code-enforcement is the Checkpoint A decision.
62
+ - **Artifact bus** — session handoffs live under `.pi/agent-sessions/artifacts/` with conventional
63
+ `returns/`, `plans/`, `reviews/`, `inventories/`, and `evidence/` subdirectories, all wiped and
64
+ recreated at session start like `findings/`. `dispatch_agent` and `spawn_research` accept optional
65
+ `artifacts: string[]` paths (repo-relative or session-artifact-relative); the hub validates that
66
+ they stay inside the repo/session roots and injects only the path plus first heading/one-line
67
+ preview, never file bodies. Document-producing specialists are instructed to write plans, reviews,
68
+ inventories, and reports to the real session path
69
+ `.pi/agent-sessions/artifacts/<kind>/<agentKey>-run<N>.md` when their tools allow it, then report/pass
70
+ the artifact-relative handoff path `artifacts/<kind>/<agentKey>-run<N>.md`, finish with that path plus
71
+ a ≤10-line digest, and still include structured returns when assertions are carried. Repo-root
72
+ `./artifacts/...` files are not session artifacts. Planner's existing PLAN_FILE behavior is preserved;
73
+ the artifact path is an additional handoff channel.
74
+ - **Dispatch scope advisory** — `dispatch_agent` accepts optional `scope: string[]` for writable
75
+ builder-style runs. The orchestrator should derive these globs from the plan task's file list,
76
+ and skip scope for exploratory/reconnaissance work where the right files are not known yet. The
77
+ hub snapshots git status before the writable dispatch, diffs after the whole tool call (including
78
+ auto-research resumes), and reports out-of-scope paths in `details.scopeViolations` plus a ⚠ text
79
+ notice. This is advisory only: the hub never blocks completion, reverts files, or escalates
80
+ automatically. Known limitation: concurrent writable dispatches can only be attributed
81
+ approximately, so overlapping runs are flagged in the notice.
82
+ - **Agent controls** — `/zoom` inspects a live agent timeline; `/agents-history` replays the run as a
83
+ timeline (orchestrator turns, dispatches, research helpers) with per-agent durations, parallel-run
84
+ markers, and a grand total; kill/restart controls manage running child agents; per-agent `model:`
85
+ fields select models from team config. Restartable team specialists at or above 70% context render
86
+ their context percentage with a warning marker/color in dashboard and compact views, and their next
87
+ `dispatch_agent` result adds a `/agents-restart <persona>` hint. Research helpers are not warned,
88
+ and the hub never restarts specialists automatically.
89
+ - **Model switching** — a persona's frontmatter `models:` list declares the models it may switch to
90
+ (the default `model:` is implicitly a candidate). `/agent-model <persona>` picks from that list;
91
+ the choice lasts for the session and takes effect on the persona's next dispatch
92
+ (`/agents-restart <persona>` applies it immediately). The dot form
93
+ `/agent-model <persona>.<role>` switches a delegate sub-role's model instead — its candidates are
94
+ the role's declared default plus the parent persona's own candidate list; the switch is applied
95
+ when the parent is next dispatched (it lands in the serialized delegate config, so nested
96
+ children inherit it). `/models [profile]` applies a named profile
97
+ from `.pi/agents/model-profiles.yaml` — a macro over the same declared candidates, validated at
98
+ session start (a profile with any entry outside a persona's candidates is dropped whole, with an
99
+ error); profiles never touch sub-role models — only `/agent-model` reaches those. Nothing
100
+ outside the declared lists is ever selectable. Per project,
101
+ `model.<persona>:` / `models.<persona>:` keys under `## agent-hub` in
102
+ `.ai/agent-fleet-overrides.md` replace a persona's default model / candidate list.
103
+ Research personas (`researcher` / `deep-researcher`, `kind: research`) are switchable the same
104
+ way — `/agent-model <persona>` and `/agent-model-thinking <persona>` accept them alongside team
105
+ members. Since research helpers are spawned fresh on each `/research` / `spawn_research`, the
106
+ switch lands on their next spawn (there is no running instance to `/agents-restart`).
107
+ `/agent-models-substitute <source> <target>` is the global one-shot form: walks every loaded
108
+ persona (team + research + orchestrator), and for each whose **current effective model** is
109
+ `<source>` and whose declared candidates include `<target>`, sets the session override to
110
+ `<target>`. One-step flow — the dry-run summary (affected vs skipped, with reasons) is shown
111
+ inline, then the swap is applied immediately and takes effect on each persona's next dispatch
112
+ (`/agents-restart` to apply now). It never touches the dispatcher or delegate sub-roles.
113
+ - **Thinking levels** — each persona's frontmatter `thinking:` sets its pi `--thinking`
114
+ reasoning effort (`off` · `minimal` · `low` · `medium` · `high` · `xhigh`). `/agent-model-thinking
115
+ <persona>` switches it among those six levels for the session; like a model switch it takes effect
116
+ on the persona's next dispatch (`/agents-restart <persona>` applies it now), and selecting the
117
+ frontmatter default clears the override. The level shows as a short badge after the model
118
+ everywhere a model is rendered — `gpt-5.5 (xh)` in the dashboard cards and the compact below-editor
119
+ view (`min`/`low`/`med`/`hi`/`xh`; `off` shows no badge). Per project, a `thinking.<persona>:` key
120
+ under `## agent-hub` in `.ai/agent-fleet-overrides.md` replaces a persona's default level.
121
+ - **Mid-turn delegation (`delegate` tool)** — a persona that declares a `subagents:` map in its
122
+ frontmatter (`role: { model, tools? }` entries, or an indented `model:`/`tools:` block per role)
123
+ gets a real mid-turn `delegate(role, instruction, context?, allow_write?)` tool, injected as an
124
+ extra `-e delegate.ts` extension into its spawned process (the `delegate` tool name is appended to
125
+ its `--tools` allowlist — pi filters extension tools too). Only declared roles are spawnable, on
126
+ their declared models — model choice is configuration, never the child LLM's. Budgets are readable
127
+ refusals: at most 4 delegate children per dispatch, tree-wide, and a per-persona `delegate_depth:`
128
+ budget capped at 1 (the default). Children spawned with remaining depth 0 do not receive the
129
+ `delegate` extension/tool. Write safety: children run read-only (`read,grep,find,ls`) unless a
130
+ SINGLE live child gets `allow_write: true`, which inherits the parent's tools intersected with the
131
+ role's `tools:` cap; if a declared role cap leaves no available tools, delegation is refused.
132
+ Concurrent children are always forced read-only. Children stream timeline events through
133
+ `.pi/agent-sessions/delegations/<persona>/events.jsonl`; the hub tails it and renders nested rows
134
+ under the parent's card (child id, model, tokens, status),
135
+ each openable with `/zoom <child-id>`. Each child also writes its full final output to
136
+ `.pi/agent-sessions/delegations/<persona>/results/<childId>.md`; the parent receives only status,
137
+ a required final `DIGEST:` section (≤30 lines with path:line citations), and the result-file path.
138
+ If a child omits `DIGEST:`, the parent gets the first ~30 lines plus a no-DIGEST warning and the
139
+ result path. Spend rolls up: every child row and the parent's subtree
140
+ total show tokens, and a session-wide `Δ delegated` counter sits in the status line.
141
+ `/agents-kill` on the parent SIGTERMs its whole process group, so the delegation tree dies with
142
+ it. `context: fork` is accepted but treated as a summary brief in v1. Per project,
143
+ `subagents.<persona>.<role>:` and `delegate-depth.<persona>:` keys under `## agent-hub` in
144
+ `.ai/agent-fleet-overrides.md` replace individual sub-roles / the depth budget. Six personas
145
+ ship with declared sub-roles, on a three-tier OpenAI model ladder — `gpt-5.3-codex-spark` for
146
+ recon/grep sweeps, `gpt-5.4` for analysis sweeps, the `gpt-5.5` (or opus) parent reserved for
147
+ synthesis and verdicts:
148
+ - `code-reviewer` — `preflight`+`docs` (spark), `quality`+`perf` (gpt-5.4); its first delegate
149
+ call is always `preflight`, which studies the project rules and the files under review and
150
+ returns a summary that drives the rest of the fan-out. Deep security review is not a
151
+ sub-role — it belongs to the separate `security-auditor` persona, which the reviewer
152
+ recommends dispatching when it spots deeper risk.
153
+ - `planner` — `scout`+`rules` (spark) fan out before the plan is drafted; `risk` (gpt-5.4)
154
+ optionally challenges the draft breakdown.
155
+ - `plan-reviewer` — `feasibility` (gpt-5.4) checks plan claims against the actual codebase;
156
+ `deps` (spark) verifies dependency ordering and file overlap. No preflight — the plan is
157
+ the map.
158
+ - `security-auditor` — solo `recon` (spark) maps the attack surface first, then
159
+ `input-sweep` (gpt-5.4) and `secrets-sweep` (spark) fan out; exploit reasoning stays with
160
+ the parent.
161
+ - `builder` — `recon` (spark) maps call sites before edits; `verifier` (spark, the one
162
+ `allow_write: true` child) runs the test suite after them. Implementation is never
163
+ delegated.
164
+ - `test-engineer` — `coverage-scout`+`conventions` (spark) inventory gaps and test patterns;
165
+ test writing is never delegated.
166
+ - **Dispatcher persona gate** — optional `persona-gate: on` can require an orchestrator persona at
167
+ session start; by default the dispatcher starts without the gate.
168
+ - **Default damage-control guardrails** — `just hub` and `just hub-solo` load the
169
+ `damage-control-continue` harness before `agent-hub`, so dispatcher tool calls are checked against
170
+ `.pi/damage-control-rules.yaml` and a blocked call feeds back instead of aborting the turn. A
171
+ guardrail is also re-loaded into every spawned subagent (see [Safety scope](#safety-scope)):
172
+ research helpers get the same continue variant, other specialists get the hard-stop `damage-control`.
173
+ - **Embedded coms** — the dispatcher is a discoverable peer on the local machine. Multiple
174
+ `agent-hub` (or plain `coms`) sessions on the same box find each other through per-project registry
175
+ files and exchange messages over a unix socket (named pipe on Windows).
176
+
177
+ Inherited `/zoom` behavior in this harness expands the latest event by default. Use `Space` or
178
+ `Ctrl+C` to copy the selected row content, and `Q` or `Esc` to close the overlay. The overlay sizes
179
+ to the terminal and keeps the selected (and last) entry fully visible while you navigate with
180
+ `↑/↓`.
181
+
182
+ ### `/agents-history`
183
+
184
+ `/agents-history` opens a read-only overlay (same chrome as `/zoom`) that replays the session as an
185
+ execution **tree**:
186
+
187
+ - **Orchestrator turns** — each dispatcher turn that actually dispatched something is a depth-0 row
188
+ labelled `(dispatcher)`. Chat-only turns add no rows.
189
+ - **Dispatched specialists and research helpers** nest one level beneath the turn that launched them;
190
+ **delegate sub-sub-agents** nest one level deeper still under the specialist that spawned them — in
191
+ start order at every level.
192
+ - **Parallel runs** — siblings whose run times overlap are marked with a `│→` connector, so a
193
+ concurrent fan-out reads as a visually grouped block.
194
+ - **Real-work durations** — each row shows that node's *own* work: its span **minus the time it spent
195
+ awaiting children**. A dispatcher blocked on six concurrent agents is credited only for the time it
196
+ actually worked between/around the awaits, never for the await itself — so the same wall-clock isn't
197
+ counted twice up the tree. The same subtraction applies to a specialist awaiting its own delegate
198
+ children. Format: plain seconds under a minute (`42sec`), `m:ss` above it (`10:20min` for 620s).
199
+ Running rows tick live (the overlay re-renders once a second) and a new dispatch appears the instant
200
+ it starts.
201
+ - **Footer** shows `Σ real work <total> · <n> runs (agents <a> + dispatchers <d>)` — the real work of
202
+ *everyone*: the dispatched specialists' and research helpers' full runtime (`agents`) plus each
203
+ dispatcher turn's own work (`dispatchers` — its span minus the time it awaited agents **and** the
204
+ human via `ask_user`). Wall-clock is deliberately **not** shown: it would fold in the idle gaps
205
+ while you're away between turns, and `ask_user` waits are subtracted for the same reason.
206
+
207
+ Navigate with `↑/↓`, press `G` to jump back to the live tail, and `Q`/`Esc` to close. The log resets
208
+ on each session start.
209
+
210
+ Press **`Alt+A`** to toggle the agent view between the full **dashboard** (bordered card grid drawn
211
+ *above* the input box) and a **compact** view that shows one line per *running* agent —
212
+ `name · context% · state` — rendered *below* the input box, just above pi's status bar. Idle and
213
+ done agents are hidden in compact mode, and the coms pool widget collapses too, so an idle session
214
+ collapses to just the prompt and footer. The current mode and binding are shown in the footer
215
+ (`Alt+A view:dashboard` / `Alt+A view:compact`).
216
+
217
+ ### Voice dictation indicator
218
+
219
+ The custom footer renders the optional [`pi-voice-stt`](../../extensions/pi-voice-stt/README.md)
220
+ extension's recording indicator on a line **below the model line** — e.g.
221
+ `● REC 0:01 ⏎ send · esc cancel` while recording, or a `transcribing…` dot. Because agent-hub
222
+ replaces pi's built-in footer (where that indicator normally lives), it reads the extension's
223
+ `setStatus("voice-stt", …)` value via the footer data provider and surfaces it itself. The
224
+ indicator only appears once `pi-voice-stt` is installed and configured; otherwise the footer is
225
+ the single model line. Press **`Alt+S`** to start/stop dictation as in a normal pi session.
226
+
227
+ ### Compact-view agent switcher
228
+
229
+ In **compact view**, the running-subagents list below the input doubles as a switcher. **`Alt+]`**
230
+ and **`Alt+[`** move a marker (`›` + highlight) to the next/previous running subagent; **`Alt+\`**
231
+ opens the read-only `/zoom` overlay on the marked one (`Q`/`Esc` to close). This only changes what
232
+ you *view* — **the input box always prompts the main session**, and `main` is never a marker target
233
+ (it is the session under the input, not a subagent). There is no transcript takeover: a subagent's
234
+ stream is surfaced through the modal zoom overlay, never by replacing the main scrollback. The keys
235
+ are inert in dashboard mode (use `/zoom <name>` there).
236
+
237
+ > Terminal note: `Alt+[` emits `ESC [` (a CSI prefix) and may be swallowed by some terminals'
238
+ > escape parsers; `Alt+]` and `Alt+\` are the reliable pair. `Alt+↑/↓/←/→` are reserved by the pi
239
+ > editor, which is why the switcher uses the bracket/backslash keys.
240
+
241
+ ## Configuration
242
+
243
+ At session start, `agent-hub` reads `.ai/agent-fleet-overrides.md` in the workspace. The
244
+ canonical section name is `## agent-hub` (the legacy `## agent-team` name is still accepted):
245
+
246
+ ```markdown
247
+ ## agent-hub
248
+ # Replace Bulgarian with any language name.
249
+ language: Bulgarian
250
+ ```
251
+
252
+ Omit the section to keep the default `English`. `language` applies to dispatcher replies,
253
+ `ask_user` questions and `context` fields, handoff summaries, and user-facing status text;
254
+ specialist task strings stay in English.
255
+
256
+ The same section can point the team at the project's own rule files and documentation
257
+ entry points:
258
+
259
+ ```markdown
260
+ ## agent-hub
261
+ rules: docs/rules, .ai/rules
262
+ docs: Docs/AGENTS.md, Docs/architecture/ARCHITECTURE_OVERVIEW.md
263
+ ```
264
+
265
+ `rules:` lists repo-relative folders of HOW rules — implementation patterns the work must
266
+ comply with. Resolution is **index-first**: a folder with a top-level `README.md`/`index.md`
267
+ is treated as curated — personas read the index first and follow its loading manifest
268
+ (session bundles, conditional-load lists) instead of bulk-reading the tree; a folder without
269
+ an index is searched **recursively** through all subfolders. When set, every dispatched
270
+ specialist's system prompt gains a "Project rules" block naming the folders and the
271
+ resolution order; the planner and code-reviewer personas additionally validate their subject
272
+ against the relevant rules and pass them on (cited in plan acceptance criteria / handed to
273
+ delegate sub-reviewers).
274
+
275
+ `docs:` lists repo-relative WHAT/WHY documentation entry points — canonical files (e.g. an
276
+ `AGENTS.md`, an architecture overview) or doc folders (personas start from the folder's
277
+ README/index). Docs orient rather than bind: every dispatched specialist **and every research
278
+ helper** gains a "Project docs" block telling it to read the entry points relevant to its
279
+ task and follow their links instead of bulk-reading doc trees. The code-reviewer flags
280
+ changes that alter documented behavior without a doc update; the documenter treats the entry
281
+ points and the trees they link as the documentation it maintains.
282
+
283
+ Paths that don't exist produce a session-start warning, never an error. The full key list for
284
+ `## agent-hub` (models, sub-roles, depth budgets, persona gate) is documented in
285
+ `docs/agent-fleet-setup.md`.
286
+
287
+ ## The coms layer
288
+
289
+ > The runtime coordination protocols this layer implements (sentinels, push over
290
+ > polling, barriers, fan-out digests, racing) are catalogued in
291
+ > [references/fleet-coordination-patterns.md](../../../references/fleet-coordination-patterns.md).
292
+
293
+ ### Fleet tools (herdr)
294
+
295
+ Inside a [herdr](https://herdr.dev) pane with a live server, the dispatcher's tool
296
+ surface additionally gets (absent otherwise, like coms):
297
+
298
+ - `herdr_spawn_peer` — stand up a persona peer (joins the coms pool via `just _peer`) or a
299
+ raw command pane in the current workspace
300
+ - `herdr_read_pane` — bounded `pane.read` (≤200 lines), read-to-decide on workers/tools;
301
+ messaging still goes through coms
302
+ - `herdr_close_pane` — kills a pane; **asks the human to confirm every call**; the
303
+ bash-level `herdr pane close`/`workspace close`/`server stop` verbs are hard-blocked
304
+ for spawned specialists by `.pi/damage-control-rules.yaml`
305
+ - `herdr_notify` — desktop notification to reach the human when they are away
306
+
307
+ This closes the fleet loop: spawn a worker, watch it, notify the human, tear it down —
308
+ without leaving the session. Claude Code panes join the same pool via the
309
+ [coms bridge](../../../docs/claude-code-coms-bridge.md).
310
+
311
+ ### Presence backend (herdr or files)
312
+
313
+ Presence is pluggable, exactly as in the standalone [coms harness](../coms/README.md#presence-backends-herdr-vs-files):
314
+ inside a [herdr](https://herdr.dev) pane with a live server, the ping cycle is replaced by
315
+ push events (`agent.list` + `events.subscribe`) and the hub reports itself into the herdr
316
+ sidebar (`custom_status` = `<name> <pct>% q<depth>`); everywhere else the original 10s
317
+ ping loop runs unchanged. The file registry is written in both backends, and the
318
+ pool-scope boundary is enforced identically.
319
+
320
+ ### Identity
321
+
322
+ Each session registers a coms identity at start-up, resolved in this precedence order:
323
+
324
+ 1. **CLI flags** — `--name`, `--purpose`, `--project`, `--color`, `--explicit`
325
+ 2. **Dispatcher persona frontmatter** — `name`, `description` (→ purpose), `color` from the
326
+ selected `kind: orchestrator` persona (see [persona sync](#persona--coms-purpose-sync))
327
+ 3. **Defaults** — auto-generated name `hub-<id>`, purpose `agent-hub dispatcher`, project
328
+ `default`, a deterministic color derived from the session id
329
+
330
+ Names are de-duplicated per project (`resolveUniqueName`), so two hubs that both want `architect`
331
+ become `architect` and `architect-2`. `--explicit` marks a **private** peer — kept out of every
332
+ pool by default, so it is neither listed nor reachable until a human opts in with `/coms --all`
333
+ (see [Pool scope is the reach boundary](#pool-scope-is-the-reach-boundary)). The registry lives
334
+ under `~/.pi/coms/projects/<project>/agents/<name>.json` and is created at runtime.
335
+
336
+ ### Commands & tools (local dispatcher plus coms)
337
+
338
+ - `/coms` — coms control surface (peer list / status)
339
+ - `/handoff <peer>` — hand the whole session off to a coms peer (see [Handoff](#handoff))
340
+ - `/compound [focus]` — end-of-session **compound-learning pass**: the dispatcher composes a
341
+ candidate-lessons brief from the session (corrections, recurring findings, root causes),
342
+ confirms it with the user, then dispatches the `documenter` to land the approved lessons as
343
+ minimal diffs on the project's `rules:`/`docs:` targets per `skills/compound-learning/SKILL.md`.
344
+ Requires the `documenter` persona in the active team; run it before `/handoff` or session end.
345
+ - `coms_list` — discover the peers in your pool: names, models, live context usage, purpose. Scoped
346
+ to your project and excluding private peers; the LLM cannot widen it (see
347
+ [Pool scope is the reach boundary](#pool-scope-is-the-reach-boundary)).
348
+ - `coms_send` — send a prompt to a peer **in your pool**; returns a `msg_id`
349
+ - `coms_await` — **block** until that `msg_id`'s reply lands (default 30 min,
350
+ `PI_COMS_TIMEOUT_MS`)
351
+ - `coms_get` — **non-blocking** poll of a `msg_id` (status `pending|complete|error`)
352
+
353
+ `/coms` and `/handoff` tab-complete live peer names **in your pool**.
354
+
355
+ ### Pool scope is the reach boundary
356
+
357
+ The set of peers shown in the pool widget is the security boundary: **a peer is reachable only if it
358
+ is in your pool.** `coms_list`, `coms_send`, and `/handoff` all resolve targets through the same
359
+ `peersInScope()` helper, so the dispatcher can never message a peer it cannot see. Two knobs define
360
+ the pool, and **both are human-only** — the LLM cannot widen scope to reach more peers:
361
+
362
+ - **Project** — defaults to your own `identity.project`. A human can retarget with `/coms --project
363
+ <name>` (one project) or `/coms --all` (every project). `coms_list`'s own parameters cannot
364
+ override this; an LLM request for a wider project is clamped back to the current pool and flagged.
365
+ - **Explicit (private) peers** — excluded from every pool by default. `/coms --all` opts them in.
366
+
367
+ This closes a cross-project leak where a peer reachable through the mesh was *not* shown in the
368
+ default project-scoped pool — so it could be messaged without being "connected." Now the reachable
369
+ set is always a subset of what the widget shows. To reach a peer outside the pool, a human widens
370
+ scope first; the dispatcher is told to **ask** rather than attempt it, and not to pass cross-project
371
+ context to a peer the human has not approved.
372
+
373
+ ### Peer as subagent
374
+
375
+ The dispatcher uses a peer as a subagent by pairing the tools: `coms_send(target, prompt)` to
376
+ issue the task, then `coms_await(msg_id)` to block for the reply (or `coms_get` to poll). This sits
377
+ alongside `dispatch_agent` — local persona specialists are dispatched as subprocesses; remote peers
378
+ are reached over coms. The two paths stay explicit for the LLM, but
379
+ [coms-backed dispatch](#coms-backed-dispatch-dispatch-policyyaml) can route a `dispatch_agent` call
380
+ to a same-name peer under the hood. (The specialist-level `delegate` tool is a third,
381
+ nested path: a dispatched specialist spawning its own declared sub-agents — it does not auto-route
382
+ between local and remote either.) Multi-hop is inherited from coms: a peer handling a dispatched task can `coms_send`
383
+ onward, hops accumulating up to `MAX_HOPS` (5).
384
+
385
+ ### Coms-backed dispatch (dispatch-policy.yaml)
386
+
387
+ `just hub-team <team>` boots the hub next to standing peers from `.pi/agents/peers.yaml` — and some
388
+ of them (e.g. `code-reviewer`, `plan-reviewer` with `runner: claude-code`) intentionally share a name
389
+ with a team member. `.pi/agents/dispatch-policy.yaml` tells the dispatcher to serve such members
390
+ **through the peer** instead of spawning a native subagent:
391
+
392
+ ```yaml
393
+ default: native # coms = substitute ANY member with a live same-name pool peer
394
+ grace_s: 30 # poll window for coms-required members
395
+ substitutions:
396
+ code-reviewer:
397
+ prefer: coms
398
+ fallback: native # none = coms-required: refuse with guidance instead of spawning
399
+ # timeout_s: 3600 # per-member reply timeout (default PI_COMS_TIMEOUT_MS, 30 min)
400
+ ```
401
+
402
+ Semantics:
403
+
404
+ - **One API.** The dispatcher LLM always calls `dispatch_agent("code-reviewer", …)`; the backend is
405
+ resolved inside `dispatchAgent()`. The whole downstream pipeline — structured return contract,
406
+ `ASK_USER:` extraction, the NEEDS_RESEARCH auto-research pipe, assertions, history, the grid —
407
+ consumes a coms reply exactly like a subagent's final output (the dispatch protocols ride in the
408
+ message body, since a standing peer only receives a user prompt).
409
+ - **Decided per dispatch, against the live pool.** Hub and peers boot in parallel, so the first
410
+ dispatch may land before the peer registers: with `fallback: native` it runs natively (one notice
411
+ per member per team activation), and later dispatches pick up the peer once it is live. With
412
+ `fallback: none` the dispatch polls the pool for `grace_s` seconds, then refuses with remediation
413
+ steps. The name match is scoped to the coms pool — the same security boundary as `coms_send`.
414
+ - **Standing context is the point.** Re-dispatches (ASK_USER answers, research resumes) go back to
415
+ the same peer session, so a Claude Code reviewer keeps its review context across rounds.
416
+ - **Visibility.** The member's grid card shows a `⇄coms <peer-model>` badge, history entries are
417
+ annotated `(coms)`, and `/dispatch-policy` prints the resolved routing per member with live-peer
418
+ status.
419
+ - **Limitations.** `/agents-kill` on a coms-backed run only abandons the wait — the peer keeps
420
+ running in its own pane and cannot be killed from the hub (`/agents-restart` abandons, then
421
+ re-dispatches). `/zoom` shows only the final reply (there is no stream), tool counts stay 0, and
422
+ context% is a registry snapshot. `/agent-model` overrides apply only to native(-fallback) runs —
423
+ the peer's model is set in `peers.yaml`.
424
+
425
+ Missing file = everything native. HOW a peer runs (persona, model, `runner: claude-code`, env) stays
426
+ in `peers.yaml`; this file only decides WHEN the hub prefers a peer over a native spawn.
427
+
428
+ ### Handoff
429
+
430
+ `/handoff <peer>` transfers the session to another **main** agent. Following the plan's
431
+ **decision G1**, it does *not* try to extract a compaction summary; instead it asks the dispatcher
432
+ LLM to compose a **self-contained brief** ("everything the target needs, assume no shared history"),
433
+ then `coms_send`s that brief to the peer, `coms_await`s the reply, and relays it back — in the
434
+ configured user-facing language. When the handoff `coms_send` fires, the hub appends machine-generated
435
+ sections after the LLM brief: `## Verification ledger (verbatim, machine-appended)` with every current
436
+ assertion in canonical ledger form, and `## Artifact index` with artifact paths plus first headings.
437
+ The target peer must treat the machine-appended ledger as the contract, not the paraphrased brief.
438
+ The target peer takes over; the source relays the result. There is no raw session copy (pi sessions
439
+ aren't portable between live agents). The target must be a peer in your pool — `/handoff` resolves
440
+ through the same [scope boundary](#pool-scope-is-the-reach-boundary) as `coms_send`, so you cannot
441
+ hand a session to a peer you cannot see.
442
+
443
+ ### Pool widget
444
+
445
+ A live "pool" widget lists connected peers with name, model, and live context usage, refreshed by a
446
+ ping cycle; a keepalive cycle re-writes this session's own registry entry (and self-heals it if an
447
+ external prune removed it). Both timers are `unref`'d so they never hold the process open.
448
+
449
+ ### Persona → coms purpose sync
450
+
451
+ The dispatcher persona gate fires *after* coms init, so the identity's `purpose` starts from the
452
+ flag/frontmatter/default and is then reconciled to the chosen persona: `syncComsPurpose()` maps the
453
+ selected `kind: orchestrator` persona to `"<Name> — <description>"` and re-writes the live registry
454
+ entry — **unless** `--purpose` was passed explicitly (an explicit flag always wins). Switching or
455
+ resetting the persona via `/persona` re-syncs.
456
+
457
+ ### Graceful degradation
458
+
459
+ If the coms socket can't bind at start-up (`comsReady` stays `false`), the session degrades to a
460
+ local dispatcher without coms: the `coms_*` tools are withheld from `setActiveTools`, the
461
+ `/handoff` command refuses with a notice, and the "Peer agents (coms)" prompt section is omitted.
462
+ Orchestration, research helpers, and the grid keep working.
463
+
464
+ ### Tool surface
465
+
466
+ `setActiveTools` always preserves the orchestration surface and adds coms when ready:
467
+
468
+ ```ts
469
+ const dispatcherTools = ["dispatch_agent", "spawn_research", "set_assertions", "update_assertion", "get_assertions"];
470
+ if (comsReady) dispatcherTools.push("coms_list", "coms_send", "coms_get", "coms_await");
471
+ if (askUserAvailable) dispatcherTools.push("ask_user");
472
+ ```
473
+
474
+ `set_assertions` / `update_assertion` / `get_assertions` are the always-on Verification Contract ledger tools (see
475
+ [What it does](#what-it-does)); like `dispatch_agent` / `spawn_research` they are part of the
476
+ orchestration surface the dispatcher persona never narrows.
477
+
478
+ The dispatcher persona is **flavor-only** (decision G4 / 9) — it enriches the role but never narrows
479
+ this tool set, so coms and dispatch stay available regardless of the chosen persona.
480
+
481
+ ## Requires
482
+
483
+ - `.pi/agents/teams.yaml` for fixed specialist teams, the referenced persona `.md` files, and
484
+ (strongly recommended) [`pi-ask-user`](https://github.com/edlsh/pi-ask-user).
485
+ - `.pi/damage-control-rules.yaml` for the default guarded `just hub` / `just hub-solo` recipes.
486
+ - Nothing extra in-repo for coms — the peer registry lives at `~/.pi/coms/` and is created at
487
+ runtime.
488
+
489
+ ## Usage
490
+
491
+ ```bash
492
+ # via the justfile (loads damage-control-continue first; accepts coms identity flags)
493
+ just hub
494
+ just hub --name architect --purpose "owns the migration design" --project myrepo
495
+
496
+ # equivalent direct guarded launch
497
+ pi -e .pi/harnesses/damage-control-continue/index.ts -e .pi/harnesses/ask-user-remote/index.ts -e .pi/harnesses/agent-hub/index.ts
498
+ pi -e .pi/harnesses/damage-control-continue/index.ts -e .pi/harnesses/ask-user-remote/index.ts -e .pi/harnesses/agent-hub/index.ts --name releaser --explicit
499
+
500
+ # direct unguarded launch, only when you intentionally want to skip damage-control
501
+ pi -e .pi/harnesses/agent-hub/index.ts
502
+ ```
503
+
504
+ Identity flags: `--name`, `--purpose`, `--project`, `--color`, `--explicit`.
505
+
506
+ ### Safety scope
507
+
508
+ `just hub` and `just hub-solo` load `damage-control-continue` and `ask-user-remote` before `agent-hub`, so guardrails and `ask_user` apply
509
+ to hub/dispatcher tool calls in that parent pi process — and because it is the *continue* variant, a
510
+ blocked dispatcher call feeds back and the turn keeps going rather than aborting. Specialist and
511
+ research agents are spawned as separate pi subprocesses with `--no-extensions` — but `agent-hub`
512
+ resolves a damage-control harness (from this session's `-e` flags, else the repo-local
513
+ `.pi/harnesses/<variant>/index.ts`) and re-loads *only* that one into each child via `-e`. The variant
514
+ is chosen per child: research helpers (`researcher` / `deep-researcher`) get `damage-control-continue`
515
+ so a blocked read lets them adapt and keep going; every other specialist gets the hard-stop
516
+ `damage-control` that aborts on a violation. (Continue falls back to the hard-stop variant when it
517
+ isn't installed, so researchers stay guarded either way.) `--no-extensions` keeps discovery off, so
518
+ children never auto-load the `.pi/extensions/` utilities or recursively re-load `agent-hub`; the
519
+ explicit `-e` still applies, so every child's tool calls are checked against the same
520
+ `.pi/damage-control-rules.yaml`. If damage-control can't be resolved, a session-start warning is
521
+ shown and children spawn unguarded. Research helpers are additionally read-only by construction.
522
+ The guided setup (`guided-workspace-setup`) enforces the pairing: installing or keeping `agent-hub`
523
+ always installs/keeps `damage-control` (and `damage-control-continue`) with it.
524
+
525
+ ### Related recipes
526
+
527
+ ```bash
528
+ # the hub without the coms layer (fixed specialists + research only — lighter)
529
+ just hub-solo
530
+
531
+ # spawn every peer of a team from .pi/agents/peers.yaml into a tiled herdr workspace
532
+ # (requires a running herdr server — https://herdr.dev)
533
+ just team-up full # launch
534
+ just team-up-dry full # print the resolved layout + peer-launch commands without herdr
535
+
536
+ # hub + team in ONE workspace: guarded hub in a larger main pane, peers tiled beside it
537
+ just hub-team docs
538
+
539
+ # fleet resume: snapshot session refs / close cleanly / rebuild with conversations restored
540
+ just team-snapshot docs # proactive snapshot while the team runs (crash insurance)
541
+ just team-down docs # snapshot + close the workspace (peers get SIGTERM)
542
+ just team-resume docs # rebuild the grid; pi peers continue via `pi --session <ref>`
543
+ ```
544
+
545
+ `peers.yaml` groups reusable peers into named teams; each entry is `name` / `persona`
546
+ (+ optional `model`). The persona's frontmatter `description`/`color` become the peer's
547
+ coms purpose/color.
548
+
549
+ ## How it differs from its sources
550
+
551
+ - **Embedded, not stacked (decision 1).** coms is folded into this one `index.ts`; the identity
552
+ flags are registered once. Loading `coms` as a second `-e` would double-register
553
+ `--name/--purpose/...` and abort start-up.
554
+ - **Single `session_start`.** coms init is folded into the former dispatcher's `session_start` and
555
+ guarded by `if (!comsReady)`, so `/new` reuses the same peer identity (no leaked socket).
556
+ - **Dispatcher is also a peer.** `setActiveTools` lists `coms_*` alongside `dispatch_agent` +
557
+ `spawn_research` (+ `ask_user`); the system prompt gains a "Peer agents (coms)" section when coms
558
+ is ready. The persona's `description` drives the coms `purpose` (decision 6 / Phase 6 peer
559
+ mapping) instead of a static `--purpose`.
560
+ - **`/handoff` uses an LLM-composed brief**, not a compaction-summary extraction (decision G1).
561
+ - **Clean shutdown** SIGTERMs any running specialist/research children, clears the coms pool
562
+ widget, and removes the registry entry on `session_shutdown` / SIGINT / SIGTERM.
@@ -0,0 +1,92 @@
1
+ import { isAbsolute, relative, resolve, sep } from "node:path";
2
+
3
+ export const ARTIFACT_KINDS = ["returns", "plans", "reviews", "inventories", "evidence"];
4
+
5
+ const SESSION_RELATIVE_PREFIXES = new Set(["artifacts", "findings", "delegations"]);
6
+ const PREVIEW_LIMIT = 180;
7
+
8
+ export function resolveArtifactPath(inputPath, options) {
9
+ const raw = String(inputPath || "").trim();
10
+ if (!raw) throw new Error("Artifact path must be a non-empty string");
11
+ if (/\0/.test(raw)) throw new Error(`Invalid artifact path ${JSON.stringify(raw)}`);
12
+
13
+ const repoDir = resolve(options.repoDir);
14
+ const sessionDir = resolve(options.sessionDir);
15
+ const artifactRoot = options.artifactRoot ? resolve(options.artifactRoot) : resolve(sessionDir, "artifacts");
16
+ const normalized = raw.replace(/\\/g, "/").replace(/^\.\//, "");
17
+
18
+ const candidates = [];
19
+ if (isAbsolute(raw)) {
20
+ const absoluteTarget = resolve(raw);
21
+ if (isWithin(artifactRoot, absoluteTarget)) {
22
+ candidates.push({ root: artifactRoot, target: absoluteTarget, displayBase: artifactRoot, prefix: "artifacts" });
23
+ } else if (isWithin(sessionDir, absoluteTarget)) {
24
+ candidates.push({ root: sessionDir, target: absoluteTarget, displayBase: sessionDir, prefix: ".pi/agent-sessions" });
25
+ }
26
+ candidates.push({ root: repoDir, target: absoluteTarget, displayBase: repoDir, prefix: "" });
27
+ } else {
28
+ const first = normalized.split("/")[0];
29
+ if (first === "artifacts") {
30
+ candidates.push({ root: sessionDir, target: safeJoin(sessionDir, normalized), displayBase: artifactRoot, prefix: "artifacts" });
31
+ } else if (ARTIFACT_KINDS.includes(first)) {
32
+ candidates.push({ root: artifactRoot, target: safeJoin(artifactRoot, normalized), displayBase: artifactRoot, prefix: "artifacts" });
33
+ candidates.push({ root: repoDir, target: safeJoin(repoDir, normalized), displayBase: repoDir, prefix: "" });
34
+ } else if (SESSION_RELATIVE_PREFIXES.has(first)) {
35
+ candidates.push({ root: sessionDir, target: safeJoin(sessionDir, normalized), displayBase: sessionDir, prefix: ".pi/agent-sessions" });
36
+ } else {
37
+ candidates.push({ root: repoDir, target: safeJoin(repoDir, normalized), displayBase: repoDir, prefix: "" });
38
+ }
39
+ }
40
+
41
+ const valid = candidates.filter((candidate) => isWithin(candidate.root, candidate.target));
42
+ if (valid.length === 0) {
43
+ throw new Error(`Refusing artifact path outside repo/session: ${raw}`);
44
+ }
45
+
46
+ const exists = typeof options.exists === "function" ? options.exists : () => true;
47
+ const picked = valid.find((candidate) => exists(candidate.target)) || valid[0];
48
+ return {
49
+ input: raw,
50
+ path: picked.target,
51
+ displayPath: displayPath(picked.target, picked.displayBase, picked.prefix),
52
+ };
53
+ }
54
+
55
+ export function resolveArtifactPaths(paths, options) {
56
+ return (paths || []).map((p) => resolveArtifactPath(p, options));
57
+ }
58
+
59
+ export function artifactPreviewFromText(text) {
60
+ const lines = String(text || "").split(/\r?\n/);
61
+ const heading = lines.map((line) => line.trim()).find((line) => /^#{1,6}\s+\S/.test(line));
62
+ if (heading) return truncate(heading.replace(/^#{1,6}\s+/, ""));
63
+ const first = lines.map((line) => line.trim()).find(Boolean);
64
+ return first ? truncate(first) : "(empty file)";
65
+ }
66
+
67
+ export function formatInputArtifactsSection(items) {
68
+ if (!items || items.length === 0) return "";
69
+ const lines = items.map((item) => `- ${item.displayPath || item.path} — ${item.preview || "(no preview)"}`);
70
+ return `\n\n## Input artifacts\nRead these files with your own read tool when needed. The dispatcher is passing paths plus a one-line preview only; file bodies are intentionally not inlined.\n${lines.join("\n")}`;
71
+ }
72
+
73
+ function safeJoin(root, relativePath) {
74
+ const target = resolve(root, relativePath);
75
+ if (!isWithin(root, target)) throw new Error(`Refusing artifact path outside repo/session: ${relativePath}`);
76
+ return target;
77
+ }
78
+
79
+ function isWithin(root, target) {
80
+ const rel = relative(resolve(root), resolve(target));
81
+ return rel === "" || (!!rel && !rel.startsWith("..") && !isAbsolute(rel));
82
+ }
83
+
84
+ function displayPath(target, base, prefix) {
85
+ const rel = relative(resolve(base), resolve(target)).split(sep).join("/");
86
+ if (!prefix) return rel || ".";
87
+ return rel ? `${prefix}/${rel}` : prefix;
88
+ }
89
+
90
+ function truncate(value) {
91
+ return value.length > PREVIEW_LIMIT ? `${value.slice(0, PREVIEW_LIMIT - 1)}…` : value;
92
+ }