execforge 0.1.0__py3-none-any.whl

orchestrator/config.py

@@ -0,0 +1,272 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from pathlib import Path
+import logging
+import os
+import tempfile
+import tomllib
+from typing import Any, Callable
+
+from platformdirs import user_data_dir
+
+from orchestrator.exceptions import ConfigError
+
+
+APP_NAME = "agent-orchestrator"
+logger = logging.getLogger("orchestrator.config")
+
+
+@dataclass(slots=True)
+class AppPaths:
+    root: Path
+    db_file: Path
+    config_file: Path
+    logs_dir: Path
+    prompt_sources_dir: Path
+    runs_dir: Path
+    cache_dir: Path
+    lock_dir: Path
+
+
+@dataclass(slots=True)
+class AppConfig:
+    log_level: str = "INFO"
+    default_timeout_seconds: int = 900
+    default_require_clean_tree: bool = True
+    default_allow_push: bool = False
+    claude_api_key: str | None = None
+    codex_api_key: str | None = None
+    opencode_api_key: str | None = None
+
+
+@dataclass(slots=True)
+class ConfigFieldSpec:
+    key: str
+    value_type: type
+    default: Any
+    sensitive: bool = False
+    validator: Callable[[Any], bool] | None = None
+    description: str = ""
+
+
+def _bool_from_text(value: str) -> bool:
+    lowered = value.strip().lower()
+    if lowered in {"true", "1", "yes", "y", "on"}:
+        return True
+    if lowered in {"false", "0", "no", "n", "off"}:
+        return False
+    raise ConfigError(f"Expected boolean value, got '{value}'")
+
+
+def _cast_value(spec: ConfigFieldSpec, raw: Any) -> Any:
+    if raw is None:
+        return None
+    if spec.value_type is bool:
+        if isinstance(raw, bool):
+            return raw
+        if isinstance(raw, str):
+            return _bool_from_text(raw)
+        raise ConfigError(f"Config '{spec.key}' must be a boolean")
+    if spec.value_type is int:
+        try:
+            return int(raw)
+        except (TypeError, ValueError) as exc:
+            raise ConfigError(f"Config '{spec.key}' must be an integer") from exc
+    if spec.value_type is str:
+        return str(raw)
+    return raw
+
+
+def _validate_log_level(value: str) -> bool:
+    return value.upper() in {"DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"}
+
+
+def _validate_timeout(value: int) -> bool:
+    return 1 <= value <= 86400
+
+
+def get_config_schema() -> dict[str, ConfigFieldSpec]:
+    return {
+        "log_level": ConfigFieldSpec(
+            key="log_level",
+            value_type=str,
+            default="INFO",
+            validator=_validate_log_level,
+            description="Logging level",
+        ),
+        "default_timeout_seconds": ConfigFieldSpec(
+            key="default_timeout_seconds",
+            value_type=int,
+            default=900,
+            validator=_validate_timeout,
+            description="Default run timeout in seconds",
+        ),
+        "default_require_clean_tree": ConfigFieldSpec(
+            key="default_require_clean_tree",
+            value_type=bool,
+            default=True,
+            description="Require clean working tree before run",
+        ),
+        "default_allow_push": ConfigFieldSpec(
+            key="default_allow_push",
+            value_type=bool,
+            default=False,
+            description="Allow push by default",
+        ),
+        "claude_api_key": ConfigFieldSpec(
+            key="claude_api_key",
+            value_type=str,
+            default=None,
+            sensitive=True,
+            description="Optional Claude API key",
+        ),
+        "codex_api_key": ConfigFieldSpec(
+            key="codex_api_key",
+            value_type=str,
+            default=None,
+            sensitive=True,
+            description="Optional Codex API key",
+        ),
+        "opencode_api_key": ConfigFieldSpec(
+            key="opencode_api_key",
+            value_type=str,
+            default=None,
+            sensitive=True,
+            description="Optional OpenCode API key",
+        ),
+    }
+
+
+def get_app_paths() -> AppPaths:
+    override = os.environ.get("AGENT_ORCHESTRATOR_HOME") or os.environ.get("ORCHESTRATOR_HOME")
+    root = Path(override).expanduser() if override else Path(user_data_dir(APP_NAME, APP_NAME))
+    return AppPaths(
+        root=root,
+        db_file=root / "app.db",
+        config_file=root / "config.toml",
+        logs_dir=root / "logs",
+        prompt_sources_dir=root / "prompt-sources",
+        runs_dir=root / "runs",
+        cache_dir=root / "cache",
+        lock_dir=root / "locks",
+    )
+
+
+def ensure_app_dirs(paths: AppPaths) -> None:
+    for p in [
+        paths.root,
+        paths.logs_dir,
+        paths.prompt_sources_dir,
+        paths.runs_dir,
+        paths.cache_dir,
+        paths.lock_dir,
+    ]:
+        p.mkdir(parents=True, exist_ok=True)
+
+
+def _normalize_loaded_data(data: dict[str, Any]) -> dict[str, Any]:
+    schema = get_config_schema()
+    normalized: dict[str, Any] = {}
+    for key, spec in schema.items():
+        if key not in data:
+            continue
+        value = _cast_value(spec, data[key])
+        if spec.validator and value is not None and not spec.validator(value):
+            raise ConfigError(f"Invalid value for '{key}': {value}")
+        normalized[key] = value
+    return normalized
+
+
+def load_config(paths: AppPaths) -> AppConfig:
+    if not paths.config_file.exists():
+        return AppConfig()
+    with paths.config_file.open("rb") as fh:
+        data = tomllib.load(fh)
+    normalized = _normalize_loaded_data(data)
+    return AppConfig(**normalized)
+
+
+def _serialize_toml(config: AppConfig) -> str:
+    data = asdict(config)
+    schema = get_config_schema()
+    lines: list[str] = []
+    for key, spec in schema.items():
+        value = data.get(key)
+        if value is None:
+            continue
+        if spec.value_type is bool:
+            lines.append(f"{key} = {str(value).lower()}")
+        elif spec.value_type is int:
+            lines.append(f"{key} = {value}")
+        else:
+            escaped = str(value).replace('"', '\\"')
+            lines.append(f'{key} = "{escaped}"')
+    lines.append("")
+    return "\n".join(lines)
+
+
+def save_config(paths: AppPaths, config: AppConfig) -> None:
+    text = _serialize_toml(config)
+    paths.config_file.parent.mkdir(parents=True, exist_ok=True)
+    with tempfile.NamedTemporaryFile("w", delete=False, encoding="utf-8", dir=str(paths.config_file.parent)) as tmp:
+        tmp.write(text)
+        tmp_path = Path(tmp.name)
+    tmp_path.replace(paths.config_file)
+
+
+def config_to_display_dict(config: AppConfig, mask_sensitive: bool = True) -> dict[str, Any]:
+    data = asdict(config)
+    schema = get_config_schema()
+    out: dict[str, Any] = {}
+    for key, spec in schema.items():
+        value = data.get(key)
+        if mask_sensitive and spec.sensitive and value:
+            out[key] = "********"
+        else:
+            out[key] = value
+    return out
+
+
+def update_config_values(paths: AppPaths, updates: dict[str, str]) -> AppConfig:
+    schema = get_config_schema()
+    unknown = [k for k in updates if k not in schema]
+    if unknown:
+        known = ", ".join(sorted(schema.keys()))
+        raise ConfigError(f"Unknown config key(s): {', '.join(unknown)}. Known keys: {known}")
+
+    config = load_config(paths)
+    data = asdict(config)
+    changed_keys: list[str] = []
+
+    for key, raw_value in updates.items():
+        spec = schema[key]
+        value = None if raw_value == "null" else _cast_value(spec, raw_value)
+        if spec.validator and value is not None and not spec.validator(value):
+            raise ConfigError(f"Invalid value for '{key}': {raw_value}")
+        if data.get(key) != value:
+            changed_keys.append(key)
+        data[key] = value
+
+    updated = AppConfig(**data)
+    save_config(paths, updated)
+    if changed_keys:
+        logger.info("config updated: keys=%s", changed_keys)
+    return updated
+
+
+def reset_config_values(paths: AppPaths, keys: list[str] | None = None) -> AppConfig:
+    schema = get_config_schema()
+    target_keys = keys or list(schema.keys())
+    unknown = [k for k in target_keys if k not in schema]
+    if unknown:
+        raise ConfigError(f"Unknown config key(s): {', '.join(unknown)}")
+
+    config = load_config(paths)
+    data = asdict(config)
+    for key in target_keys:
+        data[key] = schema[key].default
+    updated = AppConfig(**data)
+    save_config(paths, updated)
+    logger.info("config reset: keys=%s", target_keys)
+    return updated

orchestrator/domain/__init__.py

@@ -0,0 +1 @@
+"""Domain models for runtime flow."""

orchestrator/domain/types.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(slots=True)
+class TaskGitPolicy:
+    base_branch: str | None = None
+    work_branch: str | None = None
+    push_on_success: bool | None = None
+
+
+@dataclass(slots=True)
+class TaskStep:
+    id: str
+    type: str
+    tool_preferences: list[str] = field(default_factory=list)
+    prompt_file: str | None = None
+    prompt_inline: str | None = None
+    command: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(slots=True)
+class PromptTask:
+    external_id: str | None
+    source_path: str
+    title: str
+    description: str
+    priority: str = "medium"
+    status: str = "todo"
+    labels: list[str] = field(default_factory=list)
+    target_repo: str | None = None
+    target_paths: list[str] = field(default_factory=list)
+    depends_on: list[str] = field(default_factory=list)
+    acceptance_criteria: list[str] = field(default_factory=list)
+    steps: list[TaskStep] = field(default_factory=list)
+    git: TaskGitPolicy = field(default_factory=TaskGitPolicy)
+    raw_content: str = ""
+    last_seen_hash: str = ""
+
+
+@dataclass(slots=True)
+class BackendContext:
+    run_id: int
+    timeout_seconds: int
+    max_steps: int
+    safety_settings: dict[str, Any]
+
+
+@dataclass(slots=True)
+class BackendResult:
+    success: bool
+    summary: str
+    stdout: str = ""
+    stderr: str = ""
+    tool_invocations: list[dict[str, Any]] = field(default_factory=list)
+
+
+@dataclass(slots=True)
+class StepExecutionResult:
+    step_id: str
+    step_type: str
+    backend: str
+    success: bool
+    summary: str
+    stdout: str = ""
+    stderr: str = ""
+    tool_invocations: list[dict[str, Any]] = field(default_factory=list)
+
+
+@dataclass(slots=True)
+class ValidationStepResult:
+    name: str
+    success: bool
+    details: str

orchestrator/exceptions.py

@@ -0,0 +1,18 @@
+class OrchestratorError(Exception):
+    """Base exception for expected orchestration failures."""
+
+
+class ConfigError(OrchestratorError):
+    """Raised when config/state is missing or invalid."""
+
+
+class RepoError(OrchestratorError):
+    """Raised for git or repository state issues."""
+
+
+class BackendError(OrchestratorError):
+    """Raised for backend invocation failures."""
+
+
+class ValidationError(OrchestratorError):
+    """Raised when one or more validations fail."""

orchestrator/git/__init__.py

@@ -0,0 +1 @@
+"""Git integration services."""

orchestrator/git/service.py

@@ -0,0 +1,202 @@
+from __future__ import annotations
+
+from pathlib import Path
+import re
+
+from orchestrator.exceptions import RepoError
+from orchestrator.utils.process import run_command
+
+
+def _sanitize(name: str) -> str:
+    return re.sub(r"[^a-zA-Z0-9._/-]+", "-", name).strip("-").lower()
+
+
+class GitService:
+    def __init__(self, timeout_seconds: int = 900):
+        self.timeout_seconds = timeout_seconds
+
+    def ensure_git_repo(self, path: Path) -> None:
+        result = run_command(["git", "rev-parse", "--is-inside-work-tree"], cwd=path, timeout=self.timeout_seconds)
+        if result.code != 0 or "true" not in result.stdout:
+            raise RepoError(f"Not a git repository: {path}")
+
+    def is_clean(self, path: Path) -> bool:
+        result = run_command(["git", "status", "--porcelain"], cwd=path, timeout=self.timeout_seconds)
+        return result.code == 0 and result.stdout.strip() == ""
+
+    def current_branch(self, path: Path) -> str:
+        result = run_command(["git", "rev-parse", "--abbrev-ref", "HEAD"], cwd=path, timeout=self.timeout_seconds)
+        if result.code != 0:
+            raise RepoError(result.stderr.strip() or "Failed to read current branch")
+        return result.stdout.strip()
+
+    def checkout_branch(self, path: Path, branch: str) -> None:
+        result = run_command(["git", "checkout", branch], cwd=path, timeout=self.timeout_seconds)
+        if result.code != 0:
+            raise RepoError(result.stderr.strip() or f"Failed to checkout branch {branch}")
+
+    def checkout_or_create_branch(self, path: Path, branch: str, start_point: str, allow_create: bool) -> None:
+        if self.local_branch_exists(path, branch):
+            self.checkout_branch(path, branch)
+            return
+        if not allow_create:
+            raise RepoError(f"Branch '{branch}' does not exist and branch creation is disabled")
+        result = run_command(["git", "checkout", "-b", branch, start_point], cwd=path, timeout=self.timeout_seconds)
+        if result.code != 0:
+            raise RepoError(result.stderr.strip() or f"Failed to create branch {branch} from {start_point}")
+
+    def local_branch_exists(self, path: Path, branch: str) -> bool:
+        result = run_command(["git", "show-ref", "--verify", f"refs/heads/{branch}"], cwd=path, timeout=self.timeout_seconds)
+        return result.code == 0
+
+    def remote_branch_exists(self, path: Path, branch: str) -> bool:
+        remote = self.primary_remote(path)
+        result = run_command(["git", "ls-remote", "--heads", remote, branch], cwd=path, timeout=self.timeout_seconds)
+        return result.code == 0 and bool(result.stdout.strip())
+
+    def remotes(self, path: Path) -> list[str]:
+        result = run_command(["git", "remote"], cwd=path, timeout=self.timeout_seconds)
+        if result.code != 0:
+            raise RepoError(result.stderr.strip() or "Failed to read git remotes")
+        return [line.strip() for line in result.stdout.splitlines() if line.strip()]
+
+    def primary_remote(self, path: Path) -> str:
+        remotes = self.remotes(path)
+        if "origin" in remotes:
+            return "origin"
+        if remotes:
+            return remotes[0]
+        raise RepoError("No git remote configured for repository")
+
+    def has_commits(self, path: Path) -> bool:
+        result = run_command(["git", "rev-parse", "--verify", "HEAD"], cwd=path, timeout=self.timeout_seconds)
+        return result.code == 0
+
+    def checkout_or_create_tracking_branch(self, path: Path, branch: str, create_and_push_if_missing: bool) -> None:
+        remote = self.primary_remote(path)
+        if self.local_branch_exists(path, branch):
+            self.checkout_branch(path, branch)
+            return
+
+        if self.remote_branch_exists(path, branch):
+            fetch = run_command(["git", "fetch", remote, branch], cwd=path, timeout=self.timeout_seconds)
+            if fetch.code != 0:
+                raise RepoError(fetch.stderr.strip() or f"Failed to fetch {remote}/{branch}")
+            result = run_command(
+                ["git", "checkout", "-b", branch, f"{remote}/{branch}"],
+                cwd=path,
+                timeout=self.timeout_seconds,
+            )
+            if result.code != 0:
+                raise RepoError(result.stderr.strip() or f"Failed to checkout remote branch {remote}/{branch}")
+            upstream = run_command(
+                ["git", "branch", "--set-upstream-to", f"{remote}/{branch}", branch],
+                cwd=path,
+                timeout=self.timeout_seconds,
+            )
+            if upstream.code != 0:
+                raise RepoError(upstream.stderr.strip() or f"Failed to set upstream to {remote}/{branch}")
+            return
+
+        if not create_and_push_if_missing:
+            raise RepoError(f"Remote branch '{branch}' not found")
+
+        create_result = run_command(["git", "checkout", "-b", branch], cwd=path, timeout=self.timeout_seconds)
+        if create_result.code != 0:
+            raise RepoError(create_result.stderr.strip() or f"Failed to create branch {branch}")
+
+        if not self.has_commits(path):
+            bootstrap_commit = run_command(
+                [
+                    "git",
+                    "-c",
+                    "user.name=execforge",
+                    "-c",
+                    "user.email=execforge@local",
+                    "commit",
+                    "--allow-empty",
+                    "-m",
+                    f"chore(execforge): bootstrap branch {branch}",
+                ],
+                cwd=path,
+                timeout=self.timeout_seconds,
+            )
+            if bootstrap_commit.code != 0:
+                raise RepoError(
+                    bootstrap_commit.stderr.strip()
+                    or f"Created branch '{branch}' but failed to create bootstrap commit"
+                )
+
+        push_result = run_command(["git", "push", "-u", remote, branch], cwd=path, timeout=self.timeout_seconds)
+        if push_result.code != 0:
+            raise RepoError(
+                push_result.stderr.strip()
+                or f"Created local branch '{branch}' but failed to push it to {remote}"
+            )
+
+    def make_agent_branch_name(self, agent_name: str, task_ref: str) -> str:
+        return f"agent/{_sanitize(agent_name)}/{_sanitize(task_ref)}"
+
+    def commit_all(self, path: Path, message: str) -> str | None:
+        if self.is_clean(path):
+            return None
+        add_result = run_command(["git", "add", "."], cwd=path, timeout=self.timeout_seconds)
+        if add_result.code != 0:
+            raise RepoError(add_result.stderr.strip() or "git add failed")
+        commit_result = run_command(["git", "commit", "-m", message], cwd=path, timeout=self.timeout_seconds)
+        if commit_result.code != 0:
+            raise RepoError(commit_result.stderr.strip() or "git commit failed")
+        sha_result = run_command(["git", "rev-parse", "HEAD"], cwd=path, timeout=self.timeout_seconds)
+        if sha_result.code != 0:
+            raise RepoError(sha_result.stderr.strip() or "Failed to read commit sha")
+        return sha_result.stdout.strip()
+
+    def push(self, path: Path, branch: str) -> None:
+        remote = self.primary_remote(path)
+        result = run_command(["git", "push", "-u", remote, branch], cwd=path, timeout=self.timeout_seconds)
+        if result.code != 0:
+            raise RepoError(result.stderr.strip() or "git push failed")
+
+    def clone(self, repo_url: str, clone_path: Path, branch: str, bootstrap_missing_branch: bool = False) -> None:
+        clone_path.parent.mkdir(parents=True, exist_ok=True)
+        result = run_command(["git", "clone", "--branch", branch, repo_url, str(clone_path)], cwd=clone_path.parent)
+        if result.code == 0:
+            return
+
+        missing_branch = "Remote branch" in result.stderr and "not found" in result.stderr
+        if not missing_branch:
+            raise RepoError(result.stderr.strip() or "git clone failed")
+
+        fallback = run_command(["git", "clone", repo_url, str(clone_path)], cwd=clone_path.parent)
+        if fallback.code != 0:
+            raise RepoError(fallback.stderr.strip() or "git clone failed")
+
+        if not bootstrap_missing_branch:
+            raise RepoError(
+                f"Remote branch '{branch}' not found. Re-run with missing-branch bootstrap enabled to create and push it."
+            )
+        self.checkout_or_create_tracking_branch(clone_path, branch, create_and_push_if_missing=True)
+
+    def pull(
+        self,
+        repo_path: Path,
+        strategy: str = "ff-only",
+        branch: str | None = None,
+        bootstrap_missing_branch: bool = False,
+    ) -> None:
+        remote = self.primary_remote(repo_path)
+        if branch:
+            self.checkout_or_create_tracking_branch(
+                repo_path,
+                branch,
+                create_and_push_if_missing=bootstrap_missing_branch,
+            )
+        if strategy == "none":
+            return
+        if branch:
+            cmd = ["git", "pull", "--ff-only", remote, branch] if strategy == "ff-only" else ["git", "pull", "--rebase", remote, branch]
+        else:
+            cmd = ["git", "pull", "--ff-only"] if strategy == "ff-only" else ["git", "pull", "--rebase"]
+        result = run_command(cmd, cwd=repo_path, timeout=self.timeout_seconds)
+        if result.code != 0:
+            raise RepoError(result.stderr.strip() or "git pull failed")

orchestrator/logging_setup.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from datetime import datetime
+import logging
+from pathlib import Path
+
+
+def configure_logging(logs_dir: Path, level: str = "INFO", console_debug: bool = False) -> Path:
+    logs_dir.mkdir(parents=True, exist_ok=True)
+    stamp = datetime.utcnow().strftime("%Y%m%d-%H%M%S")
+    log_file = logs_dir / f"orchestrator-{stamp}.log"
+
+    root = logging.getLogger()
+    root.setLevel(level.upper())
+    root.handlers.clear()
+
+    formatter = logging.Formatter(
+        "%(asctime)s %(levelname)s %(name)s "
+        "run=%(run_id)s agent=%(agent)s task=%(task)s "
+        "base=%(base_branch)s branch=%(branch)s step=%(step)s "
+        "%(message)s"
+    )
+
+    if console_debug:
+        stream = logging.StreamHandler()
+        stream.setFormatter(formatter)
+        stream.setLevel(level.upper())
+        root.addHandler(stream)
+
+    file_handler = logging.FileHandler(log_file, encoding="utf-8")
+    file_handler.setFormatter(formatter)
+    file_handler.setLevel(level.upper())
+    root.addHandler(file_handler)
+
+    return log_file
+
+
+class ContextAdapter(logging.LoggerAdapter):
+    def process(self, msg, kwargs):
+        raw_extra = kwargs.get("extra")
+        extra = raw_extra if isinstance(raw_extra, dict) else {}
+        base: dict[str, object] = {
+            "run_id": "-",
+            "agent": "-",
+            "task": "-",
+            "base_branch": "-",
+            "branch": "-",
+            "step": "-",
+        }
+        base.update(dict(self.extra or {}))
+        base.update(extra)
+        kwargs["extra"] = base
+        return msg, kwargs

orchestrator/prompts/__init__.py

@@ -0,0 +1 @@
+"""Prompt and task parsing helpers."""