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

terminal_agent/cli/commands/clean.py

@@ -0,0 +1,170 @@
+"""CLI clean command to prune old sessions, checkpoints, and telemetry."""
+
+from __future__ import annotations
+
+import os
+import shutil
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import List, Optional, Tuple
+
+import typer
+from rich.table import Table
+
+from terminal_agent.checkpoints.manager import CheckpointManager
+from terminal_agent.cli.theme import console
+from terminal_agent.cli.ui import render_header
+from terminal_agent.session.manager import SessionManager
+
+
+def _dir_size_bytes(path: Path) -> int:
+    total = 0
+    if not path.exists():
+        return 0
+    if path.is_file():
+        return path.stat().st_size
+    for root, _, files in os.walk(path):
+        for name in files:
+            fp = Path(root) / name
+            try:
+                total += fp.stat().st_size
+            except OSError:
+                continue
+    return total
+
+
+def _format_mb(num_bytes: int) -> str:
+    return f"{num_bytes / (1024 * 1024):.2f} MB"
+
+
+def _is_older_than(path: Path, cutoff_ts: Optional[float]) -> bool:
+    if cutoff_ts is None:
+        return True
+    try:
+        return path.stat().st_mtime < cutoff_ts
+    except OSError:
+        return False
+
+
+def collect_clean_targets(
+    working_dir: Path,
+    days: Optional[int],
+    purge_all: bool,
+) -> List[Tuple[str, Path, int]]:
+    """Return (kind, path, size_bytes) items that would be removed."""
+    cutoff = None
+    if not purge_all:
+        age = days if days is not None else 7
+        cutoff = (datetime.now(timezone.utc) - timedelta(days=age)).timestamp()
+
+    root = working_dir / ".terminal_agent"
+    targets: List[Tuple[str, Path, int]] = []
+
+    sessions_dir = root / "sessions"
+    if sessions_dir.exists():
+        for json_file in sessions_dir.glob("*.json"):
+            if _is_older_than(json_file, cutoff):
+                targets.append(("session", json_file, _dir_size_bytes(json_file)))
+
+    checkpoints_dir = root / "checkpoints"
+    if checkpoints_dir.exists():
+        for entry in checkpoints_dir.iterdir():
+            if entry.is_dir() and _is_older_than(entry, cutoff):
+                targets.append(("checkpoint", entry, _dir_size_bytes(entry)))
+
+    for kind in ("telemetry", "traces"):
+        tdir = root / kind
+        if not tdir.exists():
+            continue
+        for entry in tdir.iterdir():
+            if entry.is_file() and _is_older_than(entry, cutoff):
+                targets.append((kind.rstrip("s"), entry, _dir_size_bytes(entry)))
+            elif entry.is_dir() and _is_older_than(entry, cutoff):
+                targets.append((kind.rstrip("s"), entry, _dir_size_bytes(entry)))
+
+    return targets
+
+
+def apply_deletes(working_dir: Path, days: Optional[int], purge_all: bool) -> List[Path]:
+    """Delete matching artifacts. Uses manager helpers for sessions/checkpoints."""
+    age = None if purge_all else (days if days is not None else 7)
+    SessionManager(working_dir).delete_sessions_older_than(age)
+    CheckpointManager(working_dir).prune_checkpoints(age)
+
+    deleted: List[Path] = []
+    for kind, path, _size in collect_clean_targets(working_dir, days=days, purge_all=purge_all):
+        if kind in ("session", "checkpoint"):
+            deleted.append(path)
+            continue
+        try:
+            if path.is_dir():
+                shutil.rmtree(path)
+            elif path.exists():
+                path.unlink()
+            deleted.append(path)
+        except OSError:
+            continue
+    return deleted
+
+
+def clean_command(
+    all_data: bool = typer.Option(
+        False,
+        "--all",
+        help="Purge all sessions, checkpoints, and telemetry logs.",
+    ),
+    days: int = typer.Option(
+        7,
+        "--days",
+        help="Purge items older than N days (ignored when --all is set).",
+    ),
+    dry_run: bool = typer.Option(
+        False,
+        "--dry-run",
+        help="Show files and disk space that would be freed without deleting.",
+    ),
+    working_dir: Optional[Path] = typer.Option(
+        None,
+        "--cwd",
+        "-C",
+        help="Target repository directory",
+    ),
+) -> None:
+    """Prune old session, checkpoint, and telemetry artifacts."""
+    render_header()
+    target_dir = (working_dir or Path.cwd()).resolve()
+    root = target_dir / ".terminal_agent"
+
+    if not root.exists():
+        console.print("[agent.muted]No .terminal_agent directory found. Nothing to clean.[/agent.muted]")
+        raise typer.Exit(0)
+
+    targets = collect_clean_targets(target_dir, days=days, purge_all=all_data)
+    total_bytes = sum(size for _, _, size in targets)
+
+    if not targets:
+        console.print("[agent.muted]No session, checkpoint, or telemetry files to clean.[/agent.muted]")
+        raise typer.Exit(0)
+
+    table = Table(title="[bold agent.accent]CLEAN TARGETS[/bold agent.accent]", border_style="agent.border")
+    table.add_column("Kind", style="agent.text")
+    table.add_column("Path", style="agent.muted")
+    table.add_column("Size", justify="right")
+    for kind, path, size in targets:
+        try:
+            rel = path.relative_to(target_dir)
+        except ValueError:
+            rel = path
+        table.add_row(kind, str(rel), _format_mb(size))
+    console.print(table)
+    console.print(
+        f"[agent.accent]{len(targets)} item(s)[/agent.accent] — "
+        f"[agent.success]{_format_mb(total_bytes)}[/agent.success] would be freed."
+    )
+
+    if dry_run:
+        console.print("[agent.muted]Dry run: no files were deleted.[/agent.muted]")
+        return
+
+    apply_deletes(target_dir, days=days, purge_all=all_data)
+    console.print("[agent.success]Cleanup complete. Directory structure preserved.[/agent.success]")

terminal_agent/cli/commands/config_cmd.py

@@ -0,0 +1,32 @@
+"""CLI config command viewing and generating configuration templates."""
+
+from pathlib import Path
+from typing import Optional
+import typer
+import yaml
+from rich.syntax import Syntax
+
+from terminal_agent.cli.theme import SYM_CHECK, console
+from terminal_agent.cli.ui import render_header
+from terminal_agent.config.settings import load_config, save_default_config
+
+
+def config_command(
+    init: bool = typer.Option(False, "--init", "-i", help="Generate default terminal-agent.config.yaml file"),
+    working_dir: Optional[Path] = typer.Option(None, "--cwd", "-C", help="Target repository directory"),
+) -> None:
+    """View active configuration or generate a default configuration file."""
+    render_header()
+    target_dir = (working_dir or Path.cwd()).resolve()
+    target_file = target_dir / "terminal-agent.config.yaml"
+
+    if init:
+        save_default_config(target_file)
+        console.print(f"{SYM_CHECK} [agent.success]Created default configuration at {target_file}[/agent.success]")
+        return
+
+    config = load_config(target_file)
+    yaml_str = yaml.dump(config.model_dump(mode="json"), sort_keys=False, indent=2)
+    syntax = Syntax(yaml_str, "yaml", theme="monokai", line_numbers=True)
+    console.print(syntax)
+

terminal_agent/cli/commands/diff.py

@@ -0,0 +1,45 @@
+"""CLI diff command displaying repository changes and stats."""
+
+from pathlib import Path
+from typing import Optional
+import typer
+from rich.panel import Panel
+from rich.syntax import Syntax
+
+from terminal_agent.cli.theme import console
+from terminal_agent.cli.ui import render_header
+from terminal_agent.git.adapter import GitAdapter
+
+
+def diff_command(
+    file_path: Optional[str] = typer.Argument(None, help="Specific file path to diff"),
+    stat_only: bool = typer.Option(False, "--stat", "-s", help="Show diffstat summary only"),
+    working_dir: Optional[Path] = typer.Option(None, "--cwd", "-C", help="Target repository directory"),
+) -> None:
+    """View current git diff and changes made by agent."""
+    render_header()
+    target_dir = (working_dir or Path.cwd()).resolve()
+    git_adapter = GitAdapter(target_dir)
+
+    if not git_adapter.is_git_repo():
+        console.print("[agent.error]Current directory is not a Git repository.[/agent.error]")
+        raise typer.Exit(1)
+
+    diff_stats = git_adapter.get_diff_stats()
+    diff_text = git_adapter.get_diff(file_path=file_path, stat=stat_only)
+
+    console.print(
+        f"[agent.accent]Changed Files ({diff_stats.files_changed}):[/agent.accent] "
+        f"[agent.success]+{diff_stats.insertions}[/agent.success] / [agent.error]-{diff_stats.deletions}[/agent.error] lines\n"
+    )
+
+    if not diff_text.strip():
+        console.print("[agent.muted]No working tree modifications.[/agent.muted]")
+        return
+
+    if stat_only:
+        console.print(Panel(diff_text, title="[agent.accent]DIFF STAT[/agent.accent]", border_style="agent.border"))
+    else:
+        syntax = Syntax(diff_text, "diff", theme="monokai", line_numbers=False)
+        console.print(Panel(syntax, title="[agent.accent]WORKING TREE DIFF[/agent.accent]", border_style="agent.border"))
+

terminal_agent/cli/commands/doctor.py

@@ -0,0 +1,136 @@
+"""CLI doctor command checking environment, toolchain, sandbox, and provider availability."""
+
+import os
+import shutil
+import sys
+from pathlib import Path
+from typing import Optional
+import typer
+from rich.panel import Panel
+from rich.table import Table
+
+from terminal_agent.cli.theme import SYM_CHECK, SYM_CROSS, SYM_WARN, console
+from terminal_agent.cli.ui import render_header
+from terminal_agent.config.schema import ProviderType
+from terminal_agent.config.settings import load_config
+from terminal_agent.git.adapter import GitAdapter
+from terminal_agent.providers.detector import OllamaStatus, ProviderStatus, detect_all_providers, detect_ollama
+from terminal_agent.sandbox.docker import DockerSandbox
+
+
+def doctor_command(
+    working_dir: Optional[Path] = typer.Option(None, "--cwd", "-C", help="Target repository directory"),
+) -> None:
+    """Check system toolchains, sandbox prerequisites, and model provider availability."""
+    render_header()
+    target_dir = (working_dir or Path.cwd()).resolve()
+    config = load_config(target_dir / "terminal-agent.config.yaml")
+
+    console.print("[agent.accent]Running system diagnostics and provider auto-detection...[/agent.accent]\n")
+
+    # 1. System & Toolchains Table
+    sys_table = Table(title="[bold agent.accent]SYSTEM & TOOLCHAINS[/bold agent.accent]", border_style="agent.border")
+    sys_table.add_column("Component", style="agent.text", width=22)
+    sys_table.add_column("Status", width=10)
+    sys_table.add_column("Details", style="agent.muted")
+
+    # Python Check
+    py_ver = f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}"
+    if sys.version_info >= (3, 10):
+        sys_table.add_row("Python Runtime", SYM_CHECK, f"Python {py_ver}")
+    else:
+        sys_table.add_row("Python Runtime", SYM_CROSS, f"Python {py_ver} (Requires 3.10+)")
+
+    # Git Check
+    git_path = shutil.which("git")
+    if git_path:
+        git_adapter = GitAdapter(target_dir)
+        is_repo = git_adapter.is_git_repo()
+        sys_table.add_row("Git CLI", SYM_CHECK, f"Installed, Repository Root: {'Yes' if is_repo else 'No'}")
+    else:
+        sys_table.add_row("Git CLI", SYM_CROSS, "Git is not installed or not in PATH")
+
+    # Local Sandbox Check
+    sys_table.add_row("Local Sandbox", SYM_CHECK, "Process-tree isolation with psutil timeout manager")
+
+    # Docker Sandbox Check
+    docker_ok = DockerSandbox.is_docker_available()
+    if docker_ok:
+        sys_table.add_row("Docker Sandbox", SYM_CHECK, "Docker daemon running & available")
+    else:
+        sys_table.add_row("Docker Sandbox", SYM_WARN, "Docker not running (Local sandbox used as default)")
+
+    # Workspace Permissions
+    try:
+        test_file = target_dir / ".doctor_perm_test.tmp"
+        test_file.write_text("ok", encoding="utf-8")
+        test_file.unlink()
+        sys_table.add_row("Workspace Access", SYM_CHECK, f"Read/Write OK on {target_dir.name}")
+    except Exception as e:
+        sys_table.add_row("Workspace Access", SYM_CROSS, f"Permission error: {e}")
+
+    console.print(sys_table)
+    console.print()
+
+    # 2. Providers Detection Table
+    prov_table = Table(title="[bold agent.accent]MODEL PROVIDERS[/bold agent.accent]", border_style="agent.border")
+    prov_table.add_column("Provider", style="agent.text", width=22)
+    prov_table.add_column("Status", width=10)
+    prov_table.add_column("Details", style="agent.muted")
+
+    providers = detect_all_providers(config=config, working_dir=target_dir)
+    configured_provider_name = config.provider.name.value if hasattr(config.provider.name, "value") else str(config.provider.name)
+
+    any_usable = False
+    configured_is_usable = False
+
+    for prov_name, info in providers.items():
+        is_active_config = (prov_name == configured_provider_name)
+        display_label = f"{info.display_name} {'[bold cyan](Active)[/bold cyan]' if is_active_config else ''}"
+
+        if info.status == ProviderStatus.READY:
+            any_usable = True
+            if is_active_config:
+                configured_is_usable = True
+            prov_table.add_row(display_label, SYM_CHECK, info.details)
+        elif info.status == ProviderStatus.NOT_CONFIGURED:
+            # Optional missing provider -> SYM_WARN / Info, NOT SYM_CROSS
+            status_badge = SYM_WARN
+            hint_str = f" - Hint: {info.action_hint}" if info.action_hint else ""
+            prov_table.add_row(display_label, status_badge, f"{info.details}{hint_str}")
+        else:
+            # Error or explicitly selected but broken
+            status_badge = SYM_CROSS if is_active_config else SYM_WARN
+            hint_str = f" - Hint: {info.action_hint}" if info.action_hint else ""
+            prov_table.add_row(display_label, status_badge, f"{info.details}{hint_str}")
+
+    console.print(prov_table)
+    console.print()
+
+    # 3. Overall Readiness Assessment
+    if configured_is_usable or any_usable:
+        active_provider_info = providers.get(configured_provider_name)
+        if active_provider_info and active_provider_info.is_usable:
+            lines = [
+                "[bold agent.success]Overall Status: READY[/bold agent.success]",
+                f"Active Provider: [bold agent.accent]{active_provider_info.display_name}[/bold agent.accent] (Model: {config.provider.model})"
+            ]
+        else:
+            usable_names = [p.display_name for p in providers.values() if p.is_usable and p.name != "mock"]
+            if not usable_names:
+                usable_names = ["Mock Provider"]
+            lines = [
+                "[bold agent.success]Overall Status: READY[/bold agent.success]",
+                f"Available Provider(s): [bold agent.accent]{', '.join(usable_names)}[/bold agent.accent]",
+                "[agent.muted]Run [bold]terminal-agent setup[/bold] to switch default provider.[/agent.muted]"
+            ]
+        console.print(Panel("\n".join(lines), border_style="agent.success", title="[bold agent.success]DIAGNOSTIC RESULT[/bold agent.success]"))
+    else:
+        lines = [
+            "[bold agent.error]Overall Status: NOT READY[/bold agent.error]",
+            "[agent.warning]No model provider is currently configured or reachable.[/agent.warning]",
+            "",
+            "Next Action:",
+            "  Run [bold agent.accent]terminal-agent setup[/bold agent.accent] to interactively configure Ollama or cloud API keys."
+        ]
+        console.print(Panel("\n".join(lines), border_style="agent.error", title="[bold agent.error]DIAGNOSTIC RESULT[/bold agent.error]"))

terminal_agent/cli/commands/resume.py

@@ -0,0 +1,109 @@
+"""CLI resume command restoring and continuing an interrupted session."""
+
+from pathlib import Path
+from typing import Optional
+import typer
+
+from terminal_agent.agent.loop import AgentLoop
+from terminal_agent.checkpoints.manager import CheckpointManager
+from terminal_agent.cli.theme import SYM_CHECK, console
+from terminal_agent.cli.ui import (
+    render_contract_card,
+    render_header,
+    render_plan,
+    render_proof_of_done,
+    render_task_card,
+    render_tool_event,
+    render_verification_result,
+)
+from terminal_agent.config.settings import load_config
+from terminal_agent.context.engine import RepositoryContextEngine
+from terminal_agent.git.adapter import GitAdapter
+from terminal_agent.providers.factory import create_provider
+from terminal_agent.sandbox.local import LocalSandbox
+from terminal_agent.security.policy import SecurityPolicyEnforcer
+from terminal_agent.security.secrets import SecretGuard
+from terminal_agent.session.manager import SessionManager
+from terminal_agent.session.models import VerificationStatus
+from terminal_agent.telemetry.events import TelemetryLogger
+from terminal_agent.tools.registry import ToolRegistry
+from terminal_agent.verifier.engine import IndependentVerifier
+
+
+def resume_command(
+    session_id: Optional[str] = typer.Argument(None, help="Session ID to resume (or latest if omitted)"),
+    working_dir: Optional[Path] = typer.Option(None, "--cwd", "-C", help="Target repository directory"),
+) -> None:
+    """Resume an interrupted terminal agent session."""
+    render_header()
+    target_dir = (working_dir or Path.cwd()).resolve()
+    session_mgr = SessionManager(target_dir)
+
+    if session_id:
+        state = session_mgr.load_session(session_id)
+    else:
+        state = session_mgr.get_latest_session()
+
+    if not state:
+        console.print(f"[agent.error]No resumable session found in {target_dir}.[/agent.error]")
+        raise typer.Exit(1)
+
+    console.print(f"\n[agent.accent]SESSION RESUMED: {state.session_id}[/agent.accent]")
+    render_task_card(state.task_description, target_dir)
+
+    if state.contract:
+        render_contract_card(state.contract)
+    if state.plan:
+        render_plan(state.plan)
+
+    console.print(f"[agent.muted]Completed steps: {len(state.completed_steps)}[/agent.muted]")
+    console.print(f"[agent.muted]Modified files: {', '.join(state.modified_files) if state.modified_files else 'None'}[/agent.muted]")
+    console.print(f"[agent.accent]Next: {state.next_step}[/agent.accent]\n")
+
+    if state.current_status == VerificationStatus.VERIFIED:
+        console.print("[agent.success]This session is already VERIFIED.[/agent.success]")
+        if state.proof_of_done:
+            render_proof_of_done(state.proof_of_done)
+        return
+
+    # Set up runtime to continue execution
+    config = load_config(target_dir / "terminal-agent.config.yaml")
+    secret_guard = SecretGuard(blocked_patterns=config.security.blocked_paths, working_dir=target_dir)
+    security_enforcer = SecurityPolicyEnforcer(security_config=config.security, secret_guard=secret_guard)
+    sandbox = LocalSandbox(working_dir=target_dir, default_timeout=config.sandbox.timeout_seconds, secret_guard=secret_guard)
+    git_adapter = GitAdapter(target_dir)
+    checkpoint_mgr = CheckpointManager(target_dir)
+    context_engine = RepositoryContextEngine(target_dir, secret_guard=secret_guard)
+    tool_registry = ToolRegistry(target_dir, sandbox, security_enforcer, git_adapter, checkpoint_mgr, secret_guard)
+    verifier = IndependentVerifier(sandbox, git_adapter, config.verification, target_dir)
+    provider = create_provider(config.provider)
+    telemetry_logger = TelemetryLogger(state.session_id, working_dir=target_dir)
+
+    def on_event(event_type: str, data):
+        if event_type == "tool_completed":
+            render_tool_event(
+                tool_name=data.reason.split()[0] if data.reason else "tool",
+                reason=data.reason,
+                status="success" if data.success else "error",
+                duration_ms=data.duration_ms
+            )
+        elif event_type == "verification_result":
+            render_verification_result(data)
+        elif event_type == "proof_of_done":
+            render_proof_of_done(data, duration_seconds=state.metrics.execution_time_seconds)
+
+    agent_loop = AgentLoop(
+        session_state=state,
+        config=config,
+        provider=provider,
+        tool_registry=tool_registry,
+        verifier=verifier,
+        context_engine=context_engine,
+        checkpoint_manager=checkpoint_mgr,
+        session_manager=session_mgr,
+        telemetry_logger=telemetry_logger,
+        step_callback=on_event
+    )
+
+    agent_loop.run()
+

terminal_agent/cli/commands/run.py

@@ -0,0 +1,184 @@
+"""CLI run command executing autonomous coding tasks."""
+
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+import typer
+import yaml
+
+from terminal_agent.agent.loop import AgentLoop
+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_contract_card,
+    render_header,
+    render_plan,
+    render_proof_of_done,
+    render_task_card,
+    render_tool_event,
+    render_verification_result,
+)
+from terminal_agent.config.settings import load_config
+from terminal_agent.context.engine import RepositoryContextEngine
+from terminal_agent.git.adapter import GitAdapter
+from terminal_agent.planner.contract import TaskContractGenerator
+from terminal_agent.providers.detector import ProviderStatus, resolve_active_provider
+from terminal_agent.providers.factory import create_provider
+from terminal_agent.sandbox.docker import DockerSandbox
+from terminal_agent.sandbox.local import LocalSandbox
+from terminal_agent.security.policy import SecurityPolicyEnforcer
+from terminal_agent.security.secrets import SecretGuard
+from terminal_agent.session.manager import SessionManager
+from terminal_agent.session.models import VerificationStatus
+from terminal_agent.telemetry.events import TelemetryLogger
+from terminal_agent.tools.registry import ToolRegistry
+from terminal_agent.verifier.engine import IndependentVerifier
+
+
+def run_command(
+    task: Optional[str] = typer.Argument(None, help="The coding task description to execute autonomously"),
+    task_file: Optional[Path] = typer.Option(None, "--task", "-t", help="Path to declarative task YAML file"),
+    working_dir: Optional[Path] = typer.Option(None, "--cwd", "-C", help="Target repository directory"),
+    provider_name: Optional[str] = typer.Option(None, "--provider", "-p", help="Override model provider"),
+    model_name: Optional[str] = typer.Option(None, "--model", "-m", help="Override model name"),
+    auto_approve: bool = typer.Option(False, "--yes", "-y", help="Auto-approve confirmation prompts"),
+) -> None:
+    """Execute an autonomous verify-first coding session."""
+    render_header()
+    target_dir = (working_dir or Path.cwd()).resolve()
+
+    task_desc = task
+    if task_file and task_file.exists():
+        try:
+            content = yaml.safe_load(task_file.read_text(encoding="utf-8"))
+            if isinstance(content, dict):
+                task_desc = content.get("prompt") or content.get("task") or str(content)
+            else:
+                task_desc = str(content)
+        except Exception as e:
+            console.print(f"[agent.error]Error reading task file: {e}[/agent.error]")
+            raise typer.Exit(1)
+
+    if not task_desc:
+        task_desc = typer.prompt("Describe the coding task")
+
+    render_task_card(task_desc, target_dir)
+
+    # Load configuration & resolve active provider
+    config = load_config(target_dir / "terminal-agent.config.yaml")
+    resolved_prov_cfg, prov_info = resolve_active_provider(
+        config=config,
+        explicit_provider=provider_name,
+        explicit_model=model_name,
+        working_dir=target_dir
+    )
+    config.provider = resolved_prov_cfg
+
+    # Initialize subsystems
+    secret_guard = SecretGuard(blocked_patterns=config.security.blocked_paths, working_dir=target_dir)
+
+    def confirmation_cb(cmd: str, category, reason: str) -> bool:
+        if auto_approve:
+            return True
+        console.print(f"\n[agent.warning]Security Warning: {category.value.upper()} command[/agent.warning]")
+        console.print(f"Command: [agent.accent]{cmd}[/agent.accent]")
+        console.print(f"Reason:  [agent.muted]{reason}[/agent.muted]")
+        return typer.confirm("Allow execution?")
+
+    security_enforcer = SecurityPolicyEnforcer(
+        security_config=config.security,
+        secret_guard=secret_guard,
+        confirmation_callback=confirmation_cb
+    )
+
+    if config.sandbox.mode == "docker" and DockerSandbox.is_docker_available():
+        sandbox = DockerSandbox(
+            working_dir=target_dir,
+            image=config.sandbox.image,
+            network=config.sandbox.network,
+            timeout_seconds=config.sandbox.timeout_seconds,
+            secret_guard=secret_guard
+        )
+    else:
+        sandbox = LocalSandbox(
+            working_dir=target_dir,
+            default_timeout=config.sandbox.timeout_seconds,
+            secret_guard=secret_guard
+        )
+
+    git_adapter = GitAdapter(target_dir)
+    checkpoint_mgr = CheckpointManager(target_dir)
+    session_mgr = SessionManager(target_dir)
+    context_engine = RepositoryContextEngine(target_dir, secret_guard=secret_guard)
+
+    tool_registry = ToolRegistry(
+        working_dir=target_dir,
+        sandbox=sandbox,
+        security_enforcer=security_enforcer,
+        git_adapter=git_adapter,
+        checkpoint_manager=checkpoint_mgr,
+        secret_guard=secret_guard
+    )
+
+    verifier = IndependentVerifier(
+        sandbox=sandbox,
+        git_adapter=git_adapter,
+        config=config.verification,
+        working_dir=target_dir
+    )
+
+    # Initialize Provider
+    provider = create_provider(config.provider)
+    health_ok, health_msg = provider.check_health()
+    if not health_ok and config.provider.name.value != "mock":
+        console.print(f"[agent.warning]Provider Notice ({prov_info.display_name}): {health_msg}[/agent.warning]")
+        if prov_info.action_hint:
+            console.print(f"[agent.accent]Suggested Action: {prov_info.action_hint}[/agent.accent]")
+        if not prov_info.is_usable:
+            console.print("\n[agent.muted]To configure or switch model providers, run: [bold]terminal-agent setup[/bold][/agent.muted]\n")
+
+    # Create Session
+    session_state = session_mgr.create_session(task_description=task_desc)
+    telemetry_logger = TelemetryLogger(session_state.session_id, working_dir=target_dir)
+
+    # Step callback for live display
+    def on_event(event_type: str, data: Any):
+        if event_type == "contract_ready":
+            render_contract_card(data)
+            if session_state.plan:
+                render_plan(session_state.plan)
+        elif event_type == "checkpoint_created":
+            console.print(f"{SYM_CHECK} [agent.muted]Created baseline checkpoint '{data.checkpoint_id}'[/agent.muted]")
+        elif event_type == "tool_completed":
+            render_tool_event(
+                tool_name=data.reason.split()[0] if data.reason else "tool",
+                reason=data.reason,
+                status="success" if data.success else "error",
+                duration_ms=data.duration_ms
+            )
+        elif event_type == "verification_result":
+            render_verification_result(data)
+        elif event_type == "repair_plan":
+            console.print(f"[agent.warning]Recovery Plan: Category '{data.failure_category.value}' -> {data.recovery_action}[/agent.warning]")
+        elif event_type == "proof_of_done":
+            render_proof_of_done(data, duration_seconds=session_state.metrics.execution_time_seconds)
+
+    agent_loop = AgentLoop(
+        session_state=session_state,
+        config=config,
+        provider=provider,
+        tool_registry=tool_registry,
+        verifier=verifier,
+        context_engine=context_engine,
+        checkpoint_manager=checkpoint_mgr,
+        session_manager=session_mgr,
+        telemetry_logger=telemetry_logger,
+        step_callback=on_event
+    )
+
+    # Run Loop
+    final_state = agent_loop.run()
+
+    if final_state.current_status == VerificationStatus.VERIFIED:
+        console.print(f"\n[agent.success]Task successfully VERIFIED. Session: {final_state.session_id}[/agent.success]")
+    else:
+        console.print(f"\n[agent.error]Task concluded with status: {final_state.current_status.value}[/agent.error]")