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

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,
@@ -327,7 +333,7 @@ class E2BCodeExecToolProvider(CodeExecToolProvider):
                             relative = file_path.relative_to(source)
                             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,
@@ -360,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(

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

{stirrup-0.1.2.dist-info → stirrup-0.1.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: stirrup
-Version: 0.1.2
+Version: 0.1.3
 Summary: The lightweight foundation for building agents
 Keywords: ai,agent,llm,openai,anthropic,tools,framework
 Author: Artificial Analysis, Inc.

stirrup-0.1.3.dist-info/RECORD

@@ -0,0 +1,36 @@
+stirrup/__init__.py,sha256=4p5Rw7f_wdxVu1FJTgJROe0aTlnc8tOsainBEzDRGEY,1905
+stirrup/clients/__init__.py,sha256=oO8VMHmbUhoxFyC0JLQs_kUFNSRlvTj5xz0FgzBb98E,405
+stirrup/clients/chat_completions_client.py,sha256=P0VOGFQcfLIVf7zCGYbopQDjNVEJlpeLBeGvB87sQQg,7390
+stirrup/clients/litellm_client.py,sha256=2ZrZKKAEV2dEFs6ze4qBl3it5VwiGH8s7wHVuHdw-uY,5507
+stirrup/clients/utils.py,sha256=Z_8KiENDZVD9fChUm7PA-RLhvoChswHVQsjrHXlIfkg,5684
+stirrup/constants.py,sha256=WpVPm2jRN2AqYMyoMYeJimiggoquP7M3IrcHNpduFF4,644
+stirrup/core/__init__.py,sha256=ReBVl7B9h_FNkZ77vCx2xlfuK1JuQ0yTSXrEgc4tONU,39
+stirrup/core/agent.py,sha256=2KxjuCy3scLRc59habPSZyYDCHL9a9--UcdFKYV-86w,56907
+stirrup/core/cache.py,sha256=lAbbBJzgYInewoBBPMzNooroU2Q7JbF21riggfdIDa8,16697
+stirrup/core/exceptions.py,sha256=CzLVAi7Ns-t9BWSkqQUCB7ypVHAesV2s4a09-i0NXyQ,213
+stirrup/core/models.py,sha256=qMmpecRIl8sKdUePtoVChKA3rBHxzG8lI4ZvuLFHNzo,22553
+stirrup/prompts/__init__.py,sha256=e4bpTktBaFPuO_bIW5DelGNWtT6_NIUqnD2lRv8n89I,796
+stirrup/prompts/base_system_prompt.txt,sha256=D_UlDWEnG2yaPCMFrE7IqMHI8VCzi4BZ-GnuL3qs5q4,288
+stirrup/prompts/message_summarizer.txt,sha256=uQoTxreMuC42rTGSZmoH1Dnj06WrEQb0gLkDvVMhosQ,1173
+stirrup/prompts/message_summarizer_bridge.txt,sha256=sWbfnHtI6RWemBIyQsnqHMGpnU-E6FTbfUC6rvkEHLY,372
+stirrup/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+stirrup/skills/__init__.py,sha256=BEcmdSskfBzx_QK4eKXECucndIKRjHXzzwwwsaez8k4,700
+stirrup/skills/skills.py,sha256=qhA3HI55kaRqLyvn_56Cs71833Xacg-8qP7muHrwruE,4282
+stirrup/tools/__init__.py,sha256=l8bKHZwPBZfBPgxQfLzOKyyzdfoF86NrgdmxhjYW09s,2790
+stirrup/tools/calculator.py,sha256=Cckt-8TtltxtuyY_Hh0wOr8efUzBZzg7rG4dBpvpuRM,1293
+stirrup/tools/code_backends/__init__.py,sha256=O3Rs76r0YcQ27voTrx_zuhIEFawK3b1TQdKi70MORG8,987
+stirrup/tools/code_backends/base.py,sha256=5mQxbHoOvtTdiF1y1aVe4csodaCOGvHaVN5viRnUlUE,17250
+stirrup/tools/code_backends/docker.py,sha256=Xx4aBZ1uXVznP0qV4tXL2PMMs-8QEPw1bIPvgPasEGk,30281
+stirrup/tools/code_backends/e2b.py,sha256=4I5Aqas-4PVhYgMhIAQh3xcwl_0kGiUpo64UU9-awfE,14921
+stirrup/tools/code_backends/local.py,sha256=snzbWHnZkVu1ibLLRyRVmi6U9-8407_A0sKbdDNyTe4,19600
+stirrup/tools/finish.py,sha256=zdljSs77zMVkA2AGUfV05QmeLxz6JrwJF_ar02yvsVA,950
+stirrup/tools/mcp.py,sha256=4wWYae95y8Bs7e36hHwnxRfVVj0PABrsRStw492lLaw,18749
+stirrup/tools/user_input.py,sha256=XwK14FvRQly3vGwgNzPVGoSXfbco0WWaSVpTDyjV09E,4508
+stirrup/tools/view_image.py,sha256=zazCpZMtLOD6lplLPYGNQ8JeYfc0oUDJoUUyVAp3AMU,3126
+stirrup/tools/web.py,sha256=B-zp5i1WhjOOMAlYtnvU3N5hNYnJYm8qVXAtNx_ZaRw,12292
+stirrup/utils/__init__.py,sha256=4kcuExrphSXqgxRgu1q8_Z6Rrb9aAZpIo4Xq4S9Twuk,230
+stirrup/utils/logging.py,sha256=48rCzv7B15jiVM1JlKzwTSnGodbqGSKLlsZi9xRMmVM,35045
+stirrup/utils/text.py,sha256=3lGlcXFzQ-Mclsbu7wJciG3CcHvQ_Sk98tqOZxYLlGw,479
+stirrup-0.1.3.dist-info/WHEEL,sha256=KSLUh82mDPEPk0Bx0ScXlWL64bc8KmzIPNcpQZFV-6E,79
+stirrup-0.1.3.dist-info/METADATA,sha256=EyJEJTRFzLoSXnkBPauFvskBgMwJDJ8O2Vm8HdJPdsI,12862
+stirrup-0.1.3.dist-info/RECORD,,

{stirrup-0.1.2.dist-info → stirrup-0.1.3.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: uv 0.9.18
+Generator: uv 0.9.22
 Root-Is-Purelib: true
 Tag: py3-none-any

stirrup-0.1.2.dist-info/RECORD

@@ -1,34 +0,0 @@
-stirrup/__init__.py,sha256=Dol0Uui-gBslpplfEUrgxkqqJWr1ucZJej5finNvCeI,1869
-stirrup/clients/__init__.py,sha256=oO8VMHmbUhoxFyC0JLQs_kUFNSRlvTj5xz0FgzBb98E,405
-stirrup/clients/chat_completions_client.py,sha256=p_EeXqRuo6mWnzgMhy22SWdHE6_OXIRyABvCKgHdnu4,7586
-stirrup/clients/litellm_client.py,sha256=J-HDv7ZZTkNYC-aeSNyd7xTDd_5r8DEeXOPz9eQMC7A,4985
-stirrup/clients/utils.py,sha256=Yyeh6unQSvqgDTDhjpD5DoRu_wP_nWfsNv9DGXQwgo8,5452
-stirrup/constants.py,sha256=h3NzsePJ4FKpImTpV5xtFeJarKb67jR_6n89tNOkQYs,523
-stirrup/core/__init__.py,sha256=ReBVl7B9h_FNkZ77vCx2xlfuK1JuQ0yTSXrEgc4tONU,39
-stirrup/core/agent.py,sha256=tt1V564B6n_C0ffyH24LuC6PhE4EJA8NOolQCxDG9iw,50836
-stirrup/core/exceptions.py,sha256=CzLVAi7Ns-t9BWSkqQUCB7ypVHAesV2s4a09-i0NXyQ,213
-stirrup/core/models.py,sha256=KAyjJIoqbhgy_MN0sPwGI8XWxSiziPnyndMD05ylj_U,21121
-stirrup/prompts/__init__.py,sha256=e4bpTktBaFPuO_bIW5DelGNWtT6_NIUqnD2lRv8n89I,796
-stirrup/prompts/base_system_prompt.txt,sha256=KZ2_JhJ91u4oMqRZvhuAp99nb6ZkXkJdVbIRN6drVME,348
-stirrup/prompts/message_summarizer.txt,sha256=uQoTxreMuC42rTGSZmoH1Dnj06WrEQb0gLkDvVMhosQ,1173
-stirrup/prompts/message_summarizer_bridge.txt,sha256=sWbfnHtI6RWemBIyQsnqHMGpnU-E6FTbfUC6rvkEHLY,372
-stirrup/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-stirrup/skills/__init__.py,sha256=BEcmdSskfBzx_QK4eKXECucndIKRjHXzzwwwsaez8k4,700
-stirrup/skills/skills.py,sha256=qhA3HI55kaRqLyvn_56Cs71833Xacg-8qP7muHrwruE,4282
-stirrup/tools/__init__.py,sha256=ohyeMvXb6oURiAyoHi0VmC9ksZSRyGleT341VNzHCy4,2714
-stirrup/tools/calculator.py,sha256=JkuGmGZJtaKbC4vHVrIph4aTjlGcFMhhv5MB1ntqgv4,1278
-stirrup/tools/code_backends/__init__.py,sha256=O3Rs76r0YcQ27voTrx_zuhIEFawK3b1TQdKi70MORG8,987
-stirrup/tools/code_backends/base.py,sha256=Nx0tTDX4GKoBWQK2F953vSsFgWCcOd_1WNtYCA4FG4o,17021
-stirrup/tools/code_backends/docker.py,sha256=Xx4aBZ1uXVznP0qV4tXL2PMMs-8QEPw1bIPvgPasEGk,30281
-stirrup/tools/code_backends/e2b.py,sha256=7wV1SOu4S5g5uCtnipC1xNg8kBzCrudyIEOIkf-JCkE,14072
-stirrup/tools/code_backends/local.py,sha256=WV-MMcPY5ooKPhOwd3JUUz718Ht8eRyYklGAZ0gkrx4,19598
-stirrup/tools/finish.py,sha256=K_NxwOwdvncT2QTua2A_8lZ9MwK4WQQ5FL2gdUrE29c,936
-stirrup/tools/mcp.py,sha256=4wWYae95y8Bs7e36hHwnxRfVVj0PABrsRStw492lLaw,18749
-stirrup/tools/view_image.py,sha256=zazCpZMtLOD6lplLPYGNQ8JeYfc0oUDJoUUyVAp3AMU,3126
-stirrup/tools/web.py,sha256=2yfBJsu8GgFI7Oh1dFlXwNaXth6WQfGpbJFU-rV-yuI,12261
-stirrup/utils/__init__.py,sha256=4kcuExrphSXqgxRgu1q8_Z6Rrb9aAZpIo4Xq4S9Twuk,230
-stirrup/utils/logging.py,sha256=3Li6MhjLJWwaXHDZ06EjgW42XDL6V3ZDt9rccV_ZYZ4,34292
-stirrup/utils/text.py,sha256=3lGlcXFzQ-Mclsbu7wJciG3CcHvQ_Sk98tqOZxYLlGw,479
-stirrup-0.1.2.dist-info/WHEEL,sha256=ZyFSCYkV2BrxH6-HRVRg3R9Fo7MALzer9KiPYqNxSbo,79
-stirrup-0.1.2.dist-info/METADATA,sha256=eIK1F1yXhCgFspDO8q5J48B7P3Jt16QZez3ZBVFU5n8,12862
-stirrup-0.1.2.dist-info/RECORD,,