ai-dev-workflow 0.1.0__py3-none-any.whl

worker_registry.py

@@ -0,0 +1,170 @@
+"""Provider-neutral worker registration for planner/executor agents."""
+from __future__ import annotations
+
+import re
+
+WORKER_MODES = {"planner", "executor", "hybrid"}
+WORKER_ENVIRONMENTS = {"local", "codespaces", "cloud"}
+PLANNING_ROLES = {"SetupAgent", "ArchitectAgent", "ReviewerAgent"}
+EXECUTION_ROLES = {"TesterAgent", "ImplementerAgent", "RuntimeVerifierAgent"}
+ALL_ROLES = PLANNING_ROLES | EXECUTION_ROLES
+
+ROLE_CAPABILITIES = {
+    "SetupAgent": {"planning"},
+    "ArchitectAgent": {"planning"},
+    "TesterAgent": {"test"},
+    "ImplementerAgent": {"implementation"},
+    "ReviewerAgent": {"review"},
+    "RuntimeVerifierAgent": {"runtime-verification"},
+}
+
+
+def build_worker(
+    worker_id: str,
+    *,
+    mode: str,
+    provider: str,
+    environment: str,
+    roles: list[str],
+    capabilities: list[str] | None = None,
+    capacity: int = 1,
+    managed: bool | None = None,
+    scope: dict | None = None,
+    planning_updates: str = "approval-required",
+    assignee: str | None = None,
+) -> dict:
+    caps = set(capabilities or [])
+    for role in roles:
+        caps |= ROLE_CAPABILITIES.get(role, set())
+    if managed is None:
+        managed = environment in ("codespaces", "cloud")
+    return {
+        "worker_id": worker_id,
+        "mode": mode,
+        "provider": provider,
+        "environment": environment,
+        "roles": list(roles),
+        "capabilities": sorted(caps),
+        "capacity": capacity,
+        "managed": managed,
+        "assignee": assignee,
+        "scope": scope or {"repositories": ["current"]},
+        "planning": {
+            "work_item_access": "read-write" if mode in ("planner", "hybrid") else "read",
+            "update_policy": planning_updates,
+            "frozen_contract_mutation": "forbidden",
+        },
+    }
+
+
+def validate_worker(worker: dict, providers: dict) -> list[str]:
+    errors = []
+    worker_id = worker.get("worker_id")
+    if not isinstance(worker_id, str) or not re.fullmatch(r"[A-Za-z0-9_.-]+", worker_id):
+        errors.append("worker_id must use letters, numbers, dot, underscore or dash")
+
+    mode = worker.get("mode")
+    if mode not in WORKER_MODES:
+        errors.append(f"worker {worker_id}: invalid mode {mode!r}")
+
+    environment = worker.get("environment")
+    if environment not in WORKER_ENVIRONMENTS:
+        errors.append(f"worker {worker_id}: invalid environment {environment!r}")
+
+    provider = worker.get("provider")
+    if provider not in providers:
+        errors.append(f"worker {worker_id}: unknown provider {provider!r}")
+
+    roles = worker.get("roles")
+    if not isinstance(roles, list) or not roles:
+        errors.append(f"worker {worker_id}: at least one role is required")
+        roles = []
+    for role in roles:
+        if role not in ALL_ROLES:
+            errors.append(f"worker {worker_id}: unsupported role {role!r}")
+
+    if mode == "planner" and any(role in EXECUTION_ROLES for role in roles):
+        errors.append(f"worker {worker_id}: planner mode cannot own execution roles")
+    if mode == "executor" and any(role in PLANNING_ROLES for role in roles):
+        errors.append(f"worker {worker_id}: executor mode cannot own planning roles")
+
+    caps = worker.get("capabilities")
+    if not isinstance(caps, list):
+        errors.append(f"worker {worker_id}: capabilities must be a list")
+        caps = []
+    for role in roles:
+        missing = ROLE_CAPABILITIES.get(role, set()) - set(caps)
+        if missing:
+            errors.append(
+                f"worker {worker_id}: role {role} missing capabilities {sorted(missing)}"
+            )
+
+    if mode in ("executor", "hybrid") and environment == "local" and not worker.get("managed") and not worker.get("assignee"):
+        errors.append(f"worker {worker_id}: local executor requires assignee for claim ownership")
+
+    capacity = worker.get("capacity")
+    if type(capacity) is not int or capacity < 1:
+        errors.append(f"worker {worker_id}: capacity must be >= 1")
+
+    planning = worker.get("planning") or {}
+    if planning.get("update_policy") not in (
+        "approval-required",
+        "draft-auto",
+        "read-only",
+    ):
+        errors.append(f"worker {worker_id}: invalid planning update policy")
+    if planning.get("frozen_contract_mutation") != "forbidden":
+        errors.append(f"worker {worker_id}: frozen contract mutation must be forbidden")
+
+    return errors
+
+
+def validate_worker_registry(workers: list[dict], providers: dict) -> list[str]:
+    errors = []
+    seen = set()
+    for worker in workers:
+        worker_id = worker.get("worker_id")
+        if worker_id in seen:
+            errors.append(f"duplicate worker_id: {worker_id}")
+        seen.add(worker_id)
+        errors.extend(validate_worker(worker, providers))
+    return errors
+
+
+def worker_credential_requirements(workers: list[dict], work_item_provider: str) -> list[dict]:
+    result = []
+    if any(w.get("environment") == "codespaces" for w in workers):
+        result.append({
+            "name": "CODESPACES_TOKEN",
+            "purpose": "Provision/start/stop registered Codespaces workers.",
+            "required_for_setup": False,
+            "store": "GitHub Actions repository secret",
+        })
+    if any(w.get("mode") in ("planner", "hybrid") for w in workers):
+        result.append({
+            "name": f"{work_item_provider} connector access",
+            "purpose": "Allow planner/hybrid workers to read project context and propose work-item updates.",
+            "required_for_setup": False,
+            "store": "connector/MCP authentication configured during setup",
+        })
+    return result
+
+
+def dispatcher_registry(workers: list[dict]) -> dict:
+    """Project first-class workers into the existing queue-dispatcher registry contract."""
+    projected = []
+    for worker in workers:
+        if worker.get("mode") not in ("executor", "hybrid"):
+            continue
+        item = {
+            "worker_id": worker["worker_id"],
+            "execution_location": "local" if worker["environment"] == "local" else "cloud",
+            "provider": worker["provider"],
+            "capabilities": list(worker.get("capabilities", [])),
+            "capacity": worker.get("capacity", 1),
+            "managed": bool(worker.get("managed", False)),
+        }
+        if worker.get("assignee"):
+            item["assignee"] = worker["assignee"]
+        projected.append(item)
+    return {"version": 1, "workers": projected}