tsugite-cli 0.3.3__py3-none-any.whl

tsugite/agent_preparation.py

@@ -0,0 +1,236 @@
+"""Agent preparation pipeline - unified logic for render and execution."""
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from tsugite.core.tools import Tool
+from tsugite.md_agents import Agent, AgentConfig
+
+
+@dataclass
+class PreparedAgent:
+    """Fully prepared agent ready for execution or display.
+
+    This dataclass contains everything needed to either:
+    1. Display what will be sent to the LLM (render command)
+    2. Execute the agent (run command)
+
+    Attributes:
+        agent: Parsed agent object with content and config
+        agent_config: Agent configuration (model, tools, etc.)
+        system_message: Complete system message sent to LLM
+        user_message: Complete user message sent to LLM
+        rendered_prompt: Rendered template (before building system message)
+        tools: List of Tool objects ready for agent execution
+        context: Full template rendering context
+        combined_instructions: Combined default + agent instructions
+        prefetch_results: Results from prefetch tool execution
+        attachments: List of (name, content) tuples for prompt caching
+    """
+
+    agent: Agent
+    agent_config: AgentConfig
+    system_message: str
+    user_message: str
+    rendered_prompt: str
+    tools: List[Tool]
+    context: Dict[str, Any]
+    combined_instructions: str
+    prefetch_results: Dict[str, Any]
+    attachments: List[tuple[str, str]]
+
+
+class AgentPreparer:
+    """Prepares agents for execution or rendering.
+
+    This class consolidates all agent preparation logic that was previously
+    duplicated across render command, run_agent, and _execute_agent_with_prompt.
+
+    The preparation pipeline:
+    1. Parse agent file (with inheritance resolution)
+    2. Execute prefetch tools
+    3. Execute tool directives (optional)
+    4. Build template context
+    5. Render template
+    6. Build instructions
+    7. Expand and create tools
+    8. Build system prompt
+
+    This ensures that render shows EXACTLY what run executes.
+    """
+
+    def _extract_tool_directive_placeholders(self, content: str) -> Dict[str, str]:
+        """Extract variable names from tool directives and return placeholders.
+
+        When rendering without executing directives, we still need variables to
+        be defined so the template doesn't fail. This extracts all assign="var"
+        names and creates placeholder values.
+
+        Args:
+            content: Markdown content with tool directives
+
+        Returns:
+            Dict mapping variable names to placeholder values
+        """
+        from tsugite.md_agents import extract_tool_directives
+
+        try:
+            directives = extract_tool_directives(content)
+        except Exception:
+            # If extraction fails, return empty dict
+            return {}
+
+        placeholders = {}
+        for directive in directives:
+            if directive.assign_var:
+                # Create a descriptive placeholder showing what would be executed
+                placeholders[directive.assign_var] = (
+                    f"[Tool directive: {directive.name}(...) - not executed in render mode]"
+                )
+
+        return placeholders
+
+    def prepare(
+        self,
+        agent: Agent,
+        prompt: str,
+        context: Optional[Dict[str, Any]] = None,
+        delegation_agents: Optional[List[tuple[str, Path]]] = None,
+        skip_tool_directives: bool = False,
+        task_summary: str = "## Current Tasks\nNo tasks yet.",
+        tasks: Optional[List[Dict[str, Any]]] = None,
+        attachments: Optional[List[tuple[str, str]]] = None,
+    ) -> PreparedAgent:
+        """Prepare agent with all context, tools, and instructions.
+
+        Args:
+            agent: Parsed agent object
+            prompt: User prompt/task
+            context: Additional context variables
+            delegation_agents: List of (name, path) tuples for delegation
+            skip_tool_directives: Skip executing tool directives (for render)
+            task_summary: Current task summary (from task manager)
+            tasks: List of task dicts for template iteration (from task manager)
+            attachments: List of (name, content) tuples for prompt caching
+
+        Returns:
+            PreparedAgent ready for execution or display
+
+        Raises:
+            RuntimeError: If preparation fails
+        """
+        from tsugite.agent_runner import (
+            _combine_instructions,
+            execute_prefetch,
+            execute_tool_directives,
+            get_default_instructions,
+        )
+        from tsugite.core.agent import build_system_prompt
+        from tsugite.core.tools import create_tool_from_tsugite
+        from tsugite.renderer import AgentRenderer
+        from tsugite.tools import expand_tool_specs
+        from tsugite.utils import is_interactive
+
+        if context is None:
+            context = {}
+
+        agent_config = agent.config
+
+        # Step 1: Execute prefetch tools
+        prefetch_context = {}
+        if agent_config.prefetch:
+            try:
+                from tsugite.agent_runner import execute_prefetch
+
+                prefetch_context = execute_prefetch(agent_config.prefetch)
+            except Exception:
+                # Silently continue if prefetch fails
+                prefetch_context = {}
+
+        # Step 2: Execute tool directives (unless skip_tool_directives=True for render)
+        if skip_tool_directives:
+            modified_content = agent.content
+            # Extract tool directive variable names and provide placeholders
+            tool_context = self._extract_tool_directive_placeholders(agent.content)
+        else:
+            modified_content, tool_context = execute_tool_directives(agent.content, prefetch_context)
+
+        # Step 3: Build template context
+        interactive_mode = is_interactive()
+        full_context = {
+            **context,
+            **prefetch_context,
+            **tool_context,
+            "user_prompt": prompt,
+            "task_summary": task_summary,
+            "tasks": tasks or [],
+            "is_interactive": interactive_mode,
+            "text_mode": agent_config.text_mode,
+            "tools": agent_config.tools,
+            # Subagent context
+            "is_subagent": context.get("is_subagent", False),
+            "parent_agent": context.get("parent_agent", None),
+            # Chat history (for chat agents)
+            "chat_history": context.get("chat_history", []),
+        }
+
+        # Step 4: Render template
+        renderer = AgentRenderer()
+        try:
+            rendered_prompt = renderer.render(modified_content, full_context)
+        except Exception as e:
+            raise RuntimeError(f"Template rendering failed: {e}") from e
+
+        # Step 5: Build instructions
+        base_instructions = get_default_instructions(text_mode=agent_config.text_mode)
+        agent_instructions = getattr(agent_config, "instructions", "")
+
+        # Render agent instructions as Jinja2 template (they may contain {% if text_mode %}, etc.)
+        if agent_instructions:
+            try:
+                agent_instructions = renderer.render(agent_instructions, full_context)
+            except Exception as e:
+                raise RuntimeError(f"Failed to render agent instructions: {e}") from e
+
+        combined_instructions = _combine_instructions(base_instructions, agent_instructions)
+
+        # Step 6: Expand and create tools
+        try:
+            # Expand tool specifications (categories, globs, regular names)
+            expanded_tools = expand_tool_specs(agent_config.tools) if agent_config.tools else []
+
+            # Add task management tools
+            task_tools = ["task_add", "task_update", "task_complete", "task_list", "task_get"]
+            all_tool_names = expanded_tools + task_tools
+
+            if delegation_agents:
+                all_tool_names.append("spawn_agent")
+
+            # Filter out interactive tools in non-interactive mode
+            if not interactive_mode and "ask_user" in all_tool_names:
+                all_tool_names.remove("ask_user")
+
+            # Convert to Tool objects
+            tools = [create_tool_from_tsugite(name) for name in all_tool_names]
+        except Exception as e:
+            raise RuntimeError(f"Failed to create tools: {e}") from e
+
+        # Step 7: Build system message (what LLM actually sees)
+        system_message = build_system_prompt(tools, combined_instructions, agent_config.text_mode)
+
+        # User message is the rendered prompt
+        user_message = rendered_prompt
+
+        return PreparedAgent(
+            agent=agent,
+            agent_config=agent_config,
+            system_message=system_message,
+            user_message=user_message,
+            rendered_prompt=rendered_prompt,
+            tools=tools,
+            context=full_context,
+            combined_instructions=combined_instructions,
+            prefetch_results=prefetch_context,
+            attachments=attachments or [],
+        )

tsugite/agent_runner/__init__.py

@@ -0,0 +1,45 @@
+"""Agent execution engine - public API."""
+
+# Re-export public functions for backwards compatibility
+from tsugite.agent_runner.helpers import (  # noqa: F401
+    clear_current_agent,
+    get_current_agent,
+    get_display_console,
+    get_ui_handler,
+    set_current_agent,
+)
+from tsugite.agent_runner.metrics import StepMetrics, display_step_metrics  # noqa: F401
+from tsugite.agent_runner.runner import (  # noqa: F401
+    _combine_instructions,
+    _execute_agent_with_prompt,
+    execute_prefetch,
+    execute_tool_directives,
+    get_default_instructions,
+    preview_multistep_agent,
+    run_agent,
+    run_agent_async,
+    run_multistep_agent,
+    run_multistep_agent_async,
+)
+from tsugite.agent_runner.validation import get_agent_info, validate_agent_file  # noqa: F401
+from tsugite.tools import call_tool  # noqa: F401 - Re-export for test compatibility
+
+__all__ = [
+    "run_agent",
+    "run_agent_async",
+    "run_multistep_agent",
+    "run_multistep_agent_async",
+    "preview_multistep_agent",
+    "execute_prefetch",
+    "execute_tool_directives",
+    "get_default_instructions",
+    "StepMetrics",
+    "display_step_metrics",
+    "validate_agent_file",
+    "get_agent_info",
+    "get_current_agent",
+    "set_current_agent",
+    "clear_current_agent",
+    "get_display_console",
+    "get_ui_handler",
+]

tsugite/agent_runner/helpers.py

@@ -0,0 +1,106 @@
+"""Shared helper functions for agent execution."""
+
+import threading
+from typing import Any, Optional
+
+from rich.console import Console
+
+from tsugite.console import get_stderr_console
+
+# Console for warnings and debug output (stderr)
+_stderr_console = get_stderr_console()
+
+# Thread-local storage for tracking currently executing agent
+_current_agent_context = threading.local()
+
+
+def set_current_agent(name: str) -> None:
+    """Set the name of the currently executing agent in thread-local storage."""
+    _current_agent_context.name = name
+
+
+def get_current_agent() -> Optional[str]:
+    """Get the name of the currently executing agent from thread-local storage."""
+    return getattr(_current_agent_context, "name", None)
+
+
+def clear_current_agent() -> None:
+    """Clear the currently executing agent from thread-local storage."""
+    if hasattr(_current_agent_context, "name"):
+        delattr(_current_agent_context, "name")
+
+
+def get_display_console(custom_logger: Optional[Any]) -> Console:
+    """Get console for displaying output, with fallback to stderr.
+
+    Args:
+        custom_logger: Custom logger instance (may be None)
+
+    Returns:
+        Console instance to use for output
+    """
+    if custom_logger and hasattr(custom_logger, "console"):
+        return custom_logger.console
+    return _stderr_console
+
+
+def get_ui_handler(custom_logger: Optional[Any]) -> Optional[Any]:
+    """Safely get UI handler from custom logger.
+
+    Args:
+        custom_logger: Custom logger instance (may be None)
+
+    Returns:
+        UI handler if available, None otherwise
+    """
+    return custom_logger.ui_handler if custom_logger and hasattr(custom_logger, "ui_handler") else None
+
+
+def set_multistep_ui_context(custom_logger: Optional[Any], step_number: int, step_name: str, total_steps: int) -> None:
+    """Set multistep context in UI handler if available.
+
+    Args:
+        custom_logger: Custom logger instance (may be None)
+        step_number: Current step number
+        step_name: Name of current step
+        total_steps: Total number of steps
+    """
+    ui_handler = get_ui_handler(custom_logger)
+    if ui_handler:
+        ui_handler.set_multistep_context(step_number, step_name, total_steps)
+
+
+def clear_multistep_ui_context(custom_logger: Optional[Any]) -> None:
+    """Clear multistep context from UI handler if available.
+
+    Args:
+        custom_logger: Custom logger instance (may be None)
+    """
+    ui_handler = get_ui_handler(custom_logger)
+    if ui_handler:
+        ui_handler.clear_multistep_context()
+
+
+def print_step_progress(
+    custom_logger: Optional[Any], step_header: str, message: str, debug: bool = False, style: str = "cyan"
+) -> None:
+    """Print step progress message using event system.
+
+    Args:
+        custom_logger: Custom logger instance (may be None)
+        step_header: Step header string
+        message: Message to display
+        debug: Whether debug mode is active (skips output if True)
+        style: Rich style string (e.g., "cyan", "green", "yellow")
+    """
+    if debug:
+        return
+
+    # Emit as StepProgressEvent through event bus
+    ui_handler = get_ui_handler(custom_logger)
+    if ui_handler:
+        from tsugite.events import EventBus, StepProgressEvent
+
+        event_bus = EventBus()
+        event_bus.subscribe(ui_handler.handle_event)
+        event_bus.emit(StepProgressEvent(message=f"{step_header} {message}", style=style))

tsugite/agent_runner/history_integration.py

@@ -0,0 +1,248 @@
+"""History integration for agent runs."""
+
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+
+def _process_messages_field(turn, messages: list) -> None:
+    """Process turn with messages field (full message history)."""
+    for msg in turn.messages:
+        if msg.get("role") != "system":
+            messages.append(msg)
+
+
+def _process_steps_field(turn, messages: list) -> None:
+    """Process turn with steps field (execution steps)."""
+    messages.append({"role": "user", "content": turn.user})
+    for step in turn.steps:
+        thought = step.get("thought", "")
+        code = step.get("code", "")
+        output = step.get("output", "")
+        error = step.get("error")
+
+        messages.append({"role": "assistant", "content": f"Thought: {thought}\n\n```python\n{code}\n```"})
+
+        observation = f"Observation: {output}"
+        if error:
+            observation += f"\nError: {error}"
+        messages.append({"role": "user", "content": observation})
+
+    messages.append({"role": "assistant", "content": turn.assistant})
+
+
+def _process_simple_turn(turn, messages: list) -> None:
+    """Process simple turn (user/assistant only)."""
+    messages.append({"role": "user", "content": turn.user})
+    messages.append({"role": "assistant", "content": turn.assistant})
+
+
+def load_conversation_messages(conversation_id: str) -> list[dict]:
+    """Load conversation history as message list for LLM.
+
+    Loads complete message history including tool calls and intermediate steps.
+    System messages are skipped as they will be reconstructed with current context.
+
+    Args:
+        conversation_id: Conversation ID to load
+
+    Returns:
+        List of message dicts including all tool calls and observations
+
+    Raises:
+        FileNotFoundError: If conversation doesn't exist
+        RuntimeError: If load fails
+    """
+    from tsugite.ui.chat_history import load_conversation_history
+
+    turns = load_conversation_history(conversation_id)
+
+    messages = []
+    for turn in turns:
+        if turn.messages:
+            _process_messages_field(turn, messages)
+        elif turn.steps:
+            _process_steps_field(turn, messages)
+        else:
+            _process_simple_turn(turn, messages)
+
+    return messages
+
+
+def apply_cache_control_to_messages(messages: list[dict]) -> list[dict]:
+    """Apply cache control markers to all conversation messages.
+
+    Following industry best practices from Anthropic and OpenAI, we cache
+    all conversation history.
+
+    Args:
+        messages: List of message dicts (user/assistant pairs)
+
+    Returns:
+        List of message dicts with cache_control added to all messages
+    """
+    if not messages:
+        return messages
+
+    return [{**msg, "cache_control": {"type": "ephemeral"}} for msg in messages]
+
+
+def load_and_apply_history(conversation_id: str) -> list[dict]:
+    """Load conversation history and apply cache control markers.
+
+    Consolidates the common pattern of loading conversation messages
+    and applying cache control for optimal performance.
+
+    Args:
+        conversation_id: Conversation ID to load
+
+    Returns:
+        List of message dicts with cache control applied
+
+    Raises:
+        ValueError: If conversation not found
+        RuntimeError: If loading fails
+    """
+    try:
+        messages = load_conversation_messages(conversation_id)
+        if messages:
+            messages = apply_cache_control_to_messages(messages)
+        return messages
+    except FileNotFoundError:
+        raise ValueError(f"Conversation not found: {conversation_id}")
+    except Exception as e:
+        raise RuntimeError(f"Failed to load conversation history: {e}")
+
+
+def save_run_to_history(
+    agent_path: Path,
+    agent_name: str,
+    prompt: str,
+    result: str,
+    model: str,
+    token_count: Optional[int] = None,
+    cost: Optional[float] = None,
+    execution_steps: Optional[list] = None,
+    continue_conversation_id: Optional[str] = None,
+    system_prompt: Optional[str] = None,
+    attachments: Optional[list] = None,
+) -> Optional[str]:
+    """Save a single agent run to history.
+
+    Args:
+        agent_path: Path to agent file
+        agent_name: Name of the agent
+        prompt: User prompt/task
+        result: Agent's final answer
+        model: Model used
+        token_count: Number of tokens used
+        cost: Cost of execution
+        execution_steps: List of execution steps (from agent memory)
+        continue_conversation_id: Optional conversation ID to continue (for multi-turn run mode)
+        system_prompt: System prompt sent to LLM
+        attachments: List of (name, content) tuples for attachments
+
+    Returns:
+        Conversation ID if saved, None if history disabled or failed
+    """
+    # Don't save subagent runs to history
+    import os
+
+    if os.environ.get("TSUGITE_SUBAGENT_MODE") == "1":
+        return None
+
+    try:
+        from tsugite.config import load_config
+        from tsugite.ui.chat_history import save_chat_turn, start_conversation
+
+        config = load_config()
+        if not getattr(config, "history_enabled", True):
+            return None
+
+        try:
+            from tsugite.md_agents import parse_agent_file
+
+            agent = parse_agent_file(agent_path)
+            if getattr(agent.config, "disable_history", False):
+                return None
+        except Exception as e:
+            import sys
+
+            print(f"Warning: Could not check agent history settings: {e}", file=sys.stderr)
+
+        timestamp = datetime.now(timezone.utc)
+
+        if continue_conversation_id:
+            conv_id = continue_conversation_id
+        else:
+            conv_id = start_conversation(
+                agent_name=agent_name,
+                model=model,
+                timestamp=timestamp,
+            )
+
+        messages = []
+
+        if system_prompt or attachments:
+            if attachments:
+                system_blocks = [{"type": "text", "text": system_prompt or ""}]
+                for name, content in attachments:
+                    system_blocks.append(
+                        {
+                            "type": "text",
+                            "text": f"<Attachment: {name}>\n{content}\n</Attachment: {name}>",
+                            "cache_control": {"type": "ephemeral"},
+                        }
+                    )
+                messages.append({"role": "system", "content": system_blocks})
+            else:
+                messages.append({"role": "system", "content": system_prompt})
+
+        messages.append({"role": "user", "content": prompt})
+
+        if execution_steps:
+            for step in execution_steps:
+                thought = getattr(step, "thought", "")
+                code = getattr(step, "code", "")
+                output = getattr(step, "output", "")
+
+                messages.append({"role": "assistant", "content": f"Thought: {thought}\n\n```python\n{code}\n```"})
+                messages.append({"role": "user", "content": f"Observation: {output}"})
+
+        messages.append({"role": "assistant", "content": result})
+
+        save_chat_turn(
+            conversation_id=conv_id,
+            user_message=prompt,
+            agent_response=result,
+            tool_calls=_extract_tool_calls(execution_steps) if execution_steps else [],
+            token_count=token_count,
+            cost=cost,
+            timestamp=timestamp,
+            execution_steps=execution_steps,
+            messages=messages,
+        )
+
+        return conv_id
+
+    except Exception as e:
+        import sys
+
+        print(f"Warning: Failed to save run to history: {e}", file=sys.stderr)
+        return None
+
+
+def _extract_tool_calls(execution_steps: list) -> list[str]:
+    """Extract list of tool names called during execution.
+
+    Args:
+        execution_steps: List of execution step objects
+
+    Returns:
+        List of unique tool names called
+    """
+    tool_calls = set()
+    for step in execution_steps:
+        if hasattr(step, "tools_called") and step.tools_called:
+            tool_calls.update(step.tools_called)
+    return sorted(list(tool_calls))