tsugite-cli 0.3.3__py3-none-any.whl

tsugite/tools/__init__.py

@@ -0,0 +1,265 @@
+"""Tool registry for Tsugite agents."""
+
+import inspect
+from dataclasses import dataclass
+from typing import Any, Callable, Dict, List
+
+from ..utils import tool_error, validation_error
+
+
+@dataclass
+class ToolInfo:
+    """Information about a registered tool."""
+
+    name: str
+    func: Callable
+    description: str
+    parameters: Dict[str, Any]
+
+
+# Global tool registry
+_tools: Dict[str, ToolInfo] = {}
+
+
+def tool(func: Callable) -> Callable:
+    """Register a function as a tool."""
+    # Extract function signature and docstring
+    sig = inspect.signature(func)
+    doc = func.__doc__ or "No description available"
+
+    # Extract parameter info
+    parameters = {}
+    for param_name, param in sig.parameters.items():
+        parameters[param_name] = {
+            "type": (param.annotation if param.annotation != inspect.Parameter.empty else str),
+            "default": (param.default if param.default != inspect.Parameter.empty else None),
+            "required": param.default == inspect.Parameter.empty,
+        }
+
+    tool_info = ToolInfo(
+        name=func.__name__,
+        func=func,
+        description=doc.split("\n")[0].strip(),  # First line of docstring
+        parameters=parameters,
+    )
+
+    _tools[func.__name__] = tool_info
+    return func
+
+
+def get_tool(name: str) -> ToolInfo:
+    """Get a registered tool by name."""
+    if name not in _tools:
+        # Provide helpful error message
+        from ..shell_tool_config import get_custom_tools_config_path
+
+        error_parts = ["not found"]
+
+        # Check if it might be a custom tool
+        config_path = get_custom_tools_config_path()
+        if config_path.exists():
+            error_parts.append(f"Check if '{name}' is defined in {config_path}")
+        else:
+            error_parts.append(f"Custom tools config not found at {config_path}")
+
+        # Suggest similar tool names
+        all_tools = list(_tools.keys())
+        similar = [t for t in all_tools if name.lower() in t.lower() or t.lower() in name.lower()]
+        if similar:
+            error_parts.append(f"Did you mean: {', '.join(similar[:3])}?")
+
+        error_parts.append("Run 'tsugite tools list' to see all available tools")
+
+        raise validation_error("tool", name, ". ".join(error_parts))
+    return _tools[name]
+
+
+def call_tool(name: str, **kwargs) -> Any:
+    """Call a tool with the given arguments."""
+    tool_info = get_tool(name)
+
+    # Validate required parameters
+    for param_name, param_info in tool_info.parameters.items():
+        if param_info["required"] and param_name not in kwargs:
+            raise validation_error("parameter", param_name, f"missing for tool '{name}'")
+
+    try:
+        return tool_info.func(**kwargs)
+    except Exception as e:
+        raise tool_error(name, "execute", str(e))
+
+
+def list_tools() -> List[str]:
+    """List all registered tool names."""
+    return list(_tools.keys())
+
+
+def get_tools_by_category(category: str) -> List[str]:
+    """Get all tool names in a specific category.
+
+    Args:
+        category: Category name (e.g., 'fs', 'http', 'shell')
+
+    Returns:
+        List of tool names in the category
+    """
+    category_tools = []
+    for tool_name, tool_info in _tools.items():
+        module = tool_info.func.__module__.split(".")[-1]
+        if module == category:
+            category_tools.append(tool_name)
+
+    return sorted(category_tools)
+
+
+def _expand_single_spec(spec: str, strict: bool = True) -> List[str]:
+    """Expand a single tool specification to tool names.
+
+    Args:
+        spec: Tool specification (name, @category, or glob pattern)
+        strict: If True, raise error when spec matches nothing. If False, return empty list.
+
+    Returns:
+        List of matching tool names
+    """
+    import fnmatch
+
+    if spec.startswith("@"):
+        # Category reference: @fs, @http, etc.
+        category = spec[1:]
+        category_tools = get_tools_by_category(category)
+        if not category_tools and strict:
+            raise validation_error("tool category", category, "not found or empty")
+        return category_tools
+    elif "*" in spec or "?" in spec or "[" in spec:
+        # Glob pattern
+        all_tool_names = list_tools()
+        matches = fnmatch.filter(all_tool_names, spec)
+        if not matches and strict:
+            raise validation_error("tool pattern", spec, "matched no tools")
+        return matches
+    else:
+        # Regular tool name
+        if spec not in _tools:
+            if strict:
+                available = ", ".join(list(_tools.keys())) if _tools else "none"
+                raise validation_error("tool", spec, f"not found. Available: {available}")
+            return []
+        return [spec]
+
+
+def expand_tool_specs(tool_specs: List[str]) -> List[str]:
+    """Expand tool specifications to actual tool names.
+
+    Supports:
+    - Regular tool names: 'read_file' -> ['read_file']
+    - Category references: '@fs' -> all tools in fs category
+    - Glob patterns: '*_file' -> all tools matching pattern
+    - Exclusions: '-tool_name', '-@category', '-pattern*' -> remove matching tools
+
+    Args:
+        tool_specs: List of tool specifications (names, @category, globs, or exclusions with -)
+
+    Returns:
+        Expanded list of unique tool names
+
+    Examples:
+        >>> expand_tool_specs(['read_file', 'write_file'])
+        ['read_file', 'write_file']
+        >>> expand_tool_specs(['@fs'])
+        ['create_directory', 'file_exists', 'list_files', 'read_file', 'write_file']
+        >>> expand_tool_specs(['*_file'])
+        ['read_file', 'write_file']
+        >>> expand_tool_specs(['@fs', '-*_directory'])
+        ['file_exists', 'list_files', 'read_file', 'write_file']
+        >>> expand_tool_specs(['@http', '-web_search'])
+        ['check_url', 'download_file', 'fetch_json', 'fetch_text', 'post_json']
+    """
+    # Separate inclusions and exclusions
+    inclusions = []
+    exclusions = []
+
+    for spec in tool_specs:
+        if spec.startswith("-"):
+            exclusions.append(spec[1:])  # Strip the - prefix
+        else:
+            inclusions.append(spec)
+
+    # Expand inclusions (strict - must match something)
+    expanded = []
+    for spec in inclusions:
+        expanded.extend(_expand_single_spec(spec, strict=True))
+
+    # Expand exclusions (non-strict - silently ignore if nothing matches)
+    excluded_tools = set()
+    for spec in exclusions:
+        excluded_tools.update(_expand_single_spec(spec, strict=False))
+
+    # Apply exclusions
+    result_with_exclusions = [tool for tool in expanded if tool not in excluded_tools]
+
+    # Return unique tools while preserving order
+    seen = set()
+    result = []
+    for tool in result_with_exclusions:
+        if tool not in seen:
+            seen.add(tool)
+            result.append(tool)
+
+    return result
+
+
+def load_custom_shell_tools() -> None:
+    """Load custom shell tools from config file.
+
+    This is called automatically at module import time to register
+    user-defined shell tools from custom_tools.yaml.
+    """
+    import os
+    import sys
+
+    try:
+        from ..shell_tool_config import get_custom_tools_config_path, load_custom_tools_config
+        from .shell_tools import register_shell_tools
+
+        config_path = get_custom_tools_config_path()
+
+        # Only try to load if config file exists
+        if not config_path.exists():
+            # Silently skip if no custom tools configured
+            return
+
+        definitions = load_custom_tools_config()
+        if definitions:
+            register_shell_tools(definitions)
+
+            # Show helpful message if verbose mode enabled
+            if os.environ.get("TSUGITE_VERBOSE") or os.environ.get("TSUGITE_DEBUG"):
+                tool_names = [d.name for d in definitions]
+                print(
+                    f"✓ Loaded {len(definitions)} custom tool(s): {', '.join(tool_names)}",
+                    file=sys.stderr,
+                )
+        else:
+            # Config exists but no tools defined
+            if os.environ.get("TSUGITE_VERBOSE") or os.environ.get("TSUGITE_DEBUG"):
+                print(f"⚠ Custom tools config exists but no tools defined: {config_path}", file=sys.stderr)
+
+    except Exception as e:
+        # Don't fail startup if custom tools can't be loaded, but show clear error
+        print(f"⚠ Failed to load custom tools: {e}", file=sys.stderr)
+        print(f"  Config file: {get_custom_tools_config_path()}", file=sys.stderr)
+        print("  Use 'tsugite tools validate' to check your config", file=sys.stderr)
+
+
+# Import tool modules at the end to avoid circular imports
+# (they need to import 'tool' decorator from this module)
+from . import agents as agents  # noqa: E402
+from . import fs as fs  # noqa: E402
+from . import http as http  # noqa: E402
+from . import interactive as interactive  # noqa: E402
+from . import shell as shell  # noqa: E402
+from . import tasks as tasks  # noqa: E402
+
+# Load custom shell tools after built-in tools
+load_custom_shell_tools()

tsugite/tools/agents.py

@@ -0,0 +1,312 @@
+"""Agent orchestration tools for spawning and managing sub-agents."""
+
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from ..tools import tool
+from ..utils import parse_yaml_frontmatter
+
+
+@tool
+def spawn_agent(
+    agent_path: str,
+    prompt: str,
+    context: Optional[Dict[str, Any]] = None,
+    model_override: Optional[str] = None,
+    timeout: int = 300,
+) -> str:
+    """Spawn subagent as subprocess.
+
+    Args:
+        agent_path: Path to agent .md file
+        prompt: Task for the subagent
+        context: Optional context dict (must be JSON-serializable)
+        model_override: Optional model to use
+        timeout: Timeout in seconds (default: 5 minutes)
+
+    Returns:
+        Subagent's final result as string
+
+    Raises:
+        ValueError: If agent not found or context not JSON-serializable
+        RuntimeError: If subagent fails, times out, or errors
+    """
+    import json
+    import subprocess
+
+    from ..agent_runner import get_current_agent
+
+    # Validate agent path
+    agent_file = Path(agent_path)
+    if not agent_file.is_absolute():
+        agent_file = Path.cwd() / agent_file
+    if not agent_file.exists():
+        raise ValueError(f"Agent not found: {agent_path}")
+
+    # Prepare context
+    context_data = {
+        "prompt": prompt,
+        "context": {
+            **(context or {}),
+            "parent_agent": get_current_agent(),
+            "is_subagent": True,
+        },
+    }
+
+    # Validate JSON serializability early
+    try:
+        context_json = json.dumps(context_data)
+    except (TypeError, ValueError) as e:
+        # Try to identify problematic value
+        bad_type = "unknown"
+        if hasattr(e, "__context__") and e.__context__:
+            bad_type = str(type(e.__context__)).split("'")[1]
+        raise ValueError(
+            f"Context contains non-JSON-serializable data (type: {bad_type}). "
+            "Only use dicts, lists, strings, numbers, bools, and None."
+        ) from e
+
+    # Build command
+    cmd = ["uv", "run", "tsu", "run", str(agent_file), "--subagent-mode"]
+    if model_override:
+        cmd.extend(["--model", model_override])
+
+    # Set up progress spinner
+    import queue
+    import threading
+
+    from ..ui_context import get_progress, get_ui_handler
+
+    progress = get_progress()
+    ui_handler = get_ui_handler()
+    agent_name = agent_file.stem
+
+    # Show initial message through event system
+    if ui_handler and not progress:
+        from ..events import EventBus, InfoEvent
+
+        event_bus = EventBus()
+        event_bus.subscribe(ui_handler.handle_event)
+        event_bus.emit(InfoEvent(message=f"🚀 Spawning subagent: [cyan]{agent_name}[/cyan]..."))
+
+    try:
+        # Spawn subprocess with line buffering
+        proc = subprocess.Popen(
+            cmd,
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            bufsize=1,  # Line buffered for real-time output
+            cwd=Path.cwd(),  # Subagent inherits parent's working directory
+        )
+
+        # Write context to stdin then close it
+        proc.stdin.write(context_json)
+        proc.stdin.close()
+
+        # Queue for passing lines from reader thread to main thread
+        line_queue = queue.Queue()
+        reader_exception = None
+
+        def read_stdout():
+            """Read stdout lines in separate thread and put in queue."""
+            nonlocal reader_exception
+            try:
+                for line in proc.stdout:
+                    line_queue.put(line)
+                line_queue.put(None)  # Signal EOF
+            except Exception as e:
+                reader_exception = e
+                line_queue.put(None)
+
+        # Start reader thread
+        reader_thread = threading.Thread(target=read_stdout, daemon=True)
+        reader_thread.start()
+
+        # Read JSONL stream and collect events
+        final_result = None
+        errors = []
+
+        while True:
+            # Try to get line from queue with timeout for periodic updates
+            try:
+                line = line_queue.get(timeout=0.5)
+            except queue.Empty:
+                # No data yet - just waiting for subprocess output
+                # Don't update progress here to avoid too many updates
+                continue
+
+            # Check for EOF or reader thread exception
+            if line is None:
+                if reader_exception:
+                    raise reader_exception
+                break
+
+            # Process JSONL event
+            try:
+                event = json.loads(line.strip())
+
+                # Skip non-dict events (e.g., if line is just a number)
+                if not isinstance(event, dict):
+                    continue
+
+                event_type = event.get("type")
+
+                # Update progress spinner for key events only
+                if ui_handler:
+                    if event_type == "turn_start":
+                        ui_handler.update_progress(f"🚀 {agent_name}: Turn {event['turn']}")
+                    elif event_type == "tool_call":
+                        ui_handler.update_progress(f"🚀 {agent_name}: {event['tool']}(...)")
+                    elif event_type == "code":
+                        ui_handler.update_progress(f"🚀 {agent_name}: Running code...")
+
+                # Collect results/errors
+                if event_type == "final_result":
+                    final_result = event["result"]
+                elif event_type == "error":
+                    errors.append(event)
+
+            except json.JSONDecodeError:
+                continue  # Skip malformed lines
+
+        # Wait for reader thread to finish
+        reader_thread.join(timeout=1.0)
+
+        # Wait for completion
+        try:
+            return_code = proc.wait(timeout=timeout)
+        except subprocess.TimeoutExpired:
+            proc.kill()
+            raise RuntimeError(f"Subagent timed out after {timeout}s")
+
+        # Check for failures
+        if return_code != 0:
+            stderr = proc.stderr.read()
+            error_msg = f"Subagent failed with exit code {return_code}"
+            if stderr:
+                error_msg += f": {stderr}"
+            if errors:
+                error_msg += f"\nErrors: {[e['error'] for e in errors]}"
+            raise RuntimeError(error_msg)
+
+        if errors and final_result is None:
+            # Errors occurred and no result was returned
+            error_details = errors[-1]  # Use most recent error
+            raise RuntimeError(
+                f"Subagent error at step {error_details.get('step', 'unknown')}: {error_details['error']}"
+            )
+
+        if final_result is None:
+            raise RuntimeError("Subagent did not return a result")
+
+        return final_result
+
+    finally:
+        # Restore progress to parent agent state
+        if ui_handler:
+            ui_handler.update_progress("Agent running...")
+
+
+def _show_progress(message: str):
+    """Show subagent progress in parent UI."""
+    from ..events import InfoEvent
+    from ..ui_context import get_ui_handler
+
+    ui = get_ui_handler()
+    if ui:
+        ui.handle_event(InfoEvent(message=f"[Subagent] {message}"))
+
+
+@tool
+def list_agents() -> str:
+    """List all available agents for delegation.
+
+    Scans standard agent directories and returns information about
+    available specialized agents. Use this to discover which agents
+    are available for delegation.
+
+    Returns:
+        Formatted list of available agents with their descriptions.
+        Returns empty string if no agents are found.
+    """
+    from ..agent_inheritance import get_builtin_agents_path, get_global_agents_paths
+    from ..agent_runner import get_current_agent
+
+    agents_info: List[Dict[str, str]] = []
+    seen_names = set()
+
+    # Get current agent name to exclude it from the list
+    current_agent_name = get_current_agent()
+
+    # Define search paths in priority order
+    search_paths = [
+        Path.cwd() / ".tsugite" / "agents",
+        Path.cwd() / "agents",
+    ]
+
+    # Add built-in agents directory
+    builtin_path = get_builtin_agents_path()
+    search_paths.append(builtin_path)
+
+    # Add global paths
+    search_paths.extend(get_global_agents_paths())
+
+    # Scan each directory for agent files
+    for search_dir in search_paths:
+        if not search_dir.exists() or not search_dir.is_dir():
+            continue
+
+        is_builtin_dir = search_dir == builtin_path
+
+        for agent_file in search_dir.glob("*.md"):
+            # Skip if we've already seen this agent name (higher priority paths win)
+            if agent_file.stem in seen_names:
+                continue
+
+            try:
+                content = agent_file.read_text(encoding="utf-8")
+                frontmatter, _ = parse_yaml_frontmatter(content, str(agent_file))
+
+                name = frontmatter.get("name", agent_file.stem)
+                description = frontmatter.get("description", "No description")
+
+                # Skip the currently running agent to prevent self-spawning
+                if current_agent_name and name == current_agent_name:
+                    continue
+
+                # Store relative path from cwd if possible, otherwise use name for built-ins
+                if is_builtin_dir:
+                    display_path = name
+                else:
+                    try:
+                        display_path = str(agent_file.relative_to(Path.cwd()))
+                    except ValueError:
+                        display_path = str(agent_file)
+
+                # Add marker for built-in agents
+                description_with_marker = f"{description} (built-in)" if is_builtin_dir else description
+
+                agents_info.append(
+                    {
+                        "name": name,
+                        "description": description_with_marker,
+                        "path": display_path,
+                    }
+                )
+
+                seen_names.add(agent_file.stem)
+            except Exception:
+                # Skip files that can't be parsed
+                continue
+
+    if not agents_info:
+        return ""
+
+    # Format as a simple markdown list
+    lines = []
+    for agent in agents_info:
+        lines.append(f"- **{agent['name']}** (`{agent['path']}`): {agent['description']}")
+
+    return "\n".join(lines)