coding-agents 0.0.1.dev0__py3-none-any.whl

coding_agents/evolution/skill_miner.py

@@ -0,0 +1,106 @@
+"""Autonomous Skill Synthesis and Pattern Mining from Verified Trajectories."""
+
+from __future__ import annotations
+
+import os
+import re
+from typing import Any, Dict, List, Optional
+from pydantic import BaseModel, Field
+
+
+class MinedToolStep(BaseModel):
+    tool_name: str
+    arguments: Dict[str, Any]
+    output_summary: str
+
+
+class CandidateSkill(BaseModel):
+    name: str
+    description: str
+    trigger_pattern: str
+    steps: List[MinedToolStep] = Field(default_factory=list)
+    parameter_names: List[str] = Field(default_factory=list)
+    skill_md_content: str = ""
+
+
+class SkillMiner:
+    """Extracts repeatable procedures from verified successful execution trajectories."""
+
+    @classmethod
+    def mine_trajectory(
+        cls,
+        task_description: str,
+        turn_records: List[Dict[str, Any]],
+        skill_name_hint: Optional[str] = None,
+    ) -> CandidateSkill:
+        steps: List[MinedToolStep] = []
+        param_candidates: set[str] = set()
+
+        for turn in turn_records:
+            calls = turn.get("tool_calls", [])
+            results = turn.get("tool_results", [])
+            for i, call in enumerate(calls):
+                tool_name = call.get("name", "")
+                args = call.get("arguments", {})
+                res = results[i] if i < len(results) else {}
+                output = res.get("output", "")[:200]
+
+                # Identify potential file path parameters
+                for k, v in args.items():
+                    if isinstance(v, str) and ("/" in v or "." in v):
+                        param_candidates.add(v)
+
+                steps.append(MinedToolStep(
+                    tool_name=tool_name,
+                    arguments=args,
+                    output_summary=output,
+                ))
+
+        clean_name = skill_name_hint or re.sub(r"[^a-z0-9_-]", "-", task_description.lower())[:24].strip("-")
+        clean_name = clean_name or "extracted-skill"
+
+        # Synthesize SKILL.md markdown
+        skill_md = [
+            "---",
+            f"name: {clean_name}",
+            f'description: "Procedural skill mined from successful task: {task_description}"',
+            "---",
+            f"# Procedure: {clean_name}",
+            "",
+            "## When to Use",
+            f"- Trigger on tasks matching: `{task_description}`",
+            "",
+            "## Ordered Steps",
+        ]
+
+        for idx, step in enumerate(steps, start=1):
+            skill_md.append(f"{idx}. Execute `{step.tool_name}` with arguments: `{step.arguments}`")
+
+        skill_md.append("")
+        skill_md.append("## Verification Checklist")
+        skill_md.append("- [ ] Run verification pipeline to confirm all assertions pass.")
+
+        candidate = CandidateSkill(
+            name=clean_name,
+            description=f"Auto-mined skill for {task_description}",
+            trigger_pattern=task_description,
+            steps=steps,
+            parameter_names=sorted(list(param_candidates)),
+            skill_md_content="\n".join(skill_md),
+        )
+        return candidate
+
+    @classmethod
+    def export_skill_package(cls, candidate: CandidateSkill, base_output_dir: str) -> str:
+        """Write candidate skill into standard .agents/skills/<name>/ package."""
+        skill_dir = os.path.join(base_output_dir, candidate.name)
+        os.makedirs(skill_dir, exist_ok=True)
+        os.makedirs(os.path.join(skill_dir, "scripts"), exist_ok=True)
+        os.makedirs(os.path.join(skill_dir, "references"), exist_ok=True)
+
+        skill_md_path = os.path.join(skill_dir, "SKILL.md")
+        with open(skill_md_path, "w", encoding="utf-8") as f:
+            f.write(candidate.skill_md_content)
+
+        return skill_dir
+

coding_agents/py.typed

@@ -0,0 +1,2 @@
+# Marker file for PEP 561 inline types
+

coding_agents/sandbox/__init__.py

@@ -0,0 +1,7 @@
+"""Sandbox and policy governance modules."""
+
+from coding_agents.sandbox.policy import PolicyGate
+from coding_agents.sandbox.worktree import WorktreeSandbox
+
+__all__ = ["PolicyGate", "WorktreeSandbox"]
+

coding_agents/sandbox/policy.py

@@ -0,0 +1,61 @@
+"""Policy governance gates and immutable test defenses."""
+
+from __future__ import annotations
+
+import fnmatch
+import os
+from typing import List, Optional, Tuple
+
+
+class PolicyGate:
+    """Enforces execution boundaries, command deny-lists, and test file immutability."""
+
+    DEFAULT_DENY_PATTERNS: List[str] = [
+        "rm -rf /*",
+        "rm -rf ~*",
+        ":(){ :|:& };:",
+        "mkfs*",
+        "dd if=*",
+        "chmod -R 777 /*",
+    ]
+
+    DEFAULT_IMMUTABLE_PATHS: List[str] = [
+        "tests/*",
+        "test/*",
+        "spec/*",
+        ".github/workflows/*",
+    ]
+
+    def __init__(
+        self,
+        deny_patterns: Optional[List[str]] = None,
+        immutable_paths: Optional[List[str]] = None,
+        lock_tests_during_repair: bool = True,
+    ) -> None:
+        self.deny_patterns = deny_patterns or self.DEFAULT_DENY_PATTERNS
+        self.immutable_paths = immutable_paths or self.DEFAULT_IMMUTABLE_PATHS
+        self.lock_tests_during_repair = lock_tests_during_repair
+
+    def check_command(self, cmd: str) -> Tuple[bool, Optional[str]]:
+        """Verify if a shell command violates security policies."""
+        cleaned = cmd.strip()
+        for pattern in self.deny_patterns:
+            if fnmatch.fnmatch(cleaned, pattern) or pattern in cleaned:
+                return False, f"Policy violation: Command '{cmd}' matches forbidden pattern '{pattern}'"
+        return True, None
+
+    def check_file_mutation(self, file_path: str) -> Tuple[bool, Optional[str]]:
+        """Verify if a file path is protected by test immutability rules."""
+        if not self.lock_tests_during_repair:
+            return True, None
+
+        normalized = file_path.replace("\\", "/").lstrip("./")
+        for pattern in self.immutable_paths:
+            if fnmatch.fnmatch(normalized, pattern) or fnmatch.fnmatch(os.path.basename(normalized), pattern):
+                return (
+                    False,
+                    f"Policy violation: File '{file_path}' is protected by immutable test boundary. "
+                    "You cannot edit test assertions during a bug-fix repair loop.",
+                )
+        return True, None
+

coding_agents/sandbox/worktree.py

@@ -0,0 +1,61 @@
+"""Ephemeral Git worktree sandboxing for safe workspace isolation."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import uuid
+from typing import Optional
+
+
+class WorktreeSandbox:
+    """Manages ephemeral git worktree checkouts for isolated agent execution."""
+
+    def __init__(self, repo_dir: str = ".", base_ref: str = "HEAD") -> None:
+        self.repo_dir = os.path.abspath(repo_dir)
+        self.base_ref = base_ref
+        self.worktree_dir: Optional[str] = None
+        self.branch_name: Optional[str] = None
+
+    def __enter__(self) -> WorktreeSandbox:
+        self.setup()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        self.cleanup()
+
+    def setup(self) -> str:
+        """Create an ephemeral worktree in a temporary directory."""
+        unique_id = uuid.uuid4().hex[:8]
+        self.branch_name = f"agent-sandbox-{unique_id}"
+        self.worktree_dir = os.path.join(self.repo_dir, ".worktrees", self.branch_name)
+
+        os.makedirs(os.path.dirname(self.worktree_dir), exist_ok=True)
+
+        cmd = [
+            "git", "worktree", "add", "-b", self.branch_name,
+            self.worktree_dir, self.base_ref
+        ]
+        subprocess.run(cmd, cwd=self.repo_dir, check=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+        return self.worktree_dir
+
+    def cleanup(self) -> None:
+        """Remove worktree and delete the ephemeral branch."""
+        if self.worktree_dir and os.path.exists(self.worktree_dir):
+            subprocess.run(
+                ["git", "worktree", "remove", "--force", self.worktree_dir],
+                cwd=self.repo_dir,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+            )
+            shutil.rmtree(self.worktree_dir, ignore_errors=True)
+
+        if self.branch_name:
+            subprocess.run(
+                ["git", "branch", "-D", self.branch_name],
+                cwd=self.repo_dir,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+            )
+

coding_agents/tools/__init__.py

@@ -0,0 +1,8 @@
+"""Tool interfaces and reference implementations."""
+
+from coding_agents.tools.base import BaseTool
+from coding_agents.tools.patch_editor import PatchEditor
+from coding_agents.tools.bash_tool import BashTool
+
+__all__ = ["BaseTool", "PatchEditor", "BashTool"]
+

coding_agents/tools/base.py

@@ -0,0 +1,55 @@
+"""Base protocol and interfaces for tools and skills."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict
+from pydantic import BaseModel
+from coding_agents.core.models import ToolResult
+
+
+class BaseTool(ABC):
+    """Abstract base class for all agent tools."""
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Tool name presented to the model."""
+        pass
+
+    @property
+    @abstractmethod
+    def description(self) -> str:
+        """Instructional schema docstring for the model."""
+        pass
+
+    @property
+    @abstractmethod
+    def parameters_schema(self) -> Dict[str, Any]:
+        """JSON schema defining accepted parameters."""
+        pass
+
+    @abstractmethod
+    def execute(self, **kwargs: Any) -> ToolResult:
+        """Execute the tool in the environment and return structured result."""
+        pass
+
+    def to_openai_schema(self) -> Dict[str, Any]:
+        """Format as standard OpenAI function definition."""
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description,
+                "parameters": self.parameters_schema,
+            },
+        }
+
+    def to_anthropic_schema(self) -> Dict[str, Any]:
+        """Format as Anthropic tool definition."""
+        return {
+            "name": self.name,
+            "description": self.description,
+            "input_schema": self.parameters_schema,
+        }
+

coding_agents/tools/bash_tool.py

@@ -0,0 +1,103 @@
+"""Safe subprocess execution tool with output truncation and timeouts."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from typing import Any, Dict, Optional
+from coding_agents.tools.base import BaseTool
+from coding_agents.core.models import ToolResult
+
+
+class BashTool(BaseTool):
+    """Subprocess execution tool bounded by timeout and token/byte caps."""
+
+    def __init__(
+        self,
+        working_dir: str = ".",
+        timeout_seconds: int = 60,
+        max_output_bytes: int = 32_000,
+    ) -> None:
+        self.working_dir = os.path.abspath(working_dir)
+        self.timeout_seconds = timeout_seconds
+        self.max_output_bytes = max_output_bytes
+
+    @property
+    def name(self) -> str:
+        return "bash"
+
+    @property
+    def description(self) -> str:
+        return (
+            "Run a command in the bash shell. "
+            "Returns stdout, stderr, and the process exit code. "
+            "Output is automatically truncated if it exceeds maximum byte limits."
+        )
+
+    @property
+    def parameters_schema(self) -> Dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "command": {
+                    "type": "string",
+                    "description": "The exact shell command line to run",
+                },
+            },
+            "required": ["command"],
+        }
+
+    def execute(self, command: str, **kwargs: Any) -> ToolResult:
+        try:
+            proc = subprocess.run(
+                command,
+                shell=True,
+                cwd=self.working_dir,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                text=True,
+                timeout=self.timeout_seconds,
+            )
+            stdout = proc.stdout
+            stderr = proc.stderr
+            exit_code = proc.returncode
+        except subprocess.TimeoutExpired:
+            return ToolResult(
+                name=self.name,
+                output="",
+                error=f"Error: Command timed out after {self.timeout_seconds} seconds.",
+                exit_code=124,
+            )
+        except Exception as e:
+            return ToolResult(
+                name=self.name,
+                output="",
+                error=f"Error executing command: {str(e)}",
+                exit_code=1,
+            )
+
+        combined = stdout
+        if stderr:
+            combined += f"\n[stderr]\n{stderr}"
+
+        truncated = False
+        if len(combined.encode("utf-8")) > self.max_output_bytes:
+            # Keep first 20% and last 80% of allowed budget
+            head_bytes = int(self.max_output_bytes * 0.2)
+            tail_bytes = int(self.max_output_bytes * 0.8)
+            combined_bytes = combined.encode("utf-8", errors="replace")
+            combined = (
+                combined_bytes[:head_bytes].decode("utf-8", errors="replace")
+                + f"\n\n... [Truncated {len(combined_bytes) - self.max_output_bytes} bytes] ...\n\n"
+                + combined_bytes[-tail_bytes:].decode("utf-8", errors="replace")
+            )
+            truncated = True
+
+        return ToolResult(
+            name=self.name,
+            output=combined,
+            error=stderr if exit_code != 0 else None,
+            exit_code=exit_code,
+            truncated=truncated,
+        )
+

coding_agents/tools/patch_editor.py

@@ -0,0 +1,111 @@
+"""Exact-match string replacement tool with uniqueness collision protection."""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Dict
+from coding_agents.tools.base import BaseTool
+from coding_agents.core.models import ToolResult
+
+
+class PatchEditor(BaseTool):
+    """File editing tool using strict exact-match substring replacement."""
+
+    def __init__(self, working_dir: str = ".") -> None:
+        self.working_dir = os.path.abspath(working_dir)
+
+    @property
+    def name(self) -> str:
+        return "edit_file_exact"
+
+    @property
+    def description(self) -> str:
+        return (
+            "Replace an exact substring in a file with new content. "
+            "The target string must be unique in the file to prevent ambiguous edits. "
+            "Include sufficient surrounding context lines to ensure uniqueness."
+        )
+
+    @property
+    def parameters_schema(self) -> Dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "path": {
+                    "type": "string",
+                    "description": "Relative or absolute path to the file to edit",
+                },
+                "old_str": {
+                    "type": "string",
+                    "description": "Exact substring to replace. Must occur exactly once in the file.",
+                },
+                "new_str": {
+                    "type": "string",
+                    "description": "Replacement string.",
+                },
+            },
+            "required": ["path", "old_str", "new_str"],
+        }
+
+    def execute(self, path: str, old_str: str, new_str: str, **kwargs: Any) -> ToolResult:
+        full_path = os.path.join(self.working_dir, path) if not os.path.isabs(path) else path
+
+        if not os.path.exists(full_path):
+            return ToolResult(
+                name=self.name,
+                output="",
+                error=f"Error: File '{path}' does not exist.",
+                exit_code=1,
+            )
+
+        try:
+            with open(full_path, "r", encoding="utf-8") as f:
+                content = f.read()
+        except Exception as e:
+            return ToolResult(
+                name=self.name,
+                output="",
+                error=f"Error reading '{path}': {str(e)}",
+                exit_code=1,
+            )
+
+        occurrences = content.count(old_str)
+        if occurrences == 0:
+            return ToolResult(
+                name=self.name,
+                output="",
+                error=(
+                    f"Error: 'old_str' not found in '{path}'. "
+                    "Make sure whitespace and indentation match exactly."
+                ),
+                exit_code=1,
+            )
+        elif occurrences > 1:
+            return ToolResult(
+                name=self.name,
+                output="",
+                error=(
+                    f"Error: 'old_str' found {occurrences} times in '{path}'. "
+                    "Ambiguous edit rejected. Add more surrounding context to disambiguate."
+                ),
+                exit_code=1,
+            )
+
+        new_content = content.replace(old_str, new_str, 1)
+        try:
+            with open(full_path, "w", encoding="utf-8") as f:
+                f.write(new_content)
+        except Exception as e:
+            return ToolResult(
+                name=self.name,
+                output="",
+                error=f"Error writing '{path}': {str(e)}",
+                exit_code=1,
+            )
+
+        return ToolResult(
+            name=self.name,
+            output=f"Successfully edited '{path}'. Replaced 1 occurrence.",
+            exit_code=0,
+        )
+

coding_agents/verification/__init__.py

@@ -0,0 +1,15 @@
+"""Verification pipelines, fault localization, and cycle detection."""
+
+from coding_agents.verification.pipeline import VerificationPipeline, VerificationManifest, StageResult
+from coding_agents.verification.fault_localizer import FaultLocalizer, DiagnosticFrame
+from coding_agents.verification.oscillation import OscillationDetector
+
+__all__ = [
+    "VerificationPipeline",
+    "VerificationManifest",
+    "StageResult",
+    "FaultLocalizer",
+    "DiagnosticFrame",
+    "OscillationDetector",
+]
+

coding_agents/verification/fault_localizer.py

@@ -0,0 +1,51 @@
+"""Structured diagnostic fault extraction from test and compiler outputs."""
+
+from __future__ import annotations
+
+import re
+from typing import List, Optional
+from pydantic import BaseModel
+
+
+class DiagnosticFrame(BaseModel):
+    """A localized error frame."""
+    file_path: str
+    line_number: Optional[int] = None
+    error_type: str
+    message: str
+    raw_snippet: Optional[str] = None
+
+
+class FaultLocalizer:
+    """Extracts compact, actionable error records from raw compiler and test runner output."""
+
+    @classmethod
+    def parse_pytest_output(cls, output: str) -> List[DiagnosticFrame]:
+        frames: List[DiagnosticFrame] = []
+
+        # Match pytest failure headers: FAILURES / ERRORS
+        failure_pattern = re.compile(r"_{3,}\s*(.*?)\s*_{3,}\n(.*?)(?=\n_{3,}|\n={3,}|\Z)", re.DOTALL)
+        for match in failure_pattern.finditer(output):
+            test_name = match.group(1).strip()
+            trace_body = match.group(2).strip()
+
+            # Locate file and line: File "...", line 123, in ...
+            file_match = re.search(r'File "([^"]+)", line (\d+), in (\w+)', trace_body)
+            # Locate exception line
+            exc_match = re.search(r"(\w+Error|\w+Exception|AssertionError):\s*(.*)", trace_body)
+
+            file_path = file_match.group(1) if file_match else test_name
+            line_no = int(file_match.group(2)) if file_match else None
+            error_type = exc_match.group(1) if exc_match else "AssertionFailure"
+            msg = exc_match.group(2).strip() if exc_match else "Test assertion failed"
+
+            frames.append(DiagnosticFrame(
+                file_path=file_path,
+                line_number=line_no,
+                error_type=error_type,
+                message=f"[{test_name}] {error_type}: {msg}",
+                raw_snippet=trace_body[-300:] if len(trace_body) > 300 else trace_body,
+            ))
+
+        return frames
+

coding_agents/verification/oscillation.py

@@ -0,0 +1,46 @@
+"""Cryptographic AST and diff state hashing for cycle detection."""
+
+from __future__ import annotations
+
+import ast
+import hashlib
+from typing import List, Optional, Set
+
+
+class OscillationDetector:
+    """Detects cyclic repair states where an agent alternates between identical code mutations."""
+
+    def __init__(self) -> None:
+        self.seen_state_hashes: Set[str] = set()
+        self.hash_history: List[str] = []
+
+    @staticmethod
+    def hash_diff(diff_text: str) -> str:
+        """Compute normalized cryptographic hash of candidate diff."""
+        normalized = "\n".join(line.rstrip() for line in diff_text.strip().splitlines() if line.strip())
+        return hashlib.sha256(normalized.encode("utf-8")).hexdigest()
+
+    @staticmethod
+    def hash_python_ast(source_code: str) -> Optional[str]:
+        """Compute structural AST hash invariant to whitespace and formatting changes."""
+        try:
+            tree = ast.parse(source_code)
+            dumped = ast.dump(tree, annotate_fields=False, include_attributes=False)
+            return hashlib.sha256(dumped.encode("utf-8")).hexdigest()
+        except SyntaxError:
+            return None
+
+    def record_and_check(self, diff_or_code: str, is_ast: bool = False) -> bool:
+        """Return True if the current state was already visited in this session."""
+        if is_ast:
+            state_hash = self.hash_python_ast(diff_or_code) or self.hash_diff(diff_or_code)
+        else:
+            state_hash = self.hash_diff(diff_or_code)
+
+        if state_hash in self.seen_state_hashes:
+            return True
+
+        self.seen_state_hashes.add(state_hash)
+        self.hash_history.append(state_hash)
+        return False
+