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

agent_toolkit/swarm/models.py

@@ -0,0 +1,230 @@
+"""Swarm domain model — typed dataclasses for orchestration."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+# Valid identifiers: lower kebab or snake, must start with letter
+_ROLE_RE = re.compile(r"^[a-z][a-z0-9_-]{1,31}$")
+_RUN_ID_RE = re.compile(r"^[a-zA-Z0-9][a-zA-Z0-9._-]{2,64}$")
+_BRANCH_SAFE_RE = re.compile(r"^[a-zA-Z0-9/._-]+$")
+_SHA_RE = re.compile(r"^[0-9a-f]{40}$")
+
+API_VERSION = "agent-toolkit.dev/v1alpha1"
+KIND = "SwarmRecipe"
+STATE_VERSION = 1
+HANDOFF_VERSION = 1
+
+
+class RolePolicy(str, Enum):
+    READ_ONLY = "read-only"
+    WRITER = "writer"
+    REVIEWER_WRITER = "reviewer-writer"
+    INTEGRATOR = "integrator"
+
+
+class UIBackend(str, Enum):
+    AUTO = "auto"
+    HERDR = "herdr"
+    TMUX = "tmux"
+    HEADLESS = "headless"
+
+
+class RunnerName(str, Enum):
+    OPENCODE = "opencode"
+    CLAUDE = "claude"
+    CODEX = "codex"
+    CURSOR = "cursor"
+    COPILOT = "copilot"
+    MUSE = "muse"
+    SKELETON = "skeleton"
+
+
+class RunState(str, Enum):
+    PLANNING = "planning"
+    AWAITING_PLAN_APPROVAL = "awaiting_plan_approval"
+    RUNNING = "running"
+    AWAITING_HUMAN = "awaiting_human"
+    PAUSED = "paused"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+    BUDGET_EXHAUSTED = "budget_exhausted"
+    CLEANUP_PENDING = "cleanup_pending"
+
+
+class RoleState(str, Enum):
+    INACTIVE = "inactive"
+    STARTING = "starting"
+    IDLE = "idle"
+    READY = "ready"
+    WORKING = "working"
+    BLOCKED = "blocked"
+    AWAITING_HANDOFF = "awaiting_handoff"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    STOPPED = "stopped"
+
+
+def validate_role_name(name: str) -> str:
+    if not _ROLE_RE.match(name):
+        raise ValueError(f"Invalid role name: {name!r} (must match {_ROLE_RE.pattern})")
+    return name
+
+
+def validate_run_id(run_id: str) -> str:
+    if not _RUN_ID_RE.match(run_id):
+        raise ValueError(f"Invalid run id: {run_id!r}")
+    return run_id
+
+
+def validate_branch(branch: str) -> str:
+    if (
+        not _BRANCH_SAFE_RE.match(branch)
+        or ".." in branch
+        or branch.startswith("/")
+        or branch.endswith("/")
+    ):
+        raise ValueError(f"Invalid branch: {branch!r}")
+    return branch
+
+
+def validate_commit_sha(sha: str) -> str:
+    if not _SHA_RE.match(sha.lower()):
+        raise ValueError(f"Invalid commit SHA (must be 40 hex chars): {sha!r}")
+    return sha.lower()
+
+
+@dataclass(frozen=True)
+class RoleBudget:
+    max_tokens: int | None = None
+    max_cost_usd: float | None = None
+    max_wall_seconds: int | None = None
+
+
+@dataclass(frozen=True)
+class RunBudget:
+    max_total_tokens: int | None = None
+    max_cost_usd: float | None = None
+    max_wall_seconds: int | None = None
+    max_concurrency: int = 2
+    max_role_round_trips: int = 2
+    max_handoffs: int | None = None
+    max_artifact_bytes: int | None = None
+    per_role: dict[str, RoleBudget] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class ApprovalGate:
+    id: str
+    description: str
+    required: bool = True
+    approved: bool = False
+
+
+@dataclass(frozen=True)
+class WorktreeAssignment:
+    role: str
+    path: str
+    branch: str
+    owned: bool = True
+
+
+@dataclass(frozen=True)
+class RunnerDefinition:
+    name: str
+    kind: str
+    model: str | None = None
+    capabilities: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class ModelProfile:
+    name: str
+    mapping: dict[str, str] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class TaskContract:
+    title: str
+    body: str
+    acceptance: str | None = None
+
+
+@dataclass(frozen=True)
+class Handoff:
+    version: int
+    type: str
+    from_role: str
+    to_role: str
+    priority: int
+    artifact: str | None = None
+    commit: str | None = None
+    branch: str | None = None
+    blocking: bool = False
+    handoff_id: str | None = None
+
+
+@dataclass(frozen=True)
+class ArtifactReference:
+    path: str
+    role: str
+    size_bytes: int | None = None
+
+
+@dataclass(frozen=True)
+class CommitReference:
+    sha: str
+    branch: str
+
+
+@dataclass(frozen=True)
+class RoleAssignment:
+    role: str
+    persona: str
+    policy: RolePolicy
+    model_profile: str
+    runner: str
+    worktree: str | None = None
+    consumes: list[str] = field(default_factory=list)
+    produces: list[str] = field(default_factory=list)
+    receive_mode: str = "task"  # task | batch
+    skills: list[str] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class SwarmRecipe:
+    api_version: str
+    kind: str
+    name: str
+    description: str
+    spec: dict[str, Any]
+
+    @property
+    def roles(self) -> dict[str, Any]:
+        return self.spec.get("roles", {})  # type: ignore
+
+
+@dataclass(frozen=True)
+class SwarmRun:
+    run_id: str
+    recipe: str
+    run_state: RunState
+    roles: dict[str, RoleState]
+    budget: RunBudget
+    ui_backend: UIBackend
+    runner: str
+    model_profile: str
+    created_at: str
+    worktrees: list[WorktreeAssignment] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class TraceEvent:
+    ts: str
+    kind: str
+    run_id: str
+    details: dict[str, Any] = field(default_factory=dict)

agent_toolkit/swarm/prompts.py

@@ -0,0 +1,177 @@
+"""Prompt composition — combine protocol + recipe + role + persona + skills."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+GLOBAL_PROTOCOL = """# Agent Toolkit Swarm — Global Protocol
+- You are a role in a multi-agent swarm. Work only on your assigned task.
+- Do not push, do not merge to base branch, do not publish releases.
+- Transfer code only via validated Git commits on your Toolkit-owned branch.
+- Use durable handoffs via `agent-toolkit swarm handoff create` and `agent-toolkit swarm task next/complete`.
+- Stay inside your worktree when you have one. Do not write outside `.agent-toolkit/swarm/runs/<run-id>/` except your worktree.
+- Keep artifacts under 1MB, no secrets, no full transcript forwarding.
+- Record decisions in artifacts and trace events.
+"""
+
+# Interactive bootstrap — when swarm starts without a task, the first agent must NOT invent work.
+# It does a very brief context analysis and then waits for the user to provide the first request.
+INTERACTIVE_BOOTSTRAP = """# Interactive mode — No initial task
+> This swarm was started **without an initial prompt/task**. The user will provide the first request next in this same Herdr/Tmux session.
+
+**Instructions for the first agent (planner/implementer):**
+- **Do NOT invent work** or start tasks on your own. Do not create a plan or code yet.
+- Do only a **very brief** context analysis (max 3-4 sentences / 30 seconds):
+  - If you detect a **workspace** (exists `AGENTS.md` and/or `knowledge/` or `find_workspace_root()` is not None, e.g. `~/.ai-workspace`):
+    Run `agent-toolkit workspace context` and briefly review `AGENTS.md` + `knowledge/todos/pending.md`.
+    Also check `projects/` and `loops/` if present. Summarize in 2-3 lines what workspace it is.
+  - If no workspace, briefly review the current repo (`git status`, `cat README.md` / `pyproject.toml`).
+- Then **stay on standby** and confirm with a short message:
+  "Brief analysis done — awaiting your first request. When you provide the task, I will apply `assistant` (discovery) + `workflow-generic-project` (plan -> approval -> implement -> review -> draft PR)."
+- When the user sends the request (via chat or `agent-toolkit swarm handoff create --type artifact --from planner --to implementer --artifact artifacts/task-contract.md --run-id <run-id>`), apply the full flow: discovery per `assistant` (order README -> docs/ -> AGENTS.md -> CONTRIBUTING -> PR templates -> Makefile/package.json -> devcontainer/CI), then `workflow-generic-project` with plan approval gate before implementing, and `github-cli-workflow` for draft PR.
+"""
+
+
+def load_persona_text(persona: str) -> str:
+    # Load from bundled data/agents/<persona>/AGENT.md if exists
+    try:
+        from agent_toolkit._paths import find_toolkit_root
+
+        root = find_toolkit_root()
+        # Try package data
+        candidates = [
+            Path(root) / "agents" / persona / "AGENT.md",
+            Path(__file__).parent.parent / "data" / "agents" / persona / "AGENT.md",
+        ]
+        for p in candidates:
+            if p.is_file():
+                return p.read_text(encoding="utf-8")[:2000]
+    except Exception:
+        pass
+    return f"# Persona: {persona}\nAct as {persona} per Toolkit guidance."
+
+
+def compose_role_prompt(
+    recipe: dict[str, Any],
+    role: str,
+    role_def: dict[str, Any],
+    task_contract: str | None,
+    handoff: dict[str, Any] | None,
+    included_skills: list[str] | None = None,
+) -> tuple[str, dict[str, Any]]:
+    persona = role_def.get("persona", role)
+    persona_text = load_persona_text(persona)
+    recipe_name = (recipe.get("metadata") or {}).get("name", "unknown")
+    policy = role_def.get("policy", "read-only")
+    parts: list[str] = [GLOBAL_PROTOCOL]
+    parts.append(f"# Recipe: {recipe_name} — Role: {role}\nPolicy: {policy}\nPersona: {persona}\n")
+    parts.append(persona_text)
+    # Recipe workflow snippet
+    spec = recipe.get("spec", {})
+    workflow = f"Execution: {spec.get('execution', {})}\nWorkspace: {spec.get('workspace', {})}\n"
+    parts.append(workflow)
+    # Empty / whitespace-only task_contract means interactive bootstrap — do not invent work
+    if task_contract and task_contract.strip():
+        parts.append(f"# Task Contract\n{task_contract[:3000]}")
+    else:
+        # No task provided — inject bootstrap: analyze context very briefly, then wait for user
+        parts.append(INTERACTIVE_BOOTSTRAP)
+        # Also hint workspace context command for faster readiness
+        try:
+            from agent_toolkit._paths import find_workspace_root
+
+            ws = find_workspace_root()
+            if ws is not None:
+                parts.append(
+                    f"# Workspace context hint\nDetected workspace at `{ws}` — run `agent-toolkit workspace context` to see session state before waiting."
+                )
+        except Exception:
+            pass
+    if handoff:
+        parts.append(f"# Current Handoff\n{handoff}")
+    if included_skills:
+        parts.append(f"# Skills: {', '.join(included_skills)}")
+    # Handoff instructions — explicit like swarm-forge, per role
+    try:
+        roles = spec.get("roles", {})
+        current = roles.get(role, {})
+        produces = current.get("produces", [])
+        # Find consumers of what we produce
+        next_roles = []
+        for other_name, other_def in roles.items():
+            if other_name == role:
+                continue
+            consumes = other_def.get("consumes", [])
+            # Check if any of our produces is consumed by other
+            for p in produces:
+                if p in consumes:
+                    next_roles.append(other_name)
+                    break
+        # For pair/team/full, also add fallback based on known chain
+        if not next_roles:
+            # Fallback chain for known recipes
+            chain = {
+                "pair": {"implementer": ["reviewer"], "reviewer": ["integrator"]},
+                "team": {
+                    "planner": ["implementer"],
+                    "implementer": ["reviewer"],
+                    "reviewer": ["architect"],
+                },
+                "full": {
+                    "planner": ["implementer"],
+                    "implementer": ["refactorer"],
+                    "refactorer": ["architect"],
+                    "architect": ["hardener"],
+                    "hardener": ["qa"],
+                },
+            }.get(recipe_name, {})
+            next_roles = chain.get(role, [])
+        if next_roles:
+            handoff_lines = [
+                "## Handoff — delegate to next role when done",
+                f"Your role `{role}` produces: {', '.join(produces) if produces else 'artifact'}",
+                f"Next role(s): {', '.join(next_roles)}",
+                "When you complete your work:",
+                "1. If you created/modified code, commit it on your worktree branch (`git add` + `git commit`), then:",
+                f"   `agent-toolkit swarm handoff create --type commit --from {role} --to {next_roles[0]} --commit <40-hex-sha> --branch <your-branch>`",
+                "2. If you created an artifact (e.g., `artifacts/review.md`), then:",
+                f"   `agent-toolkit swarm handoff create --type artifact --from {role} --to {next_roles[0]} --artifact artifacts/<file>.md`",
+                "The next role will run `agent-toolkit swarm task next --role <next> --run-id <run_id>` to pick it up. Do not wait — the handoff is durable and the daemon will notify. The next role's tmux window will be auto-created by the handoff.",
+                "IMPORTANT: After you finish writing the artifact or committing code, immediately run the `handoff create` command above — do NOT ask the user for confirmation, do NOT wait for 'do the handoff'.",
+                f"Run ID for this swarm: `{role_def.get('_run_id', 'see task contract')}` — if the command says 'No run found', add `--run-id <run_id>` or ensure `AGENT_TOOLKIT_SWARM_RUN_ID` is exported (it is in your tmux env).",
+            ]
+            parts.append("\n".join(handoff_lines))
+        else:
+            parts.append(
+                "## Handoff\nWhen done, create a handoff if your work should be reviewed: `agent-toolkit swarm handoff create --type artifact --from "
+                + role
+                + " --to <next> --artifact artifacts/<file>.md` (or `--type commit` with --commit/--branch for code)."
+            )
+    except Exception:
+        pass
+    # Enforce size limit 12k chars
+    text = "\n\n".join(parts)
+    if len(text) > 12000:
+        text = text[:12000] + "\n[truncated]"
+    is_interactive = not task_contract or not task_contract.strip()
+    manifest = {
+        "role": role,
+        "persona": persona,
+        "policy": policy,
+        "recipe": recipe_name,
+        "includes": [
+            "global_protocol",
+            "recipe_workflow",
+            "persona",
+            "interactive_bootstrap" if is_interactive else None,
+            "task_contract" if task_contract and task_contract.strip() else None,
+            "handoff" if handoff else None,
+            "skills" if included_skills else None,
+        ],
+        "size_chars": len(text),
+        "model_profile_task": role_def.get("model_profile"),
+        "is_interactive": is_interactive,
+    }
+    manifest["includes"] = [x for x in manifest["includes"] if x]
+    return text, manifest