tsugite-cli 0.3.3__py3-none-any.whl

tsugite/tools/shell_tools.py

@@ -0,0 +1,214 @@
+"""Shell-based custom tools for Tsugite agents.
+
+This module provides a lightweight system for defining tools that wrap shell commands,
+allowing users to create custom tools without writing Python code.
+"""
+
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from tsugite.tools import tool
+from tsugite.utils import execute_shell_command
+
+
+class ShellToolParameter(BaseModel):
+    """Definition of a parameter for a shell tool."""
+
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+
+    name: str
+    type: str  # "str", "int", "bool", "float"
+    description: str = ""
+    required: bool = False
+    default: Any = None
+    flag: Optional[str] = None  # For boolean flags (e.g., "-s" for case_sensitive)
+
+    def validate(self, value: Any) -> Any:
+        """Validate and convert parameter value to correct type."""
+        if value is None:
+            if self.required:
+                raise ValueError(f"Required parameter '{self.name}' is missing")
+            return self.default
+
+        # Type conversion
+        if self.type == "str":
+            return str(value)
+        elif self.type == "int":
+            try:
+                return int(value)
+            except (ValueError, TypeError):
+                raise ValueError(f"Parameter '{self.name}' must be an integer")
+        elif self.type == "float":
+            try:
+                return float(value)
+            except (ValueError, TypeError):
+                raise ValueError(f"Parameter '{self.name}' must be a float")
+        elif self.type == "bool":
+            if isinstance(value, bool):
+                return value
+            if isinstance(value, str):
+                return value.lower() in ("true", "yes", "1", "y")
+            return bool(value)
+        else:
+            raise ValueError(f"Unknown parameter type: {self.type}")
+
+
+class ShellToolDefinition(BaseModel):
+    """Definition of a shell-based tool."""
+
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+
+    name: str
+    description: str
+    command: str  # Template string with {param} placeholders
+    parameters: Dict[str, ShellToolParameter] = Field(default_factory=dict)
+    timeout: int = 30
+    safe_mode: bool = True  # Use run_safe vs run
+    shell: bool = True  # Execute via shell
+
+
+def interpolate_command(command_template: str, params: Dict[str, Any]) -> str:
+    """Interpolate parameters into command template.
+
+    Args:
+        command_template: Command string with {param} placeholders
+        params: Dictionary of parameter values
+
+    Returns:
+        Interpolated command string
+
+    Example:
+        >>> interpolate_command("rg {pattern} {path}", {"pattern": "test", "path": "."})
+        'rg test .'
+    """
+    # Handle boolean flags specially
+    interpolated = command_template
+
+    # First, handle any boolean parameters with flags
+    for key, value in params.items():
+        # If value is boolean and the key appears with a flag placeholder
+        if isinstance(value, bool):
+            # Replace {key} with flag or empty string
+            flag_value = params.get(f"_flag_{key}", "")
+            if value and flag_value:
+                interpolated = interpolated.replace(f"{{{key}}}", flag_value)
+            else:
+                interpolated = interpolated.replace(f"{{{key}}}", "")
+
+    # Then handle regular parameter substitution
+    try:
+        interpolated = interpolated.format(**params)
+    except KeyError as e:
+        raise ValueError(f"Missing required parameter in command template: {e}")
+
+    return interpolated.strip()
+
+
+def create_shell_tool_function(definition: ShellToolDefinition):
+    """Create a Python function that executes a shell tool.
+
+    Args:
+        definition: Shell tool definition
+
+    Returns:
+        Callable function that can be registered as a tool
+    """
+    import inspect
+
+    def shell_tool_func(**kwargs) -> str:
+        """Dynamically generated shell tool function."""
+        # Validate and process parameters
+        processed_params = {}
+
+        for param_name, param_def in definition.parameters.items():
+            value = kwargs.get(param_name)
+            validated_value = param_def.validate(value)
+
+            # Handle boolean flags
+            if param_def.type == "bool" and param_def.flag:
+                if validated_value:
+                    processed_params[f"_flag_{param_name}"] = param_def.flag
+                processed_params[param_name] = validated_value
+            else:
+                processed_params[param_name] = validated_value
+
+        # Interpolate command
+        try:
+            command = interpolate_command(definition.command, processed_params)
+        except Exception as e:
+            raise RuntimeError(f"Failed to build command: {e}")
+
+        # Execute command
+        return execute_shell_command(command, timeout=definition.timeout, shell=definition.shell)
+
+    # Set function metadata for tool registration
+    shell_tool_func.__name__ = definition.name
+    shell_tool_func.__doc__ = definition.description
+
+    # Build proper signature with actual parameters
+    # This is critical for @tool decorator to work correctly
+    params = []
+    annotations = {}
+
+    for param_name, param_def in definition.parameters.items():
+        # Map our types to Python types
+        if param_def.type == "str":
+            param_type = str
+        elif param_def.type == "int":
+            param_type = int
+        elif param_def.type == "bool":
+            param_type = bool
+        elif param_def.type == "float":
+            param_type = float
+        else:
+            param_type = str
+
+        annotations[param_name] = param_type
+
+        # Create Parameter with default if not required
+        if param_def.required:
+            param = inspect.Parameter(
+                param_name,
+                inspect.Parameter.KEYWORD_ONLY,
+                annotation=param_type,
+            )
+        else:
+            param = inspect.Parameter(
+                param_name,
+                inspect.Parameter.KEYWORD_ONLY,
+                default=param_def.default,
+                annotation=param_type,
+            )
+        params.append(param)
+
+    # Create new signature and assign it
+    new_sig = inspect.Signature(params)
+    shell_tool_func.__signature__ = new_sig
+    shell_tool_func.__annotations__ = annotations
+
+    return shell_tool_func
+
+
+def register_shell_tool(definition: ShellToolDefinition) -> None:
+    """Register a shell tool definition as a tool.
+
+    Args:
+        definition: Shell tool definition to register
+    """
+    func = create_shell_tool_function(definition)
+    tool(func)
+
+
+def register_shell_tools(definitions: List[ShellToolDefinition]) -> None:
+    """Register multiple shell tool definitions.
+
+    Args:
+        definitions: List of shell tool definitions to register
+    """
+    for definition in definitions:
+        register_shell_tool(definition)

tsugite/tools/tasks.py

@@ -0,0 +1,339 @@
+"""Task tracking tools for agents to manage work across execution steps."""
+
+from datetime import datetime
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from . import tool
+
+
+class TaskStatus(Enum):
+    """Valid status values for tasks."""
+
+    PENDING = "pending"
+    IN_PROGRESS = "in_progress"
+    COMPLETED = "completed"
+    BLOCKED = "blocked"
+    CANCELLED = "cancelled"
+
+
+class Task(BaseModel):
+    """Individual task with metadata."""
+
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+
+    id: int
+    title: str
+    status: TaskStatus
+    parent_id: Optional[int] = None
+    optional: bool = False
+    created_at: datetime = Field(default_factory=datetime.now)
+    updated_at: datetime = Field(default_factory=datetime.now)
+    completed_at: Optional[datetime] = None
+
+
+class TaskManager:
+    """Manages tasks during a single agent execution session."""
+
+    def __init__(self):
+        self.tasks: Dict[int, Task] = {}
+        self._next_id = 1
+
+    def add_task(
+        self,
+        title: str,
+        status: TaskStatus = TaskStatus.PENDING,
+        parent_id: Optional[int] = None,
+        optional: bool = False,
+    ) -> int:
+        """Add a new task and return its ID."""
+        task_id = self._next_id
+        self._next_id += 1
+
+        if parent_id is not None and parent_id not in self.tasks:
+            raise ValueError(f"Parent task {parent_id} does not exist")
+
+        task = Task(id=task_id, title=title, status=status, parent_id=parent_id, optional=optional)
+
+        self.tasks[task_id] = task
+        return task_id
+
+    def update_task(self, task_id: int, status: TaskStatus) -> None:
+        """Update a task's status."""
+        if task_id not in self.tasks:
+            raise ValueError(f"Task {task_id} does not exist")
+
+        task = self.tasks[task_id]
+        task.status = status
+        task.updated_at = datetime.now()
+
+        if status == TaskStatus.COMPLETED:
+            task.completed_at = datetime.now()
+
+    def get_task(self, task_id: int) -> Task:
+        """Get a specific task by ID."""
+        if task_id not in self.tasks:
+            raise ValueError(f"Task {task_id} does not exist")
+        return self.tasks[task_id]
+
+    def list_tasks(self, status: Optional[TaskStatus] = None, parent_id: Optional[int] = None) -> List[Task]:
+        """List tasks with optional filtering."""
+        tasks = list(self.tasks.values())
+
+        if status is not None:
+            tasks = [t for t in tasks if t.status == status]
+
+        if parent_id is not None:
+            tasks = [t for t in tasks if t.parent_id == parent_id]
+
+        # Sort by creation time
+        return sorted(tasks, key=lambda t: t.created_at)
+
+    def get_tasks_for_template(self) -> List[Dict[str, Any]]:
+        """Get all tasks as template-friendly dicts.
+
+        Returns same format as task_list() tool for consistency.
+        Useful for iterating over tasks in Jinja2 templates.
+
+        Returns:
+            List of task dictionaries with all fields
+        """
+        tasks = self.list_tasks()
+
+        return [
+            {
+                "id": task.id,
+                "title": task.title,
+                "status": task.status.value,
+                "parent_id": task.parent_id,
+                "optional": task.optional,
+                "created_at": task.created_at.isoformat(),
+                "updated_at": task.updated_at.isoformat(),
+                "completed_at": task.completed_at.isoformat() if task.completed_at else None,
+            }
+            for task in tasks
+        ]
+
+    def get_task_summary(self) -> str:
+        """Generate a formatted summary of all tasks for agent context."""
+        if not self.tasks:
+            return "## Current Tasks\nNo tasks yet."
+
+        total_tasks = len(self.tasks)
+        completed_tasks = len([t for t in self.tasks.values() if t.status == TaskStatus.COMPLETED])
+
+        summary = [f"## Current Tasks ({completed_tasks} completed / {total_tasks} total)\n"]
+
+        # Group tasks by status
+        status_groups = {
+            "Active Tasks": [TaskStatus.IN_PROGRESS, TaskStatus.PENDING],
+            "Blocked Tasks": [TaskStatus.BLOCKED],
+            "Completed Tasks": [TaskStatus.COMPLETED],
+            "Cancelled Tasks": [TaskStatus.CANCELLED],
+        }
+
+        status_icons = {
+            TaskStatus.PENDING: "⏸️",
+            TaskStatus.IN_PROGRESS: "⏳",
+            TaskStatus.COMPLETED: "✅",
+            TaskStatus.BLOCKED: "🚫",
+            TaskStatus.CANCELLED: "❌",
+        }
+
+        for group_name, statuses in status_groups.items():
+            group_tasks = [t for t in self.tasks.values() if t.status in statuses]
+            if not group_tasks:
+                continue
+
+            summary.append(f"### {group_name}")
+
+            # Show parent tasks first, then their subtasks indented
+            parent_tasks = [t for t in group_tasks if t.parent_id is None]
+            parent_tasks.sort(key=lambda t: t.id)
+
+            for parent in parent_tasks:
+                icon = status_icons[parent.status]
+                optional_marker = " ✨ (optional)" if parent.optional else ""
+                summary.append(f"[{parent.id}] {icon} {parent.title}{optional_marker}")
+
+                # Show subtasks indented
+                subtasks = [t for t in group_tasks if t.parent_id == parent.id]
+                subtasks.sort(key=lambda t: t.id)
+                for subtask in subtasks:
+                    sub_icon = status_icons[subtask.status]
+                    sub_optional = " ✨ (optional)" if subtask.optional else ""
+                    summary.append(f"  └─ [{subtask.id}] {sub_icon} {subtask.title}{sub_optional}")
+
+            # Show orphaned subtasks (parent not in this group)
+            orphaned = [
+                t for t in group_tasks if t.parent_id is not None and t.parent_id not in [p.id for p in parent_tasks]
+            ]
+            for orphan in orphaned:
+                icon = status_icons[orphan.status]
+                optional_marker = " ✨ (optional)" if orphan.optional else ""
+                summary.append(f"[{orphan.id}] {icon} {orphan.title}{optional_marker} (subtask of #{orphan.parent_id})")
+
+            summary.append("")
+
+        summary.append("Status: ⏸️ pending | ⏳ in_progress | ✅ completed | 🚫 blocked | ❌ cancelled")
+
+        return "\n".join(summary)
+
+
+# Global task manager instance for the current agent session
+_task_manager: Optional[TaskManager] = None
+
+
+def get_task_manager() -> TaskManager:
+    """Get the current task manager instance."""
+    global _task_manager
+    if _task_manager is None:
+        _task_manager = TaskManager()
+    return _task_manager
+
+
+def reset_task_manager() -> None:
+    """Reset the task manager (used at start of new agent session)."""
+    global _task_manager
+    _task_manager = TaskManager()
+
+
+@tool
+def task_add(title: str, status: str = "pending", parent_id: Optional[int] = None, optional: bool = False) -> int:
+    """Add a new task or subtask.
+
+    Args:
+        title: Description of the task
+        status: Task status (pending/in_progress/completed/blocked/cancelled)
+        parent_id: ID of parent task if this is a subtask (omit or use None for root tasks)
+        optional: Whether this task is optional (nice-to-have vs required)
+
+    Returns:
+        ID of the created task
+    """
+    try:
+        task_status = TaskStatus(status)
+    except ValueError:
+        valid_statuses = [s.value for s in TaskStatus]
+        raise ValueError(f"Invalid status '{status}'. Valid options: {valid_statuses}")
+
+    # Treat 0 as None (root task) for convenience
+    if parent_id == 0:
+        parent_id = None
+
+    manager = get_task_manager()
+    return manager.add_task(title, task_status, parent_id, optional)
+
+
+@tool
+def task_update(task_id: int, status: str) -> str:
+    """Update a task's status.
+
+    Args:
+        task_id: ID of the task to update
+        status: New status (pending/in_progress/completed/blocked/cancelled)
+
+    Returns:
+        Confirmation message with task details and new status
+    """
+    try:
+        task_status = TaskStatus(status)
+    except ValueError:
+        valid_statuses = [s.value for s in TaskStatus]
+        raise ValueError(f"Invalid status '{status}'. Valid options: {valid_statuses}")
+
+    manager = get_task_manager()
+    task = manager.get_task(task_id)  # Get task before updating to include title in response
+    manager.update_task(task_id, task_status)
+
+    # Use status icons for visual clarity
+    status_icons = {
+        "pending": "⏸️",
+        "in_progress": "⏳",
+        "completed": "✅",
+        "blocked": "🚫",
+        "cancelled": "❌",
+    }
+    icon = status_icons.get(status, "")
+    return f"{icon} Updated task #{task_id}: '{task.title}' → {status}"
+
+
+@tool
+def task_complete(task_id: int) -> str:
+    """Mark a task as completed (shortcut for task_update).
+
+    Args:
+        task_id: ID of the task to mark as completed
+
+    Returns:
+        Confirmation message with task details
+    """
+    manager = get_task_manager()
+    task = manager.get_task(task_id)  # Get task before updating to include title in response
+    manager.update_task(task_id, TaskStatus.COMPLETED)
+    return f"✅ Completed task #{task_id}: '{task.title}'"
+
+
+@tool
+def task_list(status: Optional[str] = None) -> List[Dict[str, Any]]:
+    """List tasks with optional status filtering.
+
+    Args:
+        status: Optional status filter (pending/in_progress/completed/blocked/cancelled)
+
+    Returns:
+        List of task dictionaries with id, title, status, parent_id
+    """
+    status_filter = None
+    if status is not None:
+        try:
+            status_filter = TaskStatus(status)
+        except ValueError:
+            valid_statuses = [s.value for s in TaskStatus]
+            raise ValueError(f"Invalid status '{status}'. Valid options: {valid_statuses}")
+
+    manager = get_task_manager()
+    tasks = manager.list_tasks(status_filter)
+
+    return [
+        {
+            "id": task.id,
+            "title": task.title,
+            "status": task.status.value,
+            "parent_id": task.parent_id,
+            "optional": task.optional,
+            "created_at": task.created_at.isoformat(),
+            "updated_at": task.updated_at.isoformat(),
+            "completed_at": task.completed_at.isoformat() if task.completed_at else None,
+        }
+        for task in tasks
+    ]
+
+
+@tool
+def task_get(task_id: int) -> Dict[str, Any]:
+    """Get details for a specific task.
+
+    Args:
+        task_id: ID of the task to retrieve
+
+    Returns:
+        Task dictionary with all details
+    """
+    manager = get_task_manager()
+    task = manager.get_task(task_id)
+
+    return {
+        "id": task.id,
+        "title": task.title,
+        "status": task.status.value,
+        "parent_id": task.parent_id,
+        "optional": task.optional,
+        "created_at": task.created_at.isoformat(),
+        "updated_at": task.updated_at.isoformat(),
+        "completed_at": task.completed_at.isoformat() if task.completed_at else None,
+    }

tsugite/tsugite.py

@@ -0,0 +1,7 @@
+#!/usr/bin/env python3
+"""Tsugite CLI application - entrypoint."""
+
+from tsugite.cli import app
+
+if __name__ == "__main__":
+    app()

tsugite/ui/__init__.py

@@ -0,0 +1,46 @@
+"""UI system for controlling agent execution display.
+
+This module provides a flexible UI system with multiple handlers:
+- CustomUIHandler: Rich UI with panels, colors, and emojis (default)
+- PlainUIHandler: Plain text output for copy-paste workflows
+- LiveTemplateHandler: Live Display with Tree and interactive prompts
+- TextualUIHandler: Textual TUI chat interface handler
+
+Use the helper functions to create loggers:
+- custom_agent_ui(): Context manager for rich UI
+- create_plain_logger(): Plain text logger
+- create_live_template_logger(): Live display with tree visualization
+"""
+
+from tsugite.ui.base import CustomUIHandler, CustomUILogger, UIState
+from tsugite.ui.chat import ChatManager, ChatTurn
+from tsugite.ui.helpers import (
+    create_live_template_logger,
+    create_plain_logger,
+    custom_agent_ui,
+)
+from tsugite.ui.live_template import LiveTemplateHandler
+from tsugite.ui.plain import PlainUIHandler
+from tsugite.ui.textual_handler import TextualUIHandler
+
+# Import textual_chat to make it accessible as attribute for tests
+# Must be after other imports since textual_chat imports from tsugite.ui
+from tsugite.ui import textual_chat  # noqa: F401  # isort: skip
+
+__all__ = [
+    # Core classes
+    "UIState",
+    "CustomUILogger",
+    # UI Handlers
+    "CustomUIHandler",
+    "PlainUIHandler",
+    "LiveTemplateHandler",
+    "TextualUIHandler",
+    # Chat functionality
+    "ChatManager",
+    "ChatTurn",
+    # Helper functions
+    "custom_agent_ui",
+    "create_plain_logger",
+    "create_live_template_logger",
+]