agent-toolkit-cli 1.11.0__py3-none-win_amd64.whl

agent_toolkit/swarm/recipes.py

@@ -0,0 +1,304 @@
+"""Swarm recipes — built-in pair/team/full, YAML loading, validation."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any
+
+from .models import API_VERSION, KIND, RolePolicy
+
+BUILTIN_RECIPES: dict[str, dict[str, Any]] = {
+    "pair": {
+        "apiVersion": API_VERSION,
+        "kind": KIND,
+        "metadata": {
+            "name": "pair",
+            "description": "Two-role implementer + reviewer/integrator workflow",
+        },
+        "spec": {
+            "ui": "auto",
+            "transport": "filesystem",
+            "workspace": {
+                "strategy": "worktree-per-writer",
+                "base_ref": "HEAD",
+                "integration_branch": True,
+                "keep_on_failure": True,
+            },
+            "execution": {
+                "max_concurrency": 2,
+                "lazy_start": True,
+                "resumable": True,
+                "max_role_round_trips": 2,
+            },
+            "budget": {"max_total_tokens": 900000, "max_cost_usd": 4.00, "max_wall_seconds": 7200},
+            "gates": {
+                "require_plan_approval": False,
+                "require_final_approval": True,
+                "allow_direct_base_merge": False,
+                "allow_push": False,
+            },
+            "roles": {
+                "implementer": {
+                    "persona": "tdd-guide",
+                    "policy": "writer",
+                    "model_profile": "coding",
+                    "worktree": "implementer",
+                    "consumes": ["task-contract"],
+                    "produces": ["commit", "implementation-report"],
+                    "receive_mode": "task",
+                    "skills": ["tdd"],
+                },
+                "reviewer": {
+                    "persona": "code-reviewer",
+                    "policy": "reviewer-writer",
+                    "model_profile": "review",
+                    "worktree": "reviewer",
+                    "consumes": ["commit"],
+                    "produces": ["feedback", "reviewed-commit"],
+                    "receive_mode": "task",
+                    "skills": ["code-review"],
+                },
+                "integrator": {
+                    "persona": "architect",
+                    "policy": "integrator",
+                    "model_profile": "architecture",
+                    "worktree": "integration",
+                    "consumes": ["reviewed-commit"],
+                    "produces": ["final-candidate", "final-report"],
+                    "receive_mode": "batch",
+                    "skills": [],
+                },
+            },
+        },
+    },
+    "team": {
+        "apiVersion": API_VERSION,
+        "kind": KIND,
+        "metadata": {
+            "name": "team",
+            "description": "Four-role planner → implementer → reviewer → architect workflow",
+        },
+        "spec": {
+            "ui": "auto",
+            "transport": "filesystem",
+            "workspace": {
+                "strategy": "worktree-per-writer",
+                "base_ref": "HEAD",
+                "integration_branch": True,
+                "keep_on_failure": True,
+            },
+            "execution": {
+                "max_concurrency": 2,
+                "lazy_start": True,
+                "resumable": True,
+                "max_role_round_trips": 2,
+            },
+            "budget": {"max_total_tokens": 900000, "max_cost_usd": 4.00, "max_wall_seconds": 7200},
+            "gates": {
+                "require_plan_approval": True,
+                "require_final_approval": True,
+                "allow_direct_base_merge": False,
+                "allow_push": False,
+            },
+            "roles": {
+                "planner": {
+                    "persona": "planner",
+                    "policy": "read-only",
+                    "model_profile": "planning",
+                    "worktree": None,
+                    "consumes": [],
+                    "produces": ["task-contract", "acceptance-criteria", "risk-assessment"],
+                    "receive_mode": "task",
+                    "skills": ["planning"],
+                },
+                "implementer": {
+                    "persona": "tdd-guide",
+                    "policy": "writer",
+                    "model_profile": "coding",
+                    "worktree": "implementer",
+                    "consumes": ["task-contract"],
+                    "produces": ["commit", "implementation-report"],
+                    "receive_mode": "task",
+                    "skills": ["tdd"],
+                },
+                "reviewer": {
+                    "persona": "code-reviewer",
+                    "policy": "reviewer-writer",
+                    "model_profile": "review",
+                    "worktree": "reviewer",
+                    "consumes": ["commit"],
+                    "produces": ["feedback", "reviewed-commit"],
+                    "receive_mode": "task",
+                    "skills": ["code-review"],
+                },
+                "architect": {
+                    "persona": "architect",
+                    "policy": "integrator",
+                    "model_profile": "architecture",
+                    "worktree": "integration",
+                    "consumes": ["reviewed-commit"],
+                    "produces": ["final-candidate", "final-report"],
+                    "receive_mode": "batch",
+                    "skills": ["architecture"],
+                },
+            },
+        },
+    },
+    "full": {
+        "apiVersion": API_VERSION,
+        "kind": KIND,
+        "metadata": {
+            "name": "full",
+            "description": "Six-role planner → implementer → refactorer → architect → hardener → qa workflow",
+        },
+        "spec": {
+            "ui": "auto",
+            "transport": "filesystem",
+            "workspace": {
+                "strategy": "worktree-per-writer",
+                "base_ref": "HEAD",
+                "integration_branch": True,
+                "keep_on_failure": True,
+            },
+            "execution": {
+                "max_concurrency": 2,
+                "lazy_start": True,
+                "resumable": True,
+                "max_role_round_trips": 2,
+            },
+            "budget": {
+                "max_total_tokens": 1200000,
+                "max_cost_usd": 8.00,
+                "max_wall_seconds": 10800,
+            },
+            "gates": {
+                "require_plan_approval": True,
+                "require_final_approval": True,
+                "allow_direct_base_merge": False,
+                "allow_push": False,
+            },
+            "roles": {
+                "planner": {
+                    "persona": "planner",
+                    "policy": "read-only",
+                    "model_profile": "planning",
+                    "worktree": None,
+                    "consumes": [],
+                    "produces": ["task-contract"],
+                    "receive_mode": "task",
+                    "skills": ["planning"],
+                },
+                "implementer": {
+                    "persona": "tdd-guide",
+                    "policy": "writer",
+                    "model_profile": "coding",
+                    "worktree": "implementer",
+                    "consumes": ["task-contract"],
+                    "produces": ["commit"],
+                    "receive_mode": "task",
+                    "skills": [],
+                },
+                "refactorer": {
+                    "persona": "refactor-cleaner",
+                    "policy": "writer",
+                    "model_profile": "review",
+                    "worktree": "reviewer",
+                    "consumes": ["commit"],
+                    "produces": ["refactored-commit"],
+                    "receive_mode": "task",
+                    "skills": [],
+                },
+                "architect": {
+                    "persona": "architect",
+                    "policy": "integrator",
+                    "model_profile": "architecture",
+                    "worktree": "integration",
+                    "consumes": ["refactored-commit"],
+                    "produces": ["integrated-commit"],
+                    "receive_mode": "batch",
+                    "skills": [],
+                },
+                "hardener": {
+                    "persona": "security-reviewer",
+                    "policy": "reviewer-writer",
+                    "model_profile": "hardening",
+                    "worktree": "hardener",
+                    "consumes": ["integrated-commit"],
+                    "produces": ["hardened-commit"],
+                    "receive_mode": "task",
+                    "skills": [],
+                },
+                "qa": {
+                    "persona": "e2e-runner",
+                    "policy": "reviewer-writer",
+                    "model_profile": "qa",
+                    "worktree": "qa",
+                    "consumes": ["hardened-commit"],
+                    "produces": ["qa-report", "final-report"],
+                    "receive_mode": "task",
+                    "skills": [],
+                },
+            },
+        },
+    },
+}
+
+VALID_POLICIES = {p.value for p in RolePolicy}
+
+
+def list_recipes() -> list[str]:
+    return sorted(BUILTIN_RECIPES.keys())
+
+
+def get_recipe(name: str) -> dict[str, Any] | None:
+    return BUILTIN_RECIPES.get(name)
+
+
+def validate_recipe(data: dict[str, Any]) -> list[str]:
+    errors: list[str] = []
+    if data.get("apiVersion") != API_VERSION:
+        errors.append(f"apiVersion must be {API_VERSION!r}")
+    if data.get("kind") != KIND:
+        errors.append(f"kind must be {KIND!r}")
+    meta = data.get("metadata") or {}
+    if not meta.get("name"):
+        errors.append("metadata.name required")
+    spec = data.get("spec")
+    if not isinstance(spec, dict):
+        errors.append("spec must be object")
+        return errors
+    roles = spec.get("roles")
+    if not isinstance(roles, dict) or not roles:
+        errors.append("spec.roles must be non-empty object")
+    else:
+        for rname, rdef in roles.items():
+            if not re.match(r"^[a-z][a-z0-9_-]{1,31}$", rname):
+                errors.append(f"invalid role name {rname!r}")
+            if not isinstance(rdef, dict):
+                errors.append(f"role {rname} must be object")
+                continue
+            policy = rdef.get("policy")
+            if policy not in VALID_POLICIES:
+                errors.append(
+                    f"role {rname} policy {policy!r} invalid, must be one of {VALID_POLICIES}"
+                )
+            if rdef.get("receive_mode") not in ("task", "batch", None):
+                errors.append(f"role {rname} receive_mode must be task|batch")
+    return errors
+
+
+def load_recipe_file(path: Path) -> dict[str, Any]:
+    text = path.read_text(encoding="utf-8")
+    try:
+        import yaml  # type: ignore
+
+        data = yaml.safe_load(text)
+        if not isinstance(data, dict):
+            raise ValueError("YAML top level must be mapping")
+        return data
+    except ImportError:
+        # minimal fallback: only JSON
+        import json
+
+        return json.loads(text)

agent_toolkit/swarm/runner.py

@@ -0,0 +1,267 @@
+"""Runner abstraction and OpenCode agent generation."""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Any
+
+RUNNER_CAPS: dict[str, dict[str, Any]] = {
+    "opencode": {
+        "interactive": True,
+        "resume": True,
+        "per_role_model": True,
+        "usage_data": True,
+        "herdr": "official",
+    },
+    "claude": {
+        "interactive": True,
+        "resume": True,
+        "per_role_model": True,
+        "usage_data": True,
+        "herdr": "official",
+    },
+    "codex": {
+        "interactive": True,
+        "resume": True,
+        "per_role_model": True,
+        "usage_data": True,
+        "herdr": "official",
+    },
+    "cursor": {
+        "interactive": True,
+        "resume": True,
+        "per_role_model": True,
+        "usage_data": True,
+        "herdr": "official",
+    },
+    "copilot": {
+        "interactive": True,
+        "resume": False,
+        "per_role_model": False,
+        "usage_data": False,
+        "herdr": "custom",
+    },
+    "muse": {
+        "interactive": True,
+        "resume": True,
+        "per_role_model": True,
+        "usage_data": True,
+        "herdr": "detect",
+    },
+    "skeleton": {
+        "interactive": False,
+        "resume": False,
+        "per_role_model": False,
+        "usage_data": False,
+        "herdr": "none",
+    },
+}
+
+
+def list_runners() -> list[str]:
+    return sorted(RUNNER_CAPS.keys())
+
+
+def runner_available(name: str) -> bool:
+    bin_map = {
+        "opencode": "opencode",
+        "claude": "claude",
+        "codex": "codex",
+        "cursor": "cursor-agent",
+        "copilot": "copilot",
+        "muse": "muse",
+        "skeleton": "true",
+    }
+    binary = bin_map.get(name, name)
+    return shutil.which(binary) is not None
+
+
+def capability_matrix() -> dict[str, dict[str, Any]]:
+    return {k: dict(v, available=runner_available(k)) for k, v in RUNNER_CAPS.items()}
+
+
+MODEL_PROFILES = {
+    "economy": {
+        "planning": "anthropic/claude-3-5-haiku-20241022",
+        "coding": "anthropic/claude-3-5-haiku-20241022",
+        "review": "openai/gpt-4o-mini",
+        "architecture": "anthropic/claude-3-5-haiku-20241022",
+        "hardening": "anthropic/claude-3-5-haiku-20241022",
+        "qa": "openai/gpt-4o-mini",
+    },
+    "balanced": {
+        "planning": "anthropic/claude-sonnet-4-20250514",
+        "coding": "anthropic/claude-sonnet-4-20250514",
+        "review": "openai/gpt-4o",
+        "architecture": "anthropic/claude-sonnet-4-20250514",
+        "hardening": "openai/gpt-4o",
+        "qa": "anthropic/claude-3-5-haiku-20241022",
+    },
+    "quality": {
+        "planning": "anthropic/claude-opus-4-20250514",
+        "coding": "anthropic/claude-opus-4-20250514",
+        "review": "openai/gpt-4o",
+        "architecture": "anthropic/claude-opus-4-20250514",
+        "hardening": "anthropic/claude-opus-4-20250514",
+        "qa": "openai/gpt-4o",
+    },
+    "private": {
+        "planning": "ollama/llama3.1",
+        "coding": "ollama/llama3.1",
+        "review": "ollama/llama3.1",
+        "architecture": "ollama/llama3.1",
+        "hardening": "ollama/llama3.1",
+        "qa": "ollama/llama3.1",
+    },
+}
+
+
+def resolve_model(
+    profile: str,
+    task_class: str,
+    override: str | None = None,
+    model_profiles: dict[str, dict[str, str]] | None = None,
+) -> str | None:
+    if override:
+        if "/" not in override:
+            raise ValueError(f"Model must be provider/model format: {override!r}")
+        return override
+    if model_profiles and profile in model_profiles and task_class in model_profiles[profile]:
+        return model_profiles[profile][task_class]
+    mapping = MODEL_PROFILES.get(profile) or MODEL_PROFILES["balanced"]
+    return mapping.get(task_class)
+
+
+def discover_models(runner: str) -> list[str]:
+    # Try to list models via runner CLI if available
+    cmds = {
+        "opencode": ["opencode", "models"],
+        "claude": ["claude", "models"],
+    }
+    cmd = cmds.get(runner)
+    if not cmd or not shutil.which(cmd[0]):
+        # Return profile models as fallback
+        vals = set()
+        for m in MODEL_PROFILES.values():
+            vals.update(m.values())
+        return sorted(vals)
+    try:
+        res = subprocess.run(cmd, capture_output=True, text=True, timeout=5)
+        if res.returncode == 0:
+            # naive parse: each line contains model id
+            models: list[str] = []
+            for line in res.stdout.splitlines():
+                line = line.strip()
+                if "/" in line and not line.startswith("#"):
+                    models.append(line.split()[0])
+            if models:
+                return models
+    except Exception:
+        pass
+    vals2 = set()
+    for m in MODEL_PROFILES.values():
+        vals2.update(m.values())
+    return sorted(vals2)
+
+
+# OpenCode permission generation
+OPENCODE_PERMISSIONS = {
+    "read-only": {
+        "edit": "deny",
+        "external_directory": "deny",
+        "websearch": "allow",
+        "skill": "allow",
+        "bash": {"*": "ask", "git status *": "allow", "git log *": "allow", "git diff *": "allow"},
+    },
+    "writer": {
+        "edit": "allow",
+        "external_directory": "deny",
+        "bash": {
+            "*": "ask",
+            "git status *": "allow",
+            "git diff *": "allow",
+            "git log *": "allow",
+            "git add *": "allow",
+            "git commit *": "ask",
+            "git push *": "deny",
+            "git reset --hard*": "deny",
+            "git clean *": "deny",
+        },
+    },
+    "reviewer-writer": {
+        "edit": "allow",
+        "external_directory": "deny",
+        "bash": {"*": "ask", "git status *": "allow", "git diff *": "allow", "git log *": "allow"},
+    },
+    "integrator": {
+        "edit": "allow",
+        "external_directory": "deny",
+        "bash": {
+            "*": "ask",
+            "git status *": "allow",
+            "git diff *": "allow",
+            "git log *": "allow",
+            "git merge *": "ask",
+            "git push *": "deny",
+        },
+    },
+}
+
+
+def generate_opencode_agent(
+    run_dir: Path,
+    role: str,
+    persona: str,
+    policy: str,
+    model: str,
+    recipe_name: str,
+    run_id: str,
+    worktree: str | None,
+) -> Path:
+    agents_dir = run_dir / "runner" / "opencode" / "agents"
+    agents_dir.mkdir(parents=True, exist_ok=True)
+    perm = OPENCODE_PERMISSIONS.get(policy, OPENCODE_PERMISSIONS["read-only"])
+    content = f"""---
+description: "Swarm role {role} ({persona}) for recipe {recipe_name}, run {run_id}"
+mode: primary
+model: {model}
+permission:
+  edit: {perm.get("edit", "deny")}
+  external_directory: {perm.get("external_directory", "deny")}
+---
+
+# Role: {role} ({persona})
+
+You are the **{role}** role in the Agent Toolkit Swarm `{recipe_name}` (run `{run_id}`).
+
+## Policy
+- Policy: {policy}
+- Worktree: {worktree or "read-only (no worktree)"}
+- Permissions: {json.dumps(perm)}
+
+## Workflow
+- Read the task contract at `artifacts/task-contract.md` if present.
+- Follow the handoff protocol: use `agent-toolkit swarm handoff create` and `agent-toolkit swarm task next/complete` — do not move queue files manually.
+- Work only inside your worktree path when you have one.
+- Do not push, do not merge to base branch, do not publish releases.
+- Keep artifacts small (<1MB) and do not include secrets.
+
+## Handoff commands
+```bash
+agent-toolkit swarm handoff create --type artifact --to <role> --artifact artifacts/<file>.md
+agent-toolkit swarm task next
+agent-toolkit swarm task complete --handoff <id>
+```
+
+## Context manifest
+- Run ID: {run_id}
+- Role: {role}
+- Recipe: {recipe_name}
+- Model: {model}
+"""
+    path = agents_dir / f"{role}.md"
+    path.write_text(content, encoding="utf-8")
+    return path

agent_toolkit/swarm/state.py

@@ -0,0 +1,93 @@
+"""Swarm state machine — run and role states, transitions."""
+
+from __future__ import annotations
+
+from .models import RoleState, RunState
+
+RUN_TRANSITIONS: dict[RunState, set[RunState]] = {
+    RunState.PLANNING: {
+        RunState.AWAITING_PLAN_APPROVAL,
+        RunState.RUNNING,
+        RunState.FAILED,
+        RunState.CANCELLED,
+    },
+    RunState.AWAITING_PLAN_APPROVAL: {RunState.RUNNING, RunState.CANCELLED, RunState.FAILED},
+    RunState.RUNNING: {
+        RunState.AWAITING_HUMAN,
+        RunState.PAUSED,
+        RunState.COMPLETED,
+        RunState.FAILED,
+        RunState.CANCELLED,
+        RunState.BUDGET_EXHAUSTED,
+    },
+    RunState.AWAITING_HUMAN: {
+        RunState.RUNNING,
+        RunState.PAUSED,
+        RunState.COMPLETED,
+        RunState.FAILED,
+        RunState.CANCELLED,
+    },
+    RunState.PAUSED: {RunState.RUNNING, RunState.CANCELLED, RunState.FAILED},
+    RunState.COMPLETED: {RunState.CLEANUP_PENDING},
+    RunState.FAILED: {RunState.CLEANUP_PENDING, RunState.RUNNING},
+    RunState.CANCELLED: {RunState.CLEANUP_PENDING},
+    RunState.BUDGET_EXHAUSTED: {RunState.RUNNING, RunState.CANCELLED, RunState.CLEANUP_PENDING},
+    RunState.CLEANUP_PENDING: set(),
+}
+
+ROLE_TRANSITIONS: dict[RoleState, set[RoleState]] = {
+    RoleState.INACTIVE: {RoleState.STARTING, RoleState.IDLE},
+    RoleState.STARTING: {RoleState.IDLE, RoleState.WORKING, RoleState.FAILED, RoleState.STOPPED},
+    RoleState.IDLE: {RoleState.READY, RoleState.WORKING, RoleState.STOPPED, RoleState.FAILED},
+    RoleState.READY: {
+        RoleState.WORKING,
+        RoleState.BLOCKED,
+        RoleState.COMPLETED,
+        RoleState.FAILED,
+        RoleState.STOPPED,
+    },
+    RoleState.WORKING: {
+        RoleState.AWAITING_HANDOFF,
+        RoleState.BLOCKED,
+        RoleState.COMPLETED,
+        RoleState.FAILED,
+        RoleState.STOPPED,
+        RoleState.IDLE,
+    },
+    RoleState.BLOCKED: {RoleState.WORKING, RoleState.FAILED, RoleState.STOPPED},
+    RoleState.AWAITING_HANDOFF: {
+        RoleState.WORKING,
+        RoleState.COMPLETED,
+        RoleState.FAILED,
+        RoleState.STOPPED,
+    },
+    RoleState.COMPLETED: {RoleState.WORKING, RoleState.STOPPED},
+    RoleState.FAILED: {RoleState.STARTING, RoleState.STOPPED},
+    RoleState.STOPPED: {RoleState.STARTING},
+}
+
+
+def can_transition_run(from_state: str, to_state: str) -> bool:
+    try:
+        f = RunState(from_state)
+        t = RunState(to_state)
+    except ValueError:
+        return False
+    return t in RUN_TRANSITIONS.get(f, set())
+
+
+def can_transition_role(from_state: str, to_state: str) -> bool:
+    try:
+        f = RoleState(from_state)
+        t = RoleState(to_state)
+    except ValueError:
+        return False
+    return t in ROLE_TRANSITIONS.get(f, set())
+
+
+def initial_run_state(recipe_name: str, requires_plan_approval: bool) -> str:
+    if recipe_name in ("team", "full") and requires_plan_approval:
+        return RunState.AWAITING_PLAN_APPROVAL.value
+    if recipe_name in ("team", "full"):
+        return RunState.PLANNING.value
+    return RunState.RUNNING.value