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

coding_agents/__init__.py

@@ -0,0 +1,37 @@
+"""Coding Agents: The reference harness and runtime for autonomous coding systems."""
+
+from coding_agents.core.agent import CodingAgent
+from coding_agents.core.budget import Budget
+from coding_agents.core.models import StopCondition, Trajectory, TurnRecord, ToolCall, ToolResult
+from coding_agents.tools.patch_editor import PatchEditor
+from coding_agents.tools.bash_tool import BashTool
+from coding_agents.sandbox.policy import PolicyGate
+from coding_agents.sandbox.worktree import WorktreeSandbox
+from coding_agents.verification.pipeline import VerificationPipeline, VerificationManifest
+from coding_agents.verification.fault_localizer import FaultLocalizer
+from coding_agents.verification.oscillation import OscillationDetector
+from coding_agents.evolution.skill_miner import SkillMiner
+from coding_agents.evolution.parallel_planner import ParallelPlanningEngine
+
+__version__ = "0.0.1.dev0"
+
+__all__ = [
+    "CodingAgent",
+    "Budget",
+    "StopCondition",
+    "Trajectory",
+    "TurnRecord",
+    "ToolCall",
+    "ToolResult",
+    "PatchEditor",
+    "BashTool",
+    "PolicyGate",
+    "WorktreeSandbox",
+    "VerificationPipeline",
+    "VerificationManifest",
+    "FaultLocalizer",
+    "OscillationDetector",
+    "SkillMiner",
+    "ParallelPlanningEngine",
+]
+

coding_agents/cli.py

@@ -0,0 +1,87 @@
+"""Command-Line Interface for the coding-agents harness."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+from coding_agents import __version__, CodingAgent, Budget, VerificationPipeline, SkillMiner
+
+
+def create_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="coding-agent",
+        description="Coding Agents: The Reference Software Engineering Harness & Runtime",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+
+    subparsers = parser.add_subparsers(dest="subcommand", help="Available subcommands")
+
+    # Command: run
+    run_parser = subparsers.add_parser("run", help="Execute an autonomous coding task")
+    run_parser.add_argument("--task", "-t", required=True, help="Task description or issue prompt")
+    run_parser.add_argument("--model", "-m", default="claude-3-7-sonnet", help="Base model identifier")
+    run_parser.add_argument("--max-turns", type=int, default=30, help="Maximum turn budget")
+    run_parser.add_argument("--max-cost", type=float, default=5.00, help="Maximum monetary cost budget ($)")
+
+    # Command: verify
+    verify_parser = subparsers.add_parser("verify", help="Run the 5-stage verification pipeline")
+    verify_parser.add_argument("--dir", default=".", help="Target workspace directory")
+
+    # Command: skill-mine
+    mine_parser = subparsers.add_parser("skill-mine", help="Synthesize SKILL.md from task description")
+    mine_parser.add_argument("--task", "-t", required=True, help="Task description to parameterize")
+    mine_parser.add_argument("--out", "-o", default=".agents/skills", help="Output skills directory")
+
+    return parser
+
+
+def main(args: list[str] | None = None) -> int:
+    console = Console()
+    parser = create_parser()
+    parsed = parser.parse_args(args)
+
+    if not parsed.subcommand:
+        parser.print_help()
+        return 0
+
+    if parsed.subcommand == "run":
+        console.print(Panel(f"[bold cyan]Starting Coding Agent Task[/bold cyan]\nTask: {parsed.task}\nModel: {parsed.model}", title="Coding Agents Harness"))
+        budget = Budget(max_turns=parsed.max_turns, max_cost_usd=parsed.max_cost)
+        agent = CodingAgent(model=parsed.model, budget=budget)
+        trajectory = agent.run(parsed.task)
+        console.print(f"[bold green]Task Finished[/bold green]: {trajectory.final_status.value} (Tokens: {trajectory.total_tokens:,}, Cost: ${trajectory.total_cost_usd:.3f})")
+        return 0 if trajectory.success else 1
+
+    elif parsed.subcommand == "verify":
+        console.print("[bold yellow]Executing Verification Pipeline...[/bold yellow]")
+        pipeline = VerificationPipeline(working_dir=parsed.dir)
+        manifest = pipeline.run_all()
+        table = Table(title="Verification Manifest")
+        table.add_column("Stage", style="cyan")
+        table.add_column("Status", style="bold")
+        table.add_column("Diagnostics")
+
+        for stage in manifest.stages:
+            status_str = "[green]PASS[/green]" if stage.passed else "[red]FAIL[/red]"
+            table.add_row(stage.stage_name, status_str, stage.error_message or "Clean")
+
+        console.print(table)
+        return 0 if manifest.all_passed else 1
+
+    elif parsed.subcommand == "skill-mine":
+        console.print(f"[bold magenta]Mining procedural pattern for task: {parsed.task}[/bold magenta]")
+        candidate = SkillMiner.mine_trajectory(parsed.task, [])
+        pkg_dir = SkillMiner.export_skill_package(candidate, parsed.out)
+        console.print(f"[bold green]Exported Skill Package to:[/bold green] {pkg_dir}")
+        return 0
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
+

coding_agents/core/__init__.py

@@ -0,0 +1,26 @@
+"""Core execution loop, models, budgets, and agent classes."""
+
+from coding_agents.core.models import (
+    StopCondition,
+    ToolCall,
+    ToolResult,
+    TurnRecord,
+    Trajectory,
+)
+from coding_agents.core.budget import Budget, TokenPricing
+from coding_agents.core.loop import BoundedExecutionLoop, FlailDetector
+from coding_agents.core.agent import CodingAgent
+
+__all__ = [
+    "StopCondition",
+    "ToolCall",
+    "ToolResult",
+    "TurnRecord",
+    "Trajectory",
+    "Budget",
+    "TokenPricing",
+    "BoundedExecutionLoop",
+    "FlailDetector",
+    "CodingAgent",
+]
+

coding_agents/core/agent.py

@@ -0,0 +1,164 @@
+"""Core CodingAgent reference implementation."""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, List, Optional
+from rich.console import Console
+
+from coding_agents.core.models import StopCondition, ToolCall, ToolResult, TurnRecord, Trajectory
+from coding_agents.core.budget import Budget
+from coding_agents.core.loop import BoundedExecutionLoop, FlailDetector
+from coding_agents.tools.base import BaseTool
+from coding_agents.tools.patch_editor import PatchEditor
+from coding_agents.tools.bash_tool import BashTool
+from coding_agents.sandbox.policy import PolicyGate
+from coding_agents.verification.pipeline import VerificationPipeline
+from coding_agents.verification.oscillation import OscillationDetector
+
+
+class CodingAgent:
+    """The complete 7-component Coding Agent harness."""
+
+    def __init__(
+        self,
+        model: str = "claude-3-7-sonnet",
+        working_dir: str = ".",
+        tools: Optional[List[BaseTool]] = None,
+        budget: Optional[Budget] = None,
+        policy_gate: Optional[PolicyGate] = None,
+        verification_pipeline: Optional[VerificationPipeline] = None,
+        console: Optional[Console] = None,
+    ) -> None:
+        self.model = model
+        self.working_dir = working_dir
+        self.console = console or Console()
+
+        # 1. Tools
+        self.tools: Dict[str, BaseTool] = {}
+        default_tools = tools or [
+            PatchEditor(working_dir=working_dir),
+            BashTool(working_dir=working_dir),
+        ]
+        for tool in default_tools:
+            self.tools[tool.name] = tool
+
+        # 2. Budget & Policy
+        self.budget = budget or Budget(max_turns=30, max_cost_usd=5.0)
+        self.policy_gate = policy_gate or PolicyGate()
+
+        # 3. Verification & Oscillation
+        self.verification_pipeline = verification_pipeline or VerificationPipeline(working_dir=working_dir)
+        self.oscillation_detector = OscillationDetector()
+
+        # 4. Control Loop
+        self.loop = BoundedExecutionLoop(
+            budget=self.budget,
+            flail_detector=FlailDetector(),
+            verification_oracle=self._run_ground_truth_verification,
+        )
+
+    def _run_ground_truth_verification(self) -> bool:
+        """Run verification pipeline to evaluate ground truth correctness."""
+        manifest = self.verification_pipeline.run_all(target_dir=self.working_dir)
+        return manifest.all_passed
+
+    def dispatch_tool(self, call: ToolCall) -> ToolResult:
+        """Enforce policy gate and dispatch to the matching tool."""
+        # 1. Policy check
+        if call.name == "bash":
+            cmd = call.arguments.get("command", "")
+            allowed, reason = self.policy_gate.check_command(cmd)
+            if not allowed:
+                return ToolResult(
+                    tool_call_id=call.id,
+                    name=call.name,
+                    output="",
+                    error=reason,
+                    exit_code=1,
+                )
+        elif call.name == "edit_file_exact":
+            path = call.arguments.get("path", "")
+            allowed, reason = self.policy_gate.check_file_mutation(path)
+            if not allowed:
+                return ToolResult(
+                    tool_call_id=call.id,
+                    name=call.name,
+                    output="",
+                    error=reason,
+                    exit_code=1,
+                )
+
+        # 2. Tool dispatch
+        tool = self.tools.get(call.name)
+        if not tool:
+            return ToolResult(
+                tool_call_id=call.id,
+                name=call.name,
+                output="",
+                error=f"Unknown tool: '{call.name}'",
+                exit_code=1,
+            )
+
+        try:
+            res = tool.execute(**call.arguments)
+            res.tool_call_id = call.id
+            return res
+        except Exception as e:
+            return ToolResult(
+                tool_call_id=call.id,
+                name=call.name,
+                output="",
+                error=f"Exception executing {call.name}: {str(e)}",
+                exit_code=1,
+            )
+
+    def run(
+        self,
+        task_description: str,
+        proposer_callback: Optional[Callable[[List[Dict[str, Any]]], List[ToolCall]]] = None,
+    ) -> Trajectory:
+        """Execute the agent loop until a deterministic stop condition is reached."""
+        trajectory = Trajectory(
+            task_id="task-001",
+            task_description=task_description,
+            final_status=StopCondition.BUDGET,
+        )
+
+        turn_idx = 0
+        while True:
+            # Check budget before turn
+            stop_reason = self.loop.evaluate_stop(calls=[])
+            if stop_reason:
+                trajectory.final_status = stop_reason
+                break
+
+            # If no custom proposer is provided, run mock or single turn
+            calls = proposer_callback([]) if proposer_callback else []
+
+            # Check stop condition with proposed calls
+            stop_reason = self.loop.evaluate_stop(calls=calls)
+            if stop_reason:
+                trajectory.final_status = stop_reason
+                break
+
+            # Execute calls and record turn
+            turn_results = [self.dispatch_tool(c) for c in calls]
+            turn = TurnRecord(
+                turn_index=turn_idx,
+                tool_calls=calls,
+                tool_results=turn_results,
+            )
+            trajectory.turns.append(turn)
+
+            # In simulation, break after 1 turn if no calls
+            if not calls:
+                trajectory.final_status = StopCondition.DONE if self._run_ground_truth_verification() else StopCondition.ESCALATE
+                break
+
+            turn_idx += 1
+
+        trajectory.total_cost_usd = self.budget.used_cost_usd
+        trajectory.total_tokens = self.budget.total_tokens
+        trajectory.success = (trajectory.final_status == StopCondition.DONE)
+        return trajectory
+

coding_agents/core/budget.py

@@ -0,0 +1,75 @@
+"""Budget tracking and cost modeling for agent execution loops."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Dict, Optional
+
+
+@dataclass
+class TokenPricing:
+    """Pricing per million tokens in USD."""
+    prompt_per_million: float = 3.00
+    completion_per_million: float = 15.00
+
+
+# Reference pricing for standard frontier models
+MODEL_PRICING: Dict[str, TokenPricing] = {
+    "claude-3-7-sonnet": TokenPricing(prompt_per_million=3.0, completion_per_million=15.0),
+    "claude-3-5-sonnet": TokenPricing(prompt_per_million=3.0, completion_per_million=15.0),
+    "gpt-4o": TokenPricing(prompt_per_million=2.5, completion_per_million=10.0),
+    "deepseek-r1": TokenPricing(prompt_per_million=0.55, completion_per_million=2.19),
+}
+
+
+@dataclass
+class Budget:
+    """Resource budget manager enforcing hard resource ceilings."""
+    max_turns: int = 30
+    max_tokens: int = 200_000
+    max_cost_usd: float = 5.00
+    max_wall_time_seconds: float = 600.0
+
+    used_turns: int = 0
+    used_prompt_tokens: int = 0
+    used_completion_tokens: int = 0
+    used_cost_usd: float = 0.0
+    elapsed_seconds: float = 0.0
+
+    pricing: TokenPricing = field(default_factory=TokenPricing)
+
+    def charge(self, prompt_tokens: int, completion_tokens: int, model: Optional[str] = None) -> float:
+        """Record token consumption and update cumulative monetary spend."""
+        self.used_turns += 1
+        self.used_prompt_tokens += prompt_tokens
+        self.used_completion_tokens += completion_tokens
+
+        pricing = MODEL_PRICING.get(model or "", self.pricing)
+        turn_cost = (
+            (prompt_tokens / 1_000_000.0) * pricing.prompt_per_million
+            + (completion_tokens / 1_000_000.0) * pricing.completion_per_million
+        )
+        self.used_cost_usd += turn_cost
+        return turn_cost
+
+    @property
+    def total_tokens(self) -> int:
+        return self.used_prompt_tokens + self.used_completion_tokens
+
+    def exhausted(self) -> bool:
+        """Check whether any hard budget limit has been reached."""
+        if self.used_turns >= self.max_turns:
+            return True
+        if self.total_tokens >= self.max_tokens:
+            return True
+        if self.used_cost_usd >= self.max_cost_usd:
+            return True
+        return False
+
+    def remaining_summary(self) -> str:
+        return (
+            f"Turns: {self.used_turns}/{self.max_turns} | "
+            f"Tokens: {self.total_tokens:,}/{self.max_tokens:,} | "
+            f"Cost: ${self.used_cost_usd:.3f}/${self.max_cost_usd:.2f}"
+        )
+

coding_agents/core/loop.py

@@ -0,0 +1,76 @@
+"""Bounded execution loop and oscillation detection for coding agents."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Callable, List, Optional, Set, Tuple
+from coding_agents.core.models import StopCondition, ToolCall, ToolResult, TurnRecord
+from coding_agents.core.budget import Budget
+
+
+class FlailDetector:
+    """Detects cyclic repetition and unproductive action loops."""
+
+    def __init__(self, history_window: int = 10) -> None:
+        self.history_window = history_window
+        self.seen_signatures: Set[str] = set()
+        self.signature_history: List[str] = []
+
+    def fingerprint_calls(self, calls: List[ToolCall]) -> str:
+        """Compute deterministic canonical hash of tool proposals."""
+        serialized = []
+        for call in sorted(calls, key=lambda c: (c.name, c.id)):
+            serialized.append({
+                "name": call.name,
+                "arguments": call.arguments,
+            })
+        raw = json.dumps(serialized, sort_keys=True)
+        return hashlib.sha256(raw.encode("utf-8")).hexdigest()
+
+    def check_and_record(self, calls: List[ToolCall]) -> bool:
+        """Return True if identical tool proposal was seen previously."""
+        if not calls:
+            return False
+        sig = self.fingerprint_calls(calls)
+        if sig in self.seen_signatures:
+            return True
+        self.seen_signatures.add(sig)
+        self.signature_history.append(sig)
+        return False
+
+
+class BoundedExecutionLoop:
+    """The control loop that coordinates turns, charges budgets, and enforces termination."""
+
+    def __init__(
+        self,
+        budget: Optional[Budget] = None,
+        flail_detector: Optional[FlailDetector] = None,
+        verification_oracle: Optional[Callable[[], bool]] = None,
+    ) -> None:
+        self.budget = budget or Budget()
+        self.flail_detector = flail_detector or FlailDetector()
+        self.verification_oracle = verification_oracle
+
+    def evaluate_stop(
+        self,
+        calls: List[ToolCall],
+        explicit_done_called: bool = False,
+    ) -> Optional[StopCondition]:
+        """Check termination invariants at the start/end of each turn."""
+        if self.budget.exhausted():
+            return StopCondition.BUDGET
+
+        if self.flail_detector.check_and_record(calls):
+            return StopCondition.STUCK
+
+        if explicit_done_called or not calls:
+            # Model proposed it is finished; verify with ground truth oracle
+            if self.verification_oracle is not None:
+                passed = self.verification_oracle()
+                return StopCondition.DONE if passed else StopCondition.ESCALATE
+            return StopCondition.DONE
+
+        return None
+

coding_agents/core/models.py

@@ -0,0 +1,55 @@
+"""Data models representing agent states, tool calls, and trajectories."""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any, Dict, List, Optional
+from pydantic import BaseModel, Field
+
+
+class StopCondition(str, Enum):
+    """The four deterministic ways an agent execution loop terminates."""
+    DONE = "verified_complete"       # External verification oracle passed
+    BUDGET = "budget_exhausted"      # Token/turn/cost budget exhausted
+    STUCK = "oscillation_detected"  # No progress / repeated state detected
+    ESCALATE = "needs_escalation"    # Policy denial or ambiguous invariant
+
+
+class ToolCall(BaseModel):
+    """A structured tool call proposal from the model."""
+    id: str = Field(default="", description="Unique tool invocation ID")
+    name: str = Field(description="Name of the tool being called")
+    arguments: Dict[str, Any] = Field(default_factory=dict, description="Parsed tool input parameters")
+
+
+class ToolResult(BaseModel):
+    """The observation returned from tool execution in the environment."""
+    tool_call_id: str = Field(default="", description="ID of the matching tool call")
+    name: str = Field(description="Name of the tool that executed")
+    output: str = Field(description="Stdout or formatted result text")
+    error: Optional[str] = Field(default=None, description="Stderr or exception message if failed")
+    exit_code: int = Field(default=0, description="Process exit code (0 for success)")
+    truncated: bool = Field(default=False, description="Whether output was truncated to fit context budget")
+
+
+class TurnRecord(BaseModel):
+    """A single turn in the agent execution loop."""
+    turn_index: int = Field(description="0-indexed turn counter")
+    thought: Optional[str] = Field(default=None, description="CoT reasoning trace if available")
+    tool_calls: List[ToolCall] = Field(default_factory=list, description="Tool proposals made in this turn")
+    tool_results: List[ToolResult] = Field(default_factory=list, description="Observations received from environment")
+    prompt_tokens: int = Field(default=0, description="Prompt tokens consumed")
+    completion_tokens: int = Field(default=0, description="Completion tokens consumed")
+    cost_usd: float = Field(default=0.0, description="Monetary cost of this turn")
+
+
+class Trajectory(BaseModel):
+    """Complete execution history of an agent task."""
+    task_id: str = Field(description="Unique task or issue identifier")
+    task_description: str = Field(description="User prompt or task specification")
+    turns: List[TurnRecord] = Field(default_factory=list, description="Ordered turn records")
+    final_status: StopCondition = Field(description="Termination reason")
+    success: bool = Field(default=False, description="Whether verified ground truth succeeded")
+    total_cost_usd: float = Field(default=0.0, description="Cumulative monetary spend")
+    total_tokens: int = Field(default=0, description="Cumulative tokens burned")
+

coding_agents/evolution/parallel_planner.py

@@ -0,0 +1,67 @@
+"""SPRINT: Interleaved Parallel Planning and DAG Execution Engine."""
+
+from __future__ import annotations
+
+import collections
+from typing import Callable, Dict, List, Optional, Set
+from pydantic import BaseModel, Field
+
+
+class PlanNode(BaseModel):
+    node_id: str
+    action_type: str
+    description: str
+    dependencies: List[str] = Field(default_factory=list)
+    completed: bool = False
+    result: Optional[str] = None
+
+
+class ExecutionTier(BaseModel):
+    tier_index: int
+    parallel_nodes: List[PlanNode] = Field(default_factory=list)
+
+
+class ParallelPlanningEngine:
+    """Computes topological execution tiers to run independent actions concurrently."""
+
+    def __init__(self) -> None:
+        self.nodes: Dict[str, PlanNode] = {}
+
+    def add_node(self, node_id: str, action_type: str, description: str, dependencies: Optional[List[str]] = None) -> None:
+        self.nodes[node_id] = PlanNode(
+            node_id=node_id,
+            action_type=action_type,
+            description=description,
+            dependencies=dependencies or [],
+        )
+
+    def compute_tiers(self) -> List[ExecutionTier]:
+        """Group plan nodes into non-conflicting parallel execution tiers."""
+        in_degree: Dict[str, int] = {nid: 0 for nid in self.nodes}
+        graph: Dict[str, List[str]] = collections.defaultdict(list)
+
+        for nid, node in self.nodes.items():
+            for dep in node.dependencies:
+                graph[dep].append(nid)
+                in_degree[nid] += 1
+
+        queue = collections.deque([nid for nid, deg in in_degree.items() if deg == 0])
+        tiers: List[ExecutionTier] = []
+        current_tier = 0
+
+        while queue:
+            level_size = len(queue)
+            tier_nodes: List[PlanNode] = []
+            for _ in range(level_size):
+                curr = queue.popleft()
+                tier_nodes.append(self.nodes[curr])
+                for neighbor in graph[curr]:
+                    in_degree[neighbor] -= 1
+                    if in_degree[neighbor] == 0:
+                        queue.append(neighbor)
+
+            tiers.append(ExecutionTier(tier_index=current_tier, parallel_nodes=tier_nodes))
+            current_tier += 1
+
+        return tiers
+