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

terminal_agent/cli/ui.py

@@ -0,0 +1,147 @@
+"""Rich UI rendering components for the monochrome Terminal Agent aesthetic."""
+
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+from rich.box import ROUNDED, HEAVY, DOUBLE
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+from terminal_agent.cli.theme import (
+    PALETTE,
+    SYM_ARROW,
+    SYM_CHECK,
+    SYM_CROSS,
+    SYM_WARN,
+    console,
+)
+from terminal_agent.session.models import PlanItem, TaskContract, VerificationResult, VerificationStatus
+
+
+def render_header() -> None:
+    """Render main application banner."""
+    content = Text()
+    content.append("TERMINAL AGENT\n", style="agent.title")
+    content.append("Build. Verify. Ship.", style="agent.tagline")
+    panel = Panel(content, box=ROUNDED, border_style="agent.border", padding=(0, 2))
+    console.print(panel)
+
+
+def render_task_card(task: str, project_dir: Path) -> None:
+    """Render current project and task context."""
+    t = Table.grid(padding=(0, 2))
+    t.add_column(style="agent.muted", width=12)
+    t.add_column(style="agent.text")
+
+    t.add_row("PROJECT", str(project_dir))
+    t.add_row("TASK", task)
+    console.print(Panel(t, box=ROUNDED, border_style="agent.border"))
+
+
+def render_contract_card(contract: TaskContract) -> None:
+    """Render negotiated Task Contract."""
+    t = Table(box=ROUNDED, border_style="agent.border", show_header=False, expand=True)
+    t.add_column("Key", style="agent.muted", width=16)
+    t.add_column("Value", style="agent.text")
+
+    t.add_row("GOAL", contract.goal)
+    t.add_row("CONSTRAINTS", "\n".join(f"• {c}" for c in contract.constraints))
+    t.add_row("SUCCESS CRITERIA", "\n".join(f"• {sc}" for sc in contract.success_criteria))
+    t.add_row("VERIFY COMMANDS", ", ".join(contract.verification_commands))
+
+    console.print(Panel(t, title="[agent.accent]TASK CONTRACT[/agent.accent]", border_style="agent.border"))
+
+
+def render_plan(plan: List[PlanItem]) -> None:
+    """Render live plan status."""
+    lines = []
+    for item in plan:
+        if item.status == "COMPLETED":
+            symbol = SYM_CHECK
+            style = "agent.text"
+        elif item.status == "IN_PROGRESS":
+            symbol = SYM_ARROW
+            style = "agent.accent"
+        elif item.status == "FAILED":
+            symbol = SYM_CROSS
+            style = "agent.error"
+        else:
+            symbol = "[agent.muted]○[/agent.muted]"
+            style = "agent.muted"
+        lines.append(f"{symbol} [{style}]{item.description}[/{style}]")
+
+    console.print(Panel("\n".join(lines), title="[agent.accent]PLAN[/agent.accent]", border_style="agent.border"))
+
+
+def render_tool_event(tool_name: str, reason: str, status: str = "success", duration_ms: Optional[int] = None) -> None:
+    """Render a step in the action timeline with explainability reason."""
+    dur_str = f" [agent.muted]({duration_ms}ms)[/agent.muted]" if duration_ms is not None else ""
+    symbol = SYM_CHECK if status == "success" else (SYM_CROSS if status == "error" else SYM_ARROW)
+    
+    t = Table.grid(padding=(0, 1))
+    t.add_column(width=4)
+    t.add_column()
+    t.add_row(symbol, f"[agent.accent]{tool_name}[/agent.accent]{dur_str}")
+    if reason:
+        t.add_row("", f"[agent.muted]Reason: {reason}[/agent.muted]")
+    console.print(t)
+
+
+def render_verification_result(result: VerificationResult) -> None:
+    """Render independent verification card."""
+    is_verified = result.status == VerificationStatus.VERIFIED
+    border_col = "agent.success" if is_verified else ("agent.warning" if result.status == VerificationStatus.PARTIAL else "agent.error")
+    title_text = f"[{border_col}]VERIFICATION: {result.status.value}[/{border_col}]"
+
+    table = Table(box=ROUNDED, border_style=border_col, show_header=False, expand=True)
+    table.add_column("Key", style="agent.muted", width=16)
+    table.add_column("Value", style="agent.text")
+
+    table.add_row("TESTS", f"{result.tests_passed}/{result.tests_run} passed ({result.tests_failed} failed)")
+    table.add_row("LINT", "[agent.success]PASS[/agent.success]" if result.lint_passed else "[agent.error]FAIL[/agent.error]")
+    table.add_row("FILES CHANGED", f"{result.files_changed_count} files ({', '.join(result.files_changed) if result.files_changed else 'None'})")
+
+    if result.assertions:
+        assertions_str = "\n".join(
+            f"{SYM_CHECK if a.passed else SYM_CROSS} {a.name}: {a.message}"
+            for a in result.assertions
+        )
+        table.add_row("ASSERTIONS", assertions_str)
+
+    console.print(Panel(table, title=title_text, border_style=border_col))
+
+
+def render_proof_of_done(pod: Dict[str, Any], duration_seconds: float = 0.0) -> None:
+    """Render final certified Proof of Done."""
+    mins = int(duration_seconds // 60)
+    secs = int(duration_seconds % 60)
+    time_str = f"{mins:02d}m {secs:02d}s"
+
+    t = Table(box=ROUNDED, border_style="agent.success", show_header=False, expand=True)
+    t.add_column("Key", style="agent.muted", width=18)
+    t.add_column("Value", style="agent.text")
+
+    t.add_row("TASK", pod.get("task", ""))
+    t.add_row("RESULT", f"[agent.success]{pod.get('result', 'VERIFIED')}[/agent.success]")
+    t.add_row("TESTS", f"[agent.success]{pod.get('tests_passed', 'N/A')}[/agent.success]")
+    t.add_row("LINT", pod.get("lint", "PASS"))
+    t.add_row("FILES CHANGED", f"{pod.get('files_changed_count', 0)} ({', '.join(pod.get('files_changed', []))})")
+    t.add_row("UNINTENDED FILES", str(pod.get("unintended_files_count", 0)))
+    t.add_row("RETRIES", str(pod.get("retries_count", 0)))
+    t.add_row("SUCCESS CRITERIA", pod.get("success_criteria_passed", "N/A"))
+    t.add_row("EXECUTION TIME", time_str)
+
+    console.print()
+    console.print(Panel(t, title="[agent.success]PROOF OF DONE[/agent.success]", border_style="agent.success"))
+
+    summary = pod.get("summary", {})
+    if summary:
+        sum_table = Table(box=ROUNDED, border_style="agent.border", show_header=False, expand=True)
+        sum_table.add_column("Key", style="agent.muted", width=18)
+        sum_table.add_column("Value", style="agent.text")
+        sum_table.add_row("WHAT CHANGED", summary.get("what_changed", ""))
+        sum_table.add_row("WHY IT CHANGED", summary.get("why_it_changed", ""))
+        sum_table.add_row("WHAT WAS VERIFIED", summary.get("what_was_verified", ""))
+        sum_table.add_row("LIMITATIONS", summary.get("remaining_limitations", "None"))
+        console.print(Panel(sum_table, title="[agent.accent]FINAL SUMMARY[/agent.accent]", border_style="agent.border"))
+

terminal_agent/config/__init__.py

@@ -0,0 +1,30 @@
+"""Configuration package for Terminal Agent."""
+
+from terminal_agent.config.schema import (
+    TerminalAgentConfig,
+    AgentConfig,
+    SandboxConfig,
+    VerificationConfig,
+    SecurityConfig,
+    ProviderConfig,
+    SandboxMode,
+    ProviderType,
+    CommandCategory,
+)
+from terminal_agent.config.settings import load_config, save_default_config, find_config_file
+
+__all__ = [
+    "TerminalAgentConfig",
+    "AgentConfig",
+    "SandboxConfig",
+    "VerificationConfig",
+    "SecurityConfig",
+    "ProviderConfig",
+    "SandboxMode",
+    "ProviderType",
+    "CommandCategory",
+    "load_config",
+    "save_default_config",
+    "find_config_file",
+]
+

terminal_agent/config/schema.py

@@ -0,0 +1,100 @@
+"""Configuration schemas for Terminal Agent."""
+
+from enum import Enum
+from typing import List, Optional
+from pydantic import BaseModel, Field
+
+
+class SandboxMode(str, Enum):
+    LOCAL = "local"
+    DOCKER = "docker"
+
+
+class ProviderType(str, Enum):
+    MOCK = "mock"
+    OLLAMA = "ollama"
+    OPENAI = "openai"
+    ANTHROPIC = "anthropic"
+    GEMINI = "gemini"
+    CUSTOM = "custom"
+
+
+class CommandCategory(str, Enum):
+    SAFE = "safe"
+    WRITE = "write"
+    DESTRUCTIVE = "destructive"
+    NETWORK = "network"
+    PRIVILEGED = "privileged"
+
+
+class AgentConfig(BaseModel):
+    max_steps: int = Field(default=40, description="Maximum steps allowed per task execution")
+    max_retries: int = Field(default=3, description="Maximum repair retries on verification failure")
+    timeout_seconds: int = Field(default=600, description="Overall task execution timeout in seconds")
+    token_budget: int = Field(default=128000, description="Maximum token budget for context")
+
+
+class SandboxConfig(BaseModel):
+    mode: SandboxMode = Field(default=SandboxMode.LOCAL, description="Sandbox isolation mode (local or docker)")
+    image: str = Field(default="python:3.12-slim", description="Docker image if docker mode is enabled")
+    timeout_seconds: int = Field(default=60, description="Per-command timeout in seconds")
+    network: str = Field(default="disabled", description="Network access policy: 'disabled' or 'enabled'")
+    max_memory_mb: int = Field(default=1024, description="Memory limit for docker sandbox in MB")
+
+
+class DiffConstraints(BaseModel):
+    max_files_changed: int = Field(default=10, description="Maximum allowed modified files in diff")
+    allow_untracked_files: bool = Field(default=True, description="Whether new files are permitted")
+
+
+class VerificationConfig(BaseModel):
+    tests: List[str] = Field(default_factory=lambda: ["pytest"], description="Test commands to execute for verification")
+    lint: List[str] = Field(default_factory=list, description="Lint/static check commands")
+    assertions: List[str] = Field(
+        default_factory=lambda: ["no_test_files_modified", "api_contract_preserved"],
+        description="Verification contract assertion checks"
+    )
+    diff: DiffConstraints = Field(default_factory=DiffConstraints, description="Git diff constraints")
+    auto_rollback_on_failure: bool = Field(default=False, description="Whether to rollback git changes on failure")
+
+
+class SecurityConfig(BaseModel):
+    network: str = Field(default="disabled", description="Global network policy")
+    require_confirmation_for: List[CommandCategory] = Field(
+        default_factory=lambda: [
+            CommandCategory.DESTRUCTIVE,
+            CommandCategory.PRIVILEGED,
+            CommandCategory.NETWORK
+        ],
+        description="Command categories that require explicit user confirmation"
+    )
+    blocked_paths: List[str] = Field(
+        default_factory=lambda: [
+            ".env",
+            ".env.*",
+            "**/*.pem",
+            "**/*.key",
+            "**/.ssh/*",
+            "**/.aws/*",
+            "**/id_rsa*",
+            "**/secrets.*"
+        ],
+        description="File patterns blocked from read/write to protect host secrets"
+    )
+
+
+class ProviderConfig(BaseModel):
+    name: ProviderType = Field(default=ProviderType.MOCK, description="Model provider name")
+    model: str = Field(default="mock-model", description="Model identifier")
+    base_url: Optional[str] = Field(default=None, description="Custom API base URL if needed")
+    api_key: Optional[str] = Field(default=None, description="API key or retrieved via environment variable")
+    temperature: float = Field(default=0.2, description="Sampling temperature")
+
+
+class TerminalAgentConfig(BaseModel):
+    agent: AgentConfig = Field(default_factory=AgentConfig)
+    sandbox: SandboxConfig = Field(default_factory=SandboxConfig)
+    verification: VerificationConfig = Field(default_factory=VerificationConfig)
+    security: SecurityConfig = Field(default_factory=SecurityConfig)
+    provider: ProviderConfig = Field(default_factory=ProviderConfig)
+

terminal_agent/config/settings.py

@@ -0,0 +1,85 @@
+"""Settings loader and configuration manager for Terminal Agent."""
+
+import os
+from pathlib import Path
+from typing import Optional
+import yaml
+from terminal_agent.config.schema import TerminalAgentConfig, ProviderType
+
+
+DEFAULT_CONFIG_FILENAMES = [
+    "terminal-agent.config.yaml",
+    "terminal-agent.config.yml",
+    ".terminal-agent.yaml",
+    ".terminal-agent.yml",
+]
+
+
+def find_config_file(start_dir: Optional[Path] = None) -> Optional[Path]:
+    """Find configuration file by searching current and parent directories."""
+    current = start_dir or Path.cwd()
+    root = Path(current.anchor)
+
+    while current != root:
+        for filename in DEFAULT_CONFIG_FILENAMES:
+            candidate = current / filename
+            if candidate.is_file():
+                return candidate
+        current = current.parent
+
+    for filename in DEFAULT_CONFIG_FILENAMES:
+        candidate = root / filename
+        if candidate.is_file():
+            return candidate
+
+    return None
+
+
+def load_config(config_path: Optional[Path] = None) -> TerminalAgentConfig:
+    """Load configuration from file or defaults, applying environment variables."""
+    target_path = config_path or find_config_file()
+
+    raw_data = {}
+    if target_path and target_path.exists():
+        with open(target_path, "r", encoding="utf-8") as f:
+            loaded = yaml.safe_load(f)
+            if isinstance(loaded, dict):
+                raw_data = loaded
+
+    # Environment variable overrides
+    if "TERMINAL_AGENT_PROVIDER" in os.environ:
+        provider_name = os.environ["TERMINAL_AGENT_PROVIDER"].lower()
+        if "provider" not in raw_data:
+            raw_data["provider"] = {}
+        raw_data["provider"]["name"] = provider_name
+
+    if "TERMINAL_AGENT_MODEL" in os.environ:
+        if "provider" not in raw_data:
+            raw_data["provider"] = {}
+        raw_data["provider"]["model"] = os.environ["TERMINAL_AGENT_MODEL"]
+
+    if "OLLAMA_HOST" in os.environ and "provider" in raw_data and raw_data["provider"].get("name") == "ollama":
+        raw_data["provider"]["base_url"] = os.environ["OLLAMA_HOST"]
+
+    if "OPENAI_API_KEY" in os.environ:
+        if "provider" in raw_data and raw_data["provider"].get("name") == "openai":
+            raw_data["provider"]["api_key"] = os.environ["OPENAI_API_KEY"]
+
+    if "ANTHROPIC_API_KEY" in os.environ:
+        if "provider" in raw_data and raw_data["provider"].get("name") == "anthropic":
+            raw_data["provider"]["api_key"] = os.environ["ANTHROPIC_API_KEY"]
+
+    if "GEMINI_API_KEY" in os.environ:
+        if "provider" in raw_data and raw_data["provider"].get("name") == "gemini":
+            raw_data["provider"]["api_key"] = os.environ["GEMINI_API_KEY"]
+
+    return TerminalAgentConfig.model_validate(raw_data)
+
+
+def save_default_config(destination: Path) -> Path:
+    """Write default configuration YAML template to destination."""
+    default_config = TerminalAgentConfig()
+    yaml_content = yaml.dump(default_config.model_dump(mode="json"), sort_keys=False, indent=2)
+    destination.write_text(yaml_content, encoding="utf-8")
+    return destination
+

terminal_agent/context/__init__.py

@@ -0,0 +1,11 @@
+"""Context exploration package for Terminal Agent."""
+
+from terminal_agent.context.ranker import DeterministicRanker, tokenize
+from terminal_agent.context.engine import RepositoryContextEngine
+
+__all__ = [
+    "DeterministicRanker",
+    "tokenize",
+    "RepositoryContextEngine",
+]
+

terminal_agent/context/engine.py

@@ -0,0 +1,173 @@
+"""Deterministic context retrieval engine for codebase exploration."""
+
+import fnmatch
+import os
+from pathlib import Path
+from typing import Dict, List, Optional, Set, Tuple
+
+from terminal_agent.context.ranker import DeterministicRanker, tokenize
+from terminal_agent.git.adapter import GitAdapter
+from terminal_agent.security.secrets import SecretGuard
+from terminal_agent.session.models import TaskContract
+
+
+IGNORE_PATTERNS = {
+    ".git", ".terminal_agent", ".venv", "venv", "__pycache__",
+    ".pytest_cache", ".coverage", "htmlcov", "dist", "build",
+    "node_modules", ".idea", ".vscode", "*.pyc", "*.pyo", "*.egg-info"
+}
+
+
+class RepositoryContextEngine:
+    """Explores repository structure and extracts deterministic, token-efficient context."""
+
+    def __init__(self, root_dir: Optional[Path] = None, secret_guard: Optional[SecretGuard] = None):
+        self.root_dir = (root_dir or Path.cwd()).resolve()
+        self.secret_guard = secret_guard or SecretGuard(working_dir=self.root_dir)
+        self.git_adapter = GitAdapter(self.root_dir)
+
+    def is_ignored(self, path: Path) -> bool:
+        """Check if path matches standard ignore patterns or security blocklist."""
+        if self.secret_guard.is_path_blocked(path):
+            return True
+
+        parts = path.parts
+        for part in parts:
+            if part in IGNORE_PATTERNS:
+                return True
+            for pat in IGNORE_PATTERNS:
+                if fnmatch.fnmatch(part, pat):
+                    return True
+        return False
+
+    def list_all_files(self, max_files: int = 500) -> List[Path]:
+        """Discover all valid non-ignored repository files."""
+        collected = []
+        for root, dirs, files in os.walk(self.root_dir):
+            # Prune ignored directories in-place
+            dirs[:] = [
+                d for d in dirs
+                if d not in IGNORE_PATTERNS and not any(fnmatch.fnmatch(d, p) for p in IGNORE_PATTERNS)
+            ]
+            for f in files:
+                p = Path(root) / f
+                if not self.is_ignored(p):
+                    collected.append(p)
+                    if len(collected) >= max_files:
+                        return collected
+        return collected
+
+    def build_tree_summary(self, max_depth: int = 3, max_entries: int = 60) -> str:
+        """Generate a clean ASCII directory tree summary."""
+        lines = [f"{self.root_dir.name}/"]
+        count = 0
+
+        def _traverse(current_dir: Path, prefix: str, depth: int):
+            nonlocal count
+            if depth > max_depth or count >= max_entries:
+                return
+
+            try:
+                entries = sorted(list(current_dir.iterdir()), key=lambda x: (not x.is_dir(), x.name.lower()))
+            except Exception:
+                return
+
+            valid_entries = [e for e in entries if not self.is_ignored(e)]
+            total = len(valid_entries)
+
+            for i, entry in enumerate(valid_entries):
+                if count >= max_entries:
+                    lines.append(f"{prefix}└── ... (truncated)")
+                    break
+
+                is_last = (i == total - 1)
+                connector = "└── " if is_last else "├── "
+                sub_prefix = "    " if is_last else "│   "
+
+                if entry.is_dir():
+                    lines.append(f"{prefix}{connector}{entry.name}/")
+                    count += 1
+                    _traverse(entry, prefix + sub_prefix, depth + 1)
+                else:
+                    lines.append(f"{prefix}{connector}{entry.name}")
+                    count += 1
+
+        _traverse(self.root_dir, "", 1)
+        return "\n".join(lines)
+
+    def search_relevant_files(self, query: str, top_k: int = 5) -> List[Tuple[str, float, str]]:
+        """
+        Rank repository files by relevance to query.
+        Returns List of (relative_path, score, reason).
+        """
+        query_tokens = tokenize(query)
+        if not query_tokens:
+            return []
+
+        all_files = self.list_all_files()
+        scored_files = []
+
+        for p in all_files:
+            try:
+                # Only read text files up to 500KB
+                if p.stat().st_size > 500_000:
+                    continue
+                content = p.read_text(encoding="utf-8", errors="ignore")
+                score, reason = DeterministicRanker.score_file(p, content, query_tokens, self.root_dir)
+                if score > 0.5:
+                    rel_p = str(p.relative_to(self.root_dir)).replace("\\", "/")
+                    scored_files.append((rel_p, score, reason))
+            except Exception:
+                continue
+
+        scored_files.sort(key=lambda x: x[1], reverse=True)
+        return scored_files[:top_k]
+
+    def read_file_with_lines(self, rel_path: str, max_lines: int = 300) -> str:
+        """Read file content with line numbers."""
+        full_path = (self.root_dir / rel_path).resolve()
+        if self.secret_guard.is_path_blocked(full_path):
+            return f"[ERROR: Access to {rel_path} blocked by security policy]"
+        if not full_path.exists():
+            return f"[ERROR: File {rel_path} does not exist]"
+
+        try:
+            lines = full_path.read_text(encoding="utf-8", errors="replace").splitlines()
+            numbered = [f"{i+1:4d} | {line}" for i, line in enumerate(lines[:max_lines])]
+            if len(lines) > max_lines:
+                numbered.append(f"... ({len(lines) - max_lines} more lines)")
+            return "\n".join(numbered)
+        except Exception as e:
+            return f"[ERROR reading {rel_path}: {e}]"
+
+    def build_initial_context(self, task_description: str, contract: Optional[TaskContract] = None) -> str:
+        """Assemble structured, deterministic repository context for the model."""
+        tree = self.build_tree_summary()
+        relevant = self.search_relevant_files(task_description, top_k=5)
+
+        context_parts = [
+            f"=== REPOSITORY ROOT: {self.root_dir.name} ===",
+            "=== DIRECTORY STRUCTURE ===",
+            tree,
+            "",
+            "=== RELEVANT FILES IDENTIFIED ===",
+        ]
+
+        if relevant:
+            for rel_path, score, reason in relevant:
+                context_parts.append(f"- {rel_path} (Score: {score:.1f}, Matches: {reason})")
+        else:
+            context_parts.append("(No specific file matches identified from initial keywords)")
+
+        # Include Git status if available
+        status = self.git_adapter.get_status()
+        if status.is_repo:
+            context_parts.extend([
+                "",
+                f"=== GIT STATUS: Branch '{status.branch}' ===",
+                f"Modified: {status.modified_files}",
+                f"Untracked: {status.untracked_files}",
+            ])
+
+        return "\n".join(context_parts)
+

terminal_agent/context/ranker.py

@@ -0,0 +1,87 @@
+"""Deterministic relevance ranker for repository files and symbols."""
+
+import math
+import re
+from collections import Counter
+from pathlib import Path
+from typing import Dict, List, Set, Tuple
+
+
+def tokenize(text: str) -> List[str]:
+    """Tokenize text into lowercase alpha-numeric keywords, splitting snake_case and camelCase."""
+    # Split camelCase
+    s1 = re.sub(r"([a-z0-9])([A-Z])", r"\1 \2", text)
+    # Split snake_case and non-alphanumeric
+    tokens = re.findall(r"[a-zA-Z0-9]+", s1.lower())
+    # Filter short stopwords
+    stopwords = {"the", "a", "an", "and", "or", "in", "on", "at", "to", "for", "with", "by", "of", "is", "it", "this", "that"}
+    return [t for t in tokens if len(t) > 1 and t not in stopwords]
+
+
+class DeterministicRanker:
+    """Ranks repository files based on task relevance using deterministic symbol and term scoring."""
+
+    @staticmethod
+    def score_file(
+        file_path: Path,
+        content: str,
+        query_tokens: List[str],
+        base_dir: Path
+    ) -> Tuple[float, str]:
+        """
+        Compute deterministic relevance score for a file.
+        Returns (score, summary_reason).
+        """
+        if not query_tokens:
+            return 0.0, "No query tokens"
+
+        rel_path = str(file_path.relative_to(base_dir)).replace("\\", "/")
+        path_tokens = tokenize(rel_path)
+        content_tokens = tokenize(content[:20000]) # First 20KB for fast scoring
+
+        query_set = set(query_tokens)
+        
+        # 1. Path Match Score (High weight: 10x)
+        path_matches = [t for t in path_tokens if t in query_set]
+        path_score = len(path_matches) * 10.0
+
+        # Exact filename match bonus
+        for q in query_tokens:
+            if q in file_path.name.lower():
+                path_score += 15.0
+
+        # 2. Symbol Definition Match (defs, classes, functions: 5x)
+        symbol_score = 0.0
+        symbol_matches = []
+        for line in content.splitlines()[:500]:
+            trimmed = line.strip()
+            if trimmed.startswith(("def ", "class ", "function ", "type ", "interface ", "struct ", "pub fn ")):
+                line_tokens = tokenize(trimmed)
+                matches = [t for t in line_tokens if t in query_set]
+                if matches:
+                    symbol_score += len(matches) * 5.0
+                    symbol_matches.extend(matches)
+
+        # 3. Content Frequency (TF-IDF style term frequency: 1x)
+        content_counter = Counter(content_tokens)
+        content_score = sum(math.log(1 + content_counter[t]) for t in query_set if t in content_counter)
+
+        # Penalize test files slightly for implementation queries unless query specifically asks for test
+        is_test_query = any("test" in q for q in query_tokens)
+        is_test_file = "test" in rel_path.lower()
+        if is_test_file and not is_test_query:
+            total_score = (path_score + symbol_score + content_score) * 0.6
+        else:
+            total_score = path_score + symbol_score + content_score
+
+        reasons = []
+        if path_matches:
+            reasons.append(f"path matches [{', '.join(set(path_matches))}]")
+        if symbol_matches:
+            reasons.append(f"symbols [{', '.join(set(symbol_matches))}]")
+        if content_score > 0:
+            reasons.append(f"term frequency score {content_score:.1f}")
+
+        reason_str = ", ".join(reasons) if reasons else "low keyword frequency"
+        return round(total_score, 2), reason_str
+

terminal_agent/git/__init__.py

@@ -0,0 +1,10 @@
+"""Git adapter package for Terminal Agent."""
+
+from terminal_agent.git.adapter import GitAdapter, GitStatusResult, GitDiffStat
+
+__all__ = [
+    "GitAdapter",
+    "GitStatusResult",
+    "GitDiffStat",
+]
+