fableforge-anvil-agent 0.1.0__py3-none-any.whl

anvil/__init__.py

@@ -0,0 +1,154 @@
+"""Anvil — The open-source, self-verified coding agent.
+
+Generate → Execute → Verify → Recover.
+
+Every other open agent generates and hopes. Anvil generates, runs,
+checks, and fixes — because it was trained on 210,000 examples of
+real agents doing exactly that.
+
+The core loop:
+    1. PLAN     — Decompose task into atomic steps
+    2. EXECUTE  — Run each step with real tools
+    3. VERIFY   — Check the output actually works (syntax, tests, lint, type)
+    4. RECOVER  — If verification fails, diagnose and fix automatically
+
+This isn't prompt engineering. This is behavior engineering.
+
+v2 adds multi-agent support (switching, @mention, custom agents)
+and a fine-grained permissions system.
+
+Python SDK usage::
+
+    import anvil
+
+    result = anvil.run("fix the failing tests")
+    print(result.output)
+
+    session = anvil.Session()
+    session.ask("explain this code")
+    session.ask("now refactor it")
+
+    for chunk in anvil.stream("write a function"):
+        print(chunk, end="")
+
+    report = anvil.verify(["src/app.py"])
+
+    anvil.create_agent(
+        name="reviewer", mode="subagent",
+        permission={"edit": "deny", "bash": "deny"},
+    )
+
+    agents = anvil.list_agents()
+    anvil.switch_agent("plan")
+"""
+
+from anvil.core.engine import AnvilEngine, EngineResult
+from anvil.core.config import AnvilConfig
+from anvil.core.session import Session
+from anvil.verify.pipeline import VerifyPipeline
+from anvil.models.registry import ModelRegistry
+from anvil.agents.agent_base import BaseAgent, AgentMode
+from anvil.agents.agent_manager import AgentManager
+from anvil.agents.builtin_agents import BUILTIN_AGENTS
+from anvil.permissions.permissions import PermissionAction, PermissionConfig, PermissionManager
+from anvil.sdk import (
+    run,
+    stream,
+    arun,
+    astream,
+    verify,
+    Session as SDKSession,
+    configure,
+    SDKResult,
+    SDKVerifyResult,
+    SDKAgentManager,
+    _AgentsProxy,
+)
+
+__version__ = "0.1.0"
+
+# ── Agent management via SDK ──────────────────────────────────────────────
+# anvil._agents is the SDK proxy for agent operations.
+# It's accessed via anvil.list_agents(), anvil.create_agent(), etc.
+# This avoids conflicting with the anvil.agents subpackage.
+_agents_proxy = _AgentsProxy()
+
+
+def list_agents() -> list:
+    """List all available agents."""
+    return _agents_proxy.list()
+
+
+def switch_agent(name: str) -> dict:
+    """Switch to a different agent."""
+    return _agents_proxy.switch(name)
+
+
+def create_agent(
+    name: str,
+    description: str = "",
+    mode: str = "subagent",
+    model: str = "local",
+    temperature: float = 0.2,
+    max_steps: int = 20,
+    tools_whitelist: list = None,
+    tools_blacklist: list = None,
+    permission: dict = None,
+    prompt_template: str = "",
+    hidden: bool = False,
+    color: str = "white",
+) -> dict:
+    """Create a custom agent."""
+    return _agents_proxy.create(
+        name=name,
+        description=description,
+        mode=mode,
+        model=model,
+        temperature=temperature,
+        max_steps=max_steps,
+        tools_whitelist=tools_whitelist or [],
+        tools_blacklist=tools_blacklist or [],
+        permission=permission or {},
+        prompt_template=prompt_template,
+        hidden=hidden,
+        color=color,
+    )
+
+
+def invoke_agent(name: str, task: str, **kwargs) -> dict:
+    """Invoke a subagent directly."""
+    return _agents_proxy.invoke(name, task, **kwargs)
+
+
+__all__ = [
+    # Core
+    "AnvilEngine",
+    "AnvilConfig",
+    "EngineResult",
+    "Session",
+    "VerifyPipeline",
+    "ModelRegistry",
+    "BaseAgent",
+    "AgentMode",
+    "AgentManager",
+    "BUILTIN_AGENTS",
+    "PermissionAction",
+    "PermissionConfig",
+    "PermissionManager",
+    # SDK
+    "run",
+    "stream",
+    "arun",
+    "astream",
+    "verify",
+    "SDKSession",
+    "configure",
+    "SDKResult",
+    "SDKVerifyResult",
+    "SDKAgentManager",
+    # Agent management
+    "list_agents",
+    "switch_agent",
+    "create_agent",
+    "invoke_agent",
+]

anvil/agents/__init__.py

@@ -0,0 +1,28 @@
+"""Anvil Agents — multi-agent orchestration for the self-verified coding agent."""
+
+from anvil.agents.agent_base import BaseAgent, AgentMode
+from anvil.agents.builtin_agents import (
+    BuildAgent,
+    PlanAgent,
+    ExploreAgent,
+    GeneralAgent,
+    ScoutAgent,
+    CompactionAgent,
+    TitleAgent,
+    BUILTIN_AGENTS,
+)
+from anvil.agents.agent_manager import AgentManager
+
+__all__ = [
+    "BaseAgent",
+    "AgentMode",
+    "BuildAgent",
+    "PlanAgent",
+    "ExploreAgent",
+    "GeneralAgent",
+    "ScoutAgent",
+    "CompactionAgent",
+    "TitleAgent",
+    "BUILTIN_AGENTS",
+    "AgentManager",
+]

anvil/agents/agent_base.py

@@ -0,0 +1,127 @@
+"""Base agent definition — the contract every Anvil agent satisfies."""
+
+from __future__ import annotations
+
+from enum import Enum
+from dataclasses import dataclass, field
+from typing import Optional, Any
+
+from anvil.permissions.permissions import PermissionConfig
+
+
+class AgentMode(str, Enum):
+    """Whether this agent runs as the primary loop or is invoked as a subagent."""
+    PRIMARY = "primary"
+    SUBAGENT = "subagent"
+
+
+@dataclass
+class BaseAgent:
+    """A fully-specified agent persona that the engine can switch to.
+
+    Attributes
+    ----------
+    name : str
+        Human-readable identifier, used with ``--agent build`` or ``@explore``.
+    description : str
+        One-line summary shown in ``anvil agents list``.
+    mode : AgentMode
+        PRIMARY agents own the main loop; SUBAGENT agents are invoked on-demand.
+    model : str
+        Model identifier forwarded to the model registry.
+    temperature : float
+        Sampling temperature for this agent.
+    top_p : float
+        Nucleus sampling parameter.
+    max_steps : int
+        Hard cap on tool-call iterations this agent may take per task.
+    tools_whitelist : list[str]
+        If non-empty, **only** these tools are available to the agent.
+    tools_blacklist : list[str]
+        Tools explicitly excluded even if they appear in the whitelist.
+    permission : PermissionConfig
+        Fine-grained per-tool permission overrides.
+    prompt_template : str
+        System-prompt template. May contain ``{tools}`` placeholder.
+    hidden : bool
+        Hidden agents don't appear in ``anvil agents list`` output
+        (but are still functional).
+    color : str
+        Rich colour name used in the TUI to distinguish this agent's output.
+    extra : dict
+        Additional model-level kwargs forwarded to the backend.
+    """
+
+    name: str = "build"
+    description: str = "Primary coding agent with full tool access"
+    mode: AgentMode = AgentMode.PRIMARY
+    model: str = "local"
+    temperature: float = 0.2
+    top_p: float = 1.0
+    max_steps: int = 20
+    tools_whitelist: list[str] = field(default_factory=list)
+    tools_blacklist: list[str] = field(default_factory=list)
+    permission: PermissionConfig = field(default_factory=PermissionConfig.permissive)
+    prompt_template: str = ""
+    hidden: bool = False
+    color: str = "cyan"
+    extra: dict = field(default_factory=dict)
+
+    # ── derived helpers ────────────────────────────────────────────────
+
+    @property
+    def is_primary(self) -> bool:
+        return self.mode == AgentMode.PRIMARY
+
+    @property
+    def is_subagent(self) -> bool:
+        return self.mode == AgentMode.SUBAGENT
+
+    def available_tools(self, all_tools: list[str]) -> list[str]:
+        """Return the tools this agent is allowed to see.
+
+        Whitelist wins over blacklist.  If no whitelist is given, all
+        tools except blacklisted ones are available.
+        """
+        if self.tools_whitelist:
+            allowed = [t for t in all_tools if t in self.tools_whitelist]
+        else:
+            allowed = list(all_tools)
+        return [t for t in allowed if t not in self.tools_blacklist]
+
+    def get_system_prompt(self, tools: list[str]) -> str:
+        """Render the system-prompt template with available tools."""
+        tool_str = ", ".join(tools)
+        if self.prompt_template:
+            return self.prompt_template.format(tools=tool_str)
+        return f"You are the {self.name} agent. Available tools: {tool_str}"
+
+    # ── serialisation ──────────────────────────────────────────────────
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "description": self.description,
+            "mode": self.mode.value,
+            "model": self.model,
+            "temperature": self.temperature,
+            "top_p": self.top_p,
+            "max_steps": self.max_steps,
+            "tools_whitelist": self.tools_whitelist,
+            "tools_blacklist": self.tools_blacklist,
+            "permission": self.permission.to_dict(),
+            "prompt_template": self.prompt_template,
+            "hidden": self.hidden,
+            "color": self.color,
+            "extra": self.extra,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "BaseAgent":
+        perm_data = data.pop("permission", {})
+        mode_val = data.pop("mode", "primary")
+        return cls(
+            mode=AgentMode(mode_val),
+            permission=PermissionConfig.from_dict(perm_data) if perm_data else PermissionConfig.permissive(),
+            **{k: v for k, v in data.items() if k in cls.__dataclass_fields__},
+        )

anvil/agents/agent_manager.py

@@ -0,0 +1,380 @@
+"""Agent manager — registration, switching, @mention, and lifecycle."""
+
+from __future__ import annotations
+
+import re
+import json
+from pathlib import Path
+from dataclasses import dataclass, field
+from typing import Optional, Any
+
+from anvil.agents.agent_base import BaseAgent, AgentMode
+from anvil.agents.builtin_agents import BUILTIN_AGENTS
+from anvil.models.registry import ModelRegistry, Message, ModelResponse
+
+
+@dataclass
+class AgentInvocation:
+    """Record of a single subagent invocation and its result."""
+    agent_name: str
+    task: str
+    response: str
+    success: bool
+    tool_calls: list[dict] = field(default_factory=list)
+    duration_ms: float = 0.0
+
+
+class AgentManager:
+    """Central registry and lifecycle manager for Anvil agents.
+
+    Responsibilities
+    ----------------
+    * Register and look up agents (builtins + user-defined)
+    * Switch the active primary agent (Tab-key style)
+    * Dispatch subagent invocations via ``@mention`` syntax
+    * Load custom agents from ``~/.config/anvil/agents/`` and ``.anvil/agents/``
+    * Create agents from JSON dicts or markdown front-matter
+    """
+
+    def __init__(
+        self,
+        config_dir: Optional[Path] = None,
+        project_dir: Optional[Path] = None,
+    ):
+        self._agents: dict[str, BaseAgent] = {}
+        self._active_agent: str = "build"
+        self._invocation_history: list[AgentInvocation] = []
+        self._config_dir = config_dir or Path.home() / ".config" / "anvil"
+        self._project_dir = project_dir or Path.cwd()
+
+        # Register builtins (they may be factory functions or BaseAgent instances)
+        for name, agent in BUILTIN_AGENTS.items():
+            self._agents[name] = agent() if callable(agent) and not isinstance(agent, BaseAgent) else agent
+
+        # Load user-defined agents
+        self._load_from_directory(self._config_dir / "agents")
+        self._load_from_directory(self._project_dir / ".anvil" / "agents")
+
+    # ── registration ───────────────────────────────────────────────────
+
+    def register(self, agent: BaseAgent) -> None:
+        """Register (or replace) an agent by name."""
+        self._agents[agent.name] = agent
+
+    def get(self, name: str) -> Optional[BaseAgent]:
+        """Look up an agent by name."""
+        return self._agents.get(name)
+
+    def list_agents(self, include_hidden: bool = False) -> list[BaseAgent]:
+        """Return all registered agents, optionally including hidden ones."""
+        return [
+            a for a in self._agents.values()
+            if include_hidden or not a.hidden
+        ]
+
+    @property
+    def active_agent(self) -> BaseAgent:
+        """The agent currently owning the primary loop."""
+        return self._agents[self._active_agent]
+
+    def switch(self, name: str) -> BaseAgent:
+        """Switch the active primary agent.
+
+        Raises ``KeyError`` if *name* is not registered or the agent
+        is not a PRIMARY agent.
+        """
+        agent = self._agents.get(name)
+        if agent is None:
+            raise KeyError(f"Unknown agent: {name!r}. Available: {list(self._agents.keys())}")
+        if not agent.is_primary:
+            raise ValueError(f"Agent {name!r} is a subagent — use @mention, not switch")
+        self._active_agent = name
+        return agent
+
+    # ── @mention dispatch ──────────────────────────────────────────────
+
+    _MENTION_RE = re.compile(r"@(\w+)\s+(.*)", re.DOTALL)
+
+    def parse_mention(self, text: str) -> Optional[tuple[str, str]]:
+        """Extract ``@agent task`` from *text*.
+
+        Returns ``(agent_name, task)`` or ``None`` if no @mention found.
+        """
+        m = self._MENTION_RE.search(text.strip())
+        if m:
+            return m.group(1).lower(), m.group(2).strip()
+        return None
+
+    def invoke_subagent(
+        self,
+        name: str,
+        task: str,
+        model: Any = None,
+        working_dir: str = ".",
+    ) -> AgentInvocation:
+        """Invoke a subagent and capture its response.
+
+        Parameters
+        ----------
+        name : str
+            The subagent's registered name.
+        task : str
+            Description of what the subagent should do.
+        model : BaseModel, optional
+            An already-constructed model backend. If ``None``, one is
+            created from the agent's model setting.
+        working_dir : str
+            Working directory for tool execution.
+
+        Returns
+        -------
+        AgentInvocation
+            Summary of what the subagent did.
+        """
+        import time
+
+        agent = self._agents.get(name)
+        if agent is None:
+            return AgentInvocation(
+                agent_name=name, task=task,
+                response=f"Error: unknown agent '{name}'",
+                success=False,
+            )
+        if not agent.is_subagent:
+            return AgentInvocation(
+                agent_name=name, task=task,
+                response=f"Error: '{name}' is a primary agent, not a subagent",
+                success=False,
+            )
+
+        start = time.time()
+
+        # Resolve or create the model backend.
+        if model is None:
+            from anvil.core.config import AnvilConfig
+            cfg = AnvilConfig()
+            cfg.model.model = agent.model
+            model = ModelRegistry.create(
+                agent.model,
+                api_key=cfg.model.api_key,
+                api_base=cfg.model.api_base,
+            )
+
+        # Build the tool list available to this agent.
+        from anvil.tools.executor import ToolExecutor
+        all_tool_names = [t["name"] for t in _all_tool_definitions()]
+        available = agent.available_tools(all_tool_names)
+        system_prompt = agent.get_system_prompt(available)
+
+        messages = [
+            Message(role="system", content=system_prompt),
+            Message(role="user", content=task),
+        ]
+
+        response: ModelResponse = model.complete(
+            messages,
+            temperature=agent.temperature,
+            max_tokens=agent.extra.get("max_tokens", 4096),
+        )
+
+        duration_ms = (time.time() - start) * 1000
+
+        invocation = AgentInvocation(
+            agent_name=name,
+            task=task,
+            response=response.content,
+            success=True,
+            tool_calls=response.tool_calls,
+            duration_ms=duration_ms,
+        )
+        self._invocation_history.append(invocation)
+        return invocation
+
+    # ── custom agent creation ───────────────────────────────────────────
+
+    def create_agent_from_dict(self, name: str, spec: dict[str, Any]) -> BaseAgent:
+        """Create and register a custom agent from a plain dict.
+
+        Example ``spec``::
+
+            {
+                "description": "Reviews code for quality",
+                "mode": "subagent",
+                "model": "claude-3.5-sonnet",
+                "permission": {"edit": "deny", "bash": "ask"},
+                "max_steps": 10
+            }
+
+        Missing keys default to sensible values.
+        """
+        spec_copy = dict(spec)
+        spec_copy.setdefault("description", f"Custom agent: {name}")
+        spec_copy.setdefault("mode", "subagent")
+        spec_copy.setdefault("model", "local")
+        spec_copy.setdefault("temperature", 0.2)
+        spec_copy.setdefault("top_p", 1.0)
+        spec_copy.setdefault("max_steps", 20)
+        spec_copy.setdefault("tools_whitelist", [])
+        spec_copy.setdefault("tools_blacklist", [])
+        spec_copy.setdefault("hidden", False)
+        spec_copy.setdefault("color", "white")
+        spec_copy.setdefault("prompt_template", "")
+        spec_copy.setdefault("extra", {})
+
+        agent = BaseAgent(name=name, **{
+            k: v for k, v in spec_copy.items()
+            if k in BaseAgent.__dataclass_fields__
+        })
+        self.register(agent)
+        return agent
+
+    def create_agent_from_markdown(self, text: str, name: Optional[str] = None) -> BaseAgent:
+        """Parse an agent from markdown with YAML-like front matter.
+
+        Format::
+
+            ---
+            name: code-reviewer
+            description: Reviews code for quality
+            mode: subagent
+            model: anthropic/claude-sonnet-4
+            permission:
+              edit: deny
+              bash: ask
+            ---
+
+            You are a code reviewer...
+            (body becomes the prompt_template)
+
+        """
+        front_matter: dict[str, Any] = {}
+        body = ""
+
+        if text.strip().startswith("---"):
+            parts = text.strip().split("---", 2)
+            if len(parts) >= 3:
+                fm_text = parts[1].strip()
+                body = parts[2].strip()
+                for line in fm_text.split("\n"):
+                    line = line.strip()
+                    if not line or line.startswith("#"):
+                        continue
+                    if ":" in line:
+                        key, _, value = line.partition(":")
+                        key = key.strip()
+                        value = value.strip()
+                        # Parse nested YAML (simple 2-space indent).
+                        if value == "" and key == "permission":
+                            # Will be handled in the next indented block.
+                            continue
+                        front_matter[key] = _parse_yaml_value(value)
+            else:
+                body = text
+        else:
+            body = text
+
+        # Handle indented permission block inside front matter.
+        permission_block: dict[str, str] = {}
+        if "permission" not in front_matter:
+            # Try to parse from raw front matter.
+            fm_lines = text.strip().split("---")[1].strip().split("\n") if text.strip().startswith("---") else []
+            in_permission = False
+            for line in fm_lines:
+                stripped = line.strip()
+                if stripped.startswith("permission:"):
+                    in_permission = True
+                    continue
+                if in_permission:
+                    if line.startswith("  ") or line.startswith("\t"):
+                        k, _, v = stripped.partition(":")
+                        permission_block[k.strip()] = v.strip()
+                    else:
+                        in_permission = False
+            if permission_block:
+                front_matter["permission"] = permission_block
+
+        if body and "prompt_template" not in front_matter:
+            front_matter["prompt_template"] = body + "\n\nAvailable tools: {tools}"
+
+        agent_name = name or front_matter.pop("name", "custom")
+        front_matter.pop("name", None)
+        return self.create_agent_from_dict(agent_name, front_matter)
+
+    # ── directory loading ───────────────────────────────────────────────
+
+    def _load_from_directory(self, directory: Path) -> None:
+        """Load custom agents from *.json* and *.md* files in *directory*.
+
+        JSON files should map agent-name → spec.
+        Markdown files should use front-matter format.
+        """
+        if not directory.exists():
+            return
+
+        for filepath in sorted(directory.iterdir()):
+            if filepath.suffix == ".json":
+                try:
+                    data = json.loads(filepath.read_text(encoding="utf-8"))
+                    for agent_name, spec in data.items():
+                        if isinstance(spec, dict):
+                            self.create_agent_from_dict(agent_name, spec)
+                except (json.JSONDecodeError, TypeError, KeyError) as exc:
+                    # Silently skip malformed files — they'll be logged elsewhere.
+                    pass
+
+            elif filepath.suffix == ".md":
+                try:
+                    text = filepath.read_text(encoding="utf-8")
+                    agent_name = filepath.stem
+                    self.create_agent_from_markdown(text, name=agent_name)
+                except Exception:
+                    pass
+
+    # ── lifecycle helpers ───────────────────────────────────────────────
+
+    def agent_names(self) -> list[str]:
+        """Return names of all non-hidden agents."""
+        return [a.name for a in self.list_agents(include_hidden=False)]
+
+    def all_agent_names(self) -> list[str]:
+        """Return names of all agents including hidden."""
+        return list(self._agents.keys())
+
+    def invocation_history(self) -> list[AgentInvocation]:
+        """Return the history of all subagent invocations."""
+        return list(self._invocation_history)
+
+
+def _all_tool_definitions() -> list[dict]:
+    """Return the master list of built-in tool definitions."""
+    return [
+        {"name": "bash", "description": "Run a shell command", "args": ["command"]},
+        {"name": "read", "description": "Read a file", "args": ["path", "offset", "limit"]},
+        {"name": "write", "description": "Write a file", "args": ["path", "content"]},
+        {"name": "edit", "description": "Edit a file by replacing text", "args": ["path", "old_string", "new_string"]},
+        {"name": "grep", "description": "Search file contents", "args": ["pattern", "path", "include"]},
+        {"name": "glob", "description": "Find files by pattern", "args": ["pattern", "path"]},
+        {"name": "ls", "description": "List directory contents", "args": ["path"]},
+    ]
+
+
+def _parse_yaml_value(value: str) -> Any:
+    """Minimal YAML value parser for front-matter scalars."""
+    value = value.strip()
+    if value.lower() in ("true", "yes"):
+        return True
+    if value.lower() in ("false", "no"):
+        return False
+    try:
+        return int(value)
+    except ValueError:
+        pass
+    try:
+        return float(value)
+    except ValueError:
+        pass
+    if value.startswith('"') and value.endswith('"'):
+        return value[1:-1]
+    if value.startswith("'") and value.endswith("'"):
+        return value[1:-1]
+    return value