tsugite-cli 0.3.3__py3-none-any.whl

tsugite/agent_runner/validation.py

@@ -0,0 +1,70 @@
+"""Agent validation and information utilities."""
+
+from pathlib import Path
+from typing import Any, Dict
+
+from tsugite.md_agents import parse_agent_file, validate_agent_execution
+
+
+def validate_agent_file(agent_path: Path) -> tuple[bool, str]:
+    """Validate that an agent file can be executed.
+
+    Args:
+        agent_path: Path to agent markdown file (or builtin agent path like <builtin-default>)
+
+    Returns:
+        Tuple of (is_valid, error_message)
+    """
+    try:
+        # Parse agent with inheritance resolution
+        agent = parse_agent_file(agent_path)
+
+        # Use centralized validation
+        return validate_agent_execution(agent)
+
+    except Exception as e:
+        return False, f"Agent file validation failed: {e}"
+
+
+def get_agent_info(agent_path: Path) -> Dict[str, Any]:
+    """Get information about an agent without executing it.
+
+    Args:
+        agent_path: Path to agent markdown file (or builtin agent path like <builtin-default>)
+
+    Returns:
+        Dictionary with agent information
+    """
+    try:
+        # Parse agent with inheritance resolution
+        agent = parse_agent_file(agent_path)
+        agent_config = agent.config
+
+        model_display = agent_config.model
+        if not model_display:
+            from tsugite.config import load_config
+
+            config = load_config()
+            if config.default_model:
+                model_display = f"{config.default_model} (default)"
+            else:
+                model_display = "not set"
+
+        return {
+            "name": agent_config.name,
+            "description": getattr(agent_config, "description", "No description"),
+            "model": model_display,
+            "max_turns": agent_config.max_turns,
+            "tools": agent_config.tools,
+            "prefetch_count": (len(agent_config.prefetch) if agent_config.prefetch else 0),
+            "attachments": agent_config.attachments,
+            "auto_context": getattr(agent_config, "auto_context", None),
+            "permissions_profile": getattr(agent_config, "permissions_profile", None),
+            "valid": validate_agent_file(agent_path)[0],
+            "instructions": getattr(agent_config, "instructions", ""),
+        }
+    except Exception as e:
+        return {
+            "error": str(e),
+            "valid": False,
+        }

tsugite/agent_utils.py

@@ -0,0 +1,167 @@
+"""Utility functions for agent management."""
+
+from pathlib import Path
+from typing import List, Tuple
+
+
+def _parse_agent_from_path(path: Path):
+    """Parse an agent from a file path.
+
+    Args:
+        path: Path to agent file
+
+    Returns:
+        Parsed Agent object
+    """
+    from tsugite.md_agents import parse_agent
+
+    # All agents are now file-based (including built-ins)
+    content = path.read_text(encoding="utf-8")
+    return parse_agent(content, path)
+
+
+def _is_valid_agent_file(path: Path) -> bool:
+    """Check if a file is a valid agent file.
+
+    Args:
+        path: Path to check
+
+    Returns:
+        True if file is a valid agent with a name field
+    """
+    try:
+        agent = _parse_agent_from_path(path)
+        return bool(agent.config.name)
+    except Exception:
+        return False
+
+
+def build_inheritance_chain(agent_path: Path) -> List[Tuple[str, Path]]:
+    """Build the inheritance chain for an agent.
+
+    Args:
+        agent_path: Path to the agent file
+
+    Returns:
+        List of (agent_name, agent_path) tuples in inheritance order (parent to child)
+    """
+    from tsugite.agent_inheritance import _get_default_base_agent_name, find_agent_file
+
+    chain = []
+    visited = set()
+
+    current_path = agent_path.resolve()
+    visited.add(current_path)
+
+    current_agent = _parse_agent_from_path(current_path)
+
+    if current_agent.config.extends and current_agent.config.extends != "none":
+        extends_chain = _get_parent_chain(current_agent.config.extends, current_path, visited.copy())
+        chain.extend(extends_chain)
+    elif current_agent.config.extends != "none":
+        # Auto-inherit from default base agent
+        # Priority: 1) Local .tsugite/default.md, 2) Config's default_base_agent
+        user_default_path = current_path.parent / ".tsugite" / "default.md"
+        default_path = None
+        default_name = None
+
+        if user_default_path.exists() and user_default_path.resolve() != current_path:
+            # Use local default.md if it exists
+            default_path = user_default_path
+            default_name = "default"
+        else:
+            # Fall back to config's default_base_agent
+            default_base_name = _get_default_base_agent_name()
+            if default_base_name:
+                default_path = find_agent_file(default_base_name, current_path.parent)
+                default_name = default_base_name
+
+        if default_path and default_path.resolve() != current_path:
+            chain.append((default_name, default_path))
+            visited.add(default_path.resolve())
+
+            default_agent = _parse_agent_from_path(default_path)
+            if default_agent.config.extends and default_agent.config.extends != "none":
+                parent_chain = _get_parent_chain(default_agent.config.extends, default_path, visited.copy())
+                # Insert at beginning (parents come before children)
+                chain = parent_chain + chain
+
+    chain.append((current_agent.config.name, current_path))
+
+    return chain
+
+
+def _get_parent_chain(extends_ref: str, current_path: Path, visited: set) -> List[Tuple[str, Path]]:
+    """Recursively get parent chain.
+
+    Args:
+        extends_ref: Reference to parent agent
+        current_path: Current agent path
+        visited: Set of already visited paths (for cycle detection)
+
+    Returns:
+        List of (agent_name, agent_path) tuples
+    """
+    from tsugite.agent_inheritance import find_agent_file
+
+    chain = []
+
+    parent_path = find_agent_file(extends_ref, current_path.parent)
+    if not parent_path:
+        return chain
+
+    parent_resolved = parent_path.resolve()
+    if parent_resolved in visited:
+        return chain
+
+    visited.add(parent_resolved)
+
+    parent_agent = _parse_agent_from_path(parent_path)
+
+    if parent_agent.config.extends and parent_agent.config.extends != "none":
+        grandparent_chain = _get_parent_chain(parent_agent.config.extends, parent_path, visited.copy())
+        chain.extend(grandparent_chain)
+
+    chain.append((parent_agent.config.name, parent_path))
+
+    return chain
+
+
+def list_local_agents(base_path: Path = None) -> dict[str, List[Path]]:
+    """List agents in local directories.
+
+    Args:
+        base_path: Base directory to search from (defaults to cwd)
+
+    Returns:
+        Dictionary mapping location names to list of agent paths
+    """
+    from .agent_inheritance import get_builtin_agents_path
+
+    if base_path is None:
+        base_path = Path.cwd()
+
+    results = {}
+
+    # Add built-in agents first
+    builtin_path = get_builtin_agents_path()
+    if builtin_path.exists() and builtin_path.is_dir():
+        builtin_agents = sorted(builtin_path.glob("*.md"))
+        if builtin_agents:
+            results["Built-in"] = builtin_agents
+
+    locations = [
+        ("Current directory", base_path),
+        (".tsugite/", base_path / ".tsugite"),
+        ("agents/", base_path / "agents"),
+    ]
+
+    for location_name, location_path in locations:
+        if location_path.exists() and location_path.is_dir():
+            all_md_files = sorted(location_path.glob("*.md"))
+            agent_files = [f for f in all_md_files if _is_valid_agent_file(f)]
+
+            if agent_files:
+                results[location_name] = agent_files
+
+    return results

tsugite/attachments/__init__.py

@@ -0,0 +1,65 @@
+"""Attachment handler system for different content sources."""
+
+from typing import List
+
+from tsugite.attachments.auto_context import AutoContextHandler
+from tsugite.attachments.base import AttachmentHandler
+from tsugite.attachments.file import FileHandler
+from tsugite.attachments.inline import InlineHandler
+from tsugite.attachments.storage import (
+    add_attachment,
+    get_attachment,
+    get_attachments_path,
+    list_attachments,
+    remove_attachment,
+    search_attachments,
+)
+from tsugite.attachments.url import GenericURLHandler
+from tsugite.attachments.youtube import YouTubeHandler
+
+__all__ = [
+    # Handlers
+    "AttachmentHandler",
+    "InlineHandler",
+    "FileHandler",
+    "YouTubeHandler",
+    "GenericURLHandler",
+    "AutoContextHandler",
+    "HANDLERS",
+    "get_handler",
+    # Storage functions
+    "add_attachment",
+    "get_attachment",
+    "get_attachments_path",
+    "list_attachments",
+    "remove_attachment",
+    "search_attachments",
+]
+
+# Handler registry - order matters! More specific handlers first
+HANDLERS: List[AttachmentHandler] = [
+    InlineHandler(),
+    AutoContextHandler(),  # Before FileHandler (might match file paths)
+    YouTubeHandler(),  # Before GenericURLHandler
+    FileHandler(),
+    GenericURLHandler(),  # Catch-all for URLs
+]
+
+
+def get_handler(source: str) -> AttachmentHandler:
+    """Get appropriate handler for a source.
+
+    Args:
+        source: Source string
+
+    Returns:
+        Handler that can process this source
+
+    Raises:
+        ValueError: If no handler found
+    """
+    for handler in HANDLERS:
+        if handler.can_handle(source):
+            return handler
+
+    raise ValueError(f"No handler found for source: {source}")

tsugite/attachments/auto_context.py

@@ -0,0 +1,199 @@
+"""Auto-context handler for discovering project context files."""
+
+import subprocess
+from pathlib import Path
+from typing import List, Optional
+
+from tsugite.attachments.base import AttachmentHandler
+
+
+class AutoContextHandler(AttachmentHandler):
+    """Handler for auto-discovering context files.
+
+    Searches from current directory up to git root for specific context files
+    like CONTEXT.md, AGENTS.md, CLAUDE.md and concatenates them.
+    """
+
+    def __init__(self, context_files: Optional[List[str]] = None):
+        """Initialize handler.
+
+        Args:
+            context_files: List of filenames to search for.
+                          If None, will use config at fetch time.
+        """
+        self.context_files = context_files
+
+    def can_handle(self, source: str) -> bool:
+        """Check if source is auto-context marker.
+
+        Args:
+            source: Source string
+
+        Returns:
+            True if source is "auto-context" or starts with "auto:"
+        """
+        return source in ("auto-context", "auto") or source.startswith("auto:")
+
+    def fetch(self, source: str) -> str:
+        """Not supported. Use fetch_multiple() instead.
+
+        Args:
+            source: Source string
+
+        Raises:
+            NotImplementedError: This method is not supported
+        """
+        raise NotImplementedError("AutoContextHandler.fetch() is not supported. Use fetch_multiple() instead.")
+
+    def fetch_multiple(self, source: str) -> List[tuple[str, str]]:
+        """Discover context files and return as separate attachments.
+
+        Args:
+            source: Auto-context marker
+
+        Returns:
+            List of (attachment_name, content) tuples, one per discovered file
+
+        Raises:
+            ValueError: If discovery fails
+        """
+        try:
+            found_files = self._discover_context_files()
+
+            result = []
+            for file_path, relative_name in found_files:
+                try:
+                    content = file_path.read_text(encoding="utf-8")
+                    # Use the relative name as the attachment name
+                    result.append((relative_name, content))
+                except Exception as e:
+                    # Add error as attachment content for visibility
+                    error_content = f"# Error reading {relative_name}\n\n{str(e)}"
+                    result.append((relative_name, error_content))
+
+            return result
+        except Exception as e:
+            raise ValueError(f"Failed to fetch auto-context: {e}")
+
+    def _discover_context_files(self) -> List[tuple[Path, str]]:
+        """Discover all context files from project and global locations.
+
+        Returns:
+            List of (file_path, display_name) tuples for found files
+        """
+        # Load context files from config if not set at init
+        context_files = self.context_files
+        include_global = True
+        if context_files is None:
+            from tsugite.config import load_config
+
+            config = load_config()
+            context_files = config.auto_context_files
+            include_global = config.auto_context_include_global
+
+        cwd = Path.cwd()
+        git_root = self._find_git_root(cwd)
+
+        # Search from cwd up to git root (or just cwd if not in git repo)
+        search_dirs = self._get_search_directories(cwd, git_root)
+
+        # Find all project context files
+        found_files = self._discover_files(search_dirs, context_files)
+
+        # Add global context file if enabled
+        if include_global:
+            global_file = self._get_global_context_file()
+            if global_file:
+                found_files.append(global_file)
+
+        return found_files
+
+    def _find_git_root(self, start_dir: Path) -> Optional[Path]:
+        """Find git repository root.
+
+        Args:
+            start_dir: Directory to start searching from
+
+        Returns:
+            Path to git root, or None if not in a git repository
+        """
+        try:
+            result = subprocess.run(
+                ["git", "rev-parse", "--show-toplevel"], cwd=start_dir, capture_output=True, text=True, check=False
+            )
+            if result.returncode == 0:
+                return Path(result.stdout.strip())
+            return None
+        except (subprocess.SubprocessError, FileNotFoundError):
+            return None
+
+    def _get_search_directories(self, cwd: Path, git_root: Optional[Path]) -> List[Path]:
+        """Get list of directories to search for context files.
+
+        Walks from cwd up to git root (inclusive).
+
+        Args:
+            cwd: Current working directory
+            git_root: Git repository root, or None
+
+        Returns:
+            List of directories to search, from most specific to most general
+        """
+        dirs = []
+        current = cwd
+
+        while True:
+            dirs.append(current)
+
+            # Stop at git root if we have one
+            if git_root and current == git_root:
+                break
+
+            # Stop at filesystem root
+            parent = current.parent
+            if parent == current:
+                break
+
+            current = parent
+
+        return dirs
+
+    def _discover_files(self, search_dirs: List[Path], context_files: List[str]) -> List[tuple[Path, str]]:
+        """Discover context files in search directories.
+
+        Args:
+            search_dirs: Directories to search
+            context_files: List of filenames to search for
+
+        Returns:
+            List of (file_path, relative_name) tuples for found files
+        """
+        found = []
+        seen_names = set()
+
+        # Search in order (most specific directory first)
+        for directory in search_dirs:
+            for filename in context_files:
+                # Skip if we've already found a file with this name
+                if filename in seen_names:
+                    continue
+
+                file_path = directory / filename
+                if file_path.exists() and file_path.is_file():
+                    found.append((file_path, filename))
+                    seen_names.add(filename)
+
+        return found
+
+    def _get_global_context_file(self) -> Optional[tuple[Path, str]]:
+        """Get global context file from user's config directory.
+
+        Returns:
+            Tuple of (file_path, "Global Context") if file exists, None otherwise
+        """
+        from tsugite.xdg import get_xdg_config_path
+
+        global_context_path = get_xdg_config_path("CONTEXT.md")
+        if global_context_path.exists() and global_context_path.is_file():
+            return (global_context_path, "Global Context (~/.config/tsugite/CONTEXT.md)")
+        return None

tsugite/attachments/base.py

@@ -0,0 +1,34 @@
+"""Base class for attachment handlers."""
+
+from abc import ABC, abstractmethod
+
+
+class AttachmentHandler(ABC):
+    """Base class for attachment handlers."""
+
+    @abstractmethod
+    def can_handle(self, source: str) -> bool:
+        """Check if this handler can process the source.
+
+        Args:
+            source: Source string (URL, file path, etc.)
+
+        Returns:
+            True if this handler can process the source
+        """
+        pass
+
+    @abstractmethod
+    def fetch(self, source: str) -> str:
+        """Fetch and return content for this source.
+
+        Args:
+            source: Source string to fetch
+
+        Returns:
+            Content as string
+
+        Raises:
+            ValueError: If fetch fails
+        """
+        pass

tsugite/attachments/file.py

@@ -0,0 +1,51 @@
+"""File handler for local file attachments."""
+
+from pathlib import Path
+
+from tsugite.attachments.base import AttachmentHandler
+
+
+class FileHandler(AttachmentHandler):
+    """Handler for local file references."""
+
+    def can_handle(self, source: str) -> bool:
+        """Check if source is a file path.
+
+        Args:
+            source: Source string
+
+        Returns:
+            True if source looks like a file path and exists
+        """
+        # Don't handle URLs or inline markers
+        if source.lower() in ("inline", "text"):
+            return False
+        if source.startswith("http://") or source.startswith("https://"):
+            return False
+        if source.startswith("youtube:"):
+            return False
+
+        # Check if it's a valid file path
+        try:
+            path = Path(source).expanduser()
+            return path.exists() and path.is_file()
+        except (OSError, RuntimeError):
+            return False
+
+    def fetch(self, source: str) -> str:
+        """Read file content.
+
+        Args:
+            source: File path
+
+        Returns:
+            File content as string
+
+        Raises:
+            ValueError: If file cannot be read
+        """
+        try:
+            path = Path(source).expanduser()
+            return path.read_text(encoding="utf-8")
+        except Exception as e:
+            raise ValueError(f"Failed to read file '{source}': {e}")

tsugite/attachments/inline.py

@@ -0,0 +1,31 @@
+"""Inline text handler for attachments."""
+
+from tsugite.attachments.base import AttachmentHandler
+
+
+class InlineHandler(AttachmentHandler):
+    """Handler for inline text content."""
+
+    def can_handle(self, source: str) -> bool:
+        """Check if source is inline text.
+
+        Args:
+            source: Source string
+
+        Returns:
+            True if source is "inline" or "text"
+        """
+        return source.lower() in ("inline", "text")
+
+    def fetch(self, source: str) -> str:
+        """Inline content is stored in attachments JSON, not fetched.
+
+        Args:
+            source: Source string (ignored)
+
+        Returns:
+            Empty string (inline content comes from attachments.json)
+        """
+        # Inline content is handled specially in resolve_attachments
+        # This method should not be called for inline content
+        return ""