@chankov/agent-fleet 1.0.2 → 1.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (325) hide show
  1. package/.pi/harnesses/agent-hub/README.md +60 -60
  2. package/.pi/harnesses/agent-hub/context-window.js +1 -1
  3. package/.pi/harnesses/agent-hub/drift-watchdog.js +11 -4
  4. package/.pi/harnesses/agent-hub/execution-profile.ts +69 -0
  5. package/.pi/harnesses/agent-hub/footer.ts +3 -2
  6. package/.pi/harnesses/agent-hub/hub-state-audit.js +0 -14
  7. package/.pi/harnesses/agent-hub/index.ts +351 -261
  8. package/.pi/harnesses/agent-hub/package.json +1 -1
  9. package/.pi/harnesses/agent-hub/provider-semaphore.js +1 -1
  10. package/.pi/harnesses/agent-hub/run-budget.js +67 -69
  11. package/.pi/harnesses/coms/package.json +1 -1
  12. package/.pi/harnesses/damage-control-continue/package.json +1 -1
  13. package/.pi/harnesses/lib/fleet-dashboard-view.ts +3 -1
  14. package/.pi/harnesses/lib/fleet-detail-view.ts +39 -4
  15. package/.versions/1.0.3/.pi/agents/dispatch-policy.yaml +32 -0
  16. package/.versions/1.0.3/.pi/agents/model-profiles.yaml +27 -0
  17. package/.versions/1.0.3/.pi/agents/peers.yaml +142 -0
  18. package/.versions/1.0.3/.pi/agents/teams.yaml +41 -0
  19. package/.versions/1.0.3/.pi/damage-control-rules.yaml +297 -0
  20. package/.versions/1.0.3/.pi/extensions/agent-fleet-update-check/README.md +57 -0
  21. package/.versions/1.0.3/.pi/extensions/agent-fleet-update-check/index.ts +161 -0
  22. package/.versions/1.0.3/.pi/extensions/agent-fleet-update-check/package.json +6 -0
  23. package/.versions/1.0.3/.pi/extensions/btw/README.md +120 -0
  24. package/.versions/1.0.3/.pi/extensions/btw/index.ts +914 -0
  25. package/.versions/1.0.3/.pi/extensions/btw/package.json +6 -0
  26. package/.versions/1.0.3/.pi/extensions/btw/state.js +179 -0
  27. package/.versions/1.0.3/.pi/extensions/chrome-devtools-mcp/README.md +55 -0
  28. package/.versions/1.0.3/.pi/extensions/chrome-devtools-mcp/index.ts +93 -0
  29. package/.versions/1.0.3/.pi/extensions/chrome-devtools-mcp/package.json +6 -0
  30. package/.versions/1.0.3/.pi/extensions/compact-and-continue/README.md +42 -0
  31. package/.versions/1.0.3/.pi/extensions/compact-and-continue/index.ts +120 -0
  32. package/.versions/1.0.3/.pi/extensions/compact-and-continue/package.json +6 -0
  33. package/.versions/1.0.3/.pi/extensions/mcp-bridge/README.md +46 -0
  34. package/.versions/1.0.3/.pi/extensions/mcp-bridge/index.ts +206 -0
  35. package/.versions/1.0.3/.pi/extensions/mcp-bridge/package.json +6 -0
  36. package/.versions/1.0.3/.pi/extensions/package-lock.json +1175 -0
  37. package/.versions/1.0.3/.pi/extensions/package.json +9 -0
  38. package/.versions/1.0.3/.pi/extensions/pi-voice-stt/README.md +205 -0
  39. package/.versions/1.0.3/.pi/extensions/pi-voice-stt/config.ts +198 -0
  40. package/.versions/1.0.3/.pi/extensions/pi-voice-stt/examples/stt.json +35 -0
  41. package/.versions/1.0.3/.pi/extensions/pi-voice-stt/index.ts +248 -0
  42. package/.versions/1.0.3/.pi/extensions/pi-voice-stt/package.json +6 -0
  43. package/.versions/1.0.3/.pi/extensions/pi-voice-stt/providers.ts +214 -0
  44. package/.versions/1.0.3/.pi/extensions/pi-voice-stt/recorder.ts +158 -0
  45. package/.versions/1.0.3/.pi/harnesses/agent-hub/README.md +1156 -0
  46. package/.versions/1.0.3/.pi/harnesses/agent-hub/access-approval.ts +135 -0
  47. package/.versions/1.0.3/.pi/harnesses/agent-hub/artifacts.js +146 -0
  48. package/.versions/1.0.3/.pi/harnesses/agent-hub/assertion-ledger.js +58 -0
  49. package/.versions/1.0.3/.pi/harnesses/agent-hub/backend-policy.js +174 -0
  50. package/.versions/1.0.3/.pi/harnesses/agent-hub/budget-continuation.ts +73 -0
  51. package/.versions/1.0.3/.pi/harnesses/agent-hub/capability-confirmation.ts +47 -0
  52. package/.versions/1.0.3/.pi/harnesses/agent-hub/capability-packs.ts +180 -0
  53. package/.versions/1.0.3/.pi/harnesses/agent-hub/context-budget-snapshot.ts +105 -0
  54. package/.versions/1.0.3/.pi/harnesses/agent-hub/context-pressure.ts +191 -0
  55. package/.versions/1.0.3/.pi/harnesses/agent-hub/context-window.js +106 -0
  56. package/.versions/1.0.3/.pi/harnesses/agent-hub/delegate.ts +435 -0
  57. package/.versions/1.0.3/.pi/harnesses/agent-hub/docs-lane.js +122 -0
  58. package/.versions/1.0.3/.pi/harnesses/agent-hub/drift-watchdog.js +218 -0
  59. package/.versions/1.0.3/.pi/harnesses/agent-hub/evidence-rules.js +96 -0
  60. package/.versions/1.0.3/.pi/harnesses/agent-hub/execution-profile.ts +69 -0
  61. package/.versions/1.0.3/.pi/harnesses/agent-hub/external-blocker.js +85 -0
  62. package/.versions/1.0.3/.pi/harnesses/agent-hub/footer.ts +36 -0
  63. package/.versions/1.0.3/.pi/harnesses/agent-hub/helpers.ts +266 -0
  64. package/.versions/1.0.3/.pi/harnesses/agent-hub/hub-state-audit.js +59 -0
  65. package/.versions/1.0.3/.pi/harnesses/agent-hub/index.ts +9999 -0
  66. package/.versions/1.0.3/.pi/harnesses/agent-hub/monitor-control.ts +9 -0
  67. package/.versions/1.0.3/.pi/harnesses/agent-hub/monitor-invoke-journal.ts +131 -0
  68. package/.versions/1.0.3/.pi/harnesses/agent-hub/monitor-invoke.ts +92 -0
  69. package/.versions/1.0.3/.pi/harnesses/agent-hub/monitor-lifecycle.ts +13 -0
  70. package/.versions/1.0.3/.pi/harnesses/agent-hub/monitor-publisher.ts +59 -0
  71. package/.versions/1.0.3/.pi/harnesses/agent-hub/monitor-recovery.ts +3 -0
  72. package/.versions/1.0.3/.pi/harnesses/agent-hub/monitor-runtime.ts +3 -0
  73. package/.versions/1.0.3/.pi/harnesses/agent-hub/monitor-session-bridge.ts +266 -0
  74. package/.versions/1.0.3/.pi/harnesses/agent-hub/package.json +7 -0
  75. package/.versions/1.0.3/.pi/harnesses/agent-hub/peer-spawn-plan.ts +116 -0
  76. package/.versions/1.0.3/.pi/harnesses/agent-hub/posture.ts +158 -0
  77. package/.versions/1.0.3/.pi/harnesses/agent-hub/provider-semaphore.js +138 -0
  78. package/.versions/1.0.3/.pi/harnesses/agent-hub/research-retention.js +34 -0
  79. package/.versions/1.0.3/.pi/harnesses/agent-hub/research-watchdog.ts +40 -0
  80. package/.versions/1.0.3/.pi/harnesses/agent-hub/return-contract.js +293 -0
  81. package/.versions/1.0.3/.pi/harnesses/agent-hub/return-extract.js +75 -0
  82. package/.versions/1.0.3/.pi/harnesses/agent-hub/review-findings.js +102 -0
  83. package/.versions/1.0.3/.pi/harnesses/agent-hub/run-budget.js +537 -0
  84. package/.versions/1.0.3/.pi/harnesses/agent-hub/run-namespace.js +87 -0
  85. package/.versions/1.0.3/.pi/harnesses/agent-hub/safety-routing.ts +22 -0
  86. package/.versions/1.0.3/.pi/harnesses/agent-hub/scope-gate.js +103 -0
  87. package/.versions/1.0.3/.pi/harnesses/agent-hub/session-health.js +110 -0
  88. package/.versions/1.0.3/.pi/harnesses/agent-hub/spawn.ts +366 -0
  89. package/.versions/1.0.3/.pi/harnesses/agent-hub/version.ts +42 -0
  90. package/.versions/1.0.3/.pi/harnesses/ask-user-remote/README.md +53 -0
  91. package/.versions/1.0.3/.pi/harnesses/ask-user-remote/index.ts +532 -0
  92. package/.versions/1.0.3/.pi/harnesses/ask-user-remote/race-core.js +106 -0
  93. package/.versions/1.0.3/.pi/harnesses/coms/README.md +100 -0
  94. package/.versions/1.0.3/.pi/harnesses/coms/index.ts +1767 -0
  95. package/.versions/1.0.3/.pi/harnesses/coms/package.json +7 -0
  96. package/.versions/1.0.3/.pi/harnesses/coms/version.ts +42 -0
  97. package/.versions/1.0.3/.pi/harnesses/damage-control-continue/README.md +124 -0
  98. package/.versions/1.0.3/.pi/harnesses/damage-control-continue/index.ts +536 -0
  99. package/.versions/1.0.3/.pi/harnesses/damage-control-continue/package.json +7 -0
  100. package/.versions/1.0.3/.pi/harnesses/damage-control-continue/version.ts +42 -0
  101. package/.versions/1.0.3/.pi/harnesses/lib/coms-registry-entry.ts +94 -0
  102. package/.versions/1.0.3/.pi/harnesses/lib/context-budget-child-prompt.ts +179 -0
  103. package/.versions/1.0.3/.pi/harnesses/lib/context-budget-hub-prompt.ts +116 -0
  104. package/.versions/1.0.3/.pi/harnesses/lib/context-budget-view.ts +107 -0
  105. package/.versions/1.0.3/.pi/harnesses/lib/context-budget.ts +114 -0
  106. package/.versions/1.0.3/.pi/harnesses/lib/damage-control-shared.ts +197 -0
  107. package/.versions/1.0.3/.pi/harnesses/lib/fixtures/context-budget-profiles.json +11 -0
  108. package/.versions/1.0.3/.pi/harnesses/lib/fixtures/hub-prompt-operator.legacy.txt +73 -0
  109. package/.versions/1.0.3/.pi/harnesses/lib/fixtures/hub-prompt-orchestrator.legacy.txt +73 -0
  110. package/.versions/1.0.3/.pi/harnesses/lib/fleet-dashboard-ops.ts +155 -0
  111. package/.versions/1.0.3/.pi/harnesses/lib/fleet-dashboard-view.ts +142 -0
  112. package/.versions/1.0.3/.pi/harnesses/lib/fleet-detail-view.ts +168 -0
  113. package/.versions/1.0.3/.pi/harnesses/lib/fleet-overlay.ts +26 -0
  114. package/.versions/1.0.3/.pi/harnesses/lib/fleet-panel.ts +34 -0
  115. package/.versions/1.0.3/.pi/harnesses/lib/fleet-read-model.ts +131 -0
  116. package/.versions/1.0.3/.pi/harnesses/lib/fleet-selection.ts +24 -0
  117. package/.versions/1.0.3/.pi/harnesses/lib/herdr-client.ts +472 -0
  118. package/.versions/1.0.3/.pi/harnesses/lib/herdr-presence.ts +399 -0
  119. package/.versions/1.0.3/.pi/harnesses/lib/hermes-monitor-events.ts +136 -0
  120. package/.versions/1.0.3/.pi/harnesses/lib/hermes-monitor-herdr.ts +28 -0
  121. package/.versions/1.0.3/.pi/harnesses/lib/hermes-monitor-model.ts +18 -0
  122. package/.versions/1.0.3/.pi/harnesses/lib/hermes-monitor-registry.ts +6 -0
  123. package/.versions/1.0.3/.pi/harnesses/lib/hermes-monitor-socket.ts +163 -0
  124. package/.versions/1.0.3/.pi/harnesses/lib/hermes-monitor-store.ts +31 -0
  125. package/.versions/1.0.3/.pi/harnesses/lib/spawned-peers.js +190 -0
  126. package/.versions/1.0.3/.pi/harnesses/package-lock.json +2039 -0
  127. package/.versions/1.0.3/.pi/harnesses/package.json +10 -0
  128. package/.versions/1.0.3/.pi/prompts/af-build.md +24 -0
  129. package/.versions/1.0.3/.pi/prompts/af-code-simplify.md +22 -0
  130. package/.versions/1.0.3/.pi/prompts/af-plan.md +16 -0
  131. package/.versions/1.0.3/.pi/prompts/af-review.md +16 -0
  132. package/.versions/1.0.3/.pi/prompts/af-set-hermes-telegram.md +15 -0
  133. package/.versions/1.0.3/.pi/prompts/af-set-hermes-watchdog.md +6 -0
  134. package/.versions/1.0.3/.pi/prompts/af-ship.md +17 -0
  135. package/.versions/1.0.3/.pi/prompts/af-spec.md +15 -0
  136. package/.versions/1.0.3/.pi/prompts/af-test.md +19 -0
  137. package/.versions/1.0.3/.pi/skills/bowser/SKILL.md +145 -0
  138. package/.versions/1.0.3/.version +1 -0
  139. package/.versions/1.0.3/agents/architect.md +25 -0
  140. package/.versions/1.0.3/agents/bowser.md +28 -0
  141. package/.versions/1.0.3/agents/builder.md +55 -0
  142. package/.versions/1.0.3/agents/code-reviewer.md +209 -0
  143. package/.versions/1.0.3/agents/deep-researcher.md +33 -0
  144. package/.versions/1.0.3/agents/documenter.md +19 -0
  145. package/.versions/1.0.3/agents/orchestrator.md +21 -0
  146. package/.versions/1.0.3/agents/plan-reviewer.md +84 -0
  147. package/.versions/1.0.3/agents/planner.md +71 -0
  148. package/.versions/1.0.3/agents/releaser.md +25 -0
  149. package/.versions/1.0.3/agents/researcher.md +29 -0
  150. package/.versions/1.0.3/agents/security-auditor.md +168 -0
  151. package/.versions/1.0.3/agents/test-engineer.md +154 -0
  152. package/.versions/1.0.3/agents/web-debugger.md +44 -0
  153. package/.versions/1.0.3/agents/web-performance-auditor.md +194 -0
  154. package/.versions/1.0.3/bin/catalog/harness-runtime-closure.json +38 -0
  155. package/.versions/1.0.3/codex/CONDUCTOR.md +148 -0
  156. package/.versions/1.0.3/docs/ARCHITECTURE.md +375 -0
  157. package/.versions/1.0.3/docs/agent-fleet-setup.md +468 -0
  158. package/.versions/1.0.3/docs/claude-code-coms-bridge.md +128 -0
  159. package/.versions/1.0.3/docs/codex-remote-conductor.md +170 -0
  160. package/.versions/1.0.3/docs/coms-hermes-bridge.md +189 -0
  161. package/.versions/1.0.3/docs/getting-started.md +98 -0
  162. package/.versions/1.0.3/docs/npm-install.md +292 -0
  163. package/.versions/1.0.3/docs/pi-extensions.md +441 -0
  164. package/.versions/1.0.3/docs/pi-setup.md +74 -0
  165. package/.versions/1.0.3/docs/skill-anatomy.md +150 -0
  166. package/.versions/1.0.3/hermes/README.md +347 -0
  167. package/.versions/1.0.3/hermes/desktop-plugins/agent-fleet-herdr/plugin.js +1291 -0
  168. package/.versions/1.0.3/hermes/desktop-plugins/agent-fleet-herdr/presentation.js +672 -0
  169. package/.versions/1.0.3/hermes/desktop-plugins/agent-fleet-monitor/plugin.js +19 -0
  170. package/.versions/1.0.3/hermes/desktop-plugins/agent-fleet-monitor/state.js +10 -0
  171. package/.versions/1.0.3/hermes/gates/gate-o-capability.md +8 -0
  172. package/.versions/1.0.3/hermes/gates/gate-o-validator-fixtures.json +1 -0
  173. package/.versions/1.0.3/hermes/plugins/agent-fleet-herdr/dashboard/activity.py +770 -0
  174. package/.versions/1.0.3/hermes/plugins/agent-fleet-herdr/dashboard/coms_registry.py +134 -0
  175. package/.versions/1.0.3/hermes/plugins/agent-fleet-herdr/dashboard/coms_send.py +350 -0
  176. package/.versions/1.0.3/hermes/plugins/agent-fleet-herdr/dashboard/herdr_source.py +193 -0
  177. package/.versions/1.0.3/hermes/plugins/agent-fleet-herdr/dashboard/manifest.json +4 -0
  178. package/.versions/1.0.3/hermes/plugins/agent-fleet-herdr/dashboard/plugin_api.py +444 -0
  179. package/.versions/1.0.3/hermes/plugins/agent-fleet-herdr/dashboard/sessions.py +205 -0
  180. package/.versions/1.0.3/hermes/plugins/agent-fleet-herdr/dashboard/tasks.py +300 -0
  181. package/.versions/1.0.3/hermes/plugins/agent-fleet-herdr/dashboard/watch.py +819 -0
  182. package/.versions/1.0.3/hermes/plugins/agent-fleet-herdr/plugin.yaml +8 -0
  183. package/.versions/1.0.3/hermes/plugins/agent-fleet-monitor/dashboard/adapter.py +139 -0
  184. package/.versions/1.0.3/hermes/plugins/agent-fleet-monitor/dashboard/manifest.json +11 -0
  185. package/.versions/1.0.3/hermes/plugins/agent-fleet-monitor/dashboard/plugin_api.py +50 -0
  186. package/.versions/1.0.3/hermes/skills/hub-conductor/SKILL.md +84 -0
  187. package/.versions/1.0.3/hermes/skills/hub-liaison/SKILL.md +84 -0
  188. package/.versions/1.0.3/hermes/skills/hub-watchdog/SKILL.md +76 -0
  189. package/.versions/1.0.3/hermes/skills/hub-watchdog/manifest.json +1 -0
  190. package/.versions/1.0.3/hermes/skills/hub-watchdog/scripts/watchdog.py +249 -0
  191. package/.versions/1.0.3/hermes/skills/hub-watchdog/scripts/watchdog_actions.py +124 -0
  192. package/.versions/1.0.3/hermes/skills/hub-watchdog/scripts/watchdog_contract.py +76 -0
  193. package/.versions/1.0.3/hermes/skills/hub-watchdog/scripts/watchdog_delivery.py +10 -0
  194. package/.versions/1.0.3/hermes/skills/hub-watchdog/scripts/watchdog_engine.py +128 -0
  195. package/.versions/1.0.3/hermes/skills/hub-watchdog/scripts/watchdog_judgment.py +41 -0
  196. package/.versions/1.0.3/hermes/skills/hub-watchdog/scripts/watchdog_recovery.py +103 -0
  197. package/.versions/1.0.3/hermes/skills/hub-watchdog/scripts/watchdog_state.py +163 -0
  198. package/.versions/1.0.3/hermes/skills/hub-watchdog/scripts/watchdog_transport.py +138 -0
  199. package/.versions/1.0.3/hermes/watchdog-tests/__init__.py +0 -0
  200. package/.versions/1.0.3/hooks/coms-stop-hook.mjs +84 -0
  201. package/.versions/1.0.3/install-manifest.json +2745 -0
  202. package/.versions/1.0.3/justfile +272 -0
  203. package/.versions/1.0.3/manifest-meta.json +882 -0
  204. package/.versions/1.0.3/references/accessibility-checklist.md +160 -0
  205. package/.versions/1.0.3/references/definition-of-done.md +67 -0
  206. package/.versions/1.0.3/references/fleet-coordination-patterns.md +151 -0
  207. package/.versions/1.0.3/references/observability-checklist.md +91 -0
  208. package/.versions/1.0.3/references/orchestration-patterns.md +370 -0
  209. package/.versions/1.0.3/references/performance-checklist.md +153 -0
  210. package/.versions/1.0.3/references/prompting-patterns.md +380 -0
  211. package/.versions/1.0.3/references/security-checklist.md +179 -0
  212. package/.versions/1.0.3/references/testing-patterns.md +236 -0
  213. package/.versions/1.0.3/scripts/codex-conductor.ts +41 -0
  214. package/.versions/1.0.3/scripts/codex-remote-control.ts +167 -0
  215. package/.versions/1.0.3/scripts/coms-claude-bridge.ts +411 -0
  216. package/.versions/1.0.3/scripts/coms-cli.ts +484 -0
  217. package/.versions/1.0.3/scripts/coms-hermes-bridge.ts +413 -0
  218. package/.versions/1.0.3/scripts/fleet.ts +185 -0
  219. package/.versions/1.0.3/scripts/hermes-monitor-capability-runner.ts +25 -0
  220. package/.versions/1.0.3/scripts/hermes-monitor-scenario.ts +474 -0
  221. package/.versions/1.0.3/scripts/hermes-watchdog-capability-probe.ts +45 -0
  222. package/.versions/1.0.3/scripts/install-hermes-plugin.sh +180 -0
  223. package/.versions/1.0.3/scripts/lib/claude-bridge-core.ts +210 -0
  224. package/.versions/1.0.3/scripts/lib/codex-conductor.ts +88 -0
  225. package/.versions/1.0.3/scripts/lib/codex-remote-control.ts +480 -0
  226. package/.versions/1.0.3/scripts/lib/coms-envelope.ts +582 -0
  227. package/.versions/1.0.3/scripts/lib/fake-herdr-server.ts +88 -0
  228. package/.versions/1.0.3/scripts/lib/fleet-command.ts +266 -0
  229. package/.versions/1.0.3/scripts/lib/herdr-layout.ts +281 -0
  230. package/.versions/1.0.3/scripts/lib/hermes-bridge-core.ts +241 -0
  231. package/.versions/1.0.3/scripts/lib/hermes-monitor-events.ts +1 -0
  232. package/.versions/1.0.3/scripts/lib/hermes-monitor-herdr.ts +2 -0
  233. package/.versions/1.0.3/scripts/lib/hermes-monitor-model.ts +3 -0
  234. package/.versions/1.0.3/scripts/lib/hermes-monitor-registry.ts +2 -0
  235. package/.versions/1.0.3/scripts/lib/hermes-monitor-socket.ts +2 -0
  236. package/.versions/1.0.3/scripts/lib/hermes-monitor-store.ts +2 -0
  237. package/.versions/1.0.3/scripts/lib/monitor-env.ts +146 -0
  238. package/.versions/1.0.3/scripts/lib/peer-launch.ts +318 -0
  239. package/.versions/1.0.3/scripts/lib/persona-banner.ts +62 -0
  240. package/.versions/1.0.3/scripts/lib/spawn-stagger.ts +101 -0
  241. package/.versions/1.0.3/scripts/lib/team-project.ts +213 -0
  242. package/.versions/1.0.3/scripts/lib/team-snapshot.ts +147 -0
  243. package/.versions/1.0.3/scripts/peer-banner.ts +40 -0
  244. package/.versions/1.0.3/scripts/peer-launch.ts +259 -0
  245. package/.versions/1.0.3/scripts/team-snapshot.ts +237 -0
  246. package/.versions/1.0.3/scripts/team-up.ts +406 -0
  247. package/.versions/1.0.3/skills/_internal/grilling.md +11 -0
  248. package/.versions/1.0.3/skills/browser-testing-with-devtools/SKILL.md +351 -0
  249. package/.versions/1.0.3/skills/code-review-and-quality/SKILL.md +381 -0
  250. package/.versions/1.0.3/skills/compound-learning/SKILL.md +137 -0
  251. package/.versions/1.0.3/skills/context-engineering/SKILL.md +291 -0
  252. package/.versions/1.0.3/skills/deprecation-and-migration/SKILL.md +206 -0
  253. package/.versions/1.0.3/skills/designing-agents/SKILL.md +394 -0
  254. package/.versions/1.0.3/skills/designing-agents/pi-harness-authoring.md +222 -0
  255. package/.versions/1.0.3/skills/frontend-ui-engineering/SKILL.md +328 -0
  256. package/.versions/1.0.3/skills/git-workflow-and-versioning/SKILL.md +316 -0
  257. package/.versions/1.0.3/skills/idea-refine/SKILL.md +182 -0
  258. package/.versions/1.0.3/skills/idea-refine/examples.md +238 -0
  259. package/.versions/1.0.3/skills/idea-refine/frameworks.md +99 -0
  260. package/.versions/1.0.3/skills/idea-refine/refinement-criteria.md +113 -0
  261. package/.versions/1.0.3/skills/idea-refine/scripts/idea-refine.sh +15 -0
  262. package/.versions/1.0.3/skills/incremental-implementation/SKILL.md +287 -0
  263. package/.versions/1.0.3/skills/interview-me/SKILL.md +226 -0
  264. package/.versions/1.0.3/skills/orchestration-verification/SKILL.md +181 -0
  265. package/.versions/1.0.3/skills/peer-coms/SKILL.md +90 -0
  266. package/.versions/1.0.3/skills/performance-optimization/SKILL.md +350 -0
  267. package/.versions/1.0.3/skills/planning-and-task-breakdown/SKILL.md +254 -0
  268. package/.versions/1.0.3/skills/security-and-hardening/SKILL.md +461 -0
  269. package/.versions/1.0.3/skills/spec-driven-development/SKILL.md +257 -0
  270. package/.versions/1.0.3/skills/using-agent-skills/SKILL.md +199 -0
  271. package/.versions/1.0.3/systemd/user/agent-fleet-codex-remote-control.service.in +23 -0
  272. package/.versions/1.0.3/vendor/agent-skills-upstream/LICENSE +21 -0
  273. package/.versions/1.0.3/vendor/agent-skills-upstream/README.md +11 -0
  274. package/.versions/1.0.3/vendor/agent-skills-upstream/skills/api-and-interface-design/SKILL.md +294 -0
  275. package/.versions/1.0.3/vendor/agent-skills-upstream/skills/browser-testing-with-devtools/SKILL.md +317 -0
  276. package/.versions/1.0.3/vendor/agent-skills-upstream/skills/ci-cd-and-automation/SKILL.md +390 -0
  277. package/.versions/1.0.3/vendor/agent-skills-upstream/skills/code-review-and-quality/SKILL.md +396 -0
  278. package/.versions/1.0.3/vendor/agent-skills-upstream/skills/code-simplification/SKILL.md +331 -0
  279. package/.versions/1.0.3/vendor/agent-skills-upstream/skills/context-engineering/SKILL.md +289 -0
  280. package/.versions/1.0.3/vendor/agent-skills-upstream/skills/debugging-and-error-recovery/SKILL.md +300 -0
  281. package/.versions/1.0.3/vendor/agent-skills-upstream/skills/deprecation-and-migration/SKILL.md +247 -0
  282. package/.versions/1.0.3/vendor/agent-skills-upstream/skills/documentation-and-adrs/SKILL.md +278 -0
  283. package/.versions/1.0.3/vendor/agent-skills-upstream/skills/doubt-driven-development/SKILL.md +243 -0
  284. package/.versions/1.0.3/vendor/agent-skills-upstream/skills/frontend-ui-engineering/SKILL.md +328 -0
  285. package/.versions/1.0.3/vendor/agent-skills-upstream/skills/git-workflow-and-versioning/SKILL.md +355 -0
  286. package/.versions/1.0.3/vendor/agent-skills-upstream/skills/idea-refine/SKILL.md +178 -0
  287. package/.versions/1.0.3/vendor/agent-skills-upstream/skills/idea-refine/examples.md +238 -0
  288. package/.versions/1.0.3/vendor/agent-skills-upstream/skills/idea-refine/frameworks.md +99 -0
  289. package/.versions/1.0.3/vendor/agent-skills-upstream/skills/idea-refine/refinement-criteria.md +113 -0
  290. package/.versions/1.0.3/vendor/agent-skills-upstream/skills/idea-refine/scripts/idea-refine.sh +15 -0
  291. package/.versions/1.0.3/vendor/agent-skills-upstream/skills/incremental-implementation/SKILL.md +249 -0
  292. package/.versions/1.0.3/vendor/agent-skills-upstream/skills/interview-me/SKILL.md +225 -0
  293. package/.versions/1.0.3/vendor/agent-skills-upstream/skills/observability-and-instrumentation/SKILL.md +203 -0
  294. package/.versions/1.0.3/vendor/agent-skills-upstream/skills/performance-optimization/SKILL.md +350 -0
  295. package/.versions/1.0.3/vendor/agent-skills-upstream/skills/planning-and-task-breakdown/SKILL.md +234 -0
  296. package/.versions/1.0.3/vendor/agent-skills-upstream/skills/security-and-hardening/SKILL.md +467 -0
  297. package/.versions/1.0.3/vendor/agent-skills-upstream/skills/shipping-and-launch/SKILL.md +310 -0
  298. package/.versions/1.0.3/vendor/agent-skills-upstream/skills/source-driven-development/SKILL.md +194 -0
  299. package/.versions/1.0.3/vendor/agent-skills-upstream/skills/spec-driven-development/SKILL.md +206 -0
  300. package/.versions/1.0.3/vendor/agent-skills-upstream/skills/test-driven-development/SKILL.md +383 -0
  301. package/.versions/1.0.3/vendor/agent-skills-upstream/skills/using-agent-skills/SKILL.md +191 -0
  302. package/CHANGELOG.md +6 -0
  303. package/README.md +5 -4
  304. package/agents/architect.md +1 -0
  305. package/agents/bowser.md +1 -0
  306. package/agents/builder.md +1 -0
  307. package/agents/code-reviewer.md +1 -0
  308. package/agents/deep-researcher.md +1 -0
  309. package/agents/documenter.md +1 -0
  310. package/agents/orchestrator.md +1 -0
  311. package/agents/plan-reviewer.md +1 -0
  312. package/agents/planner.md +1 -0
  313. package/agents/releaser.md +1 -0
  314. package/agents/researcher.md +1 -0
  315. package/agents/security-auditor.md +1 -0
  316. package/agents/test-engineer.md +1 -0
  317. package/agents/web-debugger.md +1 -0
  318. package/agents/web-performance-auditor.md +1 -0
  319. package/bin/lib/validate-overrides.js +1 -1
  320. package/docs/ARCHITECTURE.md +25 -19
  321. package/docs/agent-fleet-setup.md +8 -8
  322. package/docs/pi-extensions.md +4 -2
  323. package/install-manifest.json +1 -1
  324. package/package.json +2 -2
  325. package/scripts/fleet.ts +1 -1
@@ -0,0 +1,582 @@
1
+ // scripts/lib/coms-envelope.ts
2
+ //
3
+ // The coms envelope protocol for NON-pi participants (the coms-cli and the
4
+ // Claude Code bridge). Mirrors the wire behavior of .pi/harnesses/coms/
5
+ // exactly — same registry files, same endpoint sockets, same ndjson envelopes
6
+ // and ack/nack lines — so a process using this module is indistinguishable
7
+ // from a pi peer to the rest of the pool. Any change here must stay
8
+ // compatible with the coms harness (and vice versa).
9
+ //
10
+ // No pi imports; erasable-TS; the pure parts are under node --test.
11
+
12
+ import * as crypto from "node:crypto";
13
+ import * as fs from "node:fs";
14
+ import * as net from "node:net";
15
+ import * as os from "node:os";
16
+ import * as path from "node:path";
17
+
18
+ export const COMS_DIR = process.env.PI_COMS_DIR || path.join(os.homedir(), ".pi", "coms");
19
+ export const MAX_HOPS = Number(process.env.PI_COMS_MAX_HOPS) || 5;
20
+ export const DEFAULT_TIMEOUT_MS = Number(process.env.PI_COMS_TIMEOUT_MS) || 1_800_000;
21
+ const LINE_CAP_BYTES = 64 * 1024;
22
+ // Pi peers refresh heartbeat_at every 30 seconds. A fresh heartbeat is the
23
+ // portable liveness signal for callers inside a sandbox/PID namespace, where
24
+ // process.kill(pid, 0) can incorrectly report a live host peer as ESRCH.
25
+ const REGISTRY_HEARTBEAT_FRESH_MS = 90_000;
26
+
27
+ // Registry paths are shared by every coms participant. Keep their components
28
+ // conservative so callers cannot escape the project/name directory structure.
29
+ export const COMS_PROJECT_SAFE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
30
+ export const COMS_NAME_SAFE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
31
+
32
+ export function validateComsProject(project: string): string {
33
+ if (
34
+ project.length === 0 ||
35
+ project === "." ||
36
+ project.includes("..") ||
37
+ project.includes("/") ||
38
+ project.includes("\\") ||
39
+ !COMS_PROJECT_SAFE.test(project)
40
+ ) {
41
+ throw new Error(`Invalid project name: ${JSON.stringify(project)}`);
42
+ }
43
+ return project;
44
+ }
45
+
46
+ export function validateComsName(name: string): string {
47
+ if (!COMS_NAME_SAFE.test(name)) throw new Error(`Invalid coms name: ${JSON.stringify(name)}`);
48
+ if (name === "projects") throw new Error(`Invalid reserved coms name: ${JSON.stringify(name)}`);
49
+ return name;
50
+ }
51
+
52
+ // ━━ Envelope shapes (mirror coms/index.ts) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
53
+
54
+ export interface PromptEnvelope {
55
+ type: "prompt";
56
+ msg_id: string;
57
+ sender_session: string;
58
+ sender_endpoint: string;
59
+ hops: number;
60
+ timestamp: string;
61
+ prompt: string;
62
+ sender_name: string;
63
+ sender_cwd: string;
64
+ conversation_id?: string | null;
65
+ response_schema?: object | null;
66
+ /**
67
+ * How long the sender is prepared to wait, in ms. A receiver that drives an
68
+ * interactive agent uses this instead of its own default — otherwise a caller
69
+ * asking for 30 minutes is still failed at the bridge's 10-minute default.
70
+ */
71
+ reply_timeout_ms?: number | null;
72
+ }
73
+
74
+ export interface ResponseEnvelope {
75
+ type: "response";
76
+ msg_id: string;
77
+ sender_session: string;
78
+ sender_endpoint: string;
79
+ hops: number;
80
+ timestamp: string;
81
+ response: unknown;
82
+ error?: string | null;
83
+ }
84
+
85
+ export interface CancelEnvelope {
86
+ type: "cancel";
87
+ msg_id: string;
88
+ from: string;
89
+ to: string;
90
+ created_at: string;
91
+ ref_msg_id: string;
92
+ }
93
+
94
+ /**
95
+ * How addressable a peer is right now.
96
+ * idle — will pick up a `coms_send` immediately
97
+ * working — mid-turn (or blocked on its own permission prompt); a send waits
98
+ * booting — registered, but nothing has reported a live state yet
99
+ *
100
+ * Published so a sender can check before sending instead of screen-scraping the
101
+ * pane: the session behind this change issued 127 `herdr_read_pane` calls
102
+ * substituting for this one missing field.
103
+ */
104
+ export type PeerStatus = "idle" | "working" | "booting";
105
+
106
+ const PANE_STATUS_WORKING = new Set(["working", "blocked"]);
107
+ const PANE_STATUS_IDLE = new Set(["idle", "done", "ready"]);
108
+
109
+ /**
110
+ * Map a herdr pane's `agent_status` onto a peer status. Anything unrecognised —
111
+ * including the "unknown" herdr reports for a pane whose agent has not checked
112
+ * in — is `booting`: not addressable yet, but not a failure either.
113
+ */
114
+ export function paneAgentStatusToPeerStatus(agentStatus: string | null | undefined): PeerStatus {
115
+ const s = String(agentStatus ?? "").trim().toLowerCase();
116
+ if (PANE_STATUS_WORKING.has(s)) return "working";
117
+ if (PANE_STATUS_IDLE.has(s)) return "idle";
118
+ return "booting";
119
+ }
120
+
121
+ /** Display form; a peer that never answered the ping has no status of its own. */
122
+ export function peerStatusLabel(status: PeerStatus | null | undefined): string {
123
+ return status ?? "unreachable";
124
+ }
125
+
126
+ export interface AgentCard {
127
+ name: string;
128
+ purpose: string;
129
+ model: string;
130
+ color: string;
131
+ context_used_pct: number;
132
+ queue_depth: number;
133
+ /** herdr pane hosting this peer, when it runs in one. */
134
+ pane_id?: string | null;
135
+ /** Addressability right now — see PeerStatus. Absent on pre-status peers. */
136
+ status?: PeerStatus;
137
+ }
138
+
139
+ export interface RegistryEntry {
140
+ session_id: string;
141
+ name: string;
142
+ purpose: string;
143
+ model: string;
144
+ color: string;
145
+ pid: number;
146
+ endpoint: string;
147
+ cwd: string;
148
+ started_at: string;
149
+ explicit: boolean;
150
+ version: number;
151
+ context_used_pct?: number;
152
+ queue_depth?: number;
153
+ heartbeat_at?: string;
154
+ }
155
+
156
+ // ━━ ids / misc ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
157
+
158
+ const CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
159
+
160
+ export function ulid(): string {
161
+ const time = Date.now();
162
+ const rand = crypto.randomBytes(10);
163
+ let timeStr = "";
164
+ let t = time;
165
+ for (let i = 9; i >= 0; i--) {
166
+ timeStr = CROCKFORD[t % 32] + timeStr;
167
+ t = Math.floor(t / 32);
168
+ }
169
+ let randStr = "";
170
+ let bits = 0;
171
+ let value = 0;
172
+ for (const byte of rand) {
173
+ value = (value << 8) | byte;
174
+ bits += 8;
175
+ while (bits >= 5) {
176
+ bits -= 5;
177
+ randStr += CROCKFORD[(value >> bits) & 31];
178
+ }
179
+ }
180
+ return (timeStr + randStr).slice(0, 26);
181
+ }
182
+
183
+ export function nowIso(): string {
184
+ return new Date().toISOString();
185
+ }
186
+
187
+ export function makeEndpoint(sessionId: string): string {
188
+ if (process.platform === "win32") {
189
+ return `\\\\.\\pipe\\pi-coms-${sessionId}`;
190
+ }
191
+ return path.join(COMS_DIR, "sockets", `${sessionId}.sock`);
192
+ }
193
+
194
+ // ━━ Envelope constructors ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
195
+
196
+ export interface SenderIdentity {
197
+ session_id: string;
198
+ name: string;
199
+ endpoint: string;
200
+ cwd: string;
201
+ }
202
+
203
+ export function makePromptEnvelope(
204
+ from: SenderIdentity,
205
+ prompt: string,
206
+ opts: { hops?: number; response_schema?: object | null; reply_timeout_ms?: number | null } = {},
207
+ ): PromptEnvelope {
208
+ return {
209
+ type: "prompt",
210
+ msg_id: ulid(),
211
+ sender_session: from.session_id,
212
+ sender_endpoint: from.endpoint,
213
+ hops: opts.hops ?? 0,
214
+ timestamp: nowIso(),
215
+ prompt,
216
+ sender_name: from.name,
217
+ sender_cwd: from.cwd,
218
+ conversation_id: null,
219
+ response_schema: opts.response_schema ?? null,
220
+ reply_timeout_ms: opts.reply_timeout_ms ?? null,
221
+ };
222
+ }
223
+
224
+ export function makeResponseEnvelope(
225
+ from: SenderIdentity,
226
+ msg_id: string,
227
+ response: unknown,
228
+ error: string | null = null,
229
+ ): ResponseEnvelope {
230
+ return {
231
+ type: "response",
232
+ msg_id,
233
+ sender_session: from.session_id,
234
+ sender_endpoint: from.endpoint,
235
+ hops: 0,
236
+ timestamp: nowIso(),
237
+ response,
238
+ error,
239
+ };
240
+ }
241
+
242
+ export function makeCancelEnvelope(options: {
243
+ from: string;
244
+ to: string;
245
+ ref_msg_id: string;
246
+ msg_id?: string;
247
+ created_at?: string;
248
+ }): CancelEnvelope {
249
+ return {
250
+ type: "cancel",
251
+ msg_id: options.msg_id ?? ulid(),
252
+ from: options.from,
253
+ to: options.to,
254
+ created_at: options.created_at ?? nowIso(),
255
+ ref_msg_id: options.ref_msg_id,
256
+ };
257
+ }
258
+
259
+ function isNonEmptyString(value: unknown): value is string {
260
+ return typeof value === "string" && value.length > 0;
261
+ }
262
+
263
+ export function isPromptEnvelope(obj: unknown): obj is PromptEnvelope {
264
+ const e = obj as PromptEnvelope;
265
+ return (
266
+ !!e &&
267
+ e.type === "prompt" &&
268
+ typeof e.msg_id === "string" &&
269
+ typeof e.prompt === "string" &&
270
+ typeof e.sender_endpoint === "string" &&
271
+ typeof e.hops === "number"
272
+ );
273
+ }
274
+
275
+ export function isResponseEnvelope(obj: unknown): obj is ResponseEnvelope {
276
+ const e = obj as ResponseEnvelope;
277
+ return !!e && e.type === "response" && typeof e.msg_id === "string" && "response" in e;
278
+ }
279
+
280
+ export function isCancelEnvelope(obj: unknown): obj is CancelEnvelope {
281
+ const e = obj as CancelEnvelope;
282
+ return (
283
+ !!e &&
284
+ e.type === "cancel" &&
285
+ isNonEmptyString(e.msg_id) &&
286
+ isNonEmptyString(e.from) &&
287
+ isNonEmptyString(e.to) &&
288
+ isNonEmptyString(e.created_at) &&
289
+ isNonEmptyString(e.ref_msg_id)
290
+ );
291
+ }
292
+
293
+ // ━━ Registry I/O (mirrors coms/index.ts semantics) ━━━━━━━━━━━━━━━━━━━━━━━━
294
+
295
+ export function projectAgentsDir(project: string): string {
296
+ return path.join(COMS_DIR, "projects", validateComsProject(project), "agents");
297
+ }
298
+
299
+ export function registryFilePath(project: string, name: string): string {
300
+ return path.join(projectAgentsDir(project), `${validateComsName(name)}.json`);
301
+ }
302
+
303
+ export function ensureComsDirs(project: string): void {
304
+ fs.mkdirSync(projectAgentsDir(project), { recursive: true });
305
+ if (process.platform !== "win32") {
306
+ fs.mkdirSync(path.join(COMS_DIR, "sockets"), { recursive: true });
307
+ try {
308
+ fs.chmodSync(COMS_DIR, 0o700);
309
+ } catch {
310
+ // best-effort
311
+ }
312
+ }
313
+ }
314
+
315
+ export function writeRegistryAtomic(entry: RegistryEntry, project: string): string {
316
+ validateComsName(entry.name);
317
+ const file = registryFilePath(project, entry.name);
318
+ const tmp = `${file}.tmp-${process.pid}-${Date.now()}`;
319
+ fs.writeFileSync(tmp, JSON.stringify(entry, null, 2));
320
+ fs.renameSync(tmp, file);
321
+ return file;
322
+ }
323
+
324
+ export function removeRegistryEntry(project: string, name: string): void {
325
+ try {
326
+ fs.unlinkSync(registryFilePath(project, name));
327
+ } catch {
328
+ // best-effort
329
+ }
330
+ }
331
+
332
+ export function readAllRegistryEntries(project: string): RegistryEntry[] {
333
+ const dir = projectAgentsDir(project);
334
+ let files: string[];
335
+ try {
336
+ files = fs.readdirSync(dir).filter((f) => f.endsWith(".json"));
337
+ } catch (error) {
338
+ if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
339
+ throw new Error(`Unable to read coms registry ${dir}: ${(error as NodeJS.ErrnoException).code ?? "unknown error"}`);
340
+ }
341
+ const out: RegistryEntry[] = [];
342
+ for (const f of files) {
343
+ try {
344
+ const e = JSON.parse(fs.readFileSync(path.join(dir, f), "utf-8")) as RegistryEntry;
345
+ if (e && typeof e.name === "string" && typeof e.endpoint === "string") out.push(e);
346
+ } catch {
347
+ // unparseable entry — skip
348
+ }
349
+ }
350
+ return out;
351
+ }
352
+
353
+ export function registryHeartbeatIsFresh(entry: RegistryEntry, now = Date.now()): boolean {
354
+ if (!entry.heartbeat_at) return false;
355
+ const heartbeat = Date.parse(entry.heartbeat_at);
356
+ if (!Number.isFinite(heartbeat)) return false;
357
+ const age = now - heartbeat;
358
+ return age >= -5_000 && age <= REGISTRY_HEARTBEAT_FRESH_MS;
359
+ }
360
+
361
+ // A fresh heartbeat wins before the PID probe because Codex remote commands
362
+ // can execute in a distinct PID namespace. For entries without a fresh
363
+ // heartbeat, preserve the harness rule: ESRCH removes; EPERM counts as live.
364
+ export function pruneDeadEntries(project: string): RegistryEntry[] {
365
+ const live: RegistryEntry[] = [];
366
+ for (const entry of readAllRegistryEntries(project)) {
367
+ if (registryHeartbeatIsFresh(entry)) {
368
+ live.push(entry);
369
+ continue;
370
+ }
371
+ try {
372
+ process.kill(entry.pid, 0);
373
+ live.push(entry);
374
+ } catch (e) {
375
+ if ((e as NodeJS.ErrnoException)?.code === "ESRCH") {
376
+ removeRegistryEntry(project, entry.name);
377
+ } else {
378
+ live.push(entry);
379
+ }
380
+ }
381
+ }
382
+ return live;
383
+ }
384
+
385
+ export function resolveUniqueName(project: string, desiredName: string): string {
386
+ validateComsName(desiredName);
387
+ const liveNames = new Set(pruneDeadEntries(project).map((e) => e.name));
388
+ if (!liveNames.has(desiredName)) return desiredName;
389
+ let n = 2;
390
+ while (liveNames.has(`${desiredName}${n}`)) n++;
391
+ return `${desiredName}${n}`;
392
+ }
393
+
394
+ // ━━ Transport (mirrors coms/index.ts) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
395
+
396
+ export function readOneLine(socket: net.Socket): Promise<string> {
397
+ return new Promise((resolve, reject) => {
398
+ let buf = "";
399
+ let settled = false;
400
+ const onData = (chunk: Buffer) => {
401
+ buf += chunk.toString("utf-8");
402
+ if (buf.length > LINE_CAP_BYTES) {
403
+ if (settled) return;
404
+ settled = true;
405
+ socket.removeListener("data", onData);
406
+ reject(new Error("line too large"));
407
+ return;
408
+ }
409
+ const nl = buf.indexOf("\n");
410
+ if (nl >= 0) {
411
+ if (settled) return;
412
+ settled = true;
413
+ socket.removeListener("data", onData);
414
+ resolve(buf.slice(0, nl));
415
+ }
416
+ };
417
+ socket.on("data", onData);
418
+ socket.once("error", (err) => {
419
+ if (settled) return;
420
+ settled = true;
421
+ reject(err);
422
+ });
423
+ socket.once("close", () => {
424
+ if (settled) return;
425
+ settled = true;
426
+ reject(new Error("connection closed before line received"));
427
+ });
428
+ });
429
+ }
430
+
431
+ // Send one envelope, await the ack/nack (or pong) line. Rejects on nack.
432
+ export function sendEnvelope(
433
+ endpoint: string,
434
+ envelope: PromptEnvelope | ResponseEnvelope | CancelEnvelope | { type: string; msg_id?: string; [k: string]: unknown },
435
+ ): Promise<Record<string, unknown>> {
436
+ return new Promise((resolve, reject) => {
437
+ const sock = net.createConnection({ path: endpoint });
438
+ let settled = false;
439
+ const fail = (err: Error) => {
440
+ if (settled) return;
441
+ settled = true;
442
+ try {
443
+ sock.destroy();
444
+ } catch {
445
+ // ignore
446
+ }
447
+ reject(err);
448
+ };
449
+ sock.once("error", fail);
450
+ sock.once("connect", async () => {
451
+ try {
452
+ sock.write(JSON.stringify(envelope) + "\n");
453
+ const line = await readOneLine(sock);
454
+ const parsed = JSON.parse(line);
455
+ try {
456
+ sock.end();
457
+ } catch {
458
+ // ignore
459
+ }
460
+ if (settled) return;
461
+ settled = true;
462
+ if (parsed && parsed.type === "nack") {
463
+ reject(new Error(parsed.error || "nack"));
464
+ } else {
465
+ resolve(parsed);
466
+ }
467
+ } catch (err) {
468
+ fail(err instanceof Error ? err : new Error(String(err)));
469
+ }
470
+ });
471
+ });
472
+ }
473
+
474
+ function probeStaleSocket(endpoint: string): Promise<"in_use" | "stale"> {
475
+ return new Promise((resolve) => {
476
+ const sock = net.createConnection({ path: endpoint });
477
+ let settled = false;
478
+ const finish = (verdict: "in_use" | "stale") => {
479
+ if (settled) return;
480
+ settled = true;
481
+ try {
482
+ sock.destroy();
483
+ } catch {
484
+ // ignore
485
+ }
486
+ resolve(verdict);
487
+ };
488
+ const timer = setTimeout(() => finish("stale"), 250);
489
+ sock.once("connect", () => {
490
+ clearTimeout(timer);
491
+ finish("in_use");
492
+ });
493
+ sock.once("error", () => {
494
+ clearTimeout(timer);
495
+ finish("stale");
496
+ });
497
+ });
498
+ }
499
+
500
+ export async function bindEndpoint(
501
+ endpoint: string,
502
+ connHandler: (socket: net.Socket) => void,
503
+ ): Promise<net.Server> {
504
+ if (process.platform !== "win32" && fs.existsSync(endpoint)) {
505
+ const verdict = await probeStaleSocket(endpoint);
506
+ if (verdict === "in_use") {
507
+ throw new Error(`coms: endpoint already in use (${endpoint})`);
508
+ }
509
+ try {
510
+ fs.unlinkSync(endpoint);
511
+ } catch {
512
+ // best-effort
513
+ }
514
+ }
515
+ return await new Promise<net.Server>((resolve, reject) => {
516
+ const server = net.createServer(connHandler);
517
+ server.once("error", reject);
518
+ server.listen(endpoint, () => {
519
+ server.removeListener("error", reject);
520
+ resolve(server);
521
+ });
522
+ });
523
+ }
524
+
525
+ export function writeAck(socket: net.Socket, msg_id: string): void {
526
+ try {
527
+ socket.write(JSON.stringify({ type: "ack", msg_id }) + "\n");
528
+ } catch {
529
+ // ignore
530
+ }
531
+ try {
532
+ socket.end();
533
+ } catch {
534
+ // ignore
535
+ }
536
+ }
537
+
538
+ export function writeNack(socket: net.Socket, msg_id: string, error: string): void {
539
+ try {
540
+ socket.write(JSON.stringify({ type: "nack", msg_id, error }) + "\n");
541
+ } catch {
542
+ // ignore
543
+ }
544
+ try {
545
+ socket.end();
546
+ } catch {
547
+ // ignore
548
+ }
549
+ }
550
+
551
+ // Line-oriented connection handler factory: parses each ndjson line and
552
+ // dispatches; malformed lines are nacked.
553
+ export function makeConnHandler(
554
+ onEnvelope: (env: Record<string, unknown>, socket: net.Socket) => void,
555
+ ): (socket: net.Socket) => void {
556
+ return (socket) => {
557
+ let buf = "";
558
+ socket.on("error", () => {});
559
+ socket.on("data", (chunk) => {
560
+ buf += chunk.toString("utf-8");
561
+ if (buf.length > LINE_CAP_BYTES) {
562
+ writeNack(socket, "", "line too large");
563
+ socket.destroy();
564
+ return;
565
+ }
566
+ let nl: number;
567
+ while ((nl = buf.indexOf("\n")) !== -1) {
568
+ const line = buf.slice(0, nl);
569
+ buf = buf.slice(nl + 1);
570
+ if (!line.trim()) continue;
571
+ let parsed: Record<string, unknown>;
572
+ try {
573
+ parsed = JSON.parse(line);
574
+ } catch {
575
+ writeNack(socket, "", "invalid json");
576
+ continue;
577
+ }
578
+ onEnvelope(parsed, socket);
579
+ }
580
+ });
581
+ };
582
+ }
@@ -0,0 +1,88 @@
1
+ import * as fs from "node:fs";
2
+ import * as net from "node:net";
3
+ import { mkdtempSync } from "node:fs";
4
+ import { tmpdir } from "node:os";
5
+ import { join } from "node:path";
6
+
7
+ export interface FakeHerdrRequest {
8
+ id: string;
9
+ method: string;
10
+ params: Record<string, unknown>;
11
+ }
12
+
13
+ export class FakeHerdrServer {
14
+ public readonly requests: FakeHerdrRequest[] = [];
15
+ public readonly socketPath: string;
16
+ private readonly subscribers = new Set<net.Socket>();
17
+ private readonly server: net.Server;
18
+ private readonly root: string;
19
+ private workspaceId: string;
20
+ private readonly paneId: string;
21
+ private readonly resyncOutput: { sequence: number; text: string };
22
+
23
+ private constructor(socketPath: string, server: net.Server, root: string, paneId: string, workspaceId: string, resyncOutput: { sequence: number; text: string }) {
24
+ this.socketPath = socketPath;
25
+ this.server = server;
26
+ this.root = root;
27
+ this.paneId = paneId;
28
+ this.workspaceId = workspaceId;
29
+ this.resyncOutput = resyncOutput;
30
+ }
31
+
32
+ static async start(values: { paneId: string; workspaceId: string; resyncOutput?: { sequence: number; text: string } }): Promise<FakeHerdrServer> {
33
+ const root = mkdtempSync(join(tmpdir(), "fake-herdr-"));
34
+ const socketPath = join(root, "s");
35
+ let fake: FakeHerdrServer;
36
+ const server = net.createServer((socket) => {
37
+ let buffer = "";
38
+ socket.on("data", (chunk) => {
39
+ buffer += chunk.toString("utf8");
40
+ let newline: number;
41
+ while ((newline = buffer.indexOf("\n")) >= 0) {
42
+ const line = buffer.slice(0, newline);
43
+ buffer = buffer.slice(newline + 1);
44
+ if (!line) continue;
45
+ const request = JSON.parse(line) as FakeHerdrRequest;
46
+ fake.requests.push(request);
47
+ if (request.method === "events.subscribe") {
48
+ fake.subscribers.add(socket);
49
+ socket.write(JSON.stringify({ id: request.id, result: { type: "subscription_started" } }) + "\n");
50
+ continue;
51
+ }
52
+ const result = request.method === "pane.get"
53
+ ? { pane: { pane_id: fake.paneId, workspace_id: fake.workspaceId, monitor_resync_output: fake.resyncOutput } }
54
+ : request.method === "ping"
55
+ ? { type: "pong", version: "fake", protocol: 14 }
56
+ : {};
57
+ socket.end(JSON.stringify({ id: request.id, result }) + "\n");
58
+ }
59
+ });
60
+ socket.on("close", () => fake.subscribers.delete(socket));
61
+ });
62
+ fake = new FakeHerdrServer(socketPath, server, root, values.paneId, values.workspaceId, values.resyncOutput ?? { sequence: 0, text: "" });
63
+ await new Promise<void>((resolve, reject) => server.listen(socketPath, resolve).once("error", reject));
64
+ return fake;
65
+ }
66
+
67
+ setWorkspaceId(workspaceId: string): void {
68
+ this.workspaceId = workspaceId;
69
+ }
70
+
71
+ emitStatus(): void {
72
+ for (const socket of this.subscribers) socket.write(JSON.stringify({ event: "pane.agent_status_changed", data: { pane_id: this.paneId } }) + "\n");
73
+ }
74
+
75
+ disconnectSubscribers(): void {
76
+ for (const socket of this.subscribers) socket.destroy();
77
+ }
78
+
79
+ subscriptionCount(): number {
80
+ return this.requests.filter((request) => request.method === "events.subscribe").length;
81
+ }
82
+
83
+ async close(): Promise<void> {
84
+ this.disconnectSubscribers();
85
+ await new Promise<void>((resolve) => this.server.close(() => resolve()));
86
+ fs.rmSync(this.root, { recursive: true, force: true });
87
+ }
88
+ }