terminal-agent-cli 0.1.0__py3-none-any.whl

terminal_agent/__init__.py

@@ -0,0 +1,7 @@
+"""
+Terminal Agent - Build. Verify. Ship.
+Autonomous terminal-based coding agent designed around verifiable software changes.
+"""
+
+__version__ = "0.1.0"
+

terminal_agent/__main__.py

@@ -0,0 +1,7 @@
+"""Package main entrypoint."""
+
+from terminal_agent.cli.main import cli
+
+if __name__ == "__main__":
+    cli()
+

terminal_agent/agent/__init__.py

@@ -0,0 +1,9 @@
+"""Agent package for Terminal Agent."""
+
+from terminal_agent.agent.loop import AgentLoop, SYSTEM_PROMPT
+
+__all__ = [
+    "AgentLoop",
+    "SYSTEM_PROMPT",
+]
+

terminal_agent/agent/loop.py

@@ -0,0 +1,338 @@
+"""Core bounded autonomous agent loop: Observe -> Plan -> Act -> Verify -> Repair -> Verify."""
+
+import time
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional
+
+from terminal_agent.checkpoints.manager import CheckpointManager
+from terminal_agent.config.schema import TerminalAgentConfig
+from terminal_agent.context.engine import RepositoryContextEngine
+from terminal_agent.git.adapter import GitAdapter
+from terminal_agent.planner.contract import TaskContractGenerator
+from terminal_agent.planner.planner import ExecutionPlanner
+from terminal_agent.providers.base import LLMMessage, LLMResponse, LLMToolCall, ModelProvider
+from terminal_agent.recovery.classifier import FailureClassifier
+from terminal_agent.recovery.strategies import RecoveryEngine
+from terminal_agent.session.manager import SessionManager
+from terminal_agent.session.models import (
+    FailureCategory,
+    PlanItem,
+    SessionState,
+    StepAction,
+    TaskContract,
+    VerificationResult,
+    VerificationStatus,
+)
+from terminal_agent.telemetry.events import TelemetryLogger
+from terminal_agent.telemetry.metrics import MetricsCollector
+from terminal_agent.tools.registry import ToolRegistry
+from terminal_agent.verifier.engine import IndependentVerifier
+
+
+SYSTEM_PROMPT = """You are TERMINAL AGENT, an autonomous verify-first terminal coding agent.
+Tagline: Build. Verify. Ship.
+
+CORE PRINCIPLE:
+You do NOT simply modify code and claim completion.
+A task is only complete when independently verified by running tests, validating contract assertions, and inspecting git diffs.
+
+RULES:
+1. Every tool call MUST include a clear, concise 'reason' explaining what you are doing and why.
+2. Read and analyze files before making changes.
+3. Keep changes minimal and focused directly on the user's task contract.
+4. When you believe your changes are in place, run verification tests.
+5. If tests fail, analyze the error trace, determine root cause, and apply targeted repairs.
+6. Never modify test files unless the user explicitly requested test changes.
+"""
+
+
+class AgentLoop:
+    """Orchestrates the autonomous verify-first coding cycle."""
+
+    def __init__(
+        self,
+        session_state: SessionState,
+        config: TerminalAgentConfig,
+        provider: ModelProvider,
+        tool_registry: ToolRegistry,
+        verifier: IndependentVerifier,
+        context_engine: RepositoryContextEngine,
+        checkpoint_manager: CheckpointManager,
+        session_manager: SessionManager,
+        telemetry_logger: TelemetryLogger,
+        step_callback: Optional[Callable[[str, Any], None]] = None
+    ):
+        self.state = session_state
+        self.config = config
+        self.provider = provider
+        self.tools = tool_registry
+        self.verifier = verifier
+        self.context = context_engine
+        self.checkpoints = checkpoint_manager
+        self.session_mgr = session_manager
+        self.telemetry = telemetry_logger
+        self.step_callback = step_callback or (lambda event, data: None)
+        self.start_time = time.time()
+
+    def _notify(self, event_type: str, data: Any = None) -> None:
+        """Send UI update notification."""
+        try:
+            self.step_callback(event_type, data)
+        except Exception:
+            pass
+
+    def run(self) -> SessionState:
+        """Execute the bounded autonomous loop."""
+        self._notify("start", self.state)
+
+        # 1. OBSERVE & INITIALIZE CONTRACT
+        if not self.state.contract:
+            self._notify("observe_start", "Inspecting repository...")
+            contract = TaskContractGenerator.generate_from_description(
+                task_description=self.state.task_description,
+                verification_commands=self.config.verification.tests
+            )
+            self.state.contract = contract
+            self.state.plan = ExecutionPlanner.create_initial_plan(contract)
+            self.session_mgr.save_session(self.state)
+            self._notify("contract_ready", contract)
+
+        # 2. CREATE BASELINE CHECKPOINT
+        if not self.state.checkpoints:
+            self._notify("checkpoint_creating", "Creating baseline checkpoint...")
+            baseline_chk = self.checkpoints.create_checkpoint(name="baseline_before_changes")
+            self.state.checkpoints.append(baseline_chk)
+            self.session_mgr.save_session(self.state)
+            self._notify("checkpoint_created", baseline_chk)
+
+        # 3. BUILD INITIAL CONTEXT & MESSAGES
+        repo_context = self.context.build_initial_context(
+            task_description=self.state.task_description,
+            contract=self.state.contract
+        )
+
+        messages: List[LLMMessage] = [
+            LLMMessage(role="system", content=SYSTEM_PROMPT),
+            LLMMessage(
+                role="user",
+                content=(
+                    f"TASK CONTRACT:\n"
+                    f"Goal: {self.state.contract.goal}\n"
+                    f"Constraints:\n" + "\n".join(f"- {c}" for c in self.state.contract.constraints) + "\n\n"
+                    f"Success Criteria:\n" + "\n".join(f"- {sc}" for sc in self.state.contract.success_criteria) + "\n\n"
+                    f"REPOSITORY CONTEXT:\n{repo_context}\n\n"
+                    f"Please begin by inspecting the relevant code and formulating your changes."
+                )
+            )
+        ]
+
+        # Replay completed steps if resuming
+        for past_step in self.state.completed_steps:
+            if past_step.tool_name:
+                messages.append(
+                    LLMMessage(
+                        role="assistant",
+                        tool_calls=[
+                            LLMToolCall(
+                                id=f"call_{past_step.step_number}",
+                                name=past_step.tool_name,
+                                arguments=past_step.tool_args or {}
+                            )
+                        ]
+                    )
+                )
+                messages.append(
+                    LLMMessage(
+                        role="tool",
+                        name=past_step.tool_name,
+                        tool_call_id=f"call_{past_step.step_number}",
+                        content=past_step.output or ""
+                    )
+                )
+
+        step_count = len(self.state.completed_steps)
+        retry_count = len(self.state.failures)
+        max_steps = self.config.agent.max_steps
+        max_retries = self.config.agent.max_retries
+        timeout_sec = self.config.agent.timeout_seconds
+
+        # 4. BOUNDED AGENT LOOP
+        while step_count < max_steps:
+            # Check overall timeout
+            elapsed = time.time() - self.start_time
+            if elapsed > timeout_sec:
+                self.state.current_status = VerificationStatus.FAILED
+                self.session_mgr.record_step(
+                    self.state,
+                    action_type="timeout",
+                    reason=f"Task timed out after {elapsed:.1f} seconds.",
+                    status="error"
+                )
+                self._notify("timeout", f"Execution exceeded {timeout_sec}s limit.")
+                break
+
+            step_count += 1
+            self.state.next_step = f"Executing step {step_count}..."
+            self._notify("step_start", {"step": step_count, "retries": retry_count})
+
+            # Query Model Provider
+            tool_schemas = self.tools.get_schemas()
+            try:
+                response: LLMResponse = self.provider.generate(
+                    messages=messages,
+                    tools=tool_schemas,
+                    temperature=self.config.provider.temperature
+                )
+            except Exception as e:
+                self.session_mgr.record_step(
+                    self.state,
+                    action_type="provider_error",
+                    reason=f"Model provider error: {e}",
+                    status="error"
+                )
+                self._notify("error", f"Model provider failed: {e}")
+                break
+
+            # Handle model message and tool calls
+            if response.content:
+                self._notify("agent_thought", response.content)
+
+            if not response.tool_calls:
+                # Model stopped or claims completion without tool calls -> Trigger Independent Verification
+                self._notify("verification_triggered", "Model requested verification / completed actions.")
+                v_result = self.verifier.verify(contract=self.state.contract)
+                self.session_mgr.record_verification(self.state, v_result)
+                self._notify("verification_result", v_result)
+
+                if v_result.status == VerificationStatus.VERIFIED:
+                    self._finalize_success(v_result)
+                    break
+                else:
+                    # Verification failed -> enter repair logic
+                    retry_count += 1
+                    if retry_count > max_retries:
+                        self.state.current_status = VerificationStatus.FAILED
+                        self._notify("max_retries_exceeded", f"Failed verification after {max_retries} repair retries.")
+                        break
+
+                    # Classify failure & formulate repair
+                    cat, cat_reason = FailureClassifier.classify(v_result.test_output)
+                    hypothesis, repair_action = RecoveryEngine.analyze_and_plan_recovery(cat, v_result.test_output, self.state)
+                    failure_record = self.session_mgr.record_failure(
+                        self.state,
+                        category=cat,
+                        raw_output=v_result.test_output,
+                        root_cause_hypothesis=hypothesis,
+                        recovery_action=repair_action
+                    )
+                    self._notify("repair_plan", failure_record)
+
+                    # Append failure diagnostics to conversation
+                    messages.append(
+                        LLMMessage(
+                            role="user",
+                            content=(
+                                f"INDEPENDENT VERIFICATION FAILED (Status: {v_result.status.value})\n"
+                                f"Test Failures: {v_result.tests_failed}/{v_result.tests_run}\n"
+                                f"Primary Failure Category: {cat.value}\n"
+                                f"Root Cause Hypothesis: {hypothesis}\n"
+                                f"Recommended Repair: {repair_action}\n\n"
+                                f"Test Output Trace:\n{v_result.test_output[-2000:]}\n\n"
+                                f"Please repair the issue in the target files and re-test."
+                            )
+                        )
+                    )
+                    continue
+
+            # Execute tool calls
+            for tc in response.tool_calls:
+                tool_name = tc.name
+                tool_args = tc.arguments or {}
+                reason = str(tool_args.get("reason", response.content or "Executing tool action"))
+
+                self._notify("tool_executing", {"tool": tool_name, "args": tool_args, "reason": reason})
+
+                tool_result = self.tools.execute(tool_name, tool_args, reason=reason)
+                
+                # Track modified files
+                if tool_name in ("write_file", "edit_file") and tool_result.success:
+                    p = tool_args.get("path")
+                    if p and p not in self.state.modified_files:
+                        self.state.modified_files.append(p)
+
+                # Record step and telemetry
+                self.session_mgr.record_step(
+                    self.state,
+                    action_type="tool_call",
+                    tool_name=tool_name,
+                    tool_args=tool_args,
+                    reason=reason,
+                    output=tool_result.output if tool_result.success else tool_result.error,
+                    status="success" if tool_result.success else "error",
+                    duration_ms=tool_result.duration_ms
+                )
+
+                self.telemetry.log_event(
+                    step=step_count,
+                    event_type="tool_call",
+                    tool=tool_name,
+                    reason=reason,
+                    duration_ms=tool_result.duration_ms,
+                    status="success" if tool_result.success else "error",
+                    data=tool_args
+                )
+
+                self._notify("tool_completed", tool_result)
+
+                # Append tool exchange to LLM history
+                messages.append(
+                    LLMMessage(
+                        role="assistant",
+                        tool_calls=[tc]
+                    )
+                )
+                messages.append(
+                    LLMMessage(
+                        role="tool",
+                        name=tool_name,
+                        tool_call_id=tc.id,
+                        content=tool_result.output if tool_result.success else f"ERROR: {tool_result.error}"
+                    )
+                )
+
+        # End of loop: update final metrics
+        MetricsCollector.calculate_metrics(self.state)
+        self.session_mgr.save_session(self.state)
+        self._notify("finish", self.state)
+        return self.state
+
+    def _finalize_success(self, v_result: VerificationResult) -> None:
+        """Mark session as VERIFIED and synthesize final Proof of Done."""
+        self.state.current_status = VerificationStatus.VERIFIED
+        diff_stats = self.verifier.git_adapter.get_diff_stats()
+        
+        # Build structured Proof of Done
+        pod = {
+            "session_id": self.state.session_id,
+            "task": self.state.task_description,
+            "result": "VERIFIED ✓",
+            "tests_passed": f"{v_result.tests_passed}/{v_result.tests_run}",
+            "lint": "PASS" if v_result.lint_passed else "FAIL",
+            "files_changed_count": len(self.state.modified_files),
+            "files_changed": self.state.modified_files,
+            "unintended_files_count": v_result.unintended_files_count,
+            "retries_count": len(self.state.failures),
+            "git_diff_reviewed": True,
+            "success_criteria_passed": f"{sum(1 for a in v_result.assertions if a.passed)}/{len(v_result.assertions)}",
+            "summary": {
+                "what_changed": f"Modified files: {', '.join(self.state.modified_files) if self.state.modified_files else 'None'}",
+                "why_it_changed": self.state.contract.goal if self.state.contract else "Fulfilled task requirements",
+                "what_was_verified": f"Independent test suite ({v_result.tests_passed} tests passed)",
+                "remaining_limitations": "None detected under verified test suite."
+            }
+        }
+        self.state.proof_of_done = pod
+        self.session_mgr.save_session(self.state)
+        self._notify("proof_of_done", pod)
+

terminal_agent/checkpoints/__init__.py

@@ -0,0 +1,9 @@
+"""Checkpoints package for Terminal Agent."""
+
+from terminal_agent.checkpoints.manager import CheckpointManager, get_checkpoints_dir
+
+__all__ = [
+    "CheckpointManager",
+    "get_checkpoints_dir",
+]
+

terminal_agent/checkpoints/manager.py

@@ -0,0 +1,151 @@
+"""Checkpoint manager for creating and restoring repository and session snapshots."""
+
+import json
+import os
+import shutil
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Dict, List, Optional
+
+from terminal_agent.git.adapter import GitAdapter
+from terminal_agent.session.models import CheckpointSnapshot
+
+
+def get_checkpoints_dir(working_dir: Optional[Path] = None) -> Path:
+    """Return .terminal_agent/checkpoints directory."""
+    base = working_dir or Path.cwd()
+    c_dir = base / ".terminal_agent" / "checkpoints"
+    c_dir.mkdir(parents=True, exist_ok=True)
+    return c_dir
+
+
+class CheckpointManager:
+    """Creates, lists, and restores filesystem snapshots."""
+
+    def __init__(self, working_dir: Optional[Path] = None):
+        self.working_dir = (working_dir or Path.cwd()).resolve()
+        self.checkpoints_dir = get_checkpoints_dir(self.working_dir)
+        self.git_adapter = GitAdapter(self.working_dir)
+
+    def create_checkpoint(
+        self,
+        name: str,
+        step_number: int = 0,
+        target_files: Optional[List[str]] = None
+    ) -> CheckpointSnapshot:
+        """Create a checkpoint snapshot of the repository."""
+        now = datetime.now(timezone.utc)
+        chk_id = f"chk_{now.strftime('%Y%m%d_%H%M%S')}_{uuid.uuid4().hex[:4]}"
+        chk_dir = self.checkpoints_dir / chk_id
+        chk_dir.mkdir(parents=True, exist_ok=True)
+        files_store_dir = chk_dir / "files"
+        files_store_dir.mkdir(parents=True, exist_ok=True)
+        git_commit = self.git_adapter.get_head_commit()
+        files_to_save: List[Path] = []
+        if target_files:
+            for f in target_files:
+                p = (self.working_dir / f).resolve()
+                if p.exists() and p.is_file():
+                    files_to_save.append(p)
+        else:
+            for root, dirs, files in os.walk(self.working_dir):
+                dirs[:] = [d for d in dirs if d not in (".git", ".terminal_agent", ".venv", "venv", "__pycache__", "node_modules", "dist", "build", ".pytest_cache")]
+                for f in files:
+                    full_p = Path(root) / f
+                    if not full_p.name.startswith(".env") and not full_p.name.endswith((".key", ".pem")):
+                        files_to_save.append(full_p)
+        file_contents: Dict[str, str] = {}
+        modified_rel_paths: List[str] = []
+        for p in files_to_save:
+            try:
+                rel_p = str(p.relative_to(self.working_dir)).replace("\\", "/")
+                dest = files_store_dir / rel_p
+                dest.parent.mkdir(parents=True, exist_ok=True)
+                shutil.copy2(p, dest)
+                try:
+                    content = p.read_text(encoding="utf-8", errors="ignore")
+                    if len(content) < 500000:
+                        file_contents[rel_p] = content
+                except Exception:
+                    pass
+                modified_rel_paths.append(rel_p)
+            except Exception:
+                continue
+        snapshot = CheckpointSnapshot(
+            checkpoint_id=chk_id,
+            name=name,
+            created_at=now.isoformat(),
+            step_number=step_number,
+            git_commit=git_commit,
+            modified_files=modified_rel_paths,
+            file_contents=file_contents
+        )
+        metadata_file = chk_dir / "metadata.json"
+        metadata_file.write_text(snapshot.model_dump_json(indent=2), encoding="utf-8")
+        return snapshot
+
+    def list_checkpoints(self) -> List[CheckpointSnapshot]:
+        """List all available checkpoints ordered by most recent."""
+        checkpoints = []
+        if not self.checkpoints_dir.exists():
+            return checkpoints
+        for d in sorted(self.checkpoints_dir.iterdir(), key=os.path.getmtime, reverse=True):
+            if d.is_dir():
+                meta_file = d / "metadata.json"
+                if meta_file.exists():
+                    try:
+                        data = json.loads(meta_file.read_text(encoding="utf-8"))
+                        checkpoints.append(CheckpointSnapshot.model_validate(data))
+                    except Exception:
+                        continue
+        return checkpoints
+
+    def get_checkpoint(self, checkpoint_id: str) -> Optional[CheckpointSnapshot]:
+        """Retrieve checkpoint by ID or name substring."""
+        for chk in self.list_checkpoints():
+            if chk.checkpoint_id == checkpoint_id or checkpoint_id in chk.checkpoint_id or chk.name == checkpoint_id:
+                return chk
+        return None
+
+    def rollback(self, checkpoint_id: str) -> bool:
+        """Restore repository state from a checkpoint."""
+        chk = self.get_checkpoint(checkpoint_id)
+        if not chk:
+            return False
+        chk_dir = self.checkpoints_dir / chk.checkpoint_id
+        files_store_dir = chk_dir / "files"
+        if not files_store_dir.exists():
+            return False
+        for root, _, files in os.walk(files_store_dir):
+            for f in files:
+                src_path = Path(root) / f
+                rel_path = src_path.relative_to(files_store_dir)
+                target_path = self.working_dir / rel_path
+                target_path.parent.mkdir(parents=True, exist_ok=True)
+                shutil.copy2(src_path, target_path)
+        return True
+
+    def prune_checkpoints(self, days: Optional[int] = None) -> List[Path]:
+        """Delete checkpoint directories older than ``days``.
+
+        If ``days`` is None, delete every checkpoint directory. The parent
+        checkpoints directory is left in place. Returns deleted directory paths.
+        """
+        deleted: List[Path] = []
+        if not self.checkpoints_dir.exists():
+            return deleted
+        cutoff = None
+        if days is not None:
+            cutoff = datetime.now(timezone.utc).timestamp() - (days * 86400)
+        for entry in list(self.checkpoints_dir.iterdir()):
+            if not entry.is_dir():
+                continue
+            if cutoff is not None and entry.stat().st_mtime >= cutoff:
+                continue
+            try:
+                shutil.rmtree(entry)
+                deleted.append(entry)
+            except OSError:
+                continue
+        return deleted

terminal_agent/cli/commands/__init__.py

@@ -0,0 +1,26 @@
+"""CLI commands package for Terminal Agent."""
+
+from terminal_agent.cli.commands.run import run_command
+from terminal_agent.cli.commands.resume import resume_command
+from terminal_agent.cli.commands.status import status_command
+from terminal_agent.cli.commands.diff import diff_command
+from terminal_agent.cli.commands.test import test_command
+from terminal_agent.cli.commands.checkpoint import checkpoint_app, rollback_command
+from terminal_agent.cli.commands.doctor import doctor_command
+from terminal_agent.cli.commands.trace import trace_command
+from terminal_agent.cli.commands.config_cmd import config_command
+from terminal_agent.cli.commands.clean import clean_command
+
+__all__ = [
+    "run_command",
+    "resume_command",
+    "status_command",
+    "diff_command",
+    "test_command",
+    "checkpoint_app",
+    "rollback_command",
+    "doctor_command",
+    "trace_command",
+    "config_command",
+    "clean_command",
+]

terminal_agent/cli/commands/checkpoint.py

@@ -0,0 +1,76 @@
+"""CLI checkpoint and rollback commands."""
+
+from pathlib import Path
+from typing import Optional
+import typer
+from rich.table import Table
+
+from terminal_agent.checkpoints.manager import CheckpointManager
+from terminal_agent.cli.theme import SYM_CHECK, SYM_CROSS, console
+from terminal_agent.cli.ui import render_header
+
+checkpoint_app = typer.Typer(help="Manage repository checkpoints.")
+
+
+@checkpoint_app.command("list")
+def list_checkpoints_cmd(
+    working_dir: Optional[Path] = typer.Option(None, "--cwd", "-C", help="Target repository directory"),
+) -> None:
+    """List all available checkpoints for this repository."""
+    render_header()
+    target_dir = (working_dir or Path.cwd()).resolve()
+    mgr = CheckpointManager(target_dir)
+    checkpoints = mgr.list_checkpoints()
+
+    if not checkpoints:
+        console.print("[agent.muted]No checkpoints found for this repository.[/agent.muted]")
+        return
+
+    table = Table(title="[agent.accent]CHECKPOINTS[/agent.accent]", border_style="agent.border")
+    table.add_column("Checkpoint ID", style="agent.accent")
+    table.add_column("Name", style="agent.text")
+    table.add_column("Created At", style="agent.muted")
+    table.add_column("Files", style="agent.muted")
+    table.add_column("Git Commit", style="agent.muted")
+
+    for chk in checkpoints:
+        table.add_row(
+            chk.checkpoint_id,
+            chk.name,
+            chk.created_at[:19].replace("T", " "),
+            str(len(chk.modified_files)),
+            chk.git_commit[:8] if chk.git_commit else "N/A"
+        )
+
+    console.print(table)
+
+
+@checkpoint_app.command("create")
+def create_checkpoint_cmd(
+    name: str = typer.Argument("manual_checkpoint", help="Descriptive checkpoint name"),
+    working_dir: Optional[Path] = typer.Option(None, "--cwd", "-C", help="Target repository directory"),
+) -> None:
+    """Create a new manual checkpoint snapshot."""
+    render_header()
+    target_dir = (working_dir or Path.cwd()).resolve()
+    mgr = CheckpointManager(target_dir)
+    snapshot = mgr.create_checkpoint(name=name)
+    console.print(f"{SYM_CHECK} [agent.success]Created checkpoint '{snapshot.checkpoint_id}' ('{snapshot.name}') with {len(snapshot.modified_files)} files.[/agent.success]")
+
+
+def rollback_command(
+    checkpoint_id: str = typer.Argument(..., help="Checkpoint ID or name to restore"),
+    working_dir: Optional[Path] = typer.Option(None, "--cwd", "-C", help="Target repository directory"),
+) -> None:
+    """Roll back workspace files to a previous checkpoint."""
+    render_header()
+    target_dir = (working_dir or Path.cwd()).resolve()
+    mgr = CheckpointManager(target_dir)
+    success = mgr.rollback(checkpoint_id)
+
+    if success:
+        console.print(f"{SYM_CHECK} [agent.success]Successfully rolled back to checkpoint '{checkpoint_id}'.[/agent.success]")
+    else:
+        console.print(f"{SYM_CROSS} [agent.error]Failed to rollback to checkpoint '{checkpoint_id}'. Checkpoint not found.[/agent.error]")
+        raise typer.Exit(1)
+