grucli 3.3.0__py3-none-any.whl

grucli/permissions.py

@@ -0,0 +1,181 @@
+"""
+Per-tool-call permission system for grucli.
+Implements granular permissions with session-scoped "Allow always" functionality.
+"""
+
+from enum import Enum
+from typing import Set, Dict, Optional, Tuple
+from .theme import Colors, Borders, Icons, Styles, get_terminal_width
+
+
+class PermissionGroup(Enum):
+    """Permission categories for tool operations."""
+    READ = "read"           # read_file, get_current_directory_structure
+    WRITE = "write"         # create_file, edit_file
+    DESTRUCTIVE = "delete"  # delete_file
+
+
+# Tool-to-permission-group mapping
+TOOL_PERMISSION_MAP: Dict[str, PermissionGroup] = {
+    'read_file': PermissionGroup.READ,
+    'get_current_directory_structure': PermissionGroup.READ,
+    'create_file': PermissionGroup.WRITE,
+    'edit_file': PermissionGroup.WRITE,
+    'delete_file': PermissionGroup.DESTRUCTIVE,
+}
+
+
+# Human-readable descriptions for permission groups
+PERMISSION_DESCRIPTIONS: Dict[PermissionGroup, str] = {
+    PermissionGroup.READ: "Read files and directory structure",
+    PermissionGroup.WRITE: "Create and modify files",
+    PermissionGroup.DESTRUCTIVE: "Delete files permanently",
+}
+
+
+# Colors for permission groups
+PERMISSION_COLORS: Dict[PermissionGroup, str] = {
+    PermissionGroup.READ: Colors.READ_OP,
+    PermissionGroup.WRITE: Colors.WRITE_OP,
+    PermissionGroup.DESTRUCTIVE: Colors.DESTRUCTIVE_OP,
+}
+
+
+# Icons for permission groups
+PERMISSION_ICONS: Dict[PermissionGroup, str] = {
+    PermissionGroup.READ: Icons.READ,
+    PermissionGroup.WRITE: Icons.WRITE,
+    PermissionGroup.DESTRUCTIVE: Icons.DELETE,
+}
+
+
+class PermissionStore:
+    """
+    Session-scoped permission storage.
+    Tracks which permission groups have been granted "Allow always".
+    Resets when the session ends.
+    """
+    
+    def __init__(self):
+        self._allowed_always: Set[PermissionGroup] = set()
+    
+    def is_allowed(self, group: PermissionGroup) -> bool:
+        """Check if a permission group is already allowed."""
+        return group in self._allowed_always
+    
+    def allow_always(self, group: PermissionGroup) -> None:
+        """Grant persistent permission for this session."""
+        self._allowed_always.add(group)
+        # If allowing write (edits), also allow read
+        if group == PermissionGroup.WRITE:
+            self._allowed_always.add(PermissionGroup.READ)
+
+    def revoke_always(self, group: PermissionGroup) -> None:
+        """Revoke persistent permission for this session."""
+        self._allowed_always.discard(group)
+    
+    def reset(self) -> None:
+        """Clear all permissions (called on session end)."""
+        self._allowed_always.clear()
+    
+    def get_allowed_groups(self) -> Set[PermissionGroup]:
+        """Get all currently allowed permission groups."""
+        return self._allowed_always.copy()
+
+
+# Global permission store instance
+PERMISSION_STORE = PermissionStore()
+
+
+def get_tool_permission_group(tool_name: str) -> Optional[PermissionGroup]:
+    """Get the permission group for a tool."""
+    return TOOL_PERMISSION_MAP.get(tool_name)
+
+
+def format_tool_for_permission(tool_name: str, args: dict) -> str:
+    """Format a tool call for display in permission prompt."""
+    group = get_tool_permission_group(tool_name)
+    if not group:
+        return f"{tool_name}(...)"
+    
+    color = PERMISSION_COLORS.get(group, Colors.WHITE)
+    icon = PERMISSION_ICONS.get(group, "")
+    
+    # Format args nicely
+    arg_parts = []
+    for key, value in args.items():
+        if isinstance(value, str) and len(value) > 50:
+            value = value[:47] + "..."
+        arg_parts.append(f"{Colors.MUTED}{key}={Colors.RESET}{repr(value)}")
+    
+    args_str = ", ".join(arg_parts) if arg_parts else ""
+    
+    return f"{color}{icon} {tool_name}{Colors.RESET}({args_str})"
+
+
+def prompt_permission(tool_name: str, args: dict) -> str:
+    """
+    Display permission prompt and get user decision.
+    
+    Returns:
+        'once' - Allow this single invocation
+        'always' - Allow all future calls in this permission group
+        'deny' - Deny this and all remaining tool calls
+    """
+    from . import interrupt
+    
+    group = get_tool_permission_group(tool_name)
+    if not group:
+        # Unknown tool - default to requiring permission
+        group = PermissionGroup.WRITE
+    
+    # Check if already allowed
+    if PERMISSION_STORE.is_allowed(group):
+        return 'always'
+    
+    color = PERMISSION_COLORS.get(group, Colors.WHITE)
+    
+    # Print options (the tool box is printed by main.py)
+    print(f"  {Colors.SUCCESS}1{Colors.RESET}) Allow once")
+    print(f"  {Colors.PRIMARY}2{Colors.RESET}) Allow always {Colors.MUTED}(this session, {group.value} operations){Colors.RESET}")
+    print(f"  {Colors.ERROR}3{Colors.RESET}) Deny {Colors.MUTED}(cancels all remaining operations){Colors.RESET}")
+    print()
+    
+    while True:
+        try:
+            choice = interrupt.safe_input(f"{color}Choose [1/2/3]: {Colors.RESET}").strip()
+            if choice in ['1', '2', '3']:
+                print("\033[A\033[K" * 5, end="", flush=True)
+            if choice == '1':
+                return 'once'
+            elif choice == '2':
+                PERMISSION_STORE.allow_always(group)
+                print(f"{Colors.SUCCESS}{Icons.CHECK} Allowed {group.value} operations for this session{Colors.RESET}")
+                return 'always'
+            elif choice == '3':
+                print(f"{Colors.WARNING}{Icons.WARNING} Operation denied{Colors.RESET}")
+                return 'deny'
+            else:
+                print(f"{Colors.ERROR}Please enter 1, 2, or 3{Colors.RESET}")
+                pass
+        except KeyboardInterrupt:
+            print(f"\n{Colors.WARNING}{Icons.WARNING} Operation cancelled{Colors.RESET}")
+            return 'deny'
+
+
+def check_permission(tool_name: str, args: dict) -> Tuple[bool, str]:
+    """
+    Check if a tool has permission to execute.
+    
+    Returns:
+        (allowed: bool, decision: str)
+        - allowed: Whether the tool can execute
+        - decision: 'once', 'always', or 'deny'
+    """
+    group = get_tool_permission_group(tool_name)
+    
+    if group and PERMISSION_STORE.is_allowed(group):
+        return True, 'always'
+    
+    decision = prompt_permission(tool_name, args)
+    return decision != 'deny', decision

grucli/stats.py

@@ -0,0 +1,100 @@
+"""
+Session statistics tracking for grucli.
+"""
+
+import time
+import uuid
+import sys
+from .theme import Colors, Borders, Icons
+
+
+class SessionStats:
+    """Track statistics for the current session."""
+    
+    def __init__(self):
+        self.session_id = str(uuid.uuid4())[:8]  # Short ID
+        self.start_time = time.time()
+        self.tool_calls_total = 0
+        self.tool_calls_success = 0
+        self.tool_calls_failed = 0
+        self.model_usage = {}  # {model_name: {'reqs': 0, 'input_tokens': 0, 'cache_reads': 0, 'output_tokens': 0}}
+        self.api_time_total = 0
+    
+    def record_tool_call(self, success=True):
+        """Record a tool call result."""
+        self.tool_calls_total += 1
+        if success:
+            self.tool_calls_success += 1
+        else:
+            self.tool_calls_failed += 1
+            
+    def record_request(self, model_name, api_duration=0):
+        """Record an API request."""
+        if model_name not in self.model_usage:
+            self.model_usage[model_name] = {'reqs': 0, 'input_tokens': 0, 'cache_reads': 0, 'output_tokens': 0}
+        self.model_usage[model_name]['reqs'] += 1
+        self.api_time_total += api_duration
+        
+    def record_tokens(self, model_name, input_tokens=0, output_tokens=0, cache_reads=0):
+        """Record token usage for a model."""
+        if model_name not in self.model_usage:
+            self.model_usage[model_name] = {'reqs': 0, 'input_tokens': 0, 'cache_reads': 0, 'output_tokens': 0}
+        self.model_usage[model_name]['input_tokens'] += input_tokens
+        self.model_usage[model_name]['output_tokens'] += output_tokens
+        self.model_usage[model_name]['cache_reads'] += cache_reads
+
+    def get_formatted_summary(self):
+        """Generate a formatted summary of the session."""
+        end_time = time.time()
+        wall_time = end_time - self.start_time
+        
+        minutes = int(wall_time // 60)
+        seconds = int(wall_time % 60)
+        wall_time_str = f"{minutes}m {seconds}s" if minutes > 0 else f"{seconds}s"
+        
+        tool_success_rate = 0.0
+        if self.tool_calls_total > 0:
+            tool_success_rate = (self.tool_calls_success / self.tool_calls_total) * 100
+            
+        api_time_pct = 0.0
+        if wall_time > 0:
+            api_time_pct = (self.api_time_total / wall_time) * 100
+
+        summary = []
+        
+        # Header
+        summary.append("")
+        summary.append(f"{Colors.MUTED}{Borders.HORIZONTAL * 50}{Colors.RESET}")
+        summary.append(f"{Colors.PRIMARY}{Colors.BOLD}Session Summary{Colors.RESET}  {Colors.MUTED}#{self.session_id}{Colors.RESET}")
+        summary.append(f"{Colors.MUTED}{Borders.HORIZONTAL * 50}{Colors.RESET}")
+        
+        # Time
+        summary.append(f"  {Colors.MUTED}Duration:{Colors.RESET}    {Colors.WHITE}{wall_time_str}{Colors.RESET}")
+        summary.append(f"  {Colors.MUTED}API Time:{Colors.RESET}    {Colors.WHITE}{self.api_time_total:.1f}s{Colors.RESET} {Colors.MUTED}({api_time_pct:.0f}%){Colors.RESET}")
+        
+        # Tools
+        if self.tool_calls_total > 0:
+            success_color = Colors.SUCCESS if self.tool_calls_failed == 0 else Colors.WARNING
+            summary.append(f"  {Colors.MUTED}Tool Calls:{Colors.RESET}  {Colors.WHITE}{self.tool_calls_total}{Colors.RESET} {Colors.MUTED}({Colors.SUCCESS}{Icons.CHECK}{self.tool_calls_success}{Colors.MUTED} {Colors.ERROR}{Icons.CROSS}{self.tool_calls_failed}{Colors.MUTED}){Colors.RESET}")
+        
+        # Model usage
+        if self.model_usage:
+            summary.append("")
+            summary.append(f"  {Colors.MUTED}Models Used:{Colors.RESET}")
+            for model, usage in self.model_usage.items():
+                # Truncate long model names
+                display_model = model if len(model) < 30 else model[:27] + "..."
+                summary.append(f"    {Colors.SECONDARY}{display_model}{Colors.RESET} {Colors.MUTED}({usage['reqs']} requests){Colors.RESET}")
+
+        summary.append(f"{Colors.MUTED}{Borders.HORIZONTAL * 50}{Colors.RESET}")
+        summary.append("")
+        
+        return "\n".join(summary)
+
+    def print_summary(self):
+        """Print the session summary."""
+        print(self.get_formatted_summary())
+
+
+# Global instance
+STATS = SessionStats()

grucli/sysprompts/main_sysprompt.txt

@@ -0,0 +1,65 @@
+# Agentic CLI LLM
+
+You are a precise local development assistant. You operate strictly within the current directory using relative paths.
+
+## Environment & Paths
+- **Relative Paths Only**: Use paths starting with `/` relative to the project root (e.g., `/src/main.py`). Never use absolute paths or `../`.
+- **Context**: The current project structure is:
+<auto_inject_file_tree>
+Read files before assuming their content.
+
+## Tools
+Call tools using Python syntax: `tool_name(arg="value")`. 
+
+**Recommended: One Tool Call Per Response**: It is generally best to run only one tool call per response for reliability. However, if the situation clearly benefits—such as when making multiple small, non-conflicting edits—you may batch several tool calls together in a single response. Use your judgment and prioritize reliability.
+
+- `read_file(path, start_line=None, end_line=None)`: Reads file content. Use `start_line` and `end_line` (1-indexed) for large files.
+- `create_file(path, content)`: Creates a new file (and directories if needed).
+- `edit_file(path, old_string, new_string)`: Replaces the **exact, unique** occurrence of `old_string`. Always provide enough context in `old_string` to ensure it only matches once.
+- `delete_file(path)`: Deletes a file. Use with caution.
+- `get_current_directory_structure()`: Returns the latest file tree. ONLY use if a file is not found or you don't know where it is.
+
+## STRICT Tool Usage Protocols (CRITICAL)
+
+### 1. NO Redundant Verification (MOST IMPORTANT)
+- **NEVER** immediately read a file you just created or edited. Trust that the tool worked.
+- **NEVER** read a file if the user provided the full content in the prompt.
+- **Exception**: Only read back if you encounter a specific error message or if the user explicitly asks "Verify the file content".
+- **ANTI-PATTERN (DO NOT DO THIS)**: 
+    1. `create_file(path="script.py", ...)`
+    2. "Now I will read it to verify." -> `read_file(path="script.py")` <--- WRONG! STOP!
+
+### 2. When NOT to use tools
+- **Chat**: "Hello", "Thanks", "What is Python?" -> **No tools**. Text only. Respond naturally and politely to pleasantries.
+- **Clarification**: Need more info? Ask text questions. Don't scan directory or read files just to "look busy".
+- **Redundancy**: NEVER use a tool if the information is already present in the prompt or recent context.
+- **Empty Directory**: If context says "Current directory empty", **do not** run `get_current_directory_structure()`.
+- **Directory Structure**: NEVER use `get_current_directory_structure()` unless a file is not found or when the user explicitly asks for it.
+
+### 3. When to USE tools
+- **Mandatory Action**: If the user asks for a code change, bug fix, or new file, you **MUST** use the appropriate tool (`create_file`, `edit_file`). **Never** output code blocks as plain text if the intent is to modify the codebase.
+- **Exploration**: ONLY if a file is not found in the provided tree, or the user explicitly asks for it -> `get_current_directory_structure()`
+- **Modifying**: "Fix the bug in line 10" -> `read_file(...)` (to find context) -> `edit_file(...)`.
+
+## Rules of Engagement
+1. **Tool Invocation**: Any tool call **must be the final output** of your response. 
+2. **No Post-Tool Talk**: Do not add explanations, summaries, or "Done" messages after a tool call.
+3. **Atomic Changes**: Prefer small, verifiable edits over large rewrites. Instead of trying to edit a full 100-line function in a single tool call, batch multiple smaller tool calls in the same response—each operating on a small part (e.g., a few lines) of the function.  
+   - **Example**:  
+     Instead of:  
+     `edit_file(path="/foo.py", old_string="(entire 100-line function)", new_string="(entire new function)")`  
+     Prefer:  
+     ```  
+     edit_file(path="/foo.py", old_string="def foo(...):\n    # lines 1-10", new_string="def foo(...):\n    # updated lines 1-10")  
+     edit_file(path="/foo.py", old_string="    # lines 11-20", new_string="    # updated lines 11-20")  
+     ```  
+     This greatly reduces risk and aids verification.
+4. **No Hallucinations**: If a file path isn't in the tree and you don't know where it is, use `get_current_directory_structure()`. Do not use it otherwise.
+5. **Conciseness**: Minimize fluff. Focus on reasoning and action. However, do not be robotic; acknowledge greetings and thanks naturally alongside normal language.
+6. **Tool Necessity**: Only trigger tools when a task requires action or specific information not present in the current prompt context. Avoid "informational" tool calls if you can answer from context.
+7. **No Passive Code Blocks**: If the user's request implies a file modification, never output a markdown code block alone. You must call the relevant tool.
+8. **Efficiency**: Use your existing knowledge and the provided file tree to answer simple questions before reaching for a tool.
+
+## Example output
+I'll check the config before updating it.
+read_file(path="/config.json")

grucli/theme.py

@@ -0,0 +1,144 @@
+"""
+Centralized theme and color constants for grucli UI.
+All ANSI color codes and styling are defined here for consistency.
+"""
+
+from enum import Enum
+
+
+class Colors:
+    """ANSI color codes for terminal output."""
+    
+    # Branding colors
+    PRIMARY = "\033[38;5;33m"      # Deep sky blue (better contrast than 39)
+    SECONDARY = "\033[38;5;135m"   # Medium purple (better contrast than 141)
+    ACCENT = "\033[38;5;214m"     # Orange/Gold
+    
+    # Semantic colors
+    SUCCESS = "\033[38;5;71m"      # Medium green
+    WARNING = "\033[38;5;214m"     # Orange
+    ERROR = "\033[38;5;196m"       # Red
+    INFO = "\033[38;5;33m"         # Blue
+    MUTED = "\033[38;5;244m"       # Medium gray (readable on both)
+    WHITE = "\033[97m"             # Bright white
+    THINK_COLOR = "\033[38;5;213m" # Pinkish for reasoning
+    
+    # Tool category colors
+    READ_OP = "\033[38;5;45m"      # Cyan for read operations
+    WRITE_OP = "\033[38;5;214m"    # Orange for write operations
+    DESTRUCTIVE_OP = "\033[91m"   # Red for destructive operations
+    
+    # UI element colors
+    PROMPT = "\033[38;5;39;1m"    # Bold blue for prompts
+    HEADER = "\033[1;4m"          # Bold underline for headers
+    TITLE = "\033[38;5;39;1m"     # Bold blue for titles
+    SUBTITLE = "\033[38;5;245m"   # Dim gray for subtitles
+    
+    # Text modifiers
+    DIM = "\033[2m"
+    BOLD = "\033[1m"
+    ITALIC = "\033[3m"
+    UNDERLINE = "\033[4m"
+    REVERSE = "\033[7m"
+    RESET = "\033[0m"
+    
+    # Input states
+    INPUT_ACTIVE = "\033[38;5;39m"      # Blue for active input
+    INPUT_DISABLED = "\033[38;5;240m"   # Dark gray for disabled
+    INPUT_CONFIRM = "\033[38;5;220m"    # Gold for confirmation
+    INPUT_ERROR = "\033[91m"            # Red for error state
+
+
+class Borders:
+    """Box drawing characters for clean UI elements."""
+    
+    # Rounded corners
+    TOP_LEFT = "╭"
+    TOP_RIGHT = "╮"
+    BOTTOM_LEFT = "╰"
+    BOTTOM_RIGHT = "╯"
+    
+    # Lines
+    HORIZONTAL = "─"
+    VERTICAL = "│"
+    
+    # T-junctions
+    T_LEFT = "├"
+    T_RIGHT = "┤"
+    T_TOP = "┬"
+    T_BOTTOM = "┴"
+    
+    # Cross
+    CROSS = "┼"
+
+
+class Icons:
+    """Unicode icons for visual enhancement."""
+    
+    # Status icons
+    CHECK = "✓"
+    CROSS = "✗"
+    WARNING = "⚠"
+    INFO = "ℹ"
+    
+    # Tool icons
+    READ = "[READ]"
+    WRITE = "[WRITE]"
+    DELETE = "[DELETE]"
+    FOLDER = "[FOLDER]"
+    
+    # UI icons
+    ARROW_RIGHT = "→"
+    ARROW_DOWN = "↓"
+    BULLET = "•"
+    DIAMOND = "◆"
+    CIRCLE = "○"
+    CIRCLE_FILLED = "●"
+    
+    # Spinner frames
+    SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"]
+
+
+class Styles:
+    """Pre-composed style combinations."""
+    
+    @staticmethod
+    def success(text: str) -> str:
+        return f"{Colors.SUCCESS}{text}{Colors.RESET}"
+    
+    @staticmethod
+    def error(text: str) -> str:
+        return f"{Colors.ERROR}{text}{Colors.RESET}"
+    
+    @staticmethod
+    def warning(text: str) -> str:
+        return f"{Colors.WARNING}{text}{Colors.RESET}"
+    
+    @staticmethod
+    def info(text: str) -> str:
+        return f"{Colors.INFO}{text}{Colors.RESET}"
+    
+    @staticmethod
+    def muted(text: str) -> str:
+        return f"{Colors.MUTED}{text}{Colors.RESET}"
+    
+    @staticmethod
+    def bold(text: str) -> str:
+        return f"{Colors.BOLD}{text}{Colors.RESET}"
+    
+    @staticmethod
+    def primary(text: str) -> str:
+        return f"{Colors.PRIMARY}{text}{Colors.RESET}"
+    
+    @staticmethod
+    def accent(text: str) -> str:
+        return f"{Colors.ACCENT}{text}{Colors.RESET}"
+
+
+def get_terminal_width() -> int:
+    """Get terminal width, defaulting to 80 if unavailable."""
+    import shutil
+    try:
+        return shutil.get_terminal_size().columns
+    except Exception:
+        return 80