stirrup 0.1.1__py3-none-any.whl → 0.1.3__py3-none-any.whl

stirrup/skills/skills.py

@@ -0,0 +1,145 @@
+"""Skills loader for agent capabilities.
+
+Skills are modular packages that extend agent capabilities with instructions,
+scripts, and resources. Each skill is a directory containing a SKILL.md file
+with YAML frontmatter (name, description) and detailed instructions.
+
+Based on: https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills
+"""
+
+import logging
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class SkillMetadata:
+    """Metadata extracted from a skill's SKILL.md frontmatter."""
+
+    name: str
+    description: str
+    path: str  # Relative path like "skills/data_analysis"
+
+
+def parse_frontmatter(content: str) -> dict[str, str]:
+    """Parse YAML frontmatter from markdown content.
+
+    Extracts metadata between --- markers at the start of the file.
+
+    Args:
+        content: Markdown content with optional YAML frontmatter
+
+    Returns:
+        Dictionary of frontmatter key-value pairs, empty if no frontmatter found
+
+    """
+    # Match YAML frontmatter between --- markers
+    pattern = r"^---\s*\n(.*?)\n---"
+    match = re.match(pattern, content, re.DOTALL)
+
+    if not match:
+        return {}
+
+    frontmatter_text = match.group(1)
+    result: dict[str, str] = {}
+
+    # Simple YAML parsing for key: value pairs
+    for line in frontmatter_text.strip().split("\n"):
+        line = line.strip()
+        if ":" in line:
+            key, value = line.split(":", 1)
+            result[key.strip()] = value.strip()
+
+    return result
+
+
+def load_skills_metadata(skills_dir: Path) -> list[SkillMetadata]:
+    """Scan skills directory for SKILL.md files and extract metadata.
+
+    Args:
+        skills_dir: Path to the skills directory
+
+    Returns:
+        List of SkillMetadata for each valid skill found.
+        Returns empty list if skills_dir doesn't exist or has no skills.
+
+    """
+    if not skills_dir.exists():
+        logger.debug("Skills directory does not exist: %s", skills_dir)
+        return []
+
+    if not skills_dir.is_dir():
+        logger.warning("Skills path is not a directory: %s", skills_dir)
+        return []
+
+    skills: list[SkillMetadata] = []
+
+    for skill_path in skills_dir.iterdir():
+        if not skill_path.is_dir():
+            continue
+
+        skill_md = skill_path / "SKILL.md"
+        if not skill_md.exists():
+            logger.debug("Skill directory missing SKILL.md: %s", skill_path)
+            continue
+
+        try:
+            content = skill_md.read_text(encoding="utf-8")
+            metadata = parse_frontmatter(content)
+
+            name = metadata.get("name")
+            description = metadata.get("description")
+
+            if not name or not description:
+                logger.warning(
+                    "Skill %s missing required frontmatter (name, description)",
+                    skill_path.name,
+                )
+                continue
+
+            skills.append(
+                SkillMetadata(
+                    name=name,
+                    description=description,
+                    path=f"skills/{skill_path.name}",
+                )
+            )
+            logger.debug("Loaded skill: %s", name)
+
+        except Exception as e:
+            logger.warning("Failed to load skill %s: %s", skill_path.name, e)
+
+    return skills
+
+
+def format_skills_section(skills: list[SkillMetadata]) -> str:
+    """Format skills metadata as a system prompt section.
+
+    Args:
+        skills: List of skill metadata to include
+
+    Returns:
+        Formatted string for inclusion in system prompt.
+        Returns empty string if no skills provided.
+
+    """
+    if not skills:
+        return ""
+
+    lines = [
+        "## Available Skills",
+        "",
+        "You have access to the following skills located in the `skills/` directory. "
+        "Each skill contains a SKILL.md file with detailed instructions and potentially bundled scripts.",
+        "",
+        "To use a skill:",
+        "1. Read the full instructions: `cat <skill_path>/SKILL.md`",
+        "2. Follow the instructions and use any bundled resources as described",
+        "",
+    ]
+    lines.extend([f"- **{skill.name}**: {skill.description} (`{skill.path}/SKILL.md`)" for skill in skills])
+
+    return "\n".join(lines)

stirrup/tools/__init__.py

@@ -55,6 +55,7 @@ from stirrup.core.models import Tool, ToolProvider
 from stirrup.tools.calculator import CALCULATOR_TOOL
 from stirrup.tools.code_backends import CodeExecToolProvider, LocalCodeExecToolProvider
 from stirrup.tools.finish import SIMPLE_FINISH_TOOL, FinishParams
+from stirrup.tools.user_input import USER_INPUT_TOOL
 from stirrup.tools.view_image import ViewImageToolProvider
 from stirrup.tools.web import WebToolProvider
 
@@ -69,6 +70,7 @@ __all__ = [
     "CALCULATOR_TOOL",
     "DEFAULT_TOOLS",
     "SIMPLE_FINISH_TOOL",
+    "USER_INPUT_TOOL",
     "CodeExecToolProvider",
     "FinishParams",
     "LocalCodeExecToolProvider",

stirrup/tools/calculator.py

@@ -21,7 +21,7 @@ def calculator_executor(params: CalculatorParams) -> ToolResult[ToolUseCountMeta
         result = eval(params.expression, {"__builtins__": {}}, {})
         return ToolResult(content=f"Result: {result}", metadata=ToolUseCountMetadata())
     except Exception as e:
-        return ToolResult(content=f"Error evaluating expression: {e!s}", metadata=ToolUseCountMetadata())
+        return ToolResult(content=f"Error evaluating expression: {e!s}", success=False, metadata=ToolUseCountMetadata())
 
 
 CALCULATOR_TOOL: Tool[CalculatorParams, ToolUseCountMetadata] = Tool[CalculatorParams, ToolUseCountMetadata](

stirrup/tools/code_backends/base.py

@@ -160,6 +160,11 @@ class CodeExecToolProvider(ToolProvider, ABC):
         if allowed_commands is not None:
             self._compiled_allowed = [re.compile(p) for p in allowed_commands]
 
+    @property
+    def temp_dir(self) -> Path | None:
+        """Return the temporary directory for this execution environment, if any."""
+        return None
+
     def _check_allowed(self, cmd: str) -> bool:
         """Check if command is allowed based on the allowlist.
 
@@ -419,11 +424,13 @@ class CodeExecToolProvider(ToolProvider, ABC):
             except FileNotFoundError:
                 return ToolResult(
                     content=f"Image `{params.path}` not found.",
+                    success=False,
                     metadata=ToolUseCountMetadata(),
                 )
             except ValueError as e:
                 return ToolResult(
                     content=str(e),
+                    success=False,
                     metadata=ToolUseCountMetadata(),
                 )
 

stirrup/tools/code_backends/docker.py

@@ -330,7 +330,7 @@ class DockerCodeExecToolProvider(CodeExecToolProvider):
             context_path = self._dockerfile_context.resolve() if self._dockerfile_context else dockerfile_path.parent
 
             # Generate unique tag based on dockerfile path
-            tag = f"agent001-exec-env-{hashlib.md5(str(dockerfile_path).encode()).hexdigest()[:8]}"
+            tag = f"stirrup-exec-env-{hashlib.md5(str(dockerfile_path).encode()).hexdigest()[:8]}"
 
             logger.info("Building image from %s with tag %s", dockerfile_path, tag)
 
@@ -710,8 +710,20 @@ class DockerCodeExecToolProvider(CodeExecToolProvider):
                     logger.debug("Uploaded file: %s -> %s", source, container_path)
 
                 elif source.is_dir():
-                    dest = dest_base / source.name
-                    shutil.copytree(source, dest, dirs_exist_ok=True)
+                    # If dest_dir was explicitly provided, copy contents directly to dest_base
+                    # Otherwise, create a subdirectory with the source's name
+                    if dest_dir:
+                        dest = dest_base
+                        # Copy contents of source directory into dest_base
+                        for item in source.iterdir():
+                            item_dest = dest / item.name
+                            if item.is_file():
+                                shutil.copy2(item, item_dest)
+                            else:
+                                shutil.copytree(item, item_dest, dirs_exist_ok=True)
+                    else:
+                        dest = dest_base / source.name
+                        shutil.copytree(source, dest, dirs_exist_ok=True)
                     # Track all individual files uploaded
                     for file_path in source.rglob("*"):
                         if file_path.is_file():
@@ -725,7 +737,7 @@ class DockerCodeExecToolProvider(CodeExecToolProvider):
                                     size=file_path.stat().st_size,
                                 ),
                             )
-                    logger.debug("Uploaded directory: %s -> %s/%s", source, self._working_dir, source.name)
+                    logger.debug("Uploaded directory: %s -> %s", source, dest)
 
             except Exception as exc:
                 result.failed[str(source)] = str(exc)

stirrup/tools/code_backends/e2b.py

@@ -2,6 +2,8 @@
 
 from pathlib import Path
 
+from pydantic import ValidationError
+
 try:
     from e2b import InvalidArgumentException, TimeoutException
     from e2b.sandbox.filesystem.filesystem import FileType
@@ -13,7 +15,7 @@ except ImportError as e:
 
 import logging
 
-from stirrup.constants import SUBMISSION_SANDBOX_TIMEOUT
+from stirrup.constants import SANDBOX_REQUEST_TIMEOUT, SANDBOX_TIMEOUT
 from stirrup.core.models import ImageContentBlock, Tool, ToolUseCountMetadata
 
 from .base import (
@@ -51,7 +53,8 @@ class E2BCodeExecToolProvider(CodeExecToolProvider):
     def __init__(
         self,
         *,
-        timeout: int = SUBMISSION_SANDBOX_TIMEOUT,
+        timeout: int = SANDBOX_TIMEOUT,
+        request_timeout: int = SANDBOX_REQUEST_TIMEOUT,
         template: str | None = None,
         allowed_commands: list[str] | None = None,
     ) -> None:
@@ -67,6 +70,7 @@ class E2BCodeExecToolProvider(CodeExecToolProvider):
         """
         super().__init__(allowed_commands=allowed_commands)
         self._timeout = timeout
+        self._request_timeout = request_timeout
         self._template = template
         self._sbx: AsyncSandbox | None = None
 
@@ -109,7 +113,7 @@ class E2BCodeExecToolProvider(CodeExecToolProvider):
         if not await self._sbx.files.exists(path):
             raise FileNotFoundError(f"File not found: {path}")
 
-        file_bytes = await self._sbx.files.read(path, format="bytes")
+        file_bytes = await self._sbx.files.read(path, format="bytes", request_timeout=self._request_timeout)
         return bytes(file_bytes)
 
     async def write_file_bytes(self, path: str, content: bytes) -> None:
@@ -126,7 +130,7 @@ class E2BCodeExecToolProvider(CodeExecToolProvider):
         if self._sbx is None:
             raise RuntimeError("ExecutionEnvironment not started.")
 
-        await self._sbx.files.write(path, content)
+        await self._sbx.files.write(path, content, request_timeout=self._request_timeout)
 
     async def run_command(self, cmd: str, *, timeout: int = SHELL_TIMEOUT) -> CommandResult:
         """Execute command in E2B execution environment, returning raw CommandResult."""
@@ -146,7 +150,7 @@ class E2BCodeExecToolProvider(CodeExecToolProvider):
             )
 
         try:
-            r = await self._sbx.commands.run(cmd, timeout=timeout)
+            r = await self._sbx.commands.run(cmd, timeout=timeout, request_timeout=self._request_timeout)
 
             return CommandResult(
                 exit_code=getattr(r, "exit_code", 0),
@@ -231,7 +235,7 @@ class E2BCodeExecToolProvider(CodeExecToolProvider):
                     continue
 
                 # Read file content from execution environment
-                file_bytes = await self._sbx.files.read(env_path, format="bytes")
+                file_bytes = await self._sbx.files.read(env_path, format="bytes", request_timeout=self._request_timeout)
                 content = bytes(file_bytes)
 
                 # Save with original filename directly in output_dir
@@ -297,6 +301,7 @@ class E2BCodeExecToolProvider(CodeExecToolProvider):
         result = UploadFilesResult()
 
         for source in paths:
+            original_name = Path(source).name  # Get name BEFORE resolve
             source = Path(source).resolve()
 
             if not source.exists():
@@ -306,9 +311,10 @@ class E2BCodeExecToolProvider(CodeExecToolProvider):
 
             try:
                 if source.is_file():
-                    dest = f"{dest_base}/{source.name}"
+                    source = Path(source).resolve()
+                    dest = f"{dest_base}/{original_name}"
                     content = source.read_bytes()
-                    await self._sbx.files.write(dest, content)
+                    await self._sbx.files.write(dest, content, request_timeout=self._request_timeout)
                     result.uploaded.append(
                         UploadedFile(
                             source_path=source,
@@ -320,12 +326,14 @@ class E2BCodeExecToolProvider(CodeExecToolProvider):
 
                 elif source.is_dir():
                     # Upload all files in directory recursively
+                    # If dest_dir was explicitly provided, copy contents directly to dest_base
+                    # Otherwise, create a subdirectory with the source's name
                     for file_path in source.rglob("*"):
                         if file_path.is_file():
                             relative = file_path.relative_to(source)
-                            dest = f"{dest_base}/{source.name}/{relative}"
+                            dest = f"{dest_base}/{relative}" if dest_dir else f"{dest_base}/{source.name}/{relative}"
                             content = file_path.read_bytes()
-                            await self._sbx.files.write(dest, content)
+                            await self._sbx.files.write(dest, content, request_timeout=self._request_timeout)
                             result.uploaded.append(
                                 UploadedFile(
                                     source_path=file_path,
@@ -333,7 +341,10 @@ class E2BCodeExecToolProvider(CodeExecToolProvider):
                                     size=len(content),
                                 ),
                             )
-                    logger.debug("Uploaded directory: %s -> %s/%s", source, dest_base, source.name)
+                    if dest_dir:
+                        logger.debug("Uploaded directory contents: %s -> %s", source, dest_base)
+                    else:
+                        logger.debug("Uploaded directory: %s -> %s/%s", source, dest_base, source.name)
 
             except Exception as exc:
                 result.failed[str(source)] = str(exc)
@@ -355,5 +366,13 @@ class E2BCodeExecToolProvider(CodeExecToolProvider):
             FileNotFoundError: If file does not exist.
 
         """
-        file_bytes = await self.read_file_bytes(path)
-        return ImageContentBlock(data=file_bytes)
+        if not path.lower().endswith((".png", ".jpg", ".jpeg")):
+            raise ValueError(f"Unsupported image type for `{path}`. Only .png, .jpg, or .jpeg are allowed.")
+
+        try:
+            file_bytes = await self.read_file_bytes(path)
+            image = ImageContentBlock(data=file_bytes)
+        except ValidationError as e:
+            raise ValueError("You submitted a corrupt/unsupported image file.") from e
+
+        return image

stirrup/tools/code_backends/local.py

@@ -122,7 +122,7 @@ class LocalCodeExecToolProvider(CodeExecToolProvider):
         if self._temp_base_dir:
             self._temp_base_dir.mkdir(parents=True, exist_ok=True)
         self._temp_dir = Path(tempfile.mkdtemp(prefix="local_exec_env_", dir=self._temp_base_dir))
-        logger.info("Created local execution environment temp directory: %s", self._temp_dir)
+        logger.debug("Created local execution environment temp directory: %s", self._temp_dir)
         return self.get_code_exec_tool(description=self._description)
 
     async def __aexit__(
@@ -359,7 +359,7 @@ class LocalCodeExecToolProvider(CodeExecToolProvider):
 
                 # Move file (overwrites if exists)
                 shutil.move(str(source_path), str(dest_path))
-                logger.info("Moved file: %s -> %s", source_path, dest_path)
+                logger.debug("Moved file: %s -> %s", source_path, dest_path)
 
                 result.saved.append(
                     SavedFile(
@@ -440,8 +440,20 @@ class LocalCodeExecToolProvider(CodeExecToolProvider):
                     logger.debug("Uploaded file: %s -> %s", source, dest)
 
                 elif source.is_dir():
-                    dest = dest_base / source.name
-                    shutil.copytree(source, dest, dirs_exist_ok=True)
+                    # If dest_dir was explicitly provided, copy contents directly to dest_base
+                    # Otherwise, create a subdirectory with the source's name
+                    if dest_dir:
+                        dest = dest_base
+                        # Copy contents of source directory into dest_base
+                        for item in source.iterdir():
+                            item_dest = dest / item.name
+                            if item.is_file():
+                                shutil.copy2(item, item_dest)
+                            else:
+                                shutil.copytree(item, item_dest, dirs_exist_ok=True)
+                    else:
+                        dest = dest_base / source.name
+                        shutil.copytree(source, dest, dirs_exist_ok=True)
                     # Track all individual files uploaded
                     for file_path in source.rglob("*"):
                         if file_path.is_file():

stirrup/tools/finish.py

@@ -19,5 +19,5 @@ SIMPLE_FINISH_TOOL: Tool[FinishParams, ToolUseCountMetadata] = Tool[FinishParams
     name=FINISH_TOOL_NAME,
     description="Signal task completion with a reason. Use when the task is finished or cannot proceed further. Note that you will need a separate turn to finish.",
     parameters=FinishParams,
-    executor=lambda params: ToolResult(content=params.reason, metadata=ToolUseCountMetadata()),
+    executor=lambda params: ToolResult(content=params.reason, metadata=ToolUseCountMetadata(), success=True),
 )

stirrup/tools/user_input.py

@@ -0,0 +1,130 @@
+"""User input tool for interactive clarification during agent execution.
+
+This module provides the user_input tool that allows agents to ask questions
+and receive text responses from users during task execution.
+
+Example usage:
+    from stirrup.clients.chat_completions_client import ChatCompletionsClient
+    from stirrup.tools import DEFAULT_TOOLS, USER_INPUT_TOOL
+
+    client = ChatCompletionsClient(model="gpt-5")
+    agent = Agent(
+        client=client,
+        name="assistant",
+        tools=[*DEFAULT_TOOLS, USER_INPUT_TOOL],
+    )
+
+    async with agent.session() as session:
+        await session.run("Help me configure my project")
+"""
+
+from typing import Annotated, Literal
+
+from pydantic import BaseModel, Field
+from rich.panel import Panel
+from rich.prompt import Confirm, Prompt
+
+from stirrup.core.models import Tool, ToolResult, ToolUseCountMetadata
+from stirrup.utils.logging import AgentLoggerBase, console
+
+__all__ = ["USER_INPUT_TOOL", "UserInputParams"]
+
+
+class UserInputParams(BaseModel):
+    """Parameters for asking the user a single question.
+
+    Supports three question types:
+    - "text": Free-form text input (default)
+    - "choice": Multiple choice from a list of options
+    - "confirm": Yes/no confirmation
+    """
+
+    question: Annotated[str, Field(description="A single question to ask the user (*not* multiple questions)")]
+    question_type: Annotated[
+        Literal["text", "choice", "confirm"],
+        Field(
+            default="text",
+            description="Type of question: 'text' for free-form, 'choice' for multiple choice, 'confirm' for yes/no",
+        ),
+    ]
+    choices: Annotated[
+        list[str] | None,
+        Field(default=None, description="List of valid choices (required when question_type is 'choice')"),
+    ]
+    default: Annotated[
+        str,
+        Field(default="", description="Default value if user presses Enter without input"),
+    ]
+
+
+def _get_logger() -> "AgentLoggerBase | None":
+    """Get the current session's logger for pause/resume.
+
+    Returns the logger from SessionState if available, None otherwise.
+    """
+    from stirrup.core.agent import _SESSION_STATE
+
+    state = _SESSION_STATE.get(None)
+    return state.logger if state else None
+
+
+def user_input_executor(params: UserInputParams) -> ToolResult[ToolUseCountMetadata]:
+    """Prompt the user for input and return their response."""
+    logger = _get_logger()
+
+    # Pause spinner before prompting
+    if logger:
+        logger.pause_live()
+
+    try:
+        # Print newline to separate from spinner, then display question in a styled panel
+        console.print()
+        panel = Panel(
+            params.question,
+            title="[bold cyan]🤔 Agent Question[/]",
+            title_align="left",
+            border_style="cyan",
+            padding=(0, 1),
+        )
+        console.print(panel)
+
+        # Get user input based on question type
+        if params.question_type == "confirm":
+            # Yes/no confirmation
+            default_bool = params.default.lower() in ("yes", "y", "true", "1") if params.default else False
+            result = Confirm.ask("[bold]Your answer[/]", default=default_bool, console=console)
+            answer = "yes" if result else "no"
+
+        elif params.question_type == "choice" and params.choices:
+            # Multiple choice
+            answer = Prompt.ask(
+                "[bold]Your answer[/]",
+                choices=params.choices,
+                default=params.default,
+                console=console,
+            )
+
+        else:
+            # Free-form text (default)
+            answer = Prompt.ask("[bold]Your answer[/]", default=params.default or "", console=console)
+
+        return ToolResult(content=answer, metadata=ToolUseCountMetadata())
+
+    finally:
+        # Always resume spinner, even if an exception occurs
+        if logger:
+            logger.resume_live()
+
+
+USER_INPUT_TOOL: Tool[UserInputParams, ToolUseCountMetadata] = Tool(
+    name="user_input",
+    description=(
+        "Ask the user a question when you need clarification or are uncertain. "
+        "Supports three types: 'text' for free-form input, 'choice' for multiple choice "
+        "(provide choices list), 'confirm' for yes/no questions. Returns the user's response."
+        "There should only EVER be one question per call to this tool."
+        "If you need to ask multiple questions, you should call this tool multiple times."
+    ),
+    parameters=UserInputParams,
+    executor=user_input_executor,
+)

stirrup/tools/web.py

@@ -125,6 +125,7 @@ def _get_fetch_web_page_tool(client: httpx.AsyncClient | None = None) -> Tool[Fe
             return ToolResult(
                 content=f"<web_fetch><url>{params.url}</url><error>"
                 f"{truncate_msg(str(exc), MAX_LENGTH_WEB_FETCH_HTML)}</error></web_fetch>",
+                success=False,
                 metadata=WebFetchMetadata(pages_fetched=[params.url]),
             )
 

stirrup/utils/logging.py

@@ -27,6 +27,7 @@ from stirrup.core.models import AssistantMessage, ToolMessage, UserMessage, _agg
 __all__ = [
     "AgentLogger",
     "AgentLoggerBase",
+    "console",
 ]
 
 # Shared console instance
@@ -247,6 +248,12 @@ class AgentLoggerBase(ABC):
         """Log an error message."""
         ...
 
+    def pause_live(self) -> None:  # noqa: B027
+        """Pause live display (e.g., spinner) before user interaction."""
+
+    def resume_live(self) -> None:  # noqa: B027
+        """Resume live display after user interaction."""
+
 
 class AgentLogger(AgentLoggerBase):
     """Rich console logger for agent workflows.
@@ -655,6 +662,23 @@ class AgentLogger(AgentLoggerBase):
         if self._live:
             self._live.update(self._make_spinner())
 
+    def pause_live(self) -> None:
+        """Pause the live spinner display.
+
+        Call this before prompting for user input to prevent the spinner
+        from interfering with the input prompt.
+        """
+        if self._live is not None:
+            self._live.stop()
+
+    def resume_live(self) -> None:
+        """Resume the live spinner display.
+
+        Call this after user input is complete to restart the spinner.
+        """
+        if self._live is not None:
+            self._live.start()
+
     def set_level(self, level: int) -> None:
         """Set the logging level."""
         self._level = level