codefleet 0.3.0__py3-none-any.whl

codefleet/__init__.py

@@ -0,0 +1,3 @@
+"""codefleet — orchestrate fleets of AI coding agents across providers."""
+
+__version__ = "0.3.0"

codefleet/git_ops.py

@@ -0,0 +1,115 @@
+import shutil
+import subprocess
+from pathlib import Path
+
+
+class GitError(Exception):
+    pass
+
+
+def is_git_repo(path: Path) -> bool:
+    """Check if path is inside a git repository."""
+    try:
+        result = subprocess.run(
+            ["git", "-C", str(path), "rev-parse", "--is-inside-work-tree"],
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+        return result.returncode == 0 and result.stdout.strip() == "true"
+    except (subprocess.TimeoutExpired, FileNotFoundError):
+        return False
+
+
+def resolve_ref(repo_path: Path, ref: str = "HEAD") -> str:
+    """Resolve a git ref to a commit hash."""
+    result = subprocess.run(
+        ["git", "-C", str(repo_path), "rev-parse", ref],
+        capture_output=True,
+        text=True,
+        timeout=10,
+    )
+    if result.returncode != 0:
+        raise GitError(f"Failed to resolve ref '{ref}': {result.stderr.strip()}")
+    return result.stdout.strip()
+
+
+def create_worktree(
+    repo_path: Path,
+    worktree_path: Path,
+    branch_name: str,
+    base_ref: str = "HEAD",
+) -> None:
+    """Create a git worktree with a new branch."""
+    worktree_path.parent.mkdir(parents=True, exist_ok=True)
+    result = subprocess.run(
+        [
+            "git", "-C", str(repo_path),
+            "worktree", "add",
+            "-b", branch_name,
+            str(worktree_path),
+            base_ref,
+        ],
+        capture_output=True,
+        text=True,
+        timeout=30,
+    )
+    if result.returncode != 0:
+        raise GitError(f"Failed to create worktree: {result.stderr.strip()}")
+
+
+def remove_worktree(repo_path: Path, worktree_path: Path) -> None:
+    """Remove a git worktree."""
+    result = subprocess.run(
+        [
+            "git", "-C", str(repo_path),
+            "worktree", "remove", "--force",
+            str(worktree_path),
+        ],
+        capture_output=True,
+        text=True,
+        timeout=30,
+    )
+    if result.returncode != 0:
+        # If worktree remove fails, try to clean up manually
+        if worktree_path.exists():
+            shutil.rmtree(worktree_path, ignore_errors=True)
+        # Prune stale worktrees
+        subprocess.run(
+            ["git", "-C", str(repo_path), "worktree", "prune"],
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+
+
+def delete_branch(repo_path: Path, branch_name: str) -> None:
+    """Delete a git branch."""
+    result = subprocess.run(
+        ["git", "-C", str(repo_path), "branch", "-D", branch_name],
+        capture_output=True,
+        text=True,
+        timeout=10,
+    )
+    if result.returncode != 0:
+        raise GitError(
+            f"Failed to delete branch '{branch_name}': {result.stderr.strip()}"
+        )
+
+
+def get_git_path() -> str | None:
+    """Return the path to git, or None."""
+    return shutil.which("git")
+
+
+def get_repo_root(path: Path) -> Path | None:
+    """Return the root of the git repo containing path."""
+    result = subprocess.run(
+        ["git", "-C", str(path), "rev-parse", "--show-toplevel"],
+        capture_output=True,
+        text=True,
+        timeout=10,
+    )
+    if result.returncode == 0:
+        return Path(result.stdout.strip())
+    return None

codefleet/models.py

@@ -0,0 +1,233 @@
+from __future__ import annotations
+
+import enum
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class ExecutorType(str, enum.Enum):
+    CODEX = "codex"
+    GEMINI = "gemini"
+    CLAUDE = "claude"
+
+
+class WorkerStatus(str, enum.Enum):
+    PENDING = "pending"
+    RUNNING = "running"
+    SUCCEEDED = "succeeded"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+    TIMED_OUT = "timed_out"
+    CLEANUP_FAILED = "cleanup_failed"
+
+    @property
+    def is_terminal(self) -> bool:
+        return self in {
+            WorkerStatus.SUCCEEDED,
+            WorkerStatus.FAILED,
+            WorkerStatus.CANCELLED,
+            WorkerStatus.TIMED_OUT,
+            WorkerStatus.CLEANUP_FAILED,
+        }
+
+
+class ResultStatus(str, enum.Enum):
+    COMPLETED = "completed"
+    BLOCKED = "blocked"
+
+
+class TestStatus(str, enum.Enum):
+    PASSED = "passed"
+    FAILED = "failed"
+    NOT_RUN = "not_run"
+
+
+class TestResult(BaseModel):
+    command: str
+    status: TestStatus
+    details: str = ""
+
+
+class WorkerResult(BaseModel):
+    summary: str
+    files_changed: list[str] = Field(default_factory=list)
+    tests: list[TestResult] = Field(default_factory=list)
+    commits: list[str] = Field(default_factory=list)
+    next_steps: list[str] = Field(default_factory=list)
+    status: ResultStatus
+
+
+class WorkerRecord(BaseModel):
+    worker_id: str
+    task_name: str
+    repo_path: str
+    branch_name: str
+    worktree_path: str
+    worker_dir: str
+    model: str
+    executor: ExecutorType = ExecutorType.CODEX
+    profile: Optional[str] = None
+    status: WorkerStatus
+    created_at: float
+    started_at: Optional[float] = None
+    ended_at: Optional[float] = None
+    timeout_seconds: int
+    pid: Optional[int] = None
+    exit_code: Optional[int] = None
+    codex_command: str
+    prompt: str
+    result_json_path: str
+    stdout_path: str
+    stderr_path: str
+    prompt_path: str
+    meta_path: str
+    retry_count: int = 0
+    parent_worker_id: Optional[str] = None
+    tags: list[str] = Field(default_factory=list)
+    metadata: dict = Field(default_factory=dict)
+    error_message: Optional[str] = None
+    workflow_id: Optional[str] = None
+    stage_index: Optional[int] = None
+
+
+class WorkerStatusPayload(BaseModel):
+    """Payload returned by create_worker, get_worker_status, etc."""
+
+    worker_id: str
+    task_name: str
+    status: WorkerStatus
+    repo_path: str
+    branch_name: str
+    worktree_path: str
+    worker_dir: str
+    model: str
+    executor: ExecutorType = ExecutorType.CODEX
+    profile: Optional[str] = None
+    created_at: float
+    started_at: Optional[float] = None
+    ended_at: Optional[float] = None
+    timeout_seconds: int
+    pid: Optional[int] = None
+    exit_code: Optional[int] = None
+    retry_count: int = 0
+    tags: list[str] = Field(default_factory=list)
+    metadata: dict = Field(default_factory=dict)
+    error_message: Optional[str] = None
+    prompt_path: str
+    result_json_path: str
+    stdout_path: str
+    stderr_path: str
+    meta_path: str
+
+    @classmethod
+    def from_record(cls, record: WorkerRecord) -> WorkerStatusPayload:
+        return cls(
+            worker_id=record.worker_id,
+            task_name=record.task_name,
+            status=record.status,
+            repo_path=record.repo_path,
+            branch_name=record.branch_name,
+            worktree_path=record.worktree_path,
+            worker_dir=record.worker_dir,
+            model=record.model,
+            executor=record.executor,
+            profile=record.profile,
+            created_at=record.created_at,
+            started_at=record.started_at,
+            ended_at=record.ended_at,
+            timeout_seconds=record.timeout_seconds,
+            pid=record.pid,
+            exit_code=record.exit_code,
+            retry_count=record.retry_count,
+            tags=record.tags,
+            metadata=record.metadata,
+            error_message=record.error_message,
+            prompt_path=record.prompt_path,
+            result_json_path=record.result_json_path,
+            stdout_path=record.stdout_path,
+            stderr_path=record.stderr_path,
+            meta_path=record.meta_path,
+        )
+
+
+# --- Workflow Models ---
+
+
+class WorktreeStrategy(str, enum.Enum):
+    NEW = "new"
+    INHERIT = "inherit"
+
+
+class StageDefinition(BaseModel):
+    name: str
+    executor: ExecutorType
+    prompt_template: str
+    model: Optional[str] = None
+    worktree_strategy: WorktreeStrategy = WorktreeStrategy.INHERIT
+    depends_on: list[int] = Field(default_factory=list)
+    timeout_seconds: Optional[int] = None
+    reasoning_effort: Optional[str] = None
+    extra_args: Optional[list[str]] = None
+
+
+class WorkflowStatus(str, enum.Enum):
+    PENDING = "pending"
+    RUNNING = "running"
+    SUCCEEDED = "succeeded"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+
+class StageState(BaseModel):
+    worker_id: Optional[str] = None
+    status: WorkerStatus = WorkerStatus.PENDING
+    worktree_path: Optional[str] = None
+
+
+class WorkflowRecord(BaseModel):
+    workflow_id: str
+    name: str
+    status: WorkflowStatus
+    repo_path: str
+    base_ref: str
+    task_prompt: str
+    stages: list[StageDefinition]
+    stage_states: dict[int, StageState] = Field(default_factory=dict)
+    created_at: float
+    completed_at: Optional[float] = None
+    error_message: Optional[str] = None
+
+
+class WorkflowStatusPayload(BaseModel):
+    workflow_id: str
+    name: str
+    status: WorkflowStatus
+    repo_path: str
+    stage_summary: list[dict]
+    created_at: float
+    completed_at: Optional[float] = None
+    error_message: Optional[str] = None
+
+    @classmethod
+    def from_record(cls, record: WorkflowRecord) -> WorkflowStatusPayload:
+        stage_summary = []
+        for i, stage in enumerate(record.stages):
+            state = record.stage_states.get(i, StageState())
+            stage_summary.append({
+                "index": i,
+                "name": stage.name,
+                "executor": stage.executor.value,
+                "status": state.status.value,
+                "worker_id": state.worker_id,
+            })
+        return cls(
+            workflow_id=record.workflow_id,
+            name=record.name,
+            status=record.status,
+            repo_path=record.repo_path,
+            stage_summary=stage_summary,
+            created_at=record.created_at,
+            completed_at=record.completed_at,
+            error_message=record.error_message,
+        )

codefleet/result_schema.py

@@ -0,0 +1,39 @@
+import json
+from pathlib import Path
+
+from .models import WorkerResult
+
+
+class ResultValidationError(Exception):
+    pass
+
+
+def parse_result_file(path: Path) -> WorkerResult:
+    """Parse and validate a result.json file."""
+    if not path.exists():
+        raise ResultValidationError(f"Result file not found: {path}")
+
+    raw = path.read_text(encoding="utf-8")
+    if not raw.strip():
+        raise ResultValidationError(f"Result file is empty: {path}")
+
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError as e:
+        raise ResultValidationError(f"Invalid JSON in result file: {e}")
+
+    if not isinstance(data, dict):
+        raise ResultValidationError("Result JSON must be an object")
+
+    try:
+        return WorkerResult.model_validate(data)
+    except Exception as e:
+        raise ResultValidationError(f"Result schema validation failed: {e}")
+
+
+def validate_result_data(data: dict) -> WorkerResult:
+    """Validate a result dict against the schema."""
+    try:
+        return WorkerResult.model_validate(data)
+    except Exception as e:
+        raise ResultValidationError(f"Result schema validation failed: {e}")

codefleet/server.py

@@ -0,0 +1,196 @@
+import os
+from typing import Optional
+
+from mcp.server.fastmcp import FastMCP
+
+from .supervisor import FleetSupervisor
+
+
+def create_server(supervisor: Optional[FleetSupervisor] = None) -> FastMCP:
+    """Create the MCP server with all tools registered."""
+    mcp = FastMCP("codefleet")
+
+    if supervisor is None:
+        allowed_repos_str = os.environ.get("FLEET_ALLOWED_REPOS", "")
+        allowed_repos = (
+            [r.strip() for r in allowed_repos_str.split(",") if r.strip()] or None
+        )
+
+        supervisor = FleetSupervisor(
+            base_dir=os.environ.get("FLEET_BASE_DIR"),
+            default_model=os.environ.get("FLEET_DEFAULT_MODEL", "gpt-5.4"),
+            default_gemini_model=os.environ.get(
+                "FLEET_GEMINI_DEFAULT_MODEL", "gemini-3.1-pro-preview"
+            ),
+            default_claude_model=os.environ.get(
+                "FLEET_CLAUDE_DEFAULT_MODEL", "claude-sonnet-4-6"
+            ),
+            default_reasoning_effort=os.environ.get("FLEET_REASONING_EFFORT", "xhigh"),
+            default_timeout=int(os.environ.get("FLEET_DEFAULT_TIMEOUT", "600")),
+            max_concurrent=int(os.environ.get("FLEET_MAX_CONCURRENT", "10")),
+            allowed_repos=allowed_repos,
+            default_executor=os.environ.get("FLEET_DEFAULT_EXECUTOR", "codex"),
+            max_spawn_depth=int(os.environ.get("FLEET_MAX_SPAWN_DEPTH", "2")),
+        )
+
+    # --- Worker tools ---
+
+    @mcp.tool()
+    def healthcheck() -> dict:
+        """Return a basic capability report. Lets Claude verify the MCP server is reachable and the local environment is sane."""
+        return supervisor.healthcheck()
+
+    @mcp.tool()
+    def create_worker(
+        repo_path: str,
+        task_name: str,
+        prompt: str,
+        base_ref: str = "HEAD",
+        model: Optional[str] = None,
+        executor: Optional[str] = None,
+        reasoning_effort: Optional[str] = None,
+        timeout_seconds: Optional[int] = None,
+        profile: Optional[str] = None,
+        tags: Optional[list[str]] = None,
+        metadata: Optional[dict] = None,
+        extra_args: Optional[list[str]] = None,
+        extra_codex_args: Optional[list[str]] = None,
+        parent_worker_id: Optional[str] = None,
+    ) -> dict:
+        """Launch a new worker in an isolated git worktree. Supports 'codex', 'gemini', and 'claude' executors."""
+        result = supervisor.create_worker(
+            repo_path=repo_path,
+            task_name=task_name,
+            prompt=prompt,
+            base_ref=base_ref,
+            model=model,
+            executor=executor,
+            reasoning_effort=reasoning_effort,
+            timeout_seconds=timeout_seconds,
+            profile=profile,
+            tags=tags,
+            metadata=metadata,
+            extra_args=extra_args,
+            extra_codex_args=extra_codex_args,
+            parent_worker_id=parent_worker_id,
+        )
+        return result.model_dump()
+
+    @mcp.tool()
+    def get_worker_status(worker_id: str) -> dict:
+        """Return current status and metadata for a worker."""
+        result = supervisor.get_worker_status(worker_id)
+        return result.model_dump()
+
+    @mcp.tool()
+    def list_workers(
+        statuses: Optional[list[str]] = None,
+        limit: int = 25,
+    ) -> dict:
+        """List recent workers, optionally filtered by status."""
+        results = supervisor.list_workers(statuses=statuses, limit=limit)
+        return {"workers": [r.model_dump() for r in results], "count": len(results)}
+
+    @mcp.tool()
+    def collect_worker_result(
+        worker_id: str,
+        include_logs: bool = False,
+        log_tail_lines: int = 80,
+    ) -> dict:
+        """Return worker metadata plus parsed result.json and optional log tails."""
+        return supervisor.collect_worker_result(
+            worker_id=worker_id,
+            include_logs=include_logs,
+            log_tail_lines=log_tail_lines,
+        )
+
+    @mcp.tool()
+    def cancel_worker(worker_id: str) -> dict:
+        """Cancel a running worker."""
+        result = supervisor.cancel_worker(worker_id)
+        return result.model_dump()
+
+    @mcp.tool()
+    def cleanup_worker(
+        worker_id: str,
+        remove_branch: bool = True,
+        remove_worktree_dir: bool = True,
+    ) -> dict:
+        """Remove worktree and optional branch for a terminal worker."""
+        return supervisor.cleanup_worker(
+            worker_id=worker_id,
+            remove_branch=remove_branch,
+            remove_worktree_dir=remove_worktree_dir,
+        )
+
+    # --- Workflow tools ---
+
+    @mcp.tool()
+    def create_workflow(
+        name: str,
+        repo_path: str,
+        task_prompt: str,
+        stages: list[dict],
+        base_ref: str = "HEAD",
+        timeout_seconds: Optional[int] = None,
+    ) -> dict:
+        """Define and start a multi-stage workflow. Stages form a DAG where each stage uses any executor (codex/gemini) and results flow between stages via prompt templates."""
+        result = supervisor.create_workflow(
+            name=name,
+            repo_path=repo_path,
+            task_prompt=task_prompt,
+            stages=stages,
+            base_ref=base_ref,
+            timeout_seconds=timeout_seconds,
+        )
+        return result.model_dump()
+
+    @mcp.tool()
+    def get_workflow_status(workflow_id: str) -> dict:
+        """Return workflow state with per-stage worker statuses."""
+        result = supervisor.get_workflow_status(workflow_id)
+        return result.model_dump()
+
+    @mcp.tool()
+    def list_workflows(
+        statuses: Optional[list[str]] = None,
+        limit: int = 25,
+    ) -> dict:
+        """List workflows with optional status filter."""
+        results = supervisor.list_workflows(statuses=statuses, limit=limit)
+        return {"workflows": [r.model_dump() for r in results], "count": len(results)}
+
+    @mcp.tool()
+    def cancel_workflow(workflow_id: str) -> dict:
+        """Cancel all running stages and mark workflow cancelled."""
+        result = supervisor.cancel_workflow(workflow_id)
+        return result.model_dump()
+
+    @mcp.tool()
+    def collect_workflow_result(
+        workflow_id: str,
+        include_all_stages: bool = False,
+        include_logs: bool = False,
+    ) -> dict:
+        """Get the final stage's result (or all stages' results)."""
+        return supervisor.collect_workflow_result(
+            workflow_id=workflow_id,
+            include_all_stages=include_all_stages,
+            include_logs=include_logs,
+        )
+
+    @mcp.tool()
+    def cleanup_workflow(workflow_id: str) -> dict:
+        """Clean up all worktrees, branches, and worker dirs for a terminal workflow."""
+        return supervisor.cleanup_workflow(workflow_id)
+
+    return mcp
+
+
+def main():
+    server = create_server()
+    server.run()
+
+
+if __name__ == "__main__":
+    main()