@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,366 @@
|
|
|
1
|
+
# Agent Fleet — Project Files
|
|
2
|
+
|
|
3
|
+
agent-fleet keeps up to two small files in a project's `.ai/` directory. They
|
|
4
|
+
have different readers and different lifetimes, so they are kept separate.
|
|
5
|
+
|
|
6
|
+
| File | Read by | When |
|
|
7
|
+
|------|---------|------|
|
|
8
|
+
| `.ai/agent-fleet-overrides.md` | `spec-driven-development`, `planning-and-task-breakdown`, `browser-testing-with-devtools`, `git-workflow-and-versioning`, `compound-learning` (the `rules:`/`docs:` keys of `## agent-hub`), `agent-hub` pi harness | Every run of those skills / every session start of the harness |
|
|
9
|
+
| `.ai/agent-fleet-setup.md` | `guided-workspace-setup` | Only when setup is run or re-run |
|
|
10
|
+
| `.ai/stt.json` *(optional)* | `pi-voice-stt` extension | Every pi session start, when the extension is installed |
|
|
11
|
+
|
|
12
|
+
The `.ai/stt.json` file is present only when the optional `pi-voice-stt` voice-dictation
|
|
13
|
+
extension has been configured (by guided setup or by hand). Like the overrides file it holds
|
|
14
|
+
**no secrets** — it names the env vars (`apiKeyEnv`, plus the Azure endpoint var) whose values
|
|
15
|
+
live in a gitignored root `.env`. See [pi-voice-stt config](#ai-sttjson) below.
|
|
16
|
+
|
|
17
|
+
Keep them split: the overrides file is loaded into context constantly, so it
|
|
18
|
+
must stay minimal; the install record is consulted rarely, so it can be large.
|
|
19
|
+
|
|
20
|
+
## The overrides file — `.ai/agent-fleet-overrides.md`
|
|
21
|
+
|
|
22
|
+
Some skills and pi harnesses need facts specific to each project — where specs
|
|
23
|
+
and plans are saved, how to start a dev server, whether the agent may create
|
|
24
|
+
branches, or which user-facing language a dispatcher should use. Each reader
|
|
25
|
+
ships a sensible **default**; a project that needs something different declares
|
|
26
|
+
it here, and the reader picks it up.
|
|
27
|
+
|
|
28
|
+
- **Location:** `.ai/agent-fleet-overrides.md` at the project root.
|
|
29
|
+
- **Format:** Markdown. One `## <section-name>` section per skill or harness reader, with terse
|
|
30
|
+
`key: value` lines. Block values use the `key: |` multi-line form. No prose
|
|
31
|
+
and no install detail — readers parse it by key and load it on every run/session start.
|
|
32
|
+
- **Commit it.** Shared project configuration belongs in version control. Make
|
|
33
|
+
sure no `.gitignore` rule (for example a broad `.env*` pattern) excludes it.
|
|
34
|
+
- **No secrets.** For anything sensitive (test-account credentials), reference
|
|
35
|
+
the **name** of an environment variable; the real value lives in a gitignored
|
|
36
|
+
`.env`.
|
|
37
|
+
- If the file is absent, or a reader has no section in it, that reader uses its
|
|
38
|
+
built-in default.
|
|
39
|
+
- **Validation.** Because an unknown section or key silently falls back to the
|
|
40
|
+
default, typos are invisible at runtime. `agent-fleet doctor` (and the
|
|
41
|
+
`/doctor-agent-fleet` command) validates the file — unknown sections,
|
|
42
|
+
unknown keys in known sections, invalid values for the mechanically parsed
|
|
43
|
+
`agent-hub` keys, missing `rules:` folders, and unset `## env` vars — as
|
|
44
|
+
**advisory, warn-only findings**; it never edits the file.
|
|
45
|
+
|
|
46
|
+
### `spec-driven-development`
|
|
47
|
+
|
|
48
|
+
| Key | Default | Meaning |
|
|
49
|
+
|-----|---------|---------|
|
|
50
|
+
| `spec-dir` | `docs/prds/{area}` | Directory specs are written to |
|
|
51
|
+
| `naming` | `PRD{n}-{topic}` | File name pattern; `{n}` = next free PRD number, `{topic}` = kebab-case slug |
|
|
52
|
+
|
|
53
|
+
Default output: `docs/prds/{area}/PRD{n}-{topic}.md`.
|
|
54
|
+
|
|
55
|
+
### `planning-and-task-breakdown`
|
|
56
|
+
|
|
57
|
+
| Key | Default | Meaning |
|
|
58
|
+
|-----|---------|---------|
|
|
59
|
+
| `plan-dir` | `docs/plans/{area}` | Directory plans are written to |
|
|
60
|
+
| `naming` | `PLAN-{prd-name}-{phase}` | File name pattern; `{phase}` suffix only when a plan spans multiple files |
|
|
61
|
+
| `todo` | `embedded` | `embedded` keeps the task list inside the plan; `separate` writes a standalone `todo.md` |
|
|
62
|
+
|
|
63
|
+
Default output: `docs/plans/{area}/PLAN-{prd-name}-{phase}.md`, task list embedded.
|
|
64
|
+
|
|
65
|
+
### `browser-testing-with-devtools`
|
|
66
|
+
|
|
67
|
+
This skill has **no default** — the section is required for browser testing,
|
|
68
|
+
because dev-server commands and login flows cannot be guessed.
|
|
69
|
+
|
|
70
|
+
| Key | Meaning |
|
|
71
|
+
|-----|---------|
|
|
72
|
+
| `dev-server` | Command to start the local dev server |
|
|
73
|
+
| `ready-check` | How to confirm the server is up |
|
|
74
|
+
| `base-url` | Root URL for navigation |
|
|
75
|
+
| `auth-flow` | Steps to log in (multi-line `|` block) |
|
|
76
|
+
| `roles` | Test account per privilege level, referenced by env-var name |
|
|
77
|
+
| `notes` | Anything else the agent should know (certs, seed data, ...) |
|
|
78
|
+
|
|
79
|
+
### `git-workflow-and-versioning`
|
|
80
|
+
|
|
81
|
+
| Key | Default | Meaning |
|
|
82
|
+
|-----|---------|---------|
|
|
83
|
+
| `branching` | `never` | `never` = agent works in the current branch and never creates or switches branches; `allow` = agent may create feature branches |
|
|
84
|
+
|
|
85
|
+
### `agent-hub`
|
|
86
|
+
|
|
87
|
+
Read by the `.pi/harnesses/agent-hub/` pi harness on every session start. The canonical
|
|
88
|
+
section name is `## agent-hub`; the harness also accepts the legacy `## agent-team` name
|
|
89
|
+
(from before the standalone `agent-team` harness was retired), so existing project
|
|
90
|
+
override files keep working unchanged. When both sections are present their keys merge,
|
|
91
|
+
with later lines winning.
|
|
92
|
+
|
|
93
|
+
The `rules:` and `docs:` keys are also read outside the harness: the `compound-learning`
|
|
94
|
+
skill (and the `/compound` claude-code/opencode commands built on it) resolves them as the
|
|
95
|
+
targets an end-of-session compound pass writes lessons to.
|
|
96
|
+
|
|
97
|
+
| Key | Default | Meaning |
|
|
98
|
+
|-----|---------|---------|
|
|
99
|
+
| `language` | `English` | User-facing language the dispatcher uses for every `ask_user` question, every `context` field, and every summary. Specialist task strings always stay in English regardless. |
|
|
100
|
+
| `persona-gate` | `off` | When `on`, blocks input at session start until an orchestrator persona is picked. |
|
|
101
|
+
| `model.<persona>` | persona frontmatter `model:` | Replaces the named persona's default model for this project (a full pi model spec). |
|
|
102
|
+
| `models.<persona>` | persona frontmatter `models:` | Replaces the named persona's model-candidate list for `/agent-model` and `/models` profiles (comma-separated pi model specs). |
|
|
103
|
+
| `thinking.<persona>` | persona frontmatter `thinking:` | Replaces the named persona's pi `--thinking` reasoning level for this project: one of `off`, `minimal`, `low`, `medium`, `high`, `xhigh`. Switchable at runtime with `/agent-model-thinking <persona>`. An invalid value is ignored with a session-start warning. |
|
|
104
|
+
| `subagents.<persona>.<role>` | persona frontmatter `subagents:` | Replaces or adds one delegate sub-role for this project: `<model>[, tools=<caps>]`. Other declared roles keep their frontmatter values. |
|
|
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
|
+
| `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
|
+
| `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. |
|
|
118
|
+
|
|
119
|
+
Example — switch the dispatcher to Bulgarian, pin the builder to sonnet, raise the
|
|
120
|
+
code-reviewer's thinking level, move the code-reviewer's docs sub-reviewer to a
|
|
121
|
+
different model, and point the team at the project's rule folders and doc entry
|
|
122
|
+
points:
|
|
123
|
+
|
|
124
|
+
```markdown
|
|
125
|
+
## agent-hub
|
|
126
|
+
language: Bulgarian
|
|
127
|
+
model.builder: github-copilot/claude-sonnet-4.6
|
|
128
|
+
models.builder: github-copilot/claude-sonnet-4.6, github-copilot/claude-haiku-4.5
|
|
129
|
+
thinking.code-reviewer: xhigh
|
|
130
|
+
subagents.code-reviewer.docs: github-copilot/claude-sonnet-4.6, tools=read,grep
|
|
131
|
+
delegate-depth.code-reviewer: 1
|
|
132
|
+
recon-search-timeout-s: 120 # or off to disable the per-tool watchdog
|
|
133
|
+
rules: docs/rules, .ai/rules
|
|
134
|
+
docs: Docs/AGENTS.md, Docs/architecture/ARCHITECTURE_OVERVIEW.md
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
### `env` (optional, read by the doctor)
|
|
138
|
+
|
|
139
|
+
The overrides file references environment variables by **name** — test-account
|
|
140
|
+
credentials for `browser-testing-with-devtools`, the `pi-voice-stt` API key —
|
|
141
|
+
while the values live in a gitignored root `.env`. The optional `## env`
|
|
142
|
+
section declares which names the project's readers expect, so a fresh clone
|
|
143
|
+
can find out what's missing *before* a skill fails mid-run:
|
|
144
|
+
|
|
145
|
+
| Key | Meaning |
|
|
146
|
+
|-----|---------|
|
|
147
|
+
| `required` | Comma-separated env-var **names** (never values) the project's sections reference |
|
|
148
|
+
|
|
149
|
+
```markdown
|
|
150
|
+
## env
|
|
151
|
+
required: APP_TEST_ADMIN_USER, APP_TEST_ADMIN_PASS, AZURE_SPEECH_KEY
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
No skill or harness loads this section. Its only reader is `agent-fleet doctor`
|
|
155
|
+
(and `/doctor-agent-fleet`), which warns when a declared name is neither set in
|
|
156
|
+
the environment nor declared in the workspace root `.env`.
|
|
157
|
+
|
|
158
|
+
### Per-peer env files (`env_file:` in peers.yaml)
|
|
159
|
+
|
|
160
|
+
Fleet peers spawned by `just team-up` / `just hub-team` can carry their own
|
|
161
|
+
environment: an `env_file:` entry in `.pi/agents/peers.yaml` names a
|
|
162
|
+
**repo-relative** KEY=VALUE file (same format as `.env`, no shell evaluation)
|
|
163
|
+
that herdr injects into the peer's pane before the command runs — no `source`,
|
|
164
|
+
no leaking into sibling panes. The file must exist at spawn (team-up refuses
|
|
165
|
+
otherwise, never mid-run), and its **values never appear in `--dry-run`
|
|
166
|
+
output** — only the path. Keep these files gitignored exactly like the root
|
|
167
|
+
`.env` this section describes.
|
|
168
|
+
|
|
169
|
+
## The setup file — `.ai/agent-fleet-setup.md`
|
|
170
|
+
|
|
171
|
+
The `guided-workspace-setup` skill writes this file to record what it installed
|
|
172
|
+
into the project — which skills, commands, personas, and extensions, by what
|
|
173
|
+
method, and when. It reads the file on a re-run to add, update, or remove
|
|
174
|
+
artifacts without reinstalling everything. No other skill loads it.
|
|
175
|
+
|
|
176
|
+
| Section | Meaning |
|
|
177
|
+
|---------|---------|
|
|
178
|
+
| `workspace-summary` | Workspace path, coding agent, **agent-fleet version**, project shape, checks discovered |
|
|
179
|
+
| `install-status` | Installed artifacts, their targets, and the method (`copy` or `symlink`) |
|
|
180
|
+
| `doctor-runs` | One line per doctor pass (preflight / postflight, repaired / deleted / skipped counts) |
|
|
181
|
+
| `verification` | Checks confirming the install |
|
|
182
|
+
|
|
183
|
+
### The `version:` line
|
|
184
|
+
|
|
185
|
+
`workspace-summary` carries a `version:` line set to the package version that
|
|
186
|
+
performed the install (e.g. `version: 1.4.2`). It drives the version-aware
|
|
187
|
+
update flow — on every re-run, `guided-workspace-setup` compares this against
|
|
188
|
+
the current package version and:
|
|
189
|
+
|
|
190
|
+
1. Reads `CHANGELOG.md` between the two versions.
|
|
191
|
+
2. For each installed artifact, runs a three-way diff between
|
|
192
|
+
*source@recorded*, the installed copy on disk, and *source@current*.
|
|
193
|
+
3. Surfaces the result in the install menu using these `Status` values:
|
|
194
|
+
|
|
195
|
+
| Status | Meaning |
|
|
196
|
+
|---|---|
|
|
197
|
+
| `installed · upgrade available` | Source changed upstream; user copy still matches the old source → clean refresh |
|
|
198
|
+
| `installed · conflicting upgrade` | Source changed upstream AND user modified the copy → menu shows the three-way diff before overwriting |
|
|
199
|
+
| `installed · removed upstream` | Artifact gone in the new version → menu proposes deletion (subject to the removal-scope rule) |
|
|
200
|
+
| `not installed · new in this version` | New artifact added in the new version → menu offers it, marked `★` if recommended |
|
|
201
|
+
|
|
202
|
+
The diff sources at *source@recorded* are read from the package's
|
|
203
|
+
`.versions/<x.y.z>/` snapshot tree, which the release pipeline writes for every
|
|
204
|
+
published version. If the snapshot is missing (e.g. an unpublished local
|
|
205
|
+
build), the skill falls back to "treat installed copy as canonical" and
|
|
206
|
+
prompts for an explicit baseline.
|
|
207
|
+
|
|
208
|
+
### Pre-versioning workspaces
|
|
209
|
+
|
|
210
|
+
A workspace whose `agent-fleet-setup.md` predates the `version:` line is
|
|
211
|
+
treated as "pre-versioning". On first re-run, `guided-workspace-setup` prompts
|
|
212
|
+
for a clean baseline: either accept the installed artifacts as matching the
|
|
213
|
+
current source (stamp the current version), or re-run the install from scratch.
|
|
214
|
+
|
|
215
|
+
Commit this file if the team should share install state — keep paths relative
|
|
216
|
+
so it stays portable. A self-referencing checkout (agent-fleet itself) may
|
|
217
|
+
instead `.gitignore` it, since its recorded paths are local to one machine.
|
|
218
|
+
|
|
219
|
+
## The `/orchestrate` command and its team config
|
|
220
|
+
|
|
221
|
+
`/orchestrate` turns the main session (Claude Code) or primary agent (OpenCode)
|
|
222
|
+
into an **orchestrator** that drives a config-defined team of installed
|
|
223
|
+
subagents — subagents cannot nest, so all dispatching is the main session's job.
|
|
224
|
+
The default team is `planner` + `builder` (no reviewer); the orchestrator routes
|
|
225
|
+
the team as a **runtime roster, not a fixed `researcher → planner → builder`
|
|
226
|
+
pipeline** — it skips planning when a plan already exists, re-runs `researcher`
|
|
227
|
+
at any point, and loops back to `planner` when the build surfaces a wrong plan.
|
|
228
|
+
It honours the existing subagent handoff markers: `PLAN_FILE: <path>` from the
|
|
229
|
+
planner, and `NEEDS_RESEARCH: <question>` from planner/builder (which dispatches a
|
|
230
|
+
read-only `researcher` and resumes the paused persona with the findings inlined).
|
|
231
|
+
|
|
232
|
+
The named teams live in a per-agent config that mirrors pi's
|
|
233
|
+
`.pi/agents/teams.yaml` (a map of team-name → ordered persona list, first key =
|
|
234
|
+
default; `researcher`/`deep-researcher` deliberately unlisted but always
|
|
235
|
+
available). The reader differs by runtime: pi's harness parses its YAML, while
|
|
236
|
+
`/orchestrate` has the **command's instructions** read the YAML via the Read tool
|
|
237
|
+
(no harness runtime in claude-code/opencode):
|
|
238
|
+
|
|
239
|
+
| | Config file | Command |
|
|
240
|
+
|---|---|---|
|
|
241
|
+
| claude-code | `.claude/orchestrate-teams.yaml` | `/orchestrate` |
|
|
242
|
+
| opencode | `.opencode/orchestrate-teams.yaml` | `/af-orchestrate` |
|
|
243
|
+
| pi | `.pi/agents/teams.yaml` | via the `agent-hub` harness (no `/orchestrate`) |
|
|
244
|
+
|
|
245
|
+
Switch teams at runtime with `/orchestrate <team> "<task>"` (parallel of pi's
|
|
246
|
+
`/agents-team`); use `/orchestrate team=<name> <task>` to disambiguate when the
|
|
247
|
+
task text starts with a word that collides with a team key.
|
|
248
|
+
|
|
249
|
+
**Guided-setup behaviour.** `guided-workspace-setup` offers `/orchestrate`
|
|
250
|
+
**`★`-recommended** for claude-code + opencode (hidden for pi via the existing
|
|
251
|
+
source-availability filter — there is no `.pi/prompts/orchestrate.md`), and
|
|
252
|
+
installs the agent's `orchestrate-teams.yaml` as a **companion** of the command
|
|
253
|
+
(a user-edited config is preserved on uninstall, never silently clobbered).
|
|
254
|
+
Two artifacts stay **claude-only**: the lifecycle **hooks** (they register into
|
|
255
|
+
`.claude/settings.json`, which opencode/pi have no install path for) and the
|
|
256
|
+
**`AskUserQuestion` questionnaire menu mode** (the primary menu interaction on
|
|
257
|
+
claude-code). The orchestrate command and its team config are *not* claude-only —
|
|
258
|
+
they ship for opencode too.
|
|
259
|
+
|
|
260
|
+
## Templates
|
|
261
|
+
|
|
262
|
+
### `.ai/agent-fleet-overrides.md`
|
|
263
|
+
|
|
264
|
+
Copy this in and delete the sections you don't need — anything absent falls
|
|
265
|
+
back to that reader's default.
|
|
266
|
+
|
|
267
|
+
```markdown
|
|
268
|
+
# Agent Fleet — Project Overrides
|
|
269
|
+
#
|
|
270
|
+
# Each section is applied ON TOP of the skill's built-in defaults.
|
|
271
|
+
# Keys not listed keep the default. Absent file/section → pure defaults.
|
|
272
|
+
|
|
273
|
+
## spec-driven-development
|
|
274
|
+
spec-dir: docs/prds/{area}
|
|
275
|
+
naming: PRD{n}-{topic}
|
|
276
|
+
|
|
277
|
+
## planning-and-task-breakdown
|
|
278
|
+
plan-dir: docs/plans/{area}
|
|
279
|
+
naming: PLAN-{prd-name}-{phase}
|
|
280
|
+
todo: embedded
|
|
281
|
+
|
|
282
|
+
## browser-testing-with-devtools
|
|
283
|
+
dev-server: <command to start the local dev server>
|
|
284
|
+
ready-check: <url or check that confirms the server is up>
|
|
285
|
+
base-url: <root url>
|
|
286
|
+
auth-flow: |
|
|
287
|
+
1. Navigate to <login url>
|
|
288
|
+
2. Submit credentials for the role needed by the screen under test
|
|
289
|
+
roles:
|
|
290
|
+
admin: env APP_TEST_ADMIN_USER / APP_TEST_ADMIN_PASS
|
|
291
|
+
player: env APP_TEST_PLAYER_USER / APP_TEST_PLAYER_PASS
|
|
292
|
+
notes: |
|
|
293
|
+
<anything else: self-signed certs, required seed data, ...>
|
|
294
|
+
|
|
295
|
+
## git-workflow-and-versioning
|
|
296
|
+
branching: never
|
|
297
|
+
|
|
298
|
+
# Optional for pi agent-hub; omit this section to keep default English.
|
|
299
|
+
# (`## agent-team` is still accepted as a legacy alias for this section.)
|
|
300
|
+
## agent-hub
|
|
301
|
+
language: <language name>
|
|
302
|
+
rules: <repo-relative rule folder>[, <another folder>]
|
|
303
|
+
docs: <repo-relative doc entry point>[, <another file or folder>]
|
|
304
|
+
|
|
305
|
+
# Optional; names (never values) of env vars the sections above reference.
|
|
306
|
+
# Only `agent-fleet doctor` reads this — it warns when one is unset.
|
|
307
|
+
## env
|
|
308
|
+
required: <ENV_VAR_NAME>[, <ANOTHER_NAME>]
|
|
309
|
+
```
|
|
310
|
+
|
|
311
|
+
### `.ai/agent-fleet-setup.md`
|
|
312
|
+
|
|
313
|
+
Written and maintained by `guided-workspace-setup`; shown here for reference.
|
|
314
|
+
|
|
315
|
+
```markdown
|
|
316
|
+
# Agent Fleet — Workspace Setup
|
|
317
|
+
#
|
|
318
|
+
# Maintained by the guided-workspace-setup skill.
|
|
319
|
+
|
|
320
|
+
## workspace-summary
|
|
321
|
+
agent: claude-code
|
|
322
|
+
method: copy
|
|
323
|
+
version: 1.4.2
|
|
324
|
+
shape: <one line on the project shape>
|
|
325
|
+
|
|
326
|
+
## install-status
|
|
327
|
+
skills: [spec-driven-development, test-driven-development, code-review-and-quality]
|
|
328
|
+
commands: [spec, plan, build]
|
|
329
|
+
personas: [code-reviewer]
|
|
330
|
+
extensions: []
|
|
331
|
+
harnesses: []
|
|
332
|
+
harness-support: [] # justfile (managed region) + scripts/agents companions; tracked when any harness is installed
|
|
333
|
+
updated: 2026-05-22
|
|
334
|
+
|
|
335
|
+
## verification
|
|
336
|
+
- Every recorded artifact exists at its target path.
|
|
337
|
+
- No secrets are stored in this file.
|
|
338
|
+
```
|
|
339
|
+
|
|
340
|
+
### `.ai/stt.json`
|
|
341
|
+
|
|
342
|
+
Optional. Present only when the `pi-voice-stt` extension is installed and configured. Read by
|
|
343
|
+
the extension on every pi session start, ahead of the global `~/.pi/agent/stt.json`. Holds the
|
|
344
|
+
non-secret provider config; the API key (and Azure endpoint) live in a gitignored root `.env`
|
|
345
|
+
as named env vars, which the `justfile`'s `dotenv-load` exposes to the session.
|
|
346
|
+
|
|
347
|
+
```json
|
|
348
|
+
{
|
|
349
|
+
"language": "bg-BG",
|
|
350
|
+
"provider": {
|
|
351
|
+
"type": "azure",
|
|
352
|
+
"apiKeyEnv": "AZURE_SPEECH_KEY",
|
|
353
|
+
"locales": ["bg-BG", "en-US"]
|
|
354
|
+
}
|
|
355
|
+
}
|
|
356
|
+
```
|
|
357
|
+
|
|
358
|
+
Corresponding gitignored `.env` at the repo root:
|
|
359
|
+
|
|
360
|
+
```sh
|
|
361
|
+
AZURE_SPEECH_ENDPOINT=https://<resource>.cognitiveservices.azure.com
|
|
362
|
+
AZURE_SPEECH_KEY=<your-resource-key>
|
|
363
|
+
```
|
|
364
|
+
|
|
365
|
+
For the OpenAI-compatible backend, `provider.type` is `openai` with `baseUrl` / `model` and an
|
|
366
|
+
`OPENAI_API_KEY` env var instead. Full schema: [.pi/extensions/pi-voice-stt/README.md](../.pi/extensions/pi-voice-stt/README.md).
|
|
@@ -0,0 +1,103 @@
|
|
|
1
|
+
# Claude Code as a coms peer — the bridge
|
|
2
|
+
|
|
3
|
+
Makes an interactive Claude Code (terminal CLI) a **first-class, bidirectional peer** in
|
|
4
|
+
the local coms pool: pi agents reach it with plain `coms_send`/`coms_await`, and Claude
|
|
5
|
+
Code itself asks pi peers questions mid-task via `coms-cli`. Requires a running
|
|
6
|
+
[herdr](https://herdr.dev) server (the bridge drives the Claude pane through herdr's
|
|
7
|
+
socket API).
|
|
8
|
+
|
|
9
|
+
```
|
|
10
|
+
pi hub ── coms envelope ──▶ coms-claude-bridge ── pane.send_text ──▶ Claude Code (pane)
|
|
11
|
+
pi hub ◀── response ─────── coms-claude-bridge ◀── Stop hook file ─── (turn ends)
|
|
12
|
+
Claude Code ── Bash: coms-cli send/await ──▶ any pi peer (outbound asks)
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
## Pieces
|
|
16
|
+
|
|
17
|
+
| Piece | File | Role |
|
|
18
|
+
|---|---|---|
|
|
19
|
+
| Bridge daemon | `scripts/coms-claude-bridge.ts` | One per Claude pane. Registers coms peer `<name>`, serializes inbound prompts, types them into the pane (+ Enter separately — TUI quirk), captures the reply, sends the response envelope. |
|
|
20
|
+
| Envelope CLI | `scripts/coms-cli.ts` | `list` / `send` / `await` / `reply` — any process becomes a coms participant. `send --await` is a blocking round trip; plain `send` prints a `msg_id` and a detached waiter holds the reply for `await`. |
|
|
21
|
+
| Stop hook | `hooks/coms-stop-hook.mjs` | PRIMARY completion path: writes each turn's final assistant message to `~/.pi/coms/claude-bridge/<pane>/last-message.json` (keyed by `HERDR_PANE_ID`). Exact text, no scraping. |
|
|
22
|
+
| Skill | `skills/peer-coms/SKILL.md` | Teaches Claude Code its peer role: discover with `coms-cli list`, ask with `send --await`, answer inbound prompts normally, never drive panes itself. |
|
|
23
|
+
| Runner | `runner: claude-code` in `.pi/agents/peers.yaml` | `just team-up` spawns the Claude CLI + its bridge in one pane (`_claude-peer` recipe); `model:` maps to `claude --model`, team-resume maps the herdr-captured session id to `claude --resume`. |
|
|
24
|
+
|
|
25
|
+
## Setup
|
|
26
|
+
|
|
27
|
+
1. **Hook (recommended):** add to the project's (or user's) Claude Code `settings.json`:
|
|
28
|
+
|
|
29
|
+
```json
|
|
30
|
+
{
|
|
31
|
+
"hooks": {
|
|
32
|
+
"Stop": [{ "hooks": [{ "type": "command",
|
|
33
|
+
"command": "node /path/to/agent-fleet/hooks/coms-stop-hook.mjs" }] }]
|
|
34
|
+
}
|
|
35
|
+
}
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
Without the hook the bridge falls back to asking Claude for a
|
|
39
|
+
`<<COMS_DONE:msg_id>>` sentinel and scraping the pane — it works, but replies can
|
|
40
|
+
carry TUI noise (tool-status lines). The hook returns exact text.
|
|
41
|
+
|
|
42
|
+
2. **Skill:** install `peer-coms` via the normal per-agent flow so Claude Code knows it
|
|
43
|
+
is a peer and how to use `coms-cli`.
|
|
44
|
+
|
|
45
|
+
3. **Spawn:** either add a `runner: claude-code` peer to a peers.yaml team and
|
|
46
|
+
`just team-up <team>`, or attach a bridge to an existing herdr Claude pane:
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
node --experimental-strip-types scripts/coms-claude-bridge.ts --name claude-main
|
|
50
|
+
# (inside the pane: HERDR_PANE_ID is inherited; or pass --pane <id>)
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
## Demo scenario (verified live)
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
just team-up docs # pi peers up
|
|
57
|
+
# pane with: bridge (claude-main) + claude
|
|
58
|
+
just hub # in another pane: the orchestrator
|
|
59
|
+
# from the hub (or any shell):
|
|
60
|
+
node --experimental-strip-types scripts/coms-cli.ts send claude-main \
|
|
61
|
+
"Summarize the failing test output in artifacts/test.log" --await --timeout 300000
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
And the reverse — Claude Code, mid-task, asking a pi peer:
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
node --experimental-strip-types scripts/coms-cli.ts send researcher \
|
|
68
|
+
"Where is the retry logic for webhooks? file:line" --await --timeout 300000
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
## Serving team dispatches (coms-backed dispatch)
|
|
72
|
+
|
|
73
|
+
A bridge peer that shares a name with an agent-hub team member (e.g. `code-reviewer`,
|
|
74
|
+
`plan-reviewer` in the shipped `peers.yaml`) can serve that member's `dispatch_agent`
|
|
75
|
+
calls transparently: `.pi/agents/dispatch-policy.yaml` marks the member `prefer: coms`,
|
|
76
|
+
and the hub routes the dispatch to the live peer instead of spawning a native subagent —
|
|
77
|
+
same return contract, ASK_USER handling, and history. The standing Claude session keeps
|
|
78
|
+
its context across review rounds, which is the point for code/plan review. See
|
|
79
|
+
"Coms-backed dispatch" in `.pi/harnesses/agent-hub/README.md`.
|
|
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
|
+
|
|
91
|
+
## Behavior notes
|
|
92
|
+
|
|
93
|
+
- **Serialization:** one prompt at a time per pane; queue depth shows in the peer's
|
|
94
|
+
agent card and the herdr sidebar (`<name> q<depth>`).
|
|
95
|
+
- **Blocked panes:** a Claude waiting on a permission prompt returns a readable error
|
|
96
|
+
envelope ("blocked on a permission prompt — a human must approve it") instead of
|
|
97
|
+
hanging until timeout.
|
|
98
|
+
- **Busy panes:** a prompt arriving while Claude is mid-turn errors immediately
|
|
99
|
+
("mid-turn — try again shortly") rather than typing into a running turn.
|
|
100
|
+
- **Restarts:** the bridge is bound to the pane id, not the Claude process — restart
|
|
101
|
+
Claude in the pane and the bridge keeps working.
|
|
102
|
+
- **Fleet safety:** the bridge and skill never create or close panes; herdr driving
|
|
103
|
+
stays with the orchestrator (see `.pi/damage-control-rules.yaml`).
|
|
@@ -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.
|