cleveragents-core/tools/dispatch_implementer.py

#!/usr/bin/env python3
"""Deterministic dispatcher for implementation workers.

The dispatcher preserves the existing priority order from
``implementation-supervisor``: fix failing PRs first, then PRs with
unaddressed review feedback, then new issue work.  The worker remains the
LLM boundary; Python owns queueing, PR claims, watchdogs, and telemetry.
"""
from __future__ import annotations

import argparse
import json
import os
import sys
from pathlib import Path
from typing import Any

_TOOLS_DIR = str(Path(__file__).resolve().parent)
if _TOOLS_DIR not in sys.path:
    sys.path.insert(0, _TOOLS_DIR)
from _loader import load_sibling as _load_sibling  # noqa: E402  type: ignore[import-not-found]


_dispatch = _load_sibling("_dispatch_runtime", "_dispatch_runtime.py")


DRIVER_NAME = "dispatch_implementer.py"
CLAIM_KIND = "implementer"


def _implementation_prompt(cfg: Any, item: dict[str, Any], group: Any) -> str:
    work_type = "issue_impl" if group.item_kind == "issue" else "pr_fix"
    title = str(item.get("title") or "")
    number = int(item["number"])
    claim_note = (
        "The deterministic dispatcher already claimed "
        "`auto/claimed-implementer` before starting this worker. If your "
        "startup claim step sees the label already present, treat that as "
        "success and continue normally. Still run your release step before "
        "exiting; the dispatcher will also release in its finally block."
        if work_type == "pr_fix"
        else "No PR exists yet for this issue work, so there is no "
        "`auto/claimed-implementer` claim to acquire before dispatch."
    )
    return f"""Implement or fix the indicated issue or pull request.

forgejo_url: `{cfg.forgejo_url}`
forgejo_owner: `{cfg.owner}`
forgejo_repo: `{cfg.repo}`

work_type: {json.dumps(work_type)}
work_number: {number}
work_title: {json.dumps(title)}

PR Compliance Checklist (MANDATORY - complete ALL items before creating a PR):
[ ] 1. CHANGELOG.md — add entry under [Unreleased] section
[ ] 2. CONTRIBUTORS.md — add or update contribution entry
[ ] 3. Commit footer — include `ISSUES CLOSED: #<issue-number>` in the commit message
[ ] 4. CI passes — all quality gates and tests green before requesting review
[ ] 5. BDD/Behave tests — added or updated for the changed behaviour
[ ] 6. Epic reference — PR description references the parent Epic issue number
[ ] 7. Labels — applied via forgejo-label-manager: State/In Review, Priority/<level>, MoSCoW/<level>, Type/<type>
[ ] 8. Milestone — PR assigned to the earliest open milestone matching the issue

{claim_note}

When the implementation work is complete, include exactly one JSON object in
your final response:
{{"outcome": "resolved", "files_touched": ["path/changed"]}}

If you cannot complete the implementation because of an unrecoverable setup,
API, or repository problem, include:
{{"outcome": "rebase-failed", "files_touched": []}}
"""


WORK_GROUPS = [
    _dispatch.WorkGroup(
        name="failing_ci_pr",
        script_name="list_prs_ci_failing",
        item_kind="pr",
        claim_kind=CLAIM_KIND,
        worker_agent="implementation-worker",
        tag_prefix="AUTO-IMP",
        prompt_factory=_implementation_prompt,
    ),
    _dispatch.WorkGroup(
        name="request_changes_pr",
        script_name="list_prs_changes_requested",
        item_kind="pr",
        claim_kind=CLAIM_KIND,
        worker_agent="implementation-worker",
        tag_prefix="AUTO-IMP",
        prompt_factory=_implementation_prompt,
    ),
    _dispatch.WorkGroup(
        name="new_issue",
        script_name="list_issues",
        item_kind="issue",
        claim_kind=None,
        worker_agent="implementation-worker",
        tag_prefix="AUTO-IMP",
        prompt_factory=_implementation_prompt,
    ),
]


def load_config(*, dry_run: bool = False) -> Any:
    token = _dispatch.load_secret("FORGEJO_PAT", "GITEA_TOKEN")
    return _dispatch.DispatchConfig(
        token=token,
        forgejo_url=_dispatch.derive_forgejo_url(),
        owner=os.environ.get("FORGEJO_OWNER", _dispatch.REPO_OWNER),
        repo=os.environ.get("FORGEJO_REPO", _dispatch.REPO_NAME),
        server_url=os.environ.get("OPENCODE_SERVER_URL", "http://127.0.0.1:4096").rstrip(
            "/"
        ),
        lock_path=_dispatch.resolve_lock_or_heartbeat(
            "IMPLEMENTER_DISPATCHER_LOCK_PATH", "implementer-dispatcher.lock"
        ),
        heartbeat_path=_dispatch.resolve_lock_or_heartbeat(
            "IMPLEMENTER_DISPATCHER_HEARTBEAT_PATH",
            "implementer-dispatcher.heartbeat",
        ),
        cycle_interval_seconds=int(
            os.environ.get("IMPLEMENTER_DISPATCHER_CYCLE_SECONDS", "120")
        ),
        max_items_per_cycle=int(
            os.environ.get("IMPLEMENTER_DISPATCHER_MAX_ITEMS_PER_CYCLE", "1")
        ),
        worker_timeout_seconds=int(
            os.environ.get("IMPLEMENTER_DISPATCHER_WORKER_TIMEOUT_SECONDS", "7200")
        ),
        claim_ttl_seconds=int(
            os.environ.get("IMPLEMENTER_DISPATCHER_CLAIM_TTL_SECONDS", "7200")
        ),
        api_retries=int(os.environ.get("IMPLEMENTER_DISPATCHER_API_RETRIES", "3")),
        request_timeout_s=int(
            os.environ.get("IMPLEMENTER_DISPATCHER_REQUEST_TIMEOUT_S", "30")
        ),
        script_timeout_seconds=int(
            os.environ.get("IMPLEMENTER_DISPATCHER_SCRIPT_TIMEOUT_SECONDS", "120")
        ),
        table_name="dispatch_implementer_cycles",
        dry_run=dry_run,
        cycle_failure_budget=int(
            os.environ.get("IMPLEMENTER_DISPATCHER_CYCLE_FAILURE_BUDGET", "5")
        ),
    )


SUPERVISOR_TAGS = ["AUTO-IMP-SUP"]
SUPERVISOR_OVERRIDE_ENV = "IMPLEMENTER_DISPATCHER_ALLOW_SUPERVISOR_COEXIST"


def main() -> int:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--once", action="store_true", help="run one cycle and exit")
    parser.add_argument("--status", action="store_true", help="print config and exit")
    parser.add_argument("--dry-run", action="store_true", help="claim nothing and do not dispatch")
    args = parser.parse_args()
    _dispatch._configure_logging("IMPLEMENTER_DISPATCHER_LOG_LEVEL")
    cfg = load_config(dry_run=args.dry_run)
    if args.status:
        _dispatch.json_line(_dispatch.status_payload(cfg, driver_name=DRIVER_NAME))
        return 0
    if not args.dry_run:
        _dispatch.assert_no_legacy_supervisor(
            cfg,
            driver_name=DRIVER_NAME,
            supervisor_tags=SUPERVISOR_TAGS,
            override_env=SUPERVISOR_OVERRIDE_ENV,
        )
    if args.once:
        _dispatch.json_line(
            _dispatch.run_one_cycle(
                cfg,
                WORK_GROUPS,
                driver_name=DRIVER_NAME,
                sweep_claim_kind=CLAIM_KIND,
            )
        )
        return 0
    _dispatch.run_outer_loop(
        cfg,
        WORK_GROUPS,
        driver_name=DRIVER_NAME,
        sweep_claim_kind=CLAIM_KIND,
    )
    return 0


if __name__ == "__main__":
    raise SystemExit(main())