AI-Agent-Hub

# Tool List AI Agent Hub is a lightweight MCP scheduling service running on Windows. It enables main agents like Claude Code and Codex to call local CLI Coding Agents through unified tools. V1 has completed a stable, secure, and auditable CLI Agent call chain; V2-M1 has delivered deterministic engineering gateways, V2-M2 has delivered Worktree isolation, and V2-M3 has delivered Review and integration gateways. The current milestone is V2-M4 "Secure Parallel Scheduling". The project's current milestones, acceptance evidence, and next steps are recorded in [docs/PROJECT-STATUS.md](docs/PROJECT-STATUS.md). ## Current Capabilities - Java 17 + Maven - Official MCP Java SDK 2.0.0 - stdio MCP Server - `list_agents`, `get_task`, `list_tasks`, `submit_agent_task`, `cancel_task`, `run_agent`, `run_review`, and `cleanup_worktree` - Codex CLI Adapter - Qoder CLI Adapter (`qodercli -p` non-interactive mode) - Generic CLI Adapter - Windows native process startup, no shell command string concatenation - stdin UTF-8 task transmission - Timeout, process tree termination, stdout/stderr capture and output limit - Working directory whitelist, Agent command whitelist, environment variable whitelist - Git repository and clean working directory verification - JSONL audit log and stdout/stderr independent log - Cross-Hub process workspace file lock - `scope.include` / `scope.exclude` file range enforcement verification - Server-side whitelist Verification Profile and automatic quality gateway - Agent and verification command independent output log - Git Worktree isolation execution, unique task branch, cross-process lifecycle lock, and idempotent cleanup - Retained Worktree independent read-only Reviewer and `run_review` MCP tool - JSON Schema constraint, independent final response file, and strict Review JSON parsing - Content SHA-256 fingerprint and Git HEAD/branch/index state dual immutability verification - Worker, Review, and integration verification combined deterministic `ready_for_integration` / `changes_requested` gateway - `.tasks/<runId>.json` atomic task snapshot, strict state migration, and Hub restart Review recovery - Server-side persistent queue, deterministic Worker Dispatcher, Scope conflict gateway, and cross-process global/repository/Agent quota slot - `get_task` and stable sorting `list_tasks` with state, Agent, and repository filtering - Immediate return persistent `queued` snapshot, background reuse of the same Dispatcher `submit_agent_task` - Queued task and Hub-owned Worker/Verification process tree idempotent `cancel_task` ## Architecture ```text Claude Code / Codex | | MCP tools v AI Agent Hub (Java) | +-- AgentRegistry +-- AgentAdapter +-- ProcessRunner +-- GitVerifier / ScopeVerifier +-- WorkspaceLockManager +-- WorktreeManager +-- ReviewService / ReviewOutputParser +-- WorkspaceFingerprinter +-- TaskStore / TaskRecord +-- ScopeConflictDetector / SchedulingCapacityManager +-- SchedulingDispatcher / TaskQuery +-- VerificationRunner +-- AuditLogger | v Codex CLI / Generic CLI | v Allowed Git workspace ``` ## Environment Requirements - Windows 10/11 - JDK 17 or higher - Maven 3.9+ - Git - At least one installed and logged-in CLI Agent Default Java on the local machine may still be Java 8. Explicitly set JDK 17 before building: ```powershell $env:JAVA_HOME = "D:\App\JDK\JDK17" $env:Path = "$env:JAVA_HOME\bin;$env:Path" java -version ``` ## Build and Test ```powershell mvn clean package ``` Generated executable: ```text target\ai-agent-hub.jar ``` Run regular tests only: ```powershell mvn test ``` Explicitly run real MCP + Codex E2E: ```powershell mvn -Dtest=McpV2E2eTest -DaiAgentHub.e2e=true test ``` This E2E will actually call Codex CLI, and the default build will skip it; only run during milestone acceptance or explicit regression. ## Configuration Edit `config/agents.yml`: ```yaml allowedWorkspaceRoots: - "D:/Study/MY_PROJECT" logsDirectory: "logs" worktreesDirectory: "worktrees" worktreeBranchPrefix: "ai-agent-hub/task" requireCleanWorkspace: true maxOutputBytes: 1048576 scheduling: maxConcurrentTasks: 4 maxConcurrentPerRepository: 2 defaultMaxConcurrentPerAgent: 1 agentLimits: codex: 1 qoder: 1 queueCapacity: 100 heartbeatIntervalSeconds: 5 staleAfterSeconds: 30 verificationProfiles: maven-test: displayName: Maven tests command: [mvn.cmd, test] timeoutSeconds: 600 agents: codex: adapter: codex command: codex.cmd enabled: true capabilities: [code, review, test] timeoutSeconds: 1800 qoder: adapter: qodercli command: qodercli.exe enabled: true capabilities: [code, review, test] timeoutSeconds: 1800 ``` Security rules: - `workspace` must be under `allowedWorkspaceRoots`. - Default requires a clean Git working directory to avoid mistakenly considering old changes as the current result. - MCP parameters cannot pass arbitrary commands; Agent and verification commands can only come from the configuration whitelist. - In `in_place` mode, the same workspace cannot execute concurrently; Worktree creation uses a short-term benchmark repository lock. - Worktree root directory must be outside the target repository, and task branches must be under the configured branch prefix. - Worktree is retained after success or failure; dirty Worktree can only be cleaned with explicit `force: true`. - `scope` uses workspace relative paths, supporting `*`, `**`, and `?`. - Agent out-of-bounds modifications will not be considered successful, returning `scope_violation`. - Codex Worker uses `workspace-write` by default; Reviewer uses `read-only`, JSON Schema, and independent final response files, without adding dangerous parameters that bypass approval and sandboxing. - Reviewer checks content fingerprints and Git status before and after; any content, HEAD, branch, index, or untracked state drift will block integration. ## Start ```powershell $env:AI_AGENT_HUB_JAVA_HOME = "D:\App\JDK\JDK17" .\scripts\run-hub.cmd ``` stdio mode, stdout can only be used for MCP JSON-RPC. Service logs are written to stderr or `logs/`. ## Access Claude Code Claude Code on Windows needs to find Git Bash: ```powershell $env:CLAUDE_CODE_GIT_BASH_PATH = "D:\App\Git\Git\bin\bash.exe" ``` Build JAR and register project-level MCP Server: ```powershell claude mcp add --scope project -e AI_AGENT_HUB_JAVA_HOME=D:\App\JDK\JDK17 ai-agent-hub -- D:\Study\MY_PROJECT\AI-Agent-Hub\scripts\run-hub.cmd ``` Check configuration: ```powershell claude mcp get ai-agent-hub claude mcp list ``` Then restart Claude Code and confirm that you can see through `/mcp`: - `list_agents` - `get_task` - `list_tasks` - `submit_agent_task` - `cancel_task` - `run_agent` - `run_review` - `cleanup_worktree` ## MCP Request Example ```json { "agentId": "codex", "workspace": "D:/Study/MY_PROJECT/demo-project", "timeoutSeconds": 900, "task": { "title": "Implement Todo deletion function", "goal": "Add deletion interface and supplement test", "files": ["TodoService", "TodoController"], "constraints": ["Do not modify database structure"], "acceptanceCriteria": ["Test passed", "Only modify Todo module"] }, "scope": { "include": ["src/main/java/**/todo/**", "src/test/java/**/todo/**"], "exclude": ["src/main/java/**/migration/**"] }, "verificationProfile": "maven-test", "isolation": { "mode": "worktree", "baseRef": "HEAD", "retention": "retain" } } ``` `scope` is omitted when not limiting files; `verificationProfile` is omitted when no additional verification is performed. Verification commands cannot be temporarily specified by MCP requests and can only select existing Profiles in `config/agents.yml`. `isolation` is omitted when keeping compatibility and continuing to use `in_place`; specify `mode: worktree` and then Agent, Git snapshot, and verification commands run in an independent Worktree. `run_agent` will wait synchronously for queuing and execution. When needing to return immediately, use the same request structure to call `submit_agent_task`; it will return a `queued` snapshot after security pre-check and continue execution in the background. The returned `runId` is also a persistent `taskId`. Read the latest task snapshot anytime: ```json { "taskId": "run-20260715-001" } ``` Tasks can be canceled with `cancel_task` and the same `taskId` idempotently. `queued` will atomically migrate to `cancelled`; tasks started by the current Hub with `submit_agent_task` and in `starting`, `running`, or `verifying` will first migrate to `cancel_requested`, and the Worker/Verification process tree will be terminated in a controlled manner, and only after confirmation of exit will `cancelled` be written. Cross-Hub instances, synchronous calls, and `reviewing` will explicitly fail and close without forging a cancelled state; cancellation will not delete Worktree, branches, logs, or audit evidence. You can also query with stable sorting `list_tasks`; all fields can be omitted, `limit` defaults to 100, and the maximum is 1000: ```json { "state": "worker_succeeded", "agentId": "codex", "workspace": "D:/Study/MY_PROJECT/demo-project", "limit": 50 } ``` Worktree result `execution` will return `mode`, `baseWorkspace`, `workspace`, `baseRef`, `baseCommit`, `branch`, `headCommit`, and `retained`. When reviewing, you must pass the complete `execution` and original Worker `runId` to `run_review`: ```json { "reviewerAgentId": "codex", "workerRunId": "run-20260715-001", "execution": { "mode": "worktree", "baseWorkspace": "D:/Study/MY_PROJECT/demo-project", "workspace": "D:/Study/MY_PROJECT/ai-agent-hub-worktrees/demo-project-run-20260715-001", "baseRef": "HEAD", "baseCommit": "0123456789abcdef", "branch": "ai-agent-hub/task/run-20260715-001", "headCommit": "0123456789abcdef", "retained": true }, "focus": ["correctness", "security", "tests"], "standards": ["No public API regression"], "integrationVerificationProfile": "maven-test" } ``` Review only returns structured Finding and deterministic `gateStatus`, without automatic merging or cleaning. The result is `ready_for_integration` and still requires explicit integration by subsequent processes; `changes_requested` or other failed states will retain the scene. When cleaning up, pass `execution` to `cleanup_worktree`; if there are uncommitted modifications, you must explicitly set `force: true`, and the cleanup interface can be called repeatedly. Worker result states include `success`, `failed`, `timeout`, `scope_violation`, `verification_failed`, and `workspace_busy`. When assigning tasks to Qoder, simply change the `agentId` in the MCP request to `qoder`: ```json { "agentId": "qoder", "workspace": "D:/Study/MY_PROJECT/demo-project", "task": { "title": "Implement Todo deletion function", "goal": "Add deletion interface and supplement related test" } } ``` ## V2 Current Progress V2-M1 "Deterministic Engineering Gateway" has been completed, and the delivery commit is `35e27d1`; 16 regular tests and 1 real MCP + Codex E2E have passed. V2-M2 "Git Worktree and Task Branch Lifecycle" has been completed, and the delivery commit is `cc04d72`: `run_agent` supports isolated execution, and the result and audit return complete execution context. Dual tasks can run in parallel, and `cleanup_worktree` supports safe idempotent cleanup. V2-M3 "Review and Integration Gateway" has been completed, and the delivery commit is `c62418b`: a new read-only Reviewer, structured Finding, content fingerprint and Git status dual immutability, integration verification, and deterministic "integrable / need to rework" gateway. The current milestone is V2-M4 "Secure Parallel Scheduling". Persistent task registry, scheduling configuration, conservative Scope conflict judgment, cross-process quota slot, and deterministic Worker Dispatcher have been implemented; synchronous `run_agent` and asynchronous `submit_agent_task` reuse the same execution link, `get_task` / `list_tasks` can query tasks across restarts, and `cancel_task` has covered queued tasks and the Hub's own Worker/Verification process tree. Currently, persistent operation ownership, heartbeat, and orphan reconciliation are being implemented. Detailed tasks, acceptance conditions, evidence, and risks are based on [`docs/PROJECT-STATUS.md`](docs/PROJECT-STATUS.md); Worktree boundary see [`docs/V2-WORKTREE-DESIGN.md`](docs/V2-WORKTREE-DESIGN.md); Review design see [`docs/V2-REVIEW-DESIGN.md`](docs/V2-REVIEW-DESIGN.md); and parallel scheduling contract see [`docs/V2-PARALLEL-SCHEDULING-DESIGN.md`](docs/V2-PARALLEL-SCHEDULING-DESIGN.md). ## Test Scope Automatic test coverage: - YAML configuration loading - Codex command construction and dangerous parameter checking - UTF-8 stdin/stdout - Non-zero exit code and stderr - Timeout and process termination - Output truncation - Git repository, clean state, and change file recognition - Generic Adapter to log and Git result service-level link - Cross-instance workspace lock competition and release - File range matching, exclusion, and path escape checking - Verification Profile loading, execution, skipping, and audit log - Space-delimited Git path, space-delimited file name, and renaming recognition - Worktree creation, query, residue reconciliation, lifecycle lock, dirty directory protection, and idempotent cleanup - `run_agent` isolated execution, structured execution result, audit field, and dual-task safe parallel - Review JSON Schema, strict field/enum/path/conclusion consistency parsing - Workspace content fingerprint, Git HEAD/branch/index state drift detection - Read-only Reviewer, Worker gateway short circuit, Finding, integration verification, audit, and deterministic Gate state - Reviewer and cleanup between retained Worktree lifecycle mutual exclusion - Task snapshot atomic replacement, strict field/state machine verification, concurrent final state writing, and cross-Hub instance Review recovery - Scheduling numerical constraints, unknown field rejection, static path prefix conflict, and cross-instance quota acquisition/release In addition, the project has completed real link verification on Windows: ```text MCP initialize -> tools/list found run_agent / submit_agent_task / get_task / list_tasks / cancel_task / run_review / cleanup_worktree -> run_agent(codex, isolation=worktree) -> Hub creates task branch and independent Worktree -> Codex Worker and Verification run in Worktree -> Hub returns changedFiles and complete execution -> run_review(codex, retained execution) -> Codex Reviewer outputs JSON that meets the schema in a read-only sandbox -> Hub verifies content fingerprint and Git status and executes integration Verification -> gateStatus=ready_for_integration -> cleanup_worktree(force=true) -> Second cleanup returns alreadyAbsent ``` For more design background, see `docs/Windows-AI-Agent-Hub-Architecture-Whitepaper-V2.md`.