@chankov/agent-fleet 0.0.2 → 0.0.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude/commands/doctor-agent-fleet.md +1 -1
- package/.claude/commands/setup-agent-fleet.md +5 -5
- package/.opencode/commands/af-doctor-agent-fleet.md +2 -0
- package/.opencode/commands/af-setup-agent-fleet.md +1 -1
- package/.pi/agents/peers.yaml +4 -0
- package/.pi/agents/teams.yaml +2 -2
- package/.pi/harnesses/agent-hub/README.md +254 -18
- package/.pi/harnesses/agent-hub/access-approval.ts +135 -0
- package/.pi/harnesses/agent-hub/delegate.ts +32 -9
- package/.pi/harnesses/agent-hub/drift-watchdog.js +165 -0
- package/.pi/harnesses/agent-hub/footer.ts +29 -0
- package/.pi/harnesses/agent-hub/helpers.ts +49 -0
- package/.pi/harnesses/agent-hub/index.ts +1269 -322
- package/.pi/harnesses/agent-hub/monitor-control.ts +9 -0
- package/.pi/harnesses/agent-hub/monitor-lifecycle.ts +13 -0
- package/.pi/harnesses/agent-hub/monitor-publisher.ts +59 -0
- package/.pi/harnesses/agent-hub/monitor-recovery.ts +3 -0
- package/.pi/harnesses/agent-hub/monitor-runtime.ts +3 -0
- package/.pi/harnesses/agent-hub/monitor-session-bridge.ts +11 -0
- package/.pi/harnesses/agent-hub/package.json +5 -4
- package/.pi/harnesses/agent-hub/research-retention.js +34 -0
- package/.pi/harnesses/agent-hub/research-watchdog.ts +40 -0
- package/.pi/harnesses/agent-hub/run-budget.js +155 -0
- package/.pi/harnesses/agent-hub/safety-routing.ts +22 -0
- package/.pi/harnesses/agent-hub/spawn.ts +161 -94
- package/.pi/harnesses/agent-hub/version.ts +18 -0
- package/.pi/harnesses/ask-user-remote/README.md +2 -0
- package/.pi/harnesses/coms/README.md +21 -0
- package/.pi/harnesses/coms/index.ts +2 -0
- package/.pi/harnesses/coms/package.json +5 -4
- package/.pi/harnesses/coms/version.ts +18 -0
- package/.pi/harnesses/damage-control-continue/README.md +32 -31
- package/.pi/harnesses/damage-control-continue/index.ts +23 -9
- package/.pi/harnesses/damage-control-continue/package.json +5 -4
- package/.pi/harnesses/damage-control-continue/version.ts +18 -0
- package/.pi/harnesses/{damage-control/shared.ts → lib/damage-control-shared.ts} +20 -6
- package/.pi/prompts/doctor-agent-fleet.md +1 -1
- package/.pi/prompts/setup-agent-fleet.md +5 -5
- package/.versions/0.0.4/.claude/commands/build.md +44 -0
- package/.versions/0.0.4/.claude/commands/code-simplify.md +22 -0
- package/.versions/0.0.4/.claude/commands/design-agent.md +14 -0
- package/.versions/0.0.4/.claude/commands/doctor-agent-fleet.md +17 -0
- package/.versions/0.0.4/.claude/commands/orchestrate.md +112 -0
- package/.versions/0.0.4/.claude/commands/plan.md +16 -0
- package/.versions/0.0.4/.claude/commands/prime.md +22 -0
- package/.versions/0.0.4/.claude/commands/review.md +16 -0
- package/.versions/0.0.4/.claude/commands/setup-agent-fleet.md +25 -0
- package/.versions/0.0.4/.claude/commands/ship.md +72 -0
- package/.versions/0.0.4/.claude/commands/spec.md +15 -0
- package/.versions/0.0.4/.claude/commands/test.md +19 -0
- package/.versions/0.0.4/.claude/commands/webperf.md +32 -0
- package/.versions/0.0.4/.claude/orchestrate-teams.yaml +24 -0
- package/.versions/0.0.4/.opencode/commands/af-build.md +17 -0
- package/.versions/0.0.4/.opencode/commands/af-code-simplify.md +16 -0
- package/.versions/0.0.4/.opencode/commands/af-compound.md +16 -0
- package/.versions/0.0.4/.opencode/commands/af-design-agent.md +15 -0
- package/.versions/0.0.4/.opencode/commands/af-doctor-agent-fleet.md +17 -0
- package/.versions/0.0.4/.opencode/commands/af-orchestrate.md +112 -0
- package/.versions/0.0.4/.opencode/commands/af-plan.md +16 -0
- package/.versions/0.0.4/.opencode/commands/af-prime.md +22 -0
- package/.versions/0.0.4/.opencode/commands/af-review.md +15 -0
- package/.versions/0.0.4/.opencode/commands/af-setup-agent-fleet.md +15 -0
- package/.versions/0.0.4/.opencode/commands/af-ship.md +16 -0
- package/.versions/0.0.4/.opencode/commands/af-spec.md +16 -0
- package/.versions/0.0.4/.opencode/commands/af-test.md +21 -0
- package/.versions/0.0.4/.opencode/commands/af-webperf.md +32 -0
- package/.versions/0.0.4/.opencode/orchestrate-teams.yaml +24 -0
- package/.versions/0.0.4/.pi/agents/dispatch-policy.yaml +32 -0
- package/.versions/0.0.4/.pi/agents/model-profiles.yaml +20 -0
- package/.versions/0.0.4/.pi/agents/peers.yaml +146 -0
- package/.versions/0.0.4/.pi/agents/teams.yaml +39 -0
- package/.versions/0.0.4/.pi/damage-control-rules.yaml +297 -0
- package/.versions/0.0.4/.pi/extensions/agent-fleet-update-check/README.md +58 -0
- package/.versions/0.0.4/.pi/extensions/agent-fleet-update-check/index.ts +161 -0
- package/{.pi/harnesses/damage-control → .versions/0.0.4/.pi/extensions/agent-fleet-update-check}/package.json +1 -1
- package/.versions/0.0.4/.pi/extensions/btw/README.md +118 -0
- package/.versions/0.0.4/.pi/extensions/btw/index.ts +917 -0
- package/.versions/0.0.4/.pi/extensions/btw/package.json +6 -0
- package/.versions/0.0.4/.pi/extensions/btw/state.js +179 -0
- package/.versions/0.0.4/.pi/extensions/chrome-devtools-mcp/README.md +58 -0
- package/.versions/0.0.4/.pi/extensions/chrome-devtools-mcp/index.ts +92 -0
- package/.versions/0.0.4/.pi/extensions/chrome-devtools-mcp/package.json +6 -0
- package/.versions/0.0.4/.pi/extensions/compact-and-continue/README.md +42 -0
- package/.versions/0.0.4/.pi/extensions/compact-and-continue/index.ts +120 -0
- package/.versions/0.0.4/.pi/extensions/compact-and-continue/package.json +6 -0
- package/.versions/0.0.4/.pi/extensions/mcp-bridge/README.md +46 -0
- package/.versions/0.0.4/.pi/extensions/mcp-bridge/index.ts +206 -0
- package/.versions/0.0.4/.pi/extensions/mcp-bridge/package.json +6 -0
- package/.versions/0.0.4/.pi/extensions/package-lock.json +1143 -0
- package/.versions/0.0.4/.pi/extensions/package.json +9 -0
- package/.versions/0.0.4/.pi/extensions/pi-voice-stt/README.md +201 -0
- package/.versions/0.0.4/.pi/extensions/pi-voice-stt/config.ts +198 -0
- package/.versions/0.0.4/.pi/extensions/pi-voice-stt/examples/stt.json +35 -0
- package/.versions/0.0.4/.pi/extensions/pi-voice-stt/index.ts +248 -0
- package/.versions/0.0.4/.pi/extensions/pi-voice-stt/package.json +6 -0
- package/.versions/0.0.4/.pi/extensions/pi-voice-stt/providers.ts +214 -0
- package/.versions/0.0.4/.pi/extensions/pi-voice-stt/recorder.ts +158 -0
- package/.versions/0.0.4/.pi/harnesses/agent-hub/README.md +798 -0
- package/.versions/0.0.4/.pi/harnesses/agent-hub/access-approval.ts +135 -0
- package/.versions/0.0.4/.pi/harnesses/agent-hub/artifacts.js +92 -0
- package/.versions/0.0.4/.pi/harnesses/agent-hub/backend-policy.js +153 -0
- package/.versions/0.0.4/.pi/harnesses/agent-hub/delegate.ts +386 -0
- package/.versions/0.0.4/.pi/harnesses/agent-hub/drift-watchdog.js +165 -0
- package/.versions/0.0.4/.pi/harnesses/agent-hub/evidence-rules.js +96 -0
- package/.versions/0.0.4/.pi/harnesses/agent-hub/footer.ts +29 -0
- package/.versions/0.0.4/.pi/harnesses/agent-hub/helpers.ts +214 -0
- package/.versions/0.0.4/.pi/harnesses/agent-hub/index.ts +8045 -0
- package/.versions/0.0.4/.pi/harnesses/agent-hub/monitor-control.ts +9 -0
- package/.versions/0.0.4/.pi/harnesses/agent-hub/monitor-lifecycle.ts +13 -0
- package/.versions/0.0.4/.pi/harnesses/agent-hub/monitor-publisher.ts +59 -0
- package/.versions/0.0.4/.pi/harnesses/agent-hub/monitor-recovery.ts +3 -0
- package/.versions/0.0.4/.pi/harnesses/agent-hub/monitor-runtime.ts +3 -0
- package/.versions/0.0.4/.pi/harnesses/agent-hub/monitor-session-bridge.ts +11 -0
- package/.versions/0.0.4/.pi/harnesses/agent-hub/package.json +7 -0
- package/.versions/0.0.4/.pi/harnesses/agent-hub/research-retention.js +34 -0
- package/.versions/0.0.4/.pi/harnesses/agent-hub/research-watchdog.ts +40 -0
- package/.versions/0.0.4/.pi/harnesses/agent-hub/return-contract.js +215 -0
- package/.versions/0.0.4/.pi/harnesses/agent-hub/run-budget.js +155 -0
- package/.versions/0.0.4/.pi/harnesses/agent-hub/safety-routing.ts +22 -0
- package/.versions/0.0.4/.pi/harnesses/agent-hub/scope-gate.js +103 -0
- package/.versions/0.0.4/.pi/harnesses/agent-hub/spawn.ts +246 -0
- package/.versions/0.0.4/.pi/harnesses/agent-hub/version.ts +18 -0
- package/.versions/0.0.4/.pi/harnesses/ask-user-remote/README.md +18 -0
- package/.versions/0.0.4/.pi/harnesses/ask-user-remote/index.ts +293 -0
- package/.versions/0.0.4/.pi/harnesses/ask-user-remote/race-core.js +106 -0
- package/.versions/0.0.4/.pi/harnesses/coms/README.md +92 -0
- package/.versions/0.0.4/.pi/harnesses/coms/index.ts +1745 -0
- package/.versions/0.0.4/.pi/harnesses/coms/package.json +7 -0
- package/.versions/0.0.4/.pi/harnesses/coms/version.ts +18 -0
- package/.versions/0.0.4/.pi/harnesses/damage-control-continue/README.md +117 -0
- package/.versions/0.0.4/.pi/harnesses/damage-control-continue/index.ts +536 -0
- package/.versions/0.0.4/.pi/harnesses/damage-control-continue/package.json +7 -0
- package/.versions/0.0.4/.pi/harnesses/damage-control-continue/version.ts +18 -0
- package/.versions/0.0.4/.pi/harnesses/lib/damage-control-shared.ts +197 -0
- package/.versions/0.0.4/.pi/harnesses/lib/herdr-client.ts +458 -0
- package/.versions/0.0.4/.pi/harnesses/lib/herdr-presence.ts +288 -0
- package/.versions/0.0.4/.pi/harnesses/package-lock.json +35 -0
- package/.versions/0.0.4/.pi/harnesses/package.json +9 -0
- package/.versions/0.0.4/.pi/prompts/build.md +24 -0
- package/.versions/0.0.4/.pi/prompts/code-simplify.md +22 -0
- package/.versions/0.0.4/.pi/prompts/doctor-agent-fleet.md +15 -0
- package/.versions/0.0.4/.pi/prompts/plan.md +16 -0
- package/.versions/0.0.4/.pi/prompts/review.md +16 -0
- package/.versions/0.0.4/.pi/prompts/setup-agent-fleet.md +27 -0
- package/.versions/0.0.4/.pi/prompts/ship.md +17 -0
- package/.versions/0.0.4/.pi/prompts/spec.md +15 -0
- package/.versions/0.0.4/.pi/prompts/test.md +19 -0
- package/.versions/0.0.4/.pi/skills/bowser/SKILL.md +145 -0
- package/.versions/0.0.4/.version +1 -0
- package/.versions/0.0.4/agents/architect.md +23 -0
- package/.versions/0.0.4/agents/bowser.md +26 -0
- package/.versions/0.0.4/agents/builder.md +53 -0
- package/.versions/0.0.4/agents/code-reviewer.md +205 -0
- package/.versions/0.0.4/agents/deep-researcher.md +31 -0
- package/.versions/0.0.4/agents/documenter.md +18 -0
- package/.versions/0.0.4/agents/orchestrator.md +54 -0
- package/.versions/0.0.4/agents/plan-reviewer.md +60 -0
- package/.versions/0.0.4/agents/planner.md +69 -0
- package/.versions/0.0.4/agents/releaser.md +24 -0
- package/.versions/0.0.4/agents/researcher.md +28 -0
- package/.versions/0.0.4/agents/security-auditor.md +166 -0
- package/.versions/0.0.4/agents/test-engineer.md +151 -0
- package/.versions/0.0.4/agents/web-debugger.md +42 -0
- package/.versions/0.0.4/agents/web-performance-auditor.md +192 -0
- package/.versions/0.0.4/codex/CONDUCTOR.md +148 -0
- package/.versions/0.0.4/docs/ARCHITECTURE.md +210 -0
- package/.versions/0.0.4/docs/agent-fleet-setup.md +366 -0
- package/.versions/0.0.4/docs/claude-code-coms-bridge.md +103 -0
- package/.versions/0.0.4/docs/codex-remote-conductor.md +170 -0
- package/.versions/0.0.4/docs/coms-hermes-bridge.md +121 -0
- package/.versions/0.0.4/docs/getting-started.md +183 -0
- package/.versions/0.0.4/docs/npm-install.md +337 -0
- package/.versions/0.0.4/docs/opencode-setup.md +248 -0
- package/.versions/0.0.4/docs/pi-extensions.md +288 -0
- package/.versions/0.0.4/docs/pi-setup.md +463 -0
- package/.versions/0.0.4/docs/skill-anatomy.md +150 -0
- package/.versions/0.0.4/hermes/README.md +228 -0
- package/.versions/0.0.4/hermes/desktop-plugins/agent-fleet-monitor/plugin.js +19 -0
- package/.versions/0.0.4/hermes/desktop-plugins/agent-fleet-monitor/state.js +10 -0
- package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/adapter-cap.test.py +15 -0
- package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/adapter-discovery.test.py +19 -0
- package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/adapter-envelope.test.py +13 -0
- package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/adapter-forged-owner.test.py +11 -0
- package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/adapter-lease-list.test.py +9 -0
- package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/adapter-multihub.test.py +17 -0
- package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/adapter-output.test.py +34 -0
- package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/adapter.py +151 -0
- package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/adapter.test.py +39 -0
- package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/manifest.json +11 -0
- package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/plugin-api-validation.test.py +12 -0
- package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/plugin_api.py +50 -0
- package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/review-live-wiring.red.test.py +22 -0
- package/.versions/0.0.4/hermes/skills/hub-conductor/SKILL.md +84 -0
- package/.versions/0.0.4/hermes/skills/hub-liaison/SKILL.md +84 -0
- package/.versions/0.0.4/hooks/SIMPLIFY-IGNORE.md +90 -0
- package/.versions/0.0.4/hooks/coms-stop-hook.mjs +73 -0
- package/.versions/0.0.4/hooks/hooks.json +14 -0
- package/.versions/0.0.4/hooks/session-start.sh +74 -0
- package/.versions/0.0.4/hooks/simplify-ignore.sh +302 -0
- package/.versions/0.0.4/justfile +256 -0
- package/.versions/0.0.4/references/accessibility-checklist.md +160 -0
- package/.versions/0.0.4/references/definition-of-done.md +67 -0
- package/.versions/0.0.4/references/fleet-coordination-patterns.md +151 -0
- package/.versions/0.0.4/references/observability-checklist.md +91 -0
- package/.versions/0.0.4/references/orchestration-patterns.md +370 -0
- package/.versions/0.0.4/references/performance-checklist.md +153 -0
- package/.versions/0.0.4/references/prompting-patterns.md +380 -0
- package/.versions/0.0.4/references/security-checklist.md +179 -0
- package/.versions/0.0.4/references/testing-patterns.md +236 -0
- package/.versions/0.0.4/scripts/codex-conductor.ts +41 -0
- package/.versions/0.0.4/scripts/codex-remote-control.ts +167 -0
- package/.versions/0.0.4/scripts/coms-claude-bridge.ts +286 -0
- package/.versions/0.0.4/scripts/coms-cli.ts +484 -0
- package/.versions/0.0.4/scripts/coms-hermes-bridge.ts +403 -0
- package/.versions/0.0.4/scripts/hermes-monitor-capability-runner.ts +25 -0
- package/.versions/0.0.4/scripts/hermes-monitor-scenario.ts +7 -0
- package/.versions/0.0.4/scripts/lib/claude-bridge-core.ts +100 -0
- package/.versions/0.0.4/scripts/lib/codex-conductor.ts +88 -0
- package/.versions/0.0.4/scripts/lib/codex-remote-control.ts +480 -0
- package/.versions/0.0.4/scripts/lib/coms-envelope.ts +539 -0
- package/.versions/0.0.4/scripts/lib/fake-herdr-server.ts +88 -0
- package/.versions/0.0.4/scripts/lib/herdr-layout.ts +263 -0
- package/.versions/0.0.4/scripts/lib/hermes-bridge-core.ts +238 -0
- package/.versions/0.0.4/scripts/lib/hermes-monitor-herdr.ts +28 -0
- package/.versions/0.0.4/scripts/lib/hermes-monitor-model.ts +9 -0
- package/.versions/0.0.4/scripts/lib/hermes-monitor-registry.ts +6 -0
- package/.versions/0.0.4/scripts/lib/hermes-monitor-socket.ts +118 -0
- package/.versions/0.0.4/scripts/lib/hermes-monitor-store.ts +31 -0
- package/.versions/0.0.4/scripts/lib/persona-banner.ts +62 -0
- package/.versions/0.0.4/scripts/lib/spawn-stagger.ts +101 -0
- package/.versions/0.0.4/scripts/lib/team-project.ts +184 -0
- package/.versions/0.0.4/scripts/lib/team-snapshot.ts +147 -0
- package/.versions/0.0.4/scripts/peer-banner.ts +40 -0
- package/.versions/0.0.4/scripts/team-snapshot.ts +238 -0
- package/.versions/0.0.4/scripts/team-up.ts +333 -0
- package/.versions/0.0.4/skills/_internal/grilling.md +11 -0
- package/.versions/0.0.4/skills/browser-testing-with-devtools/SKILL.md +352 -0
- package/.versions/0.0.4/skills/code-review-and-quality/SKILL.md +381 -0
- package/.versions/0.0.4/skills/compound-learning/SKILL.md +137 -0
- package/.versions/0.0.4/skills/context-engineering/SKILL.md +291 -0
- package/.versions/0.0.4/skills/deprecation-and-migration/SKILL.md +206 -0
- package/.versions/0.0.4/skills/designing-agents/SKILL.md +394 -0
- package/.versions/0.0.4/skills/designing-agents/pi-harness-authoring.md +222 -0
- package/.versions/0.0.4/skills/frontend-ui-engineering/SKILL.md +328 -0
- package/.versions/0.0.4/skills/git-workflow-and-versioning/SKILL.md +316 -0
- package/.versions/0.0.4/skills/guided-workspace-setup/SKILL.md +535 -0
- package/.versions/0.0.4/skills/guided-workspace-setup/companion-manifest.json +33 -0
- package/.versions/0.0.4/skills/idea-refine/SKILL.md +182 -0
- package/.versions/0.0.4/skills/idea-refine/examples.md +238 -0
- package/.versions/0.0.4/skills/idea-refine/frameworks.md +99 -0
- package/.versions/0.0.4/skills/idea-refine/refinement-criteria.md +113 -0
- package/.versions/0.0.4/skills/idea-refine/scripts/idea-refine.sh +15 -0
- package/.versions/0.0.4/skills/incremental-implementation/SKILL.md +287 -0
- package/.versions/0.0.4/skills/interview-me/SKILL.md +226 -0
- package/.versions/0.0.4/skills/orchestration-verification/SKILL.md +181 -0
- package/.versions/0.0.4/skills/peer-coms/SKILL.md +90 -0
- package/.versions/0.0.4/skills/performance-optimization/SKILL.md +350 -0
- package/.versions/0.0.4/skills/planning-and-task-breakdown/SKILL.md +236 -0
- package/.versions/0.0.4/skills/security-and-hardening/SKILL.md +461 -0
- package/.versions/0.0.4/skills/spec-driven-development/SKILL.md +245 -0
- package/.versions/0.0.4/skills/using-agent-skills/SKILL.md +199 -0
- package/.versions/0.0.4/systemd/user/agent-fleet-codex-remote-control.service.in +23 -0
- package/.versions/0.0.4/vendor/agent-skills-upstream/LICENSE +21 -0
- package/.versions/0.0.4/vendor/agent-skills-upstream/README.md +11 -0
- package/.versions/0.0.4/vendor/agent-skills-upstream/skills/api-and-interface-design/SKILL.md +294 -0
- package/.versions/0.0.4/vendor/agent-skills-upstream/skills/browser-testing-with-devtools/SKILL.md +317 -0
- package/.versions/0.0.4/vendor/agent-skills-upstream/skills/ci-cd-and-automation/SKILL.md +390 -0
- package/.versions/0.0.4/vendor/agent-skills-upstream/skills/code-review-and-quality/SKILL.md +396 -0
- package/.versions/0.0.4/vendor/agent-skills-upstream/skills/code-simplification/SKILL.md +331 -0
- package/.versions/0.0.4/vendor/agent-skills-upstream/skills/context-engineering/SKILL.md +289 -0
- package/.versions/0.0.4/vendor/agent-skills-upstream/skills/debugging-and-error-recovery/SKILL.md +300 -0
- package/.versions/0.0.4/vendor/agent-skills-upstream/skills/deprecation-and-migration/SKILL.md +247 -0
- package/.versions/0.0.4/vendor/agent-skills-upstream/skills/documentation-and-adrs/SKILL.md +278 -0
- package/.versions/0.0.4/vendor/agent-skills-upstream/skills/doubt-driven-development/SKILL.md +243 -0
- package/.versions/0.0.4/vendor/agent-skills-upstream/skills/frontend-ui-engineering/SKILL.md +328 -0
- package/.versions/0.0.4/vendor/agent-skills-upstream/skills/git-workflow-and-versioning/SKILL.md +355 -0
- package/.versions/0.0.4/vendor/agent-skills-upstream/skills/idea-refine/SKILL.md +178 -0
- package/.versions/0.0.4/vendor/agent-skills-upstream/skills/idea-refine/examples.md +238 -0
- package/.versions/0.0.4/vendor/agent-skills-upstream/skills/idea-refine/frameworks.md +99 -0
- package/.versions/0.0.4/vendor/agent-skills-upstream/skills/idea-refine/refinement-criteria.md +113 -0
- package/.versions/0.0.4/vendor/agent-skills-upstream/skills/idea-refine/scripts/idea-refine.sh +15 -0
- package/.versions/0.0.4/vendor/agent-skills-upstream/skills/incremental-implementation/SKILL.md +249 -0
- package/.versions/0.0.4/vendor/agent-skills-upstream/skills/interview-me/SKILL.md +225 -0
- package/.versions/0.0.4/vendor/agent-skills-upstream/skills/observability-and-instrumentation/SKILL.md +203 -0
- package/.versions/0.0.4/vendor/agent-skills-upstream/skills/performance-optimization/SKILL.md +350 -0
- package/.versions/0.0.4/vendor/agent-skills-upstream/skills/planning-and-task-breakdown/SKILL.md +234 -0
- package/.versions/0.0.4/vendor/agent-skills-upstream/skills/security-and-hardening/SKILL.md +467 -0
- package/.versions/0.0.4/vendor/agent-skills-upstream/skills/shipping-and-launch/SKILL.md +310 -0
- package/.versions/0.0.4/vendor/agent-skills-upstream/skills/source-driven-development/SKILL.md +194 -0
- package/.versions/0.0.4/vendor/agent-skills-upstream/skills/spec-driven-development/SKILL.md +206 -0
- package/.versions/0.0.4/vendor/agent-skills-upstream/skills/test-driven-development/SKILL.md +383 -0
- package/.versions/0.0.4/vendor/agent-skills-upstream/skills/using-agent-skills/SKILL.md +191 -0
- package/CHANGELOG.md +53 -0
- package/README.md +103 -541
- package/agents/architect.md +1 -1
- package/agents/builder.md +1 -1
- package/agents/code-reviewer.md +1 -1
- package/agents/deep-researcher.md +3 -3
- package/agents/orchestrator.md +20 -11
- package/agents/plan-reviewer.md +3 -3
- package/agents/planner.md +1 -1
- package/agents/security-auditor.md +1 -1
- package/agents/test-engineer.md +11 -4
- package/bin/lib/validate-overrides.js +19 -0
- package/bin/snapshot-version.js +17 -1
- package/bin/sync-harness-versions.js +94 -0
- package/codex/CONDUCTOR.md +148 -0
- package/docs/ARCHITECTURE.md +210 -0
- package/docs/agent-fleet-setup.md +11 -0
- package/docs/claude-code-coms-bridge.md +10 -0
- package/docs/codex-remote-conductor.md +170 -0
- package/docs/coms-hermes-bridge.md +121 -0
- package/docs/getting-started.md +14 -0
- package/docs/npm-install.md +2 -0
- package/docs/pi-extensions.md +49 -14
- package/docs/pi-setup.md +12 -4
- package/hermes/README.md +228 -0
- package/hermes/desktop-plugins/agent-fleet-monitor/plugin.js +19 -0
- package/hermes/desktop-plugins/agent-fleet-monitor/state.js +10 -0
- package/hermes/plugins/agent-fleet-monitor/dashboard/adapter-cap.test.py +15 -0
- package/hermes/plugins/agent-fleet-monitor/dashboard/adapter-discovery.test.py +19 -0
- package/hermes/plugins/agent-fleet-monitor/dashboard/adapter-envelope.test.py +13 -0
- package/hermes/plugins/agent-fleet-monitor/dashboard/adapter-forged-owner.test.py +11 -0
- package/hermes/plugins/agent-fleet-monitor/dashboard/adapter-lease-list.test.py +9 -0
- package/hermes/plugins/agent-fleet-monitor/dashboard/adapter-multihub.test.py +17 -0
- package/hermes/plugins/agent-fleet-monitor/dashboard/adapter-output.test.py +34 -0
- package/hermes/plugins/agent-fleet-monitor/dashboard/adapter.py +151 -0
- package/hermes/plugins/agent-fleet-monitor/dashboard/adapter.test.py +39 -0
- package/hermes/plugins/agent-fleet-monitor/dashboard/dist/index.js +10 -0
- package/hermes/plugins/agent-fleet-monitor/dashboard/manifest.json +11 -0
- package/hermes/plugins/agent-fleet-monitor/dashboard/plugin-api-validation.test.py +12 -0
- package/hermes/plugins/agent-fleet-monitor/dashboard/plugin_api.py +50 -0
- package/hermes/plugins/agent-fleet-monitor/dashboard/review-live-wiring.red.test.py +22 -0
- package/hermes/skills/hub-conductor/SKILL.md +84 -0
- package/hermes/skills/hub-liaison/SKILL.md +84 -0
- package/justfile +106 -23
- package/package.json +17 -5
- package/scripts/codex-conductor.ts +41 -0
- package/scripts/codex-remote-control.ts +167 -0
- package/scripts/coms-cli.ts +311 -199
- package/scripts/coms-hermes-bridge.ts +2 -2
- package/scripts/lib/codex-conductor.ts +88 -0
- package/scripts/lib/codex-remote-control.ts +480 -0
- package/scripts/lib/coms-envelope.ts +51 -6
- package/scripts/lib/fake-herdr-server.ts +88 -0
- package/scripts/lib/herdr-layout.ts +18 -3
- package/scripts/lib/hermes-bridge-core.ts +4 -4
- package/scripts/lib/hermes-monitor-herdr.ts +28 -0
- package/scripts/lib/hermes-monitor-model.ts +9 -0
- package/scripts/lib/hermes-monitor-registry.ts +6 -0
- package/scripts/lib/hermes-monitor-socket.ts +118 -0
- package/scripts/lib/hermes-monitor-store.ts +31 -0
- package/scripts/lib/team-project.ts +85 -1
- package/scripts/team-up.ts +77 -18
- package/skills/designing-agents/SKILL.md +2 -2
- package/skills/designing-agents/pi-harness-authoring.md +26 -13
- package/skills/guided-workspace-setup/SKILL.md +131 -102
- package/skills/guided-workspace-setup/companion-manifest.json +33 -0
- package/skills/peer-coms/SKILL.md +9 -0
- package/systemd/user/agent-fleet-codex-remote-control.service.in +23 -0
- package/.pi/harnesses/damage-control/README.md +0 -65
- package/.pi/harnesses/damage-control/index.ts +0 -250
|
@@ -0,0 +1,210 @@
|
|
|
1
|
+
# Agent Fleet Architecture
|
|
2
|
+
|
|
3
|
+
Agent Fleet is a Pi-centered multi-agent orchestration system. This page maps
|
|
4
|
+
the runtime responsibilities and where each module lives in the repository.
|
|
5
|
+
|
|
6
|
+
## Runtime layers
|
|
7
|
+
|
|
8
|
+
| Layer | Role | Implementation |
|
|
9
|
+
| --- | --- | --- |
|
|
10
|
+
| **Pi Coding Agent** | Primary local runtime — runs the dispatcher and specialist subagents | `.pi/harnesses/`, `.pi/extensions/`, `.pi/agents/`, `.pi/prompts/` |
|
|
11
|
+
| **agent-hub** | Thin-context multi-agent harness: dispatcher + specialists + research helpers + Verification Contract | `.pi/harnesses/agent-hub/` |
|
|
12
|
+
| **Herdr** | Fleet/workspace control plane — spawns peer teams as tiled workspaces, presence via push events, snapshot/resume | [herdr.dev](https://herdr.dev); client in `.pi/harnesses/lib/herdr-client.ts`, layout in `scripts/lib/herdr-layout.ts` |
|
|
13
|
+
| **coms** | Peer communication protocol/data plane — envelope-based P2P messaging between agents | `.pi/harnesses/coms/`, `scripts/lib/coms-envelope.ts`, `scripts/coms-cli.ts` |
|
|
14
|
+
| **Claude Code bridge** | Makes an interactive Claude Code pane a bidirectional coms peer | `scripts/coms-claude-bridge.ts`, `hooks/coms-stop-hook.mjs`, `skills/peer-coms/` — see [claude-code-coms-bridge.md](claude-code-coms-bridge.md) |
|
|
15
|
+
| **Hermes bridge** | Remote human control — relays hub questions to Telegram, races phone vs. local answers, conductor/liaison skills | `scripts/coms-hermes-bridge.ts`, `.pi/harnesses/ask-user-remote/`, `hermes/skills/` — see [coms-hermes-bridge.md](coms-hermes-bridge.md) |
|
|
16
|
+
| **Hermes local monitor transport** | Local, authenticated visibility/control contract for hub-owned task generations; presentation is supplied by an external consumer | `.pi/harnesses/agent-hub/monitor-*.ts`, `scripts/lib/hermes-monitor-{model,store,registry,socket}.ts` — see [Hermes artifacts](../hermes/README.md#local-agent-hub-monitor-integration) |
|
|
17
|
+
| **Codex remote-control conductor** | Experimental outbound-only, user-systemd-managed Android conductor; verified on Codex CLI 0.144.x | `scripts/codex-remote-control.ts`, `scripts/codex-conductor.ts`, `codex/CONDUCTOR.md`, `systemd/user/`; runtime under `~/.local/state/agent-fleet/codex-conductor/` — see [codex-remote-conductor.md](codex-remote-conductor.md) |
|
|
18
|
+
| **Skill library** | Lifecycle workflows and quality gates every agent follows | `skills/` (native) + `vendor/agent-skills-upstream/skills/` (vendored) — see [UPSTREAM-SKILLS.md](UPSTREAM-SKILLS.md) |
|
|
19
|
+
| **Personas** | Reusable specialist definitions, transformed per harness | `agents/`, `bin/lib/transform-persona.js` |
|
|
20
|
+
|
|
21
|
+
## Fleet hierarchy
|
|
22
|
+
|
|
23
|
+
Agent Fleet is layered on purpose. Work flows **down** (delegate); evidence and status flow **up** — as compact structured returns, never raw dumps.
|
|
24
|
+
|
|
25
|
+
```mermaid
|
|
26
|
+
flowchart TD
|
|
27
|
+
You(["You · Hermes inbound relay · Codex outbound conductor on your phone"])
|
|
28
|
+
|
|
29
|
+
subgraph HUBL["HUB — thin dispatcher (just hub · just hub-team)"]
|
|
30
|
+
Hub["agent-hub harness + orchestrator persona<br/>routes tasks · owns the Verification Contract on disk<br/>never swallows research dumps into its own context"]
|
|
31
|
+
end
|
|
32
|
+
|
|
33
|
+
subgraph TEAML["TEAM — named roster (.pi/agents/teams.yaml)"]
|
|
34
|
+
Team["default: planner · plan-reviewer · builder · test-engineer · code-reviewer · documenter<br/>also: debug · frontend · security · hotfix · release · info"]
|
|
35
|
+
end
|
|
36
|
+
|
|
37
|
+
subgraph RESL["RESEARCH HELPERS — read-only, always available"]
|
|
38
|
+
Research["researcher (fast tier — simple reads)<br/>deep-researcher (deep tier — hard, cross-cutting questions)"]
|
|
39
|
+
end
|
|
40
|
+
|
|
41
|
+
subgraph SUBL["SUB-AGENTS — focused children, narrow tools + models"]
|
|
42
|
+
Subs["planner → scout · rules · risk<br/>plan-reviewer → feasibility · deps<br/>builder → recon · verifier<br/>test-engineer → coverage-scout · conventions<br/>code-reviewer → preflight · quality · perf · docs<br/>security-auditor → recon · input-sweep · secrets-sweep"]
|
|
43
|
+
end
|
|
44
|
+
|
|
45
|
+
You -->|task| Hub
|
|
46
|
+
Hub -->|"dispatch_agent — one persona = one specialist session"| Team
|
|
47
|
+
Hub -->|"spawn_research"| Research
|
|
48
|
+
Research -.->|"findings written to disk — hub gets paths, not dumps"| Hub
|
|
49
|
+
Team -->|"subagents: block (delegate_depth ≥ 1)"| Subs
|
|
50
|
+
Subs -.->|"results return to the parent agent only"| Team
|
|
51
|
+
Team -.->|"structured return + evidence"| Hub
|
|
52
|
+
Hub -.->|"one status line: Assertions: 2✓ 1○ 1✗"| You
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Every specialist session is one persona from [`agents/`](../agents/) — *skills* tell each agent **how** to work; *personas* define **who** they are (see [agents.md](agents.md)).
|
|
56
|
+
|
|
57
|
+
The same idea as a tree:
|
|
58
|
+
|
|
59
|
+
```text
|
|
60
|
+
hub (orchestrator)
|
|
61
|
+
├── team: default
|
|
62
|
+
│ ├── planner → scout · rules · risk
|
|
63
|
+
│ ├── plan-reviewer → feasibility · deps
|
|
64
|
+
│ ├── builder → recon · verifier
|
|
65
|
+
│ ├── test-engineer → coverage-scout · conventions
|
|
66
|
+
│ ├── code-reviewer → preflight · quality · perf · docs
|
|
67
|
+
│ └── documenter
|
|
68
|
+
├── research helpers (spawn_research, any time)
|
|
69
|
+
│ ├── researcher
|
|
70
|
+
│ └── deep-researcher
|
|
71
|
+
└── optional fleet peers (herdr + coms)
|
|
72
|
+
├── architect / releaser / web-debugger panes
|
|
73
|
+
├── Claude Code peer (coms bridge)
|
|
74
|
+
├── Hermes (phone human · inbound ask_user)
|
|
75
|
+
└── Codex Remote Control (Android · outbound coms delegation)
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
Composition rule: **the hub (or a slash command) orchestrates; personas do not invoke other personas as peers.** Specialists may only fan out to their configured **sub-agents**. Research helpers write findings to disk; the hub resumes specialists with paths, not raw dumps.
|
|
79
|
+
|
|
80
|
+
### Research search supervision
|
|
81
|
+
|
|
82
|
+
The shared `spawnPiAgent` seam supervises every `read`/`grep`/`find`/`ls` call from native
|
|
83
|
+
research helpers and nested delegate children. The supervisor tracks JSONL `toolCallId` values
|
|
84
|
+
independently, with a default 120-second deadline (`recon-search-timeout-s: 1..3600|off` under
|
|
85
|
+
`## agent-hub`). It is a per-tool watchdog; the whole-run bound is separate — the execution
|
|
86
|
+
mode's per-run deadline (`agent-turn-timeout-s`), which terminates a hung run as `turn_timeout`.
|
|
87
|
+
On timeout or caller cancellation it owns and terminates the child's process group (SIGTERM,
|
|
88
|
+
then SIGKILL after a bounded grace), has a separate settlement timer for missing `close`/pipe
|
|
89
|
+
drain, and reports timeout separately from cancellation. Research helpers and nested delegates
|
|
90
|
+
are each given safe process-group ownership; delegates forward parent termination so no detached
|
|
91
|
+
child is orphaned. Full pattern catalog: [references/orchestration-patterns.md](../references/orchestration-patterns.md).
|
|
92
|
+
|
|
93
|
+
### Execution modes & turn budgets
|
|
94
|
+
|
|
95
|
+
The hub enforces per-user-turn budgets in code (`run-budget.js`): `fast`/`standard`/`strict`
|
|
96
|
+
modes cap `dispatch_agent` calls, `spawn_research` calls, and wall clock per turn, set the
|
|
97
|
+
per-run deadline above, and control nested delegation. Exhausted budgets make the dispatch
|
|
98
|
+
tools refuse with "summarize and ask the user"; a new user message opens a fresh window.
|
|
99
|
+
Specialist context pressure is measured over input + cacheRead + cacheWrite, and specialist
|
|
100
|
+
sessions are recycled (fresh spawn instead of `-c` resume) after `session-recycle-runs` runs
|
|
101
|
+
or ≥60% measured context — resumed sessions otherwise re-bill their accumulated context on
|
|
102
|
+
every model call. Configured under `## agent-hub` (`mode`, `max-dispatches-per-turn`,
|
|
103
|
+
`max-research-per-turn`, `turn-wall-time-s`, `agent-turn-timeout-s`, `session-recycle-runs`);
|
|
104
|
+
switched live with `/hub-mode`.
|
|
105
|
+
|
|
106
|
+
On top of the mode sit three qualitative guardrails. **Task triage**: the dispatcher
|
|
107
|
+
classifies each turn via the `set_task_tier` tool (`trivial`/`small`/`feature`/`project`)
|
|
108
|
+
and the caps drop to min(mode, tier); a duplicate-dispatch guard refuses near-identical
|
|
109
|
+
re-dispatches within a turn. **Drift watchdog** (`drift-watchdog.js`): armed dispatches are
|
|
110
|
+
observed in-flight from the JSON event stream — deterministic rules (out-of-scope writes
|
|
111
|
+
against the declared `scope` globs, tool-call loops, consecutive failures, tool-call cap)
|
|
112
|
+
escalate to a one-shot cheap LLM judge whose DRIFTING/STUCK verdict terminates the run as
|
|
113
|
+
`drift_stop` (exit 125, partial output preserved); enabled per hub/agent/dispatch
|
|
114
|
+
(`watchdog` key, `/watchdog`, `watchdog` param). **Dynamic teams**: `/agents-add`,
|
|
115
|
+
`/agents-drop`, `/agents-save` restructure the roster live (the system prompt rebuilds
|
|
116
|
+
every turn), and the gated `team_adjust` tool lets the dispatcher itself adjust the roster
|
|
117
|
+
outside fast mode, with user notification. `/hub-report` accounts each turn's dispatches,
|
|
118
|
+
tokens (billed = input + cacheRead + cacheWrite), recycles, drift stops, and refusals.
|
|
119
|
+
|
|
120
|
+
## Runtime stack (tools the fleet sits on)
|
|
121
|
+
|
|
122
|
+
```mermaid
|
|
123
|
+
flowchart TD
|
|
124
|
+
AF["<b>Agent Fleet</b><br/>agent-hub · personas · skills · coms · bridges · CLI"]
|
|
125
|
+
AF -->|primary runtime| PI["<b>pi</b><br/>coding agent — loads harnesses,<br/>extensions, prompts, personas"]
|
|
126
|
+
AF -->|control plane| HERDR["<b>herdr</b><br/>tiled peer workspaces,<br/>presence, snapshot/resume"]
|
|
127
|
+
AF -->|peer + install target| CC["<b>Claude Code</b><br/>bidirectional peer via<br/>the coms bridge"]
|
|
128
|
+
AF -->|install target| OC["<b>OpenCode</b><br/>skill-driven execution<br/>(AGENTS.md + skill tool)"]
|
|
129
|
+
AF -->|remote human| HERMES["<b>Hermes</b><br/>hub questions relayed<br/>to your phone (Telegram)"]
|
|
130
|
+
AF -->|outbound remote delegation| CODEX["<b>Codex Remote Control</b><br/>Android-approved calls to<br/>listed coms peers (experimental)"]
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
### External dependencies
|
|
134
|
+
|
|
135
|
+
These are the external systems Agent Fleet assumes or integrates with — not npm packages, but the **runtime stack** the fleet operates on top of.
|
|
136
|
+
|
|
137
|
+
| Dependency | Role | Required? |
|
|
138
|
+
| --- | --- | --- |
|
|
139
|
+
| **[pi](https://github.com/badlogic/pi-mono)** (or your pi install) | Primary coding-agent runtime; loads harnesses, extensions, prompts, and personas | Yes for full fleet mode (`just hub`) |
|
|
140
|
+
| **[herdr](https://herdr.dev)** | Workspace control plane: tiled peer panes, presence push events, team snapshot/resume | Yes for fleet recipes (`just team-up`, `just hub-team`, …); optional for solo hub |
|
|
141
|
+
| **[Claude Code](https://docs.anthropic.com/en/docs/claude-code)** | First-class peer via the [coms bridge](claude-code-coms-bridge.md); also a supported install target for skills/personas | Optional peer / alternate harness |
|
|
142
|
+
| **[OpenCode](https://opencode.ai)** | Skill-driven execution target (`AGENTS.md` + `skill` tool); `af-*` slash commands | Optional alternate harness |
|
|
143
|
+
| **Hermes** | Remote human-in-the-loop (Telegram relay for hub questions) — [coms-hermes-bridge](coms-hermes-bridge.md) | Optional |
|
|
144
|
+
| **Codex CLI + ChatGPT Android** | Experimental outbound remote-control conductor on supported `0.144.x`; requires Node `22.6+`, user systemd, interactive pairing, and per-command mobile approvals — [runbook](codex-remote-conductor.md) | Optional / revalidate after minor-version or mobile-client changes |
|
|
145
|
+
| **[addyosmani/agent-skills](https://github.com/addyosmani/agent-skills)** | Upstream skill library (manually vendored) | Bundled (vendored) |
|
|
146
|
+
| **[disler/pi-vs-claude-code](https://github.com/disler/pi-vs-claude-code)** | Source inspiration / MIT port origin for pi harnesses | Design lineage (ported in-repo) |
|
|
147
|
+
| **LLM providers** | Models per persona (`model:` / `models:` in agent frontmatter) — e.g. OpenAI Codex, GitHub Copilot, Ollama, … | Yes (at least one provider your agents can call) |
|
|
148
|
+
| **Chrome DevTools MCP** / **Playwright Agent CLI** | Browser verify (`browser-testing-with-devtools`) and headless automation (`bowser`) | Optional, feature-specific |
|
|
149
|
+
| **Node.js + npm** | CLI (`npx @chankov/agent-fleet`), package install, `just` recipes | Yes for install & tooling |
|
|
150
|
+
|
|
151
|
+
## Repository module map
|
|
152
|
+
|
|
153
|
+
```text
|
|
154
|
+
.pi/ # Pi runtime: harnesses, extensions, agents config, prompts
|
|
155
|
+
skills/ # Agent Fleet-native skills (shadow vendored names)
|
|
156
|
+
agents/ # Personas/subagents used by Agent Fleet
|
|
157
|
+
scripts/ # CLI helpers, bridges, team launchers (pure logic in scripts/lib/)
|
|
158
|
+
hermes/ # Hermes-facing skills/integration assets
|
|
159
|
+
codex/ # Canonical Codex conductor contract (runtime copy lives outside checkout)
|
|
160
|
+
systemd/user/ # Owned user-unit template for Codex remote control
|
|
161
|
+
vendor/agent-skills-upstream/ # Manually imported upstream skills (pinned SHA)
|
|
162
|
+
bin/ # npm CLI: init/update/doctor/transform-persona
|
|
163
|
+
hooks/ # Session lifecycle + coms Stop hooks
|
|
164
|
+
references/ # Supplementary checklists (see fleet-coordination-patterns.md)
|
|
165
|
+
docs/ # This file, setup guides, bridge references, vendoring policy
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
Reserved for future modules (do not repurpose these paths):
|
|
169
|
+
|
|
170
|
+
```text
|
|
171
|
+
apps/dashboard/ # future dashboard: Kanban state, Herdr workspaces, peer status
|
|
172
|
+
packages/fleet-core/ # future extracted core orchestration library
|
|
173
|
+
packages/herdr-bridge/ # future Herdr integration package
|
|
174
|
+
packages/hermes-bridge/ # future Hermes integration package
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
## Design rules
|
|
178
|
+
|
|
179
|
+
- **Thin dispatcher context.** Nothing lands persistently in the dispatcher's
|
|
180
|
+
context if it can live on disk or in a one-line status. Research findings,
|
|
181
|
+
the Verification Contract ledger, and team snapshots are all disk-first.
|
|
182
|
+
- **Herdr owns panes, presence, and lifecycle; coms owns messages.** Fleet
|
|
183
|
+
recipes hard-require a running herdr server and refuse with an actionable
|
|
184
|
+
message otherwise; non-fleet recipes never touch herdr.
|
|
185
|
+
- **External agents are peers, not plugins.** Claude Code (and future CLI
|
|
186
|
+
agents) join the fleet through bridge adaptors that speak coms envelopes —
|
|
187
|
+
the fleet core stays agent-agnostic. Hermes remains the inbound `ask_user`/
|
|
188
|
+
Telegram route; the experimental Codex conductor is outbound-initiated only,
|
|
189
|
+
approval-gated, and restricted to listed peers through the validated wrapper.
|
|
190
|
+
- **Hermes monitor presentation is outside the fleet core.** Agent Fleet owns task state,
|
|
191
|
+
bounded output, leases, and generation-safe cancellation, and exposes them only through
|
|
192
|
+
owner-only discovery and a local Unix socket. A Hermes-facing consumer owns its UI and
|
|
193
|
+
reconnect behavior; no Hermes backend/Desktop plugin is bundled or installed.
|
|
194
|
+
- **External conductor contracts are advisory.** Pi damage-control wraps Pi
|
|
195
|
+
tool calls, not Hermes or Codex processes; human approvals and their
|
|
196
|
+
contracts reduce risk but do not provide an OS command allowlist.
|
|
197
|
+
- **Destructive fleet verbs are damage-control-guarded.** Specialists cannot
|
|
198
|
+
spawn/close herdr panes; the human confirms destructive actions.
|
|
199
|
+
- **Native-over-vendored skills.** The skill catalogue resolves `skills/`
|
|
200
|
+
first, then the vendored upstream import; upstream updates are explicit
|
|
201
|
+
maintainer actions ([UPSTREAM-SKILLS.md](UPSTREAM-SKILLS.md)).
|
|
202
|
+
|
|
203
|
+
## History
|
|
204
|
+
|
|
205
|
+
Agent Fleet began as a fork of `addyosmani/agent-skills` and was split into a
|
|
206
|
+
standalone repository in July 2026, with upstream demoted to vendored content.
|
|
207
|
+
The one-time migration record, including the history-filtering commands, lives
|
|
208
|
+
in [MIGRATION-agent-fleet.md](MIGRATION-agent-fleet.md); the product
|
|
209
|
+
requirements that drove the split are in
|
|
210
|
+
[prd-agent-fleet-split.md](prd-agent-fleet-split.md).
|
|
@@ -105,6 +105,16 @@ targets an end-of-session compound pass writes lessons to.
|
|
|
105
105
|
| `delegate-depth.<persona>` | persona frontmatter `delegate_depth:` (default/max 1) | Replaces the persona's delegation depth budget: `0` makes its delegate tool refuse (delegation off for this project), `1` lets it spawn terminal children. Values above 1 are clamped to 1; children at remaining depth 0 do not receive delegate tooling. |
|
|
106
106
|
| `rules` | none | Comma-separated repo-relative folders holding the project's own rule files (HOW — implementation patterns the work must comply with). Resolution is **index-first**: when a folder has a top-level `README.md`/`index.md`, personas read it first and follow its loading manifest (session bundles, conditional-load lists) instead of bulk-reading the tree; a folder without an index is searched **recursively** through all subfolders. The harness tells every dispatched specialist where the rules live and how to resolve them; the planner and code-reviewer personas read the relevant rules, validate their subject against them, and pass them on (cited in plan acceptance criteria / handed to delegate sub-reviewers). Missing folders produce a session-start warning. |
|
|
107
107
|
| `docs` | none | Comma-separated repo-relative documentation **entry points** (WHAT/WHY — architecture, standards, decisions): canonical files (e.g. `Docs/AGENTS.md`) or doc folders (personas start from a folder's `README.md`/index). Unlike `rules`, docs orient rather than bind: every dispatched specialist and research helper is told to read the entry points relevant to its task and follow their links instead of bulk-reading doc trees; the code-reviewer flags changes that alter documented behavior without a doc update; the documenter treats the entry points and the trees they link as the docs it maintains. Missing paths produce a session-start warning. |
|
|
108
|
+
| `research-keep` | `4` | How many **finished** manual/persona research helpers the hub retains (LRU by finish time) so they stay resumable via `/agents-cont rN`; older ones are pruned along with their session files. `all` disables the cap. Auto-research pipe helpers (spawned for `NEEDS_RESEARCH:` pauses) are always pruned as soon as they finish — their findings persist as files under `.pi/agent-sessions/findings/`. Running helpers are never pruned. An invalid value is ignored with a session-start warning. |
|
|
109
|
+
| `recon-search-timeout-s` | `120` | Parent-side deadline, in seconds, for each `read`, `grep`, `find`, or `ls` call made by a native research helper or nested delegate child. Accepts an integer `1`–`3600` or `off`; invalid input warns and falls back to `120`. This is **not** an agent/turn deadline: non-tool work can run indefinitely. On timeout the hub returns `tool_timeout` with call metadata, sends SIGTERM to its owned process group, escalates to SIGKILL after a finite grace period, and settles even if the child never closes or a descendant holds a pipe. If that bounded cleanup cannot confirm child/process-group death, the metadata reports `terminationConfirmed: false`; this prevents a parent hang but may indicate an uninterruptible OS-level process needing operator attention. |
|
|
110
|
+
| `mode` | `standard` | Execution mode for the hub's per-turn budgets: `fast` (single-specialist path, no nested delegation, assertion ledger optional), `standard` (batched execution with moderate budgets), or `strict` (full Verification Contract with wide budgets). Budgets are per **user turn** — exhausted budgets make `dispatch_agent`/`spawn_research` refuse with "summarize and ask the user"; the next user message opens a fresh window. Switchable live with `/hub-mode`. |
|
|
111
|
+
| `max-dispatches-per-turn` | mode default (2/8/24) | `dispatch_agent` calls allowed per user turn. Positive integer or `off` (unlimited). |
|
|
112
|
+
| `max-research-per-turn` | mode default (1/4/12) | `spawn_research` calls allowed per user turn (the auto-research pipe and the `/research` command are exempt). Positive integer or `off`. |
|
|
113
|
+
| `turn-wall-time-s` | mode default (900/3600/14400) | Wall-clock budget, in seconds, per user turn; once exceeded, further dispatch/research calls refuse. Positive integer or `off`. |
|
|
114
|
+
| `agent-turn-timeout-s` | mode default (600/1800/off) | Whole-run deadline, in seconds, for each spawned specialist, research helper, and nested delegate child (unlike `recon-search-timeout-s`, this bounds the entire run). On expiry the run terminates as `turn_timeout` (exit 124) with partial output preserved. Positive integer or `off`. |
|
|
115
|
+
| `session-recycle-runs` | mode default (3/5/5) | Recycle a specialist's accumulated session (fresh spawn instead of `-c` resume) after this many resumed runs. Context is also always recycled at ≥60% measured context (input + cacheRead + cacheWrite). Positive integer or `off` (context threshold still applies). |
|
|
116
|
+
| `watchdog` | `auto` | Drift watchdog default for dispatched specialists: `auto`/`on` arm the in-flight rules (out-of-scope writes, tool-call loops, repeated failures, tool-call cap) with LLM-judge escalation; `off` disarms. Overridable live per hub (`/watchdog on\|off\|auto`), per agent (`/watchdog <agent> on\|off\|clear`), and per dispatch (the `watchdog` param). A DRIFTING/STUCK verdict terminates the run as `drift_stop` (exit 125) with partial output preserved. |
|
|
117
|
+
| `watchdog-judge-model` | researcher persona's model | pi model spec for the one-shot drift judge (e.g. `openai-codex/gpt-5.3-codex-spark`). Falls back to the researcher persona's resolved model, then the dispatcher's. |
|
|
108
118
|
|
|
109
119
|
Example — switch the dispatcher to Bulgarian, pin the builder to sonnet, raise the
|
|
110
120
|
code-reviewer's thinking level, move the code-reviewer's docs sub-reviewer to a
|
|
@@ -119,6 +129,7 @@ models.builder: github-copilot/claude-sonnet-4.6, github-copilot/claude-haiku-4.
|
|
|
119
129
|
thinking.code-reviewer: xhigh
|
|
120
130
|
subagents.code-reviewer.docs: github-copilot/claude-sonnet-4.6, tools=read,grep
|
|
121
131
|
delegate-depth.code-reviewer: 1
|
|
132
|
+
recon-search-timeout-s: 120 # or off to disable the per-tool watchdog
|
|
122
133
|
rules: docs/rules, .ai/rules
|
|
123
134
|
docs: Docs/AGENTS.md, Docs/architecture/ARCHITECTURE_OVERVIEW.md
|
|
124
135
|
```
|
|
@@ -78,6 +78,16 @@ same return contract, ASK_USER handling, and history. The standing Claude sessio
|
|
|
78
78
|
its context across review rounds, which is the point for code/plan review. See
|
|
79
79
|
"Coms-backed dispatch" in `.pi/harnesses/agent-hub/README.md`.
|
|
80
80
|
|
|
81
|
+
## Migrating legacy CLI spools
|
|
82
|
+
|
|
83
|
+
Current releases isolate CLI queues by project at:
|
|
84
|
+
|
|
85
|
+
```text
|
|
86
|
+
~/.pi/coms/cli/projects/<project>/<name>/
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
Older releases used the ambiguous name-only path `~/.pi/coms/cli/<name>/`. If that legacy directory exists, `send`, `await`, `reply`, and listener operations fail closed rather than assigning queued messages to whichever project runs first. Before upgrading, stop commands using that CLI identity, inspect its `pending`, `responses`, and `inbound` files, determine the owning project, and move the complete `<name>` directory to `cli/projects/<project>/<name>`. Do not merge two queues or delete pending data merely to clear the error. The name `projects` is reserved for the namespace and cannot be used as a coms identity.
|
|
90
|
+
|
|
81
91
|
## Behavior notes
|
|
82
92
|
|
|
83
93
|
- **Serialization:** one prompt at a time per pane; queue depth shows in the peer's
|
|
@@ -0,0 +1,170 @@
|
|
|
1
|
+
# Codex Remote-Control Conductor
|
|
2
|
+
|
|
3
|
+
> **Experimental; verified with Codex CLI 0.144.6 on Linux.** The daemon is user-systemd-managed on the headless host, while manual pairing happens in the operator's interactive terminal. Revalidate the live gate after any Codex minor-version or mobile-client behavior change.
|
|
4
|
+
|
|
5
|
+
The conductor is an outbound-initiated, singleton Codex remote-control service with a visible Herdr **control** pane. The pane displays user-systemd requested state; it never starts, stops, or owns the daemon. Based on the verified design boundary, closing its workspace leaves the enabled service running. Codex uses the dedicated advisory contract at [`../codex/CONDUCTOR.md`](../codex/CONDUCTOR.md); Hermes/Telegram remains the inbound `ask_user` route.
|
|
6
|
+
|
|
7
|
+
## Supported facts and limits
|
|
8
|
+
|
|
9
|
+
- The pilot was validated with `codex-cli 0.144.6`. Public policy supports **only `0.144.x`**. Resolve the local binary with `command -v codex`; normal lifecycle state changes run a capability preflight, and `0.145.x` or later fail closed until reviewed.
|
|
10
|
+
- The confirmed remote-control subcommands are `start`, `stop`, and `pair`.
|
|
11
|
+
- The only approval modes are `untrusted`, `on-request`, and `never`. The only sandbox modes are `read-only`, `workspace-write`, and `danger-full-access`. **There is no `writes` mode.**
|
|
12
|
+
- The verified posture is `on-request` with `workspace-write`. The runtime-only container is `$HOME/.local/state/agent-fleet/codex-conductor`, outside every checkout; wrapper commands execute from its `workspace` child. Codex 0.144.x/Android may expose the container parent as writable, but repository source and canonical `codex/CONDUCTOR.md` remain outside it. Setup places a managed `workspace/AGENTS.md` copy inside the container. The helper requests the configured `~/.pi/coms` directory as the only extra writable root. The mobile client's managed permission profile still requires a visible one-command escalation for `send`; this approval is mandatory. A remote thread that reports `approval_policy=never` must not delegate.
|
|
13
|
+
- Codex documents neither a foreground daemon lifecycle nor a websocket address/port. Do not configure, probe, document, or depend on a websocket port, PID, or health endpoint.
|
|
14
|
+
- `systemd` state is not daemon health: `active (exited)` means that the requested start command succeeded, not that a paired client is usable.
|
|
15
|
+
- Remote control is outbound-initiated and exclusive **as far as verified for this pilot**. It does not create inbound questions; use Hermes/Telegram for inbound `ask_user`.
|
|
16
|
+
|
|
17
|
+
Both Codex and Hermes are external conductors. Their contracts and human approvals are advisory safeguards outside Pi's damage-control harness; Pi's guardrails and an OS command allowlist do not technically constrain either process. See [Hermes and coms](coms-hermes-bridge.md).
|
|
18
|
+
|
|
19
|
+
## Before touching the host
|
|
20
|
+
|
|
21
|
+
1. Confirm the operator accepts the singleton/global-stop limitation: `stop` can affect the remote-control daemon rather than a process systemd can prove it owns.
|
|
22
|
+
2. Use a Node runtime that supports `--experimental-strip-types` (Node `22.6+`) for these optional TypeScript recipes. Setup persists the exact `process.execPath` for systemd, and team-up passes the same absolute binary to the control pane.
|
|
23
|
+
3. Close Codex Desktop, editor-owned Codex app servers, and interactive Codex sessions for this host before starting the headless service. The remote-control host is singleton; a desktop/app-server owner can make headless `start` fail with `connection is errored`. Do not mix Mode B with the community Linux desktop workaround.
|
|
24
|
+
4. Set global `approval_policy = "on-request"` in `~/.codex/config.toml` after making a private backup. The Android client applies this global value to new threads and can override daemon-only config. This affects all local Codex sessions; the lifecycle preflight verifies the effective redacted `codex doctor --json` value and refuses `never`.
|
|
25
|
+
5. Keep pairing codes, credentials, auth files, remote-control URLs, approval transcripts, and screenshots **out of Git, documentation, plans, test fixtures, and logs**. Pairing output stays in the operator's terminal.
|
|
26
|
+
6. Run the non-mutating compatibility evidence. It confirms only advertised static capabilities and configured approval posture; it does not prove daemon ownership, pairing, session root, contract loading, approval delivery, or health.
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
CODEX="$(command -v codex)"
|
|
30
|
+
"$CODEX" --version
|
|
31
|
+
"$CODEX" remote-control --help
|
|
32
|
+
"$CODEX" remote-control start --help
|
|
33
|
+
"$CODEX" remote-control stop --help
|
|
34
|
+
"$CODEX" remote-control pair --help
|
|
35
|
+
"$CODEX" doctor --json # redacted; preflight requires approval policy OnRequest
|
|
36
|
+
node --experimental-strip-types scripts/codex-remote-control.ts preflight --codex-bin "$CODEX"
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
**Compatibility stop condition:** if the version is not `0.144.x`, a required subcommand is absent, or `on-request` plus `workspace-write` cannot be demonstrated for this remote-control path, stop. Do not use guessed flags, a port, or a fallback launcher.
|
|
40
|
+
|
|
41
|
+
The loading mechanism uses a managed runtime contract at `$HOME/.local/state/agent-fleet/codex-conductor/workspace/AGENTS.md`, copied from canonical `codex/CONDUCTOR.md`. A fresh thread must prove that managed copy was loaded and that any mobile writable root remains inside the external user-state runtime container; cwd and environment markers alone remain insufficient.
|
|
42
|
+
|
|
43
|
+
## Lifecycle
|
|
44
|
+
|
|
45
|
+
Run these recipes from the repository root. The helper rejects unsafe scope, invalid paths, unsupported Codex versions, and mismatched singleton configuration.
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
just conductor-codex-setup docs --project af
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
The recipe resolves `codex`, the real repository root, and `$HOME/.pi/coms`, derives the isolated identity `codex-docs-conductor`, creates `$HOME/.local/state/agent-fleet/codex-conductor/workspace` outside the checkout and refreshes its owned contract copy with the absolute validated wrapper path. The lower-level `scripts/codex-remote-control.ts setup` command remains available for explicit integrations.
|
|
52
|
+
|
|
53
|
+
`setup` preflights, writes non-secret owned files, reloads user systemd, and enables the service. It does **not** pair or start it. The owned paths are:
|
|
54
|
+
|
|
55
|
+
- `~/.config/agent-fleet/codex-remote-control.json` (mode-restricted, non-secret configuration, including the external runtime directory)
|
|
56
|
+
- `~/.config/systemd/user/agent-fleet-codex-remote-control.service`
|
|
57
|
+
- `~/.local/state/agent-fleet/codex-conductor/workspace/AGENTS.md` (managed runtime copy)
|
|
58
|
+
|
|
59
|
+
The unit is `Type=oneshot` with `RemainAfterExit=yes`, has no `Restart=` policy, uses the dedicated scratch directory as daemon `WorkingDirectory` (the verified mobile client broadens its managed root only to the runtime-only parent container), and runs preflight immediately before `remote-control start`. Start passes the verified `approval_policy="on-request"`, `sandbox_mode="workspace-write"`, and one `sandbox_workspace_write.writable_roots` entry for the validated coms directory. `ExecStopPost` uses the capability-checked stop path even after a failed `ExecStart`. A mobile managed profile can remain narrower, so the exact wrapper `send` must request and receive phone approval before its first execution. The unit makes no foreground, PID, port, or readiness claim.
|
|
60
|
+
|
|
61
|
+
### Pair — human interaction required
|
|
62
|
+
|
|
63
|
+
Pair the mobile client manually in an interactive operator TTY, after setup. Any displayed pairing code is short-lived secret material:
|
|
64
|
+
|
|
65
|
+
```bash
|
|
66
|
+
just conductor-codex-pair
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
Do not pipe, tee, capture, transcribe, screenshot, or commit the output. Never put pairing material or Codex credentials in the unit or config.
|
|
70
|
+
|
|
71
|
+
### Start, status, and conductor launch
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
just conductor-codex-start
|
|
75
|
+
just conductor-codex-status
|
|
76
|
+
just conductor-codex docs --project af
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
`status` reports only requested systemd state. Actual usability must be checked from the paired client, without inventing a network probe. The control pane similarly reports requested state only. Legacy `conductor-codex-pilot*` aliases remain available for the initial 0.144.x rollout.
|
|
80
|
+
|
|
81
|
+
### Use with `hub-team` and Android
|
|
82
|
+
|
|
83
|
+
The service does not start peers. Launch a hub/team in the exact project stored by setup:
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
just hub-team docs --project af
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
Do not also run `just conductor-codex docs --project af` for the same team unless a second peer set is intentional. `conductor-codex` is the alternative control-pane-plus-team layout when no hub is needed.
|
|
90
|
+
|
|
91
|
+
In ChatGPT Android, open the paired Remote Control host and create a fresh thread using:
|
|
92
|
+
|
|
93
|
+
```text
|
|
94
|
+
$HOME/.local/state/agent-fleet/codex-conductor/workspace
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
Do not start a local `codex` process as a substitute for the Android flow. Ask the thread to load its `AGENTS.md`, run one fresh wrapper list, and request approval once if needed. The managed contract contains the validated absolute wrapper path; do not reconstruct it or invoke `coms-cli` directly. For a send, first confirm the listed peer and exact bounded task conversationally, then approve the one displayed wrapper command. A denial stops without retry or side effect.
|
|
98
|
+
|
|
99
|
+
Example read-only delegation:
|
|
100
|
+
|
|
101
|
+
```text
|
|
102
|
+
List peers once. If researcher is visible, ask me to confirm:
|
|
103
|
+
"Inspect the current implementation and return findings with file:line evidence; do not edit files."
|
|
104
|
+
After confirmation, request approval for the exact wrapper send once.
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
### Stop, recovery, and reconfiguration
|
|
108
|
+
|
|
109
|
+
```bash
|
|
110
|
+
just conductor-codex-stop
|
|
111
|
+
just conductor-codex-recover
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
Use recovery when the unit says `active (exited)` but the paired client is unavailable, or when an `ExecStart` failure left the unit in `failed`. It is an explicit operator-confirmed systemd stop/reset/preflight/start path, not a health probe. Plain `start` still refuses `failed` and directs the operator to recovery or uninstall. Stop and emergency stop safely clear a confirmed `failed` state; other ambiguous states refuse rather than guessing.
|
|
115
|
+
|
|
116
|
+
To change the configured scope—or to upgrade an earlier in-checkout pilot runtime to the external user-state boundary—use `reconfigure` with the complete validated setup arguments, then explicitly stop/start as required. Do not edit the unit or config by hand:
|
|
117
|
+
|
|
118
|
+
```bash
|
|
119
|
+
just conductor-codex-reconfigure docs --project af
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
### Stale Codex send lock
|
|
123
|
+
|
|
124
|
+
A crash or `SIGKILL` can leave `~/.pi/coms/locks/codex-send.lock`. Automatic removal is intentionally forbidden because removing a live lock could permit concurrent sends. When the wrapper reports a held-or-stale lock:
|
|
125
|
+
|
|
126
|
+
1. Do not retry or start another delegation.
|
|
127
|
+
2. Inspect the non-secret JSON metadata (`started_at`, `project`, `name`, and advisory `pid`) without copying it into repository artifacts.
|
|
128
|
+
3. Confirm in the mobile thread that no wrapper command is still running. A host-side `kill -0` check is insufficient because remote commands may use a different PID namespace.
|
|
129
|
+
4. Wait beyond the configured send timeout. If ownership remains uncertain, stop the user service and confirm that no delegation is active.
|
|
130
|
+
5. Only then remove that one exact lock file manually and restart/recover the service if it was stopped.
|
|
131
|
+
|
|
132
|
+
Never use a wildcard cleanup or remove project spools as part of lock recovery.
|
|
133
|
+
|
|
134
|
+
### Version drift: emergency stop and uninstall
|
|
135
|
+
|
|
136
|
+
If normal preflight fails after Codex version/capability drift, normal start/stop/recovery remains blocked. The only exception is an explicit emergency stop, which first proves that the currently installed CLI still advertises the exact `remote-control stop` capability:
|
|
137
|
+
|
|
138
|
+
```bash
|
|
139
|
+
node --experimental-strip-types scripts/codex-remote-control.ts emergency-stop \
|
|
140
|
+
--confirm emergency-stop-confirmed
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
If that capability is absent, restore a supported `0.144.x` CLI before stopping or uninstalling. Never substitute a guessed stop command.
|
|
144
|
+
|
|
145
|
+
Uninstall is explicit, operates only on the owned unit/config, accepts and clears a confirmed `failed` state, resets the loaded unit before deleting it, disables the service, reloads user systemd, and leaves Codex authentication and pairing state untouched:
|
|
146
|
+
|
|
147
|
+
```bash
|
|
148
|
+
just conductor-codex-uninstall
|
|
149
|
+
# After version drift, use the lower-level helper only if the exact current
|
|
150
|
+
# stop capability is proved:
|
|
151
|
+
node --experimental-strip-types scripts/codex-remote-control.ts uninstall \
|
|
152
|
+
--confirm operator-confirmed --emergency-confirm emergency-stop-confirmed
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
Repository rollback does not stop or uninstall an already installed user service. If ownership is ambiguous, stop and review; do not remove files or use a broad manual cleanup. The scratch directory is retained if it contains operator-visible files; inspect it before removing it manually. After stopping/uninstalling the conductor, the operator may restore the private pre-change `config.toml` backup if `on-request` is not wanted for other Codex sessions.
|
|
156
|
+
|
|
157
|
+
## Verified live behavior
|
|
158
|
+
|
|
159
|
+
The Linux/Android live gate passed with CLI `0.144.6`: the managed unit completed start/stop/restart, manual pairing connected the phone, a fresh mobile thread loaded the original parent contract before workspace isolation, and the wrapper listed the `af` pool despite the remote PID namespace. The human confirmed one bounded delegation and separately approved the exact elevated wrapper command; `documenter` replied `Pilot acknowledged. No files changed.` A second approval was denied, producing no researcher message and no lock. The lock was absent after completion, and closing the control workspace did not stop the service.
|
|
160
|
+
|
|
161
|
+
Post-review live hardening passed on Android: because Codex 0.144.x can broaden the managed root to the runtime container parent regardless of daemon cwd, the entire container now lives under user state outside the checkout. A fresh Android thread used `$HOME/.local/state/agent-fleet/codex-conductor/workspace`, loaded its managed `AGENTS.md`, requested one approval for the rendered absolute list wrapper, listed `documenter` and `researcher`, and performed no edit or send.
|
|
162
|
+
|
|
163
|
+
Remote threads use only `scripts/codex-conductor.ts` from the dedicated scratch workspace. It reads owned scope, pins the real coms directory, and refuses repository/project/name/timeout overrides. **Human interaction remains required** twice for every send: first to confirm the freshly listed recipient/task conversationally, then to approve the exact wrapper command through Codex's `on-request` approval. The command must request escalation before its first execution because coms state and Unix sockets are outside the selected workspace.
|
|
164
|
+
|
|
165
|
+
## Related documentation
|
|
166
|
+
|
|
167
|
+
- [Experimental implementation plan](../plans/codex-remote-conductor.md) — gates and acceptance criteria.
|
|
168
|
+
- [Canonical Codex conductor contract](../codex/CONDUCTOR.md) — bounded outbound delegation rules.
|
|
169
|
+
- [Hermes/coms bridge](coms-hermes-bridge.md) — inbound human questions and Hermes conductor boundary.
|
|
170
|
+
- [Architecture](ARCHITECTURE.md) — ownership of Pi, Herdr, coms, and external conductors.
|
|
@@ -0,0 +1,121 @@
|
|
|
1
|
+
# coms Hermes bridge
|
|
2
|
+
|
|
3
|
+
Protocol contract for the Hermes ⇄ pi `coms` bridge. The first implemented daemon is `scripts/coms-hermes-bridge.ts`, which registers a `user-remote` peer and turns coms prompt envelopes into Hermes/Telegram questions.
|
|
4
|
+
|
|
5
|
+
## Pieces
|
|
6
|
+
|
|
7
|
+
| Piece | Role |
|
|
8
|
+
| --- | --- |
|
|
9
|
+
| `scripts/coms-hermes-bridge.ts` | Daemon peer, default name `user-remote`, purpose `Remote human via Hermes/Telegram`. Accepts prompt, cancel, and ping envelopes. |
|
|
10
|
+
| `scripts/lib/hermes-bridge-core.ts` | Pure contract logic: qid validation, Telegram formatting, answer-file validation, answer mapping, timeout outcome, state transitions, and log records. |
|
|
11
|
+
| `scripts/lib/coms-envelope.ts` | Shared non-pi envelope wire shapes, including additive `cancel` envelopes. |
|
|
12
|
+
| `~/.pi/coms/hermes-bridge/questions/` | Private answer-file wire written by the Hermes gateway/liaison. |
|
|
13
|
+
| `~/.pi/coms/hermes-bridge/log.ndjson` | Bridge observability log. |
|
|
14
|
+
|
|
15
|
+
## user-remote topology
|
|
16
|
+
|
|
17
|
+
1. A pi peer sends a coms `prompt` envelope to `user-remote`.
|
|
18
|
+
2. The bridge derives `qid` from `prompt.msg_id`, formats the question, and runs `hermes send --to <target> <message>` (`<target>` defaults to `telegram`).
|
|
19
|
+
3. The human replies in Telegram; the Hermes gateway/liaison writes the answer file.
|
|
20
|
+
4. The bridge polls the questions directory, validates the file, maps the answer, sends a coms `response` envelope, and removes the answer file.
|
|
21
|
+
|
|
22
|
+
## Protocol contract v1
|
|
23
|
+
|
|
24
|
+
### qid and correlation
|
|
25
|
+
|
|
26
|
+
`qid` is exactly the prompt envelope's `msg_id`. It must match the 26-character Crockford ULID regex `^[0-9A-HJKMNP-TV-Z]{26}$`. The same `qid` is the only correlation key across coms, Telegram, answer files, state, and logs.
|
|
27
|
+
|
|
28
|
+
### Telegram question format
|
|
29
|
+
|
|
30
|
+
`formatTelegramQuestion` emits UTF-16 text capped at 4096 code units:
|
|
31
|
+
|
|
32
|
+
```text
|
|
33
|
+
❓ [HUB-Q:<qid>] <question>
|
|
34
|
+
|
|
35
|
+
Context: <context, truncated if needed>
|
|
36
|
+
|
|
37
|
+
Options:
|
|
38
|
+
1. <title> — <description>
|
|
39
|
+
...
|
|
40
|
+
|
|
41
|
+
↩ Reply to this message, or type: HUB-Q:<qid>: <answer>
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
`Context:` is omitted when absent. `Options:` is omitted when no options are supplied. Context receives the remaining budget after the header, options, and reply instruction.
|
|
45
|
+
|
|
46
|
+
### Answer-file path, schema, and validation
|
|
47
|
+
|
|
48
|
+
The private wire path is:
|
|
49
|
+
|
|
50
|
+
```text
|
|
51
|
+
~/.pi/coms/hermes-bridge/questions/<qid>.answer.json
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Schema:
|
|
55
|
+
|
|
56
|
+
```json
|
|
57
|
+
{
|
|
58
|
+
"qid": "<26-character Crockford ULID>",
|
|
59
|
+
"answer": "<text>",
|
|
60
|
+
"answered_by": "telegram:<user>",
|
|
61
|
+
"at": "<ISO timestamp>"
|
|
62
|
+
}
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
Validation rejects and ignores files unless all conditions hold: filename ends in `.answer.json`; filename qid is valid; filename qid is currently pending; JSON parses; object fields match the schema; `at` parses as a timestamp; and body `qid` equals the filename qid. Rejection reasons are `invalid_path`, `invalid_qid`, `foreign_qid`, `invalid_json`, `invalid_schema`, and `qid_mismatch`; the daemon logs rejected files as `answer_rejected` and removes them. Exception: an `invalid_json` file is treated as a possible partial write and left in place for a short grace window (`max(2 × poll interval, 1s)` from first sighting); it is rejected and removed only if it still fails to parse after the grace expires.
|
|
66
|
+
|
|
67
|
+
### Answer mapping
|
|
68
|
+
|
|
69
|
+
If options exist and the trimmed answer is a 1-based number for an option, the response is `{ "kind": "selection", "selections": ["<option title>"] }`. If options exist and the trimmed answer case-insensitively equals an option title, it maps to the same selection shape. All other answers map to `{ "kind": "freeform", "text": "<trimmed answer>" }`.
|
|
70
|
+
|
|
71
|
+
### Cancel semantics
|
|
72
|
+
|
|
73
|
+
`cancel` is an additive coms envelope with shape `{ "type": "cancel", "msg_id", "from", "to", "created_at", "ref_msg_id" }`; `ref_msg_id` is the target `qid`. The bridge acks well-formed cancel envelopes before handling them.
|
|
74
|
+
|
|
75
|
+
For a pending qid, cancel clears the timeout, removes the pending question, records terminal state `cancelled`, appends a `cancelled` log event, and sends a Telegram note: `✖ [HUB-Q:<qid>] The question was cancelled — it was answered from the console.` Cancel for a non-pending or invalid qid is a no-op after the envelope ack. A later answer file for a closed qid is treated as `late_answer`: logged, removed, and answered in Telegram with a polite ignored note; no response envelope is sent.
|
|
76
|
+
|
|
77
|
+
### Timeouts
|
|
78
|
+
|
|
79
|
+
The per-question remote timeout defaults to `PI_COMS_TIMEOUT_MS`, or `1800000` ms when unset/invalid; `--timeout <ms>` overrides it. On timeout, the bridge removes the pending question, records terminal state `timeout`, logs `timeout`, sends the Telegram note `⌛ [HUB-Q:<qid>] The question timed out after <ms>ms.`, and sends an error response envelope with error `no remote answer within <ms>ms` and `response: null`.
|
|
80
|
+
|
|
81
|
+
### States
|
|
82
|
+
|
|
83
|
+
Question states are in-memory per qid: `pending`, `delivered`, `answered`, `cancelled`, and `timeout`. Implemented transitions are: `null + question_received → pending`; `pending + delivered → delivered`; `pending + delivery_error → null`; `pending|delivered + answered → answered` (the daemon currently answers from delivered or pending if the file arrives quickly); `pending|delivered + cancelled → cancelled`; `pending|delivered + timeout → timeout`; and terminal `answered|cancelled|timeout + late_answer` remains terminal.
|
|
84
|
+
|
|
85
|
+
### ndjson logging
|
|
86
|
+
|
|
87
|
+
The bridge appends one JSON object per line to `~/.pi/coms/hermes-bridge/log.ndjson`. Core log records have shape `{ "at": "<ISO>", "qid": "<qid>", "event": "<event>", "detail"?: <value> }`. Contract events are `question_received`, `delivered`, `delivery_error`, `answered`, `cancelled`, `timeout`, and `late_answer`; the daemon also writes `answer_rejected` for invalid answer files. Ping agent cards report `queue_depth` as the current number of pending questions.
|
|
88
|
+
|
|
89
|
+
## Hermes as conductor
|
|
90
|
+
|
|
91
|
+
Hermes can also act as the conductor without this daemon: use `coms-cli list` to discover peers and `coms-cli send --await --timeout <ms>` to delegate to hub-team pi peers, then synthesize the results for the human. This conductor topology uses the existing coms CLI as the bridge; no standing Hermes peer is required.
|
|
92
|
+
|
|
93
|
+
Launch a visible conductor workspace with:
|
|
94
|
+
|
|
95
|
+
```bash
|
|
96
|
+
just conductor docs # live herdr workspace: conductor pane + docs team panes
|
|
97
|
+
just conductor-dry docs # no herdr calls; prints the planned layout JSON
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
The live recipe reuses `scripts/team-up.ts --conductor`: it creates a normal herdr workspace labeled `<worktree-tag>-conductor-<team>` (the tag is the last dot-segment of the checkout's basename, so the same team from a different worktree gets its own workspace), places a `conductor` pane running `hermes -p dev`, and tiles the chosen team beside it. Team peers keep their normal coms harness and herdr presence reporting, so they continue to show agent state in the sidebar; Hermes' own herdr-agent-state plugin is responsible for the conductor pane's state.
|
|
101
|
+
|
|
102
|
+
Hard boundary: the Hermes conductor must not run `herdr` commands, drive panes, create/kill workspaces, or manage fleet lifecycle. Herdr driving stays with the human/orchestrator so the damage-control model remains intact; see `.pi/damage-control-rules.yaml` for the authoritative no-herdr boundary. Hermes may only operate inside the project coms pool through the documented coms CLI commands.
|
|
103
|
+
|
|
104
|
+
## Hermes and the experimental Codex conductor
|
|
105
|
+
|
|
106
|
+
Hermes/Telegram remains the **inbound** human `ask_user` complement to the
|
|
107
|
+
experimental Codex remote-control conductor. Codex is outbound-initiated,
|
|
108
|
+
approval-gated, and serialized; it is not an inbound question channel. The Codex user service and control-pane lifecycle are
|
|
109
|
+
separate from Hermes. See the [experimental Codex operator runbook](codex-remote-conductor.md).
|
|
110
|
+
|
|
111
|
+
Both conductor contracts are advisory outside Pi damage-control: Pi wraps Pi
|
|
112
|
+
tool calls, not Hermes or Codex, and neither has an OS command allowlist.
|
|
113
|
+
Human confirmation, approvals, and sandboxing reduce risk but do not
|
|
114
|
+
technically enforce either external contract.
|
|
115
|
+
|
|
116
|
+
## Deferred
|
|
117
|
+
|
|
118
|
+
- Standing conductor peer for pi → Hermes inbound messages.
|
|
119
|
+
- Telegram-driven conductor profile.
|
|
120
|
+
- Group/multi-recipient questions and non-text answers.
|
|
121
|
+
- Kanban-driven orchestration on top of the same conductor contract.
|
package/docs/getting-started.md
CHANGED
|
@@ -18,6 +18,20 @@ Each skill is a Markdown file (`SKILL.md`) that describes a specific engineering
|
|
|
18
18
|
|
|
19
19
|
All three converge on the same `guided-workspace-setup` skill — they only differ in how the source files reach your workspace. None is being deprecated.
|
|
20
20
|
|
|
21
|
+
## Optional experimental Android conductor
|
|
22
|
+
|
|
23
|
+
Linux/pi fleet users can pair Codex Remote Control with ChatGPT Android and delegate one approval-gated task at a time to peers already running in a coms project. It is optional, supports only Codex CLI `0.144.x`, requires Node `22.6+` and user systemd, and does not replace Hermes as the inbound `ask_user` route.
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
cd /path/to/agent-fleet
|
|
27
|
+
just conductor-codex-setup docs --project af
|
|
28
|
+
just conductor-codex-pair
|
|
29
|
+
just conductor-codex-start
|
|
30
|
+
just hub-team docs --project af
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
The runtime contract is generated under `$HOME/.local/state/agent-fleet/codex-conductor/`, outside the checkout. Pairing is interactive secret-bearing output and must never be captured. Read the complete [Codex conductor runbook](codex-remote-conductor.md) before enabling the service.
|
|
34
|
+
|
|
21
35
|
## Quick Start (Any Agent)
|
|
22
36
|
|
|
23
37
|
### 1. Clone the repository
|
package/docs/npm-install.md
CHANGED
|
@@ -56,6 +56,8 @@ The pi package manifest exposes this repo's skills, pi runtime skills, lifecycle
|
|
|
56
56
|
|
|
57
57
|
It intentionally does not auto-expose this repo's own `.pi/extensions` or harness directories; install those through guided setup or the pi setup docs so their runtime dependencies are handled explicitly. `pi-codex-image-gen` is also not bundled or required; guided setup may offer it as an optional suggested external npm/pi package when package installation is available, and installs it only if selected (`pi install -l npm:pi-codex-image-gen`). Minimal setup works without it.
|
|
58
58
|
|
|
59
|
+
The package also ships assets for the **experimental Linux Codex Remote-Control conductor** (`codex/`, `systemd/`, lifecycle/wrapper scripts, recipes, and runbook). Guided setup copies or links those assets with selected pi harnesses but never enables systemd, edits Codex config, starts a service, or pairs a phone. Those remain explicit operator actions and support only Codex CLI `0.144.x`; see [codex-remote-conductor.md](codex-remote-conductor.md). Its managed runtime contract is created later under `$HOME/.local/state/agent-fleet/codex-conductor/`, not inside the npm package or target checkout.
|
|
60
|
+
|
|
59
61
|
## Commands
|
|
60
62
|
|
|
61
63
|
### `npx @chankov/agent-fleet init`
|