hud-python 0.5.1__py3-none-any.whl → 0.5.13__py3-none-any.whl

hud/patches/mcp_patches.py

@@ -18,8 +18,10 @@ def patch_streamable_http_error_handling() -> None:
     Patch StreamableHTTPTransport.post_writer to handle request errors properly.
 
     The original implementation doesn't catch errors in handle_request_async,
-    which can cause silent failures. This patch wraps the handler to send
-    errors to the read stream so clients know the request failed.
+    which can cause the client to hang indefinitely. This patch wraps the handler
+    to send a proper JSONRPCError response when transport errors occur (e.g.,
+    ReadTimeout), allowing the waiting caller to receive the error and fail
+    gracefully instead of hanging.
     """
     try:
         from mcp.client.streamable_http import StreamableHTTPTransport
@@ -33,10 +35,67 @@ def patch_streamable_http_error_handling() -> None:
             start_get_stream: Any,
             tg: Any,
         ) -> None:
-            """Patched post_writer with error handling for handle_request_async."""
+            import asyncio
+            import ssl
+            import time
+
+            import httpx
             from mcp.client.streamable_http import RequestContext
-            from mcp.shared.message import ClientMessageMetadata
-            from mcp.types import JSONRPCRequest
+            from mcp.shared.message import ClientMessageMetadata, SessionMessage
+            from mcp.types import ErrorData, JSONRPCError, JSONRPCMessage, JSONRPCRequest
+
+            from hud.settings import settings
+
+            async def handle_request_async(ctx: RequestContext, is_resumption: bool) -> None:
+                msg = ctx.session_message.message
+                # Use configured timeout, minimum 30s to prevent instant failures
+                timeout = max(settings.client_timeout, 15.0)
+                deadline = time.monotonic() + timeout
+                retryable = (
+                    httpx.ConnectError,
+                    httpx.ReadError,
+                    httpx.TimeoutException,
+                    ssl.SSLError,
+                )
+
+                async def send_error_response(exc: Exception) -> None:
+                    """Send an error response to the client."""
+                    if isinstance(msg.root, JSONRPCRequest):
+                        error_response = JSONRPCError(
+                            jsonrpc="2.0",
+                            id=msg.root.id,
+                            error=ErrorData(
+                                code=-32000,
+                                message=f"Transport error: {type(exc).__name__}",
+                                data={"error_type": type(exc).__name__, "detail": str(exc)},
+                            ),
+                        )
+                        await ctx.read_stream_writer.send(
+                            SessionMessage(JSONRPCMessage(error_response))
+                        )
+                    else:
+                        await ctx.read_stream_writer.send(exc)
+
+                while True:
+                    try:
+                        if is_resumption:
+                            await self._handle_resumption_request(ctx)
+                        else:
+                            await self._handle_post_request(ctx)
+                        return
+                    except retryable as e:
+                        if time.monotonic() >= deadline:
+                            logger.error("MCP request failed after timeout: %s", e)
+                            await send_error_response(e)
+                            return
+                        logger.warning("Retrying MCP request after error: %s", e)
+                        await asyncio.sleep(2.0)
+                    except asyncio.CancelledError:
+                        raise
+                    except Exception as e:
+                        logger.exception("Request handler error: %s", e)
+                        await send_error_response(e)
+                        return
 
             try:
                 async with write_stream_reader:
@@ -47,7 +106,6 @@ def patch_streamable_http_error_handling() -> None:
                             if isinstance(session_message.metadata, ClientMessageMetadata)
                             else None
                         )
-
                         is_resumption = bool(metadata and metadata.resumption_token)
 
                         logger.debug("Sending client message: %s", message)
@@ -65,21 +123,6 @@ def patch_streamable_http_error_handling() -> None:
                             sse_read_timeout=self.sse_read_timeout,
                         )
 
-                        # Patched: Accept ctx and is_resumption as params, add error handling
-                        async def handle_request_async(
-                            ctx: RequestContext = ctx,
-                            is_resumption: bool = is_resumption,
-                        ) -> None:
-                            try:
-                                if is_resumption:
-                                    await self._handle_resumption_request(ctx)
-                                else:
-                                    await self._handle_post_request(ctx)
-                            except Exception as e:
-                                # Send error to read stream so client knows request failed
-                                logger.error("Request handler error: %s", e)
-                                await ctx.read_stream_writer.send(e)
-
                         if isinstance(message.root, JSONRPCRequest):
                             tg.start_soon(handle_request_async, ctx, is_resumption)
                         else:
@@ -122,6 +165,119 @@ def patch_client_session_validation() -> None:
         logger.warning("Failed to patch client session: %s", e)
 
 
+def patch_server_output_validation() -> None:
+    """
+    Patch MCP server to skip structured output validation and auto-generate
+    structuredContent for FastMCP tools with x-fastmcp-wrap-result.
+    """
+    try:
+        import json
+
+        import mcp.types as types
+        from mcp.server.lowlevel.server import Server
+
+        def patched_call_tool(
+            self: Any, validate_input: bool = True, validate_output: bool = False
+        ) -> Any:
+            """Patched call_tool that skips output validation."""
+
+            def decorator(func: Any) -> Any:
+                async def handler(req: types.CallToolRequest) -> Any:
+                    try:
+                        tool_name = req.params.name
+                        arguments = req.params.arguments or {}
+                        tool = await self._get_cached_tool_definition(tool_name)
+
+                        if validate_input and tool:
+                            try:
+                                import jsonschema
+
+                                jsonschema.validate(instance=arguments, schema=tool.inputSchema)
+                            except jsonschema.ValidationError as e:
+                                return self._make_error_result(
+                                    f"Input validation error: {e.message}"
+                                )
+
+                        results = await func(tool_name, arguments)
+
+                        # output normalization
+                        unstructured_content: list[Any]
+                        maybe_structured_content: dict[str, Any] | None
+                        if isinstance(results, types.CallToolResult):
+                            return types.ServerResult(results)
+                        elif isinstance(results, tuple) and len(results) == 2:
+                            unstructured_content, maybe_structured_content = results
+                        elif isinstance(results, dict):
+                            maybe_structured_content = results
+                            text = json.dumps(results, indent=2)
+                            unstructured_content = [types.TextContent(type="text", text=text)]
+                        elif results is None:
+                            # None means success with no content
+                            unstructured_content = []
+                            maybe_structured_content = None
+                        elif isinstance(results, (str, bytes, bytearray, memoryview)):
+                            # Handle string/bytes explicitly before iterable check
+                            # (these are iterable but should not be split into chars/ints)
+                            if isinstance(results, str):
+                                text = results
+                            elif isinstance(results, memoryview):
+                                text = bytes(results).decode("utf-8", errors="replace")
+                            else:
+                                text = bytes(results).decode("utf-8", errors="replace")
+                            unstructured_content = [types.TextContent(type="text", text=text)]
+                            maybe_structured_content = None
+                        elif isinstance(results, (int, float, bool)):
+                            # Primitives -> string representation
+                            unstructured_content = [
+                                types.TextContent(type="text", text=str(results))
+                            ]
+                            maybe_structured_content = None
+                        elif hasattr(results, "__iter__"):
+                            unstructured_content = list(results)
+                            maybe_structured_content = None
+                        else:
+                            return self._make_error_result(
+                                f"Unexpected return type: {type(results).__name__}"
+                            )
+
+                        # Auto-generate structuredContent for FastMCP tools
+                        # FastMCP generates outputSchema but doesn't populate it
+                        if maybe_structured_content is None and tool:
+                            output_schema = getattr(tool, "outputSchema", None)
+                            if output_schema and output_schema.get("x-fastmcp-wrap-result"):
+                                for item in unstructured_content:
+                                    if isinstance(item, types.TextContent):
+                                        try:
+                                            parsed = json.loads(item.text)
+                                            maybe_structured_content = {"result": parsed}
+                                        except json.JSONDecodeError:
+                                            maybe_structured_content = {"result": item.text}
+                                        break
+
+                        return types.ServerResult(
+                            types.CallToolResult(
+                                content=list(unstructured_content),
+                                structuredContent=maybe_structured_content,
+                                isError=False,
+                            )
+                        )
+                    except Exception as e:
+                        return self._make_error_result(str(e))
+
+                self.request_handlers[types.CallToolRequest] = handler
+                return func
+
+            return decorator
+
+        Server.call_tool = patched_call_tool
+        logger.debug("Patched Server.call_tool to skip output validation")
+
+    except ImportError:
+        logger.debug("mcp.server.lowlevel.server not available, skipping patch")
+    except Exception as e:
+        logger.warning("Failed to patch server output validation: %s", e)
+
+
 def suppress_fastmcp_logging(level: int = logging.WARNING) -> None:
     """
     Suppress verbose fastmcp logging.
@@ -147,5 +303,6 @@ def apply_all_patches() -> None:
     """Apply all MCP patches."""
     patch_streamable_http_error_handling()
     patch_client_session_validation()
+    patch_server_output_validation()
     suppress_fastmcp_logging()
     logger.debug("All MCP patches applied")

hud/telemetry/instrument.py

@@ -83,6 +83,7 @@ def instrument(
     name: str | None = None,
     category: str = "function",
     span_type: str | None = None,
+    internal_type: str | None = None,
     record_args: bool = True,
     record_result: bool = True,
 ) -> Callable[[Callable[..., Any]], Callable[..., Any]]: ...
@@ -95,6 +96,7 @@ def instrument(
     name: str | None = None,
     category: str = "function",
     span_type: str | None = None,
+    internal_type: str | None = None,
     record_args: bool = True,
     record_result: bool = True,
 ) -> Callable[P, R]: ...
@@ -107,6 +109,7 @@ def instrument(
     name: str | None = None,
     category: str = "function",
     span_type: str | None = None,
+    internal_type: str | None = None,
     record_args: bool = True,
     record_result: bool = True,
 ) -> Callable[P, Awaitable[R]]: ...
@@ -118,6 +121,7 @@ def instrument(
     name: str | None = None,
     category: str = "function",
     span_type: str | None = None,
+    internal_type: str | None = None,
     record_args: bool = True,
     record_result: bool = True,
 ) -> Callable[..., Any]:
@@ -130,6 +134,7 @@ def instrument(
         name: Custom span name (defaults to module.function)
         category: Span category (e.g., "agent", "tool", "function", "mcp")
         span_type: Alias for category (deprecated, use category instead)
+        internal_type: Internal span type (e.g., "user-message")
         record_args: Whether to record function arguments
         record_result: Whether to record function result
 
@@ -204,7 +209,7 @@ def instrument(
 
             # Build span
             span_id = uuid.uuid4().hex[:16]
-            span = {
+            span: dict[str, Any] = {
                 "name": span_name,
                 "trace_id": _normalize_trace_id(task_run_id),
                 "span_id": span_id,
@@ -216,6 +221,8 @@ def instrument(
                 "attributes": attributes.model_dump(mode="json", exclude_none=True),
                 "exceptions": [{"message": error}] if error else None,
             }
+            if internal_type:
+                span["internal_type"] = internal_type
             return span
 
         @functools.wraps(func)

hud/telemetry/tests/test_eval_telemetry.py

@@ -49,8 +49,8 @@ class TestEvalContextTelemetry:
             """Say hello."""
             return f"Hello, {name}!"
 
-        # Create task from environment
-        task = Task(env=env)
+        # Create task from environment (args={} = runnable, args=None = template)
+        task = Task(env=env, args={})
 
         with (
             patch("hud.settings.settings") as mock_settings,
@@ -110,7 +110,7 @@ class TestEvalContextTelemetry:
             """Always fails."""
             raise ValueError("Tool error")
 
-        task = Task(env=env)
+        task = Task(env=env, args={})
 
         with (
             patch("hud.settings.settings") as mock_settings,
@@ -162,7 +162,7 @@ class TestEvalContextTelemetry:
             """Multiply two numbers."""
             return a * b
 
-        task = Task(env=env)
+        task = Task(env=env, args={})
 
         with (
             patch("hud.settings.settings") as mock_settings,
@@ -195,7 +195,7 @@ class TestEvalContextTelemetry:
         async def simple_tool() -> str:
             return "done"
 
-        task = Task(env=env)
+        task = Task(env=env, args={})
 
         with (
             patch("hud.eval.context.flush") as mock_flush,
@@ -229,7 +229,7 @@ class TestEvalContextTelemetry:
         async def test_tool() -> str:
             return "ok"
 
-        task = Task(env=env)
+        task = Task(env=env, args={})
 
         with (
             patch("hud.settings.settings") as mock_settings,
@@ -272,7 +272,7 @@ class TestSpanFormat:
         async def echo(message: str) -> str:
             return message
 
-        task = Task(env=env)
+        task = Task(env=env, args={})
 
         with (
             patch("hud.settings.settings") as mock_settings,
@@ -329,7 +329,7 @@ class TestSpanFormat:
         async def noop() -> None:
             pass
 
-        task = Task(env=env)
+        task = Task(env=env, args={})
 
         with (
             patch("hud.settings.settings") as mock_settings,

hud/tools/__init__.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING, Any
 
+from .agent import AgentTool
 from .base import BaseHub, BaseTool
 from .bash import BashTool
 from .edit import EditTool
@@ -21,6 +22,7 @@ if TYPE_CHECKING:
     )
 
 __all__ = [
+    "AgentTool",
     "AnthropicComputerTool",
     "BaseHub",
     "BaseTool",

hud/tools/agent.py

@@ -0,0 +1,223 @@
+"""AgentTool - run a Task with an agent as a tool."""
+
+from __future__ import annotations
+
+import inspect
+from typing import TYPE_CHECKING, Any, Union, get_args, get_origin
+
+from fastmcp.tools.tool import FunctionTool, ToolResult
+from mcp.types import TextContent
+
+from hud.tools.base import BaseTool
+
+if TYPE_CHECKING:
+    from hud.agents.base import MCPAgent
+    from hud.eval.task import Task
+
+__all__ = ["AgentTool"]
+
+
+def _is_eval_only(param: inspect.Parameter) -> bool:
+    """Check if param is eval-only: has None default AND None in type union.
+
+    Handles both runtime types and string annotations (PEP 563).
+    """
+    # Must have default of None
+    if param.default is not None:
+        return False
+    if param.annotation is inspect.Parameter.empty:
+        return False
+
+    annotation = param.annotation
+
+    # Handle string annotations (from __future__ annotations or quoted)
+    if isinstance(annotation, str):
+        # Check if it looks like "X | None", "Union[X, None]", or "Optional[X]"
+        return (
+            "| None" in annotation
+            or "None |" in annotation
+            or "Optional[" in annotation
+            or ("Union[" in annotation and "None" in annotation)
+        )
+
+    # Handle runtime type annotations
+    origin = get_origin(annotation)
+
+    # Union types (X | None or Union[X, None])
+    if origin is Union:
+        return type(None) in get_args(annotation)
+
+    # For Python 3.10+ union syntax at runtime (types.UnionType)
+    try:
+        import types
+
+        if isinstance(annotation, types.UnionType):
+            return type(None) in get_args(annotation)
+    except (ImportError, AttributeError):
+        pass
+
+    return False
+
+
+class AgentTool(BaseTool):
+    """Tool that runs a Task template with an agent.
+
+    Parameters with `| None = None` are eval-only and hidden from the tool schema.
+
+    Example:
+        ```python
+        @env.scenario()
+        async def investigate(
+            issue_id: str,  # Required - orchestrator sees
+            expected_cause: str | None = None,  # Eval only - hidden
+        ):
+            yield {"task": f"Investigate {issue_id}"}
+
+
+        seer = AgentTool(env("investigate"), model="ft:seer-v2")
+        ```
+    """
+
+    def __init__(
+        self,
+        task: Task,
+        *,
+        model: str | None = None,
+        agent: type[MCPAgent] | None = None,
+        agent_params: dict[str, Any] | None = None,
+        name: str | None = None,
+        description: str | None = None,
+        trace: bool = False,
+    ) -> None:
+        if not model and agent is None:
+            raise ValueError("Must provide either 'model' or 'agent'")
+        if model and agent is not None:
+            raise ValueError("Cannot provide both 'model' and 'agent'")
+
+        self._task = task
+        self._model = model
+        self._agent_cls = agent
+        self._agent_params = agent_params or {}
+        self._trace = trace
+
+        # Get visible params from scenario function
+        self._visible_params: set[str] = set()
+        self._param_schema: dict[str, Any] = {
+            "type": "object",
+            "properties": {},
+            "required": [],
+        }
+
+        if task.env and task.scenario:
+            scenario_fn = task.env._scenarios.get(task.scenario)
+            if scenario_fn:
+                sig = inspect.signature(scenario_fn)
+                visible = {name: p for name, p in sig.parameters.items() if not _is_eval_only(p)}
+                self._visible_params = set(visible.keys())
+                self._param_schema = self._build_schema(visible)
+
+        tool_name = name or task.scenario or "agent_tool"
+        tool_desc = description or f"Run scenario: {task.scenario}"
+
+        super().__init__(name=tool_name, description=tool_desc)
+
+    def _build_schema(self, params: dict[str, inspect.Parameter]) -> dict[str, Any]:
+        """Build JSON schema using Pydantic TypeAdapter."""
+        from pydantic import TypeAdapter
+
+        properties: dict[str, Any] = {}
+        required: list[str] = []
+
+        for name, param in params.items():
+            if param.annotation is not inspect.Parameter.empty:
+                try:
+                    # Handle string annotations
+                    annotation = param.annotation
+                    if isinstance(annotation, str):
+                        # Try to evaluate the annotation
+                        try:
+                            annotation = eval(annotation)  # noqa: S307
+                        except Exception:
+                            # Fall back to string type but don't skip required handling
+                            annotation = None
+
+                    if annotation is not None:
+                        adapter = TypeAdapter(annotation)
+                        properties[name] = adapter.json_schema()
+                    else:
+                        properties[name] = {"type": "string"}
+                except Exception:
+                    properties[name] = {"type": "string"}
+            else:
+                properties[name] = {"type": "string"}
+
+            if param.default is inspect.Parameter.empty:
+                required.append(name)
+            elif param.default is not None:
+                properties[name]["default"] = param.default
+
+        return {"type": "object", "properties": properties, "required": required}
+
+    @property
+    def mcp(self) -> FunctionTool:
+        """Get as FastMCP FunctionTool with filtered schema."""
+        if not hasattr(self, "_mcp_tool"):
+            # Directly instantiate FunctionTool with our callable and schema
+            # This bypasses from_function's signature parsing
+            self._mcp_tool = FunctionTool(
+                name=self.name,
+                description=self.description or "",
+                parameters=self._param_schema,
+                fn=self._execute_with_args,
+            )
+        return self._mcp_tool
+
+    async def _execute_with_args(self, **kwargs: Any) -> ToolResult:
+        """Internal executor that FastMCP calls with parsed arguments."""
+        return await self(**kwargs)
+
+    async def __call__(self, **kwargs: Any) -> ToolResult:
+        """Execute the task with a fresh agent."""
+        from hud.eval.context import get_current_trace_id
+        from hud.eval.manager import run_eval
+        from hud.telemetry.instrument import instrument
+
+        # Filter to visible params only
+        filtered = {k: v for k, v in kwargs.items() if k in self._visible_params}
+
+        # Merge with template args
+        base_args = self._task.args or {}
+        task = self._task.model_copy(update={"args": {**base_args, **filtered}})
+
+        # Use parent trace if available (for hierarchical agents)
+        parent_trace_id = get_current_trace_id()
+
+        # If nested (has parent), skip subagent's enter/exit registration
+        # Tool calls are still recorded via the shared trace_id's context
+        is_nested = parent_trace_id is not None
+
+        # Trace if explicitly requested AND not nested (nested uses parent trace)
+        should_trace = self._trace and not is_nested
+
+        # Wrap execution with instrumentation to mark as subagent
+        # Platform uses category="subagent" to detect and render subagent tool calls
+        @instrument(category="subagent", name=self.name)
+        async def _run_subagent() -> ToolResult:
+            async with run_eval(
+                task,
+                trace=should_trace,
+                trace_id=parent_trace_id,
+                quiet=True,
+            ) as ctx:
+                if self._model:
+                    from hud.agents import create_agent
+
+                    agent = create_agent(self._model, **self._agent_params)
+                else:
+                    agent = self._agent_cls.create(**self._agent_params)  # type: ignore
+
+                result = await agent.run(ctx)
+                content = result.content if hasattr(result, "content") and result.content else ""
+                return ToolResult(content=[TextContent(type="text", text=content)])
+
+        return await _run_subagent()

hud/tools/computer/__init__.py

@@ -2,13 +2,17 @@
 
 from __future__ import annotations
 
-from .anthropic import AnthropicComputerTool
-from .gemini import GeminiComputerTool
-from .hud import HudComputerTool
-from .openai import OpenAIComputerTool
-from .qwen import QwenComputerTool
+from typing import TYPE_CHECKING
+
 from .settings import computer_settings
 
+if TYPE_CHECKING:
+    from .anthropic import AnthropicComputerTool
+    from .gemini import GeminiComputerTool
+    from .hud import HudComputerTool
+    from .openai import OpenAIComputerTool
+    from .qwen import QwenComputerTool
+
 __all__ = [
     "AnthropicComputerTool",
     "GeminiComputerTool",
@@ -17,3 +21,28 @@ __all__ = [
     "QwenComputerTool",
     "computer_settings",
 ]
+
+
+def __getattr__(name: str) -> type:
+    """Lazy import computer tools."""
+    if name == "AnthropicComputerTool":
+        from .anthropic import AnthropicComputerTool
+
+        return AnthropicComputerTool
+    elif name == "GeminiComputerTool":
+        from .gemini import GeminiComputerTool
+
+        return GeminiComputerTool
+    elif name == "HudComputerTool":
+        from .hud import HudComputerTool
+
+        return HudComputerTool
+    elif name == "OpenAIComputerTool":
+        from .openai import OpenAIComputerTool
+
+        return OpenAIComputerTool
+    elif name == "QwenComputerTool":
+        from .qwen import QwenComputerTool
+
+        return QwenComputerTool
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

hud/tools/shell.py

@@ -82,10 +82,10 @@ class _BashSession:
             await asyncio.sleep(0)
             return
 
-        # preexec_fn and user demotion only available on Unix
+        # preexec_fn and user demotion only available on Unix when running as root
         preexec_fn = None
-        if sys.platform != "win32":
-
+        if sys.platform != "win32" and os.getuid() == 0:
+            # Only demote when running as root (e.g., inside Docker containers)
             def demote() -> None:
                 # This only runs in the child process (Unix only)
                 os.setsid()  # type: ignore[attr-defined]