voxagent 0.1.1__py3-none-any.whl → 0.2.1__py3-none-any.whl

voxagent/_version.py

@@ -1,2 +1,2 @@
-__version__ = "0.1.1"
+__version__ = "0.2.1"
 __version_info__ = tuple(int(x) for x in __version__.split("."))

voxagent/code/__init__.py

@@ -5,5 +5,51 @@ This subpackage provides:
 - Tool file generation from MCP servers
 - Skills persistence and discovery
 - PII tokenization for privacy
+- Virtual filesystem for tool discovery
+- Code execution mode for agents
+- Tool proxy for routing sandbox calls to real implementations
 """
 
+from voxagent.code.sandbox import CodeSandbox, SandboxResult, SubprocessSandbox
+from voxagent.code.virtual_fs import (
+    ToolCategory,
+    ToolRegistry,
+    VirtualFilesystem,
+)
+from voxagent.code.agent import (
+    CodeModeConfig,
+    CodeModeExecutor,
+    get_code_mode_system_prompt_addition,
+    setup_code_mode_for_agent,
+    CODE_MODE_SYSTEM_PROMPT,
+)
+from voxagent.code.tool_proxy import (
+    ToolCallRequest,
+    ToolCallResponse,
+    ToolProxyClient,
+    ToolProxyServer,
+    create_tool_proxy_pair,
+)
+
+__all__ = [
+    # Sandbox
+    "CodeSandbox",
+    "SandboxResult",
+    "SubprocessSandbox",
+    # Virtual FS
+    "ToolCategory",
+    "ToolRegistry",
+    "VirtualFilesystem",
+    # Code Mode Agent
+    "CodeModeConfig",
+    "CodeModeExecutor",
+    "CODE_MODE_SYSTEM_PROMPT",
+    "get_code_mode_system_prompt_addition",
+    "setup_code_mode_for_agent",
+    # Tool Proxy
+    "ToolCallRequest",
+    "ToolCallResponse",
+    "ToolProxyClient",
+    "ToolProxyServer",
+    "create_tool_proxy_pair",
+]

voxagent/code/agent.py

@@ -0,0 +1,275 @@
+"""Code execution mode for Agent.
+
+When execution_mode="code", the agent uses a single execute_code tool
+instead of exposing all tools directly. The LLM writes Python code
+that calls tools via the virtual filesystem.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from voxagent.code.sandbox import SubprocessSandbox, SandboxResult
+from voxagent.code.virtual_fs import VirtualFilesystem, ToolRegistry
+from voxagent.tools.definition import ToolDefinition
+
+if TYPE_CHECKING:
+    from voxagent.agent.core import Agent
+
+
+# System prompt addition for code mode
+CODE_MODE_SYSTEM_PROMPT = '''
+## Code Execution Mode
+
+You have access to a single tool: `execute_code`. Use it to write Python code that:
+1. Explores available tools with `ls("tools/")` and `read("tools/<category>/<tool>.py")`
+2. Calls tools using `call_tool(category, tool_name, **kwargs)`
+3. Uses `print()` to output results
+
+### Available Functions in Sandbox
+- `ls(path)` - List directory contents (e.g., `ls("tools/")`, `ls("tools/devices/")`)
+- `read(path)` - Read file contents (e.g., `read("tools/devices/registry.py")`)
+- `call_tool(category, tool_name, **kwargs)` - Call a tool with arguments
+- `print(*args)` - Output results (captured and returned to you)
+
+### Workflow
+1. **Explore**: `print(ls("tools/"))` to see categories
+2. **Learn**: `print(read("tools/<category>/<tool>.py"))` to see tool signatures
+3. **Execute**: Use `call_tool()` to invoke tools
+4. **Report**: Use `print()` to show results
+
+### Example
+```python
+# Explore available tools
+print("Categories:", ls("tools/"))
+
+# Read a tool definition
+print(read("tools/devices/registry.py"))
+
+# Call the tool
+result = call_tool("devices", "registry.py", device_type="light")
+print("Devices:", result)
+```
+
+### Rules
+1. Always use `print()` to show results
+2. Explore before assuming - use `ls()` and `read()` first
+3. Handle errors with try/except when appropriate
+'''
+
+
+class CodeModeConfig:
+    """Configuration for code execution mode.
+    
+    Attributes:
+        enabled: Whether code mode is active
+        timeout_seconds: Max execution time per code block
+        memory_limit_mb: Max memory for sandbox
+        max_output_chars: Truncate output beyond this
+    """
+    
+    def __init__(
+        self,
+        enabled: bool = True,
+        timeout_seconds: int = 10,
+        memory_limit_mb: int = 128,
+        max_output_chars: int = 10000,
+    ):
+        self.enabled = enabled
+        self.timeout_seconds = timeout_seconds
+        self.memory_limit_mb = memory_limit_mb
+        self.max_output_chars = max_output_chars
+
+
+class CodeModeExecutor:
+    """Executes code for an agent in code mode.
+    
+    This class:
+    1. Manages the sandbox and virtual filesystem
+    2. Provides the execute_code tool implementation
+    3. Routes tool calls from sandbox to real implementations
+    """
+    
+    def __init__(
+        self,
+        config: CodeModeConfig,
+        tool_registry: ToolRegistry,
+    ):
+        self.config = config
+        self.tool_registry = tool_registry
+        self.sandbox = SubprocessSandbox(
+            timeout_seconds=config.timeout_seconds,
+            memory_limit_mb=config.memory_limit_mb,
+        )
+        self.virtual_fs = VirtualFilesystem(tool_registry)
+        
+        # Tool proxy for routing calls
+        self._tool_implementations: dict[str, Any] = {}
+    
+    def register_tool_implementation(
+        self,
+        category: str,
+        tool_name: str,
+        implementation: Any,
+    ) -> None:
+        """Register a real tool implementation for the proxy."""
+        key = f"{category}.{tool_name}"
+        self._tool_implementations[key] = implementation
+
+    async def execute_code(self, code: str) -> str:
+        """Execute Python code in the sandbox.
+
+        This is the tool exposed to the LLM.
+
+        Args:
+            code: Python source code to execute
+
+        Returns:
+            Captured output or error message
+        """
+        # Build globals with virtual filesystem functions only
+        # Note: call_tool is not passed to sandbox due to pickling constraints
+        # The LLM should use ls() and read() to explore, then describe what to call
+        globals_dict = self.virtual_fs.get_sandbox_globals()
+
+        # Execute in sandbox
+        result = await self.sandbox.execute(code, globals_dict)
+
+        # Format output
+        if result.success:
+            output = result.output or "(no output)"
+            if len(output) > self.config.max_output_chars:
+                output = output[:self.config.max_output_chars] + "\n... (truncated)"
+            return output
+        else:
+            return f"Error: {result.error}"
+
+    def call_tool(self, category: str, tool_name: str, **kwargs: Any) -> Any:
+        """Call a registered tool implementation.
+
+        This method is called outside the sandbox after the LLM
+        has explored tools and decided which one to call.
+
+        Args:
+            category: Tool category (e.g., "devices")
+            tool_name: Tool name (e.g., "registry.py")
+            **kwargs: Arguments to pass to the tool
+
+        Returns:
+            Tool result or error message
+        """
+        key = f"{category}.{tool_name}"
+        if key not in self._tool_implementations:
+            return f"Error: Tool '{key}' not found"
+        try:
+            impl = self._tool_implementations[key]
+            return impl(**kwargs)
+        except Exception as e:
+            return f"Error calling {key}: {e}"
+
+    def get_execute_code_tool(self) -> ToolDefinition:
+        """Get the execute_code tool definition for the agent."""
+        async def execute_code_wrapper(code: str) -> str:
+            """Execute Python code to explore and use tools.
+
+            Write Python code that:
+            1. Uses ls() to explore available tool categories
+            2. Uses read() to see tool signatures and documentation
+            3. Imports and calls tools to perform actions
+            4. Uses print() to output results
+
+            Args:
+                code: Python source code to execute
+
+            Returns:
+                Captured print() output or error message
+            """
+            return await self.execute_code(code)
+
+        return ToolDefinition(
+            name="execute_code",
+            description="Execute Python code to explore and use tools. Use ls() to see tools, read() to see signatures, and print() to output results.",
+            execute=execute_code_wrapper,
+            parameters={
+                "type": "object",
+                "properties": {
+                    "code": {
+                        "type": "string",
+                        "description": "Python source code to execute"
+                    }
+                },
+                "required": ["code"]
+            },
+            is_async=True,
+        )
+
+
+def get_code_mode_system_prompt_addition() -> str:
+    """Get the system prompt addition for code mode."""
+    return CODE_MODE_SYSTEM_PROMPT
+
+
+def setup_code_mode_for_agent(
+    agent: "Agent[Any, Any]",
+    config: CodeModeConfig | None = None,
+) -> CodeModeExecutor:
+    """Set up code mode for an existing agent.
+
+    This:
+    1. Creates a CodeModeExecutor
+    2. Registers the execute_code tool
+    3. Converts existing tools to virtual filesystem entries
+
+    Args:
+        agent: The agent to configure
+        config: Optional code mode configuration
+
+    Returns:
+        The CodeModeExecutor instance
+    """
+    config = config or CodeModeConfig()
+
+    # Create tool registry from agent's existing tools
+    vf_tool_registry = ToolRegistry()
+
+    # Convert agent's tools to virtual filesystem entries
+    for tool_def in agent._tool_registry.list():
+        # Create category based on tool name or use "default"
+        category = "default"
+
+        # Build tool definition content as Python stub
+        params_str = ", ".join(
+            f"{k}: {v.get('type', 'Any')}"
+            for k, v in tool_def.parameters.get("properties", {}).items()
+        )
+        tool_content = f'''def {tool_def.name}({params_str}) -> Any:
+    """{tool_def.description}"""
+    ...
+'''
+
+        # Get or create category
+        if category not in vf_tool_registry.list_categories():
+            vf_tool_registry.register_category(
+                category,
+                description="Default tool category",
+                tools={},
+            )
+
+        # Add tool to category
+        cat = vf_tool_registry.get_category(category)
+        if cat:
+            cat.tools[f"{tool_def.name}.py"] = tool_content
+
+    # Create executor
+    executor = CodeModeExecutor(config, vf_tool_registry)
+
+    # Register tool implementations
+    for tool_def in agent._tool_registry.list():
+        executor.register_tool_implementation(
+            "default",
+            f"{tool_def.name}.py",
+            tool_def.execute,
+        )
+
+    return executor
+

voxagent/code/sandbox.py

@@ -0,0 +1,335 @@
+"""Sandboxed Python code execution with security restrictions.
+
+This module provides secure code execution using RestrictedPython
+and subprocess isolation with resource limits.
+"""
+
+from __future__ import annotations
+
+import multiprocessing
+import time
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from voxagent.code.tool_proxy import ToolProxyClient
+
+
+@dataclass
+class SandboxResult:
+    """Result of sandboxed code execution.
+
+    Attributes:
+        output: Captured stdout from print() calls
+        error: Error message if execution failed
+        execution_time_ms: Time taken to execute in milliseconds
+        success: Whether execution completed without errors (derived from error being None)
+    """
+
+    output: str | None = None
+    error: str | None = None
+    execution_time_ms: float | None = None
+
+    @property
+    def success(self) -> bool:
+        """Return True if execution completed without errors."""
+        return self.error is None
+
+
+class CodeSandbox(ABC):
+    """Abstract base class for code execution sandboxes."""
+
+    @abstractmethod
+    async def execute(
+        self, code: str, globals_dict: dict[str, Any] | None = None
+    ) -> SandboxResult:
+        """Execute Python code in a sandboxed environment.
+
+        Args:
+            code: Python source code to execute
+            globals_dict: Optional globals to inject (e.g., ls, read functions)
+
+        Returns:
+            SandboxResult with output or error
+        """
+        ...
+
+
+def _inplacevar_(op: str, x: Any, y: Any) -> Any:
+    """Handle in-place operators (+=, -=, etc.) in RestrictedPython."""
+    if op == "+=":
+        return x + y
+    elif op == "-=":
+        return x - y
+    elif op == "*=":
+        return x * y
+    elif op == "/=":
+        return x / y
+    elif op == "//=":
+        return x // y
+    elif op == "%=":
+        return x % y
+    elif op == "**=":
+        return x**y
+    elif op == "&=":
+        return x & y
+    elif op == "|=":
+        return x | y
+    elif op == "^=":
+        return x ^ y
+    elif op == ">>=":
+        return x >> y
+    elif op == "<<=":
+        return x << y
+    else:
+        raise ValueError(f"Unknown operator: {op}")
+
+
+def _execute_in_subprocess(
+    code: str,
+    globals_dict: dict[str, Any],
+    result_queue: multiprocessing.Queue,  # type: ignore[type-arg]
+    memory_limit_mb: int,
+) -> None:
+    """Subprocess entry point for sandboxed execution."""
+    # Import here to avoid loading in main process
+    import ast
+    import warnings
+
+    # Suppress RestrictedPython SyntaxWarnings about print/printed variable
+    # These warnings are harmless but noisy (about print transformation internals)
+    warnings.filterwarnings(
+        "ignore",
+        message=".*Prints, but never reads 'printed' variable.*",
+        category=SyntaxWarning,
+    )
+
+    from RestrictedPython import compile_restricted, safe_builtins
+    from RestrictedPython.Eval import default_guarded_getitem, default_guarded_getiter
+    from RestrictedPython.Guards import (
+        guarded_iter_unpack_sequence,
+        safer_getattr,
+    )
+    from RestrictedPython.PrintCollector import PrintCollector
+    from RestrictedPython.transformer import (
+        IOPERATOR_TO_STR,
+        RestrictingNodeTransformer,
+        copy_locations,
+    )
+
+    # Custom policy that allows augmented assignment on attributes
+    class PermissiveNodeTransformer(RestrictingNodeTransformer):
+        """A more permissive node transformer that allows augmented assignment."""
+
+        def visit_AugAssign(self, node: ast.AugAssign) -> ast.AST:
+            """Allow augmented assignment on attributes and subscripts.
+
+            Transforms 'a.x += 1' to 'a.x = _inplacevar_("+=", a.x, 1)'
+            and 'a[i] += 1' to 'a[i] = _inplacevar_("+=", a[i], 1)'
+            """
+            node = self.node_contents_visit(node)
+
+            if isinstance(node.target, ast.Attribute):
+                # Transform a.x += 1 to a.x = _inplacevar_("+=", a.x, 1)
+                new_node = ast.Assign(
+                    targets=[
+                        ast.Attribute(
+                            value=node.target.value,
+                            attr=node.target.attr,
+                            ctx=ast.Store(),
+                        )
+                    ],
+                    value=ast.Call(
+                        func=ast.Name("_inplacevar_", ast.Load()),
+                        args=[
+                            ast.Constant(IOPERATOR_TO_STR[type(node.op)]),
+                            ast.Attribute(
+                                value=node.target.value,
+                                attr=node.target.attr,
+                                ctx=ast.Load(),
+                            ),
+                            node.value,
+                        ],
+                        keywords=[],
+                    ),
+                )
+                copy_locations(new_node, node)
+                return new_node
+
+            elif isinstance(node.target, ast.Subscript):
+                # Transform a[i] += 1 to a[i] = _inplacevar_("+=", a[i], 1)
+                new_node = ast.Assign(
+                    targets=[
+                        ast.Subscript(
+                            value=node.target.value,
+                            slice=node.target.slice,
+                            ctx=ast.Store(),
+                        )
+                    ],
+                    value=ast.Call(
+                        func=ast.Name("_inplacevar_", ast.Load()),
+                        args=[
+                            ast.Constant(IOPERATOR_TO_STR[type(node.op)]),
+                            ast.Subscript(
+                                value=node.target.value,
+                                slice=node.target.slice,
+                                ctx=ast.Load(),
+                            ),
+                            node.value,
+                        ],
+                        keywords=[],
+                    ),
+                )
+                copy_locations(new_node, node)
+                return new_node
+
+            elif isinstance(node.target, ast.Name):
+                new_node = ast.Assign(
+                    targets=[node.target],
+                    value=ast.Call(
+                        func=ast.Name("_inplacevar_", ast.Load()),
+                        args=[
+                            ast.Constant(IOPERATOR_TO_STR[type(node.op)]),
+                            ast.Name(node.target.id, ast.Load()),
+                            node.value,
+                        ],
+                        keywords=[],
+                    ),
+                )
+                copy_locations(new_node, node)
+                return new_node
+            else:
+                raise NotImplementedError(f"Unknown target type: {type(node.target)}")
+
+    # Set memory limit (Unix only)
+    try:
+        import resource
+
+        limit_bytes = memory_limit_mb * 1024 * 1024
+        # Try to set RLIMIT_AS (address space) - works on Linux
+        try:
+            soft, hard = resource.getrlimit(resource.RLIMIT_AS)
+            # Only set if we can (soft limit can be lowered)
+            if limit_bytes <= hard:
+                resource.setrlimit(resource.RLIMIT_AS, (limit_bytes, hard))
+        except (ValueError, OSError):
+            pass
+        # Also try RLIMIT_DATA
+        try:
+            soft, hard = resource.getrlimit(resource.RLIMIT_DATA)
+            if limit_bytes <= hard:
+                resource.setrlimit(resource.RLIMIT_DATA, (limit_bytes, hard))
+        except (ValueError, OSError):
+            pass
+    except ImportError:
+        pass  # Windows
+
+    # Build safe builtins
+    safe_builtins_copy = dict(safe_builtins)
+    # Remove dangerous builtins
+    for name in ("open", "eval", "exec", "compile", "__import__"):
+        safe_builtins_copy.pop(name, None)
+
+    try:
+        byte_code = compile_restricted(
+            code, "<sandbox>", "exec", policy=PermissiveNodeTransformer
+        )
+        if byte_code is None:
+            result_queue.put(SandboxResult(output="", error="SyntaxError: compilation failed"))
+            return
+
+        exec_globals: dict[str, Any] = {
+            "__builtins__": safe_builtins_copy,
+            "__name__": "__main__",
+            "__doc__": None,
+            # Required for class definitions in RestrictedPython
+            "__metaclass__": type,
+            # _print_ is a factory - RestrictedPython will call it to create a collector
+            "_print_": PrintCollector,
+            # Also provide _getattr_ for attribute access
+            "_getattr_": safer_getattr,
+            "_getitem_": default_guarded_getitem,
+            "_getiter_": default_guarded_getiter,
+            "_iter_unpack_sequence_": guarded_iter_unpack_sequence,
+            "_inplacevar_": _inplacevar_,
+            # Provide write guard for attribute writes
+            "_write_": lambda x: x,
+            **globals_dict,
+        }
+        exec(byte_code, exec_globals)
+        # Get the _print object that was created during execution and call it
+        _print_obj = exec_globals.get("_print")
+        output = _print_obj() if _print_obj else ""
+        result_queue.put(
+            SandboxResult(
+                output=output if output else "",
+            )
+        )
+    except SyntaxError as e:
+        result_queue.put(SandboxResult(output="", error=f"SyntaxError: {e}"))
+    except Exception as e:
+        result_queue.put(SandboxResult(output="", error=f"{type(e).__name__}: {e}"))
+
+
+class SubprocessSandbox(CodeSandbox):
+    """Execute Python code in an isolated subprocess with RestrictedPython.
+
+    Security features:
+    - RestrictedPython AST filtering (blocks imports, file access, etc.)
+    - Process isolation via multiprocessing
+    - Timeout enforcement
+    - Memory limits (Unix only)
+
+    Args:
+        timeout_seconds: Maximum execution time (default: 10)
+        memory_limit_mb: Maximum memory in MB (default: 128, Unix only)
+        tool_proxy_client: Optional tool proxy client for routing tool calls
+    """
+
+    def __init__(
+        self,
+        timeout_seconds: int = 10,
+        memory_limit_mb: int = 128,
+        tool_proxy_client: "ToolProxyClient | None" = None,
+    ) -> None:
+        self.timeout_seconds = timeout_seconds
+        self.memory_limit_mb = memory_limit_mb
+        self.tool_proxy_client = tool_proxy_client
+
+    async def execute(
+        self, code: str, globals_dict: dict[str, Any] | None = None
+    ) -> SandboxResult:
+        """Execute code in subprocess with RestrictedPython."""
+        start_time = time.monotonic()
+
+        result_queue: multiprocessing.Queue[SandboxResult] = multiprocessing.Queue()
+        process = multiprocessing.Process(
+            target=_execute_in_subprocess,
+            args=(code, globals_dict or {}, result_queue, self.memory_limit_mb),
+        )
+        process.start()
+        process.join(timeout=self.timeout_seconds)
+
+        execution_time_ms = (time.monotonic() - start_time) * 1000
+
+        if process.is_alive():
+            process.kill()
+            process.join()
+            return SandboxResult(
+                output="",
+                error="Execution timed out",
+                execution_time_ms=execution_time_ms,
+            )
+
+        try:
+            result = result_queue.get_nowait()
+            result.execution_time_ms = execution_time_ms
+            return result
+        except Exception:
+            return SandboxResult(
+                output="",
+                error="No result from subprocess",
+                execution_time_ms=execution_time_ms,
+            )
+

voxagent/code/tool_proxy.py

@@ -0,0 +1,259 @@
+"""Tool proxy for routing sandbox calls to real implementations.
+
+The sandbox cannot directly call async MCP tools. This module provides
+a queue-based proxy that:
+1. Captures tool calls in the sandbox
+2. Serializes them to a multiprocessing queue
+3. The main process executes real tools and returns results
+"""
+
+from __future__ import annotations
+
+import asyncio
+import multiprocessing
+import time
+from dataclasses import dataclass, field
+from multiprocessing import Queue
+from typing import Any, Callable, Awaitable, TYPE_CHECKING
+
+
+@dataclass
+class ToolCallRequest:
+    """A tool call request from the sandbox.
+
+    Attributes:
+        call_id: Unique identifier for this call
+        category: Tool category (e.g., "devices")
+        tool_name: Tool function name (e.g., "list_devices")
+        args: Positional arguments
+        kwargs: Keyword arguments
+    """
+    call_id: str
+    category: str
+    tool_name: str
+    args: tuple[Any, ...] = field(default_factory=tuple)
+    kwargs: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class ToolCallResponse:
+    """Response from a tool call.
+
+    Attributes:
+        call_id: Matches the request call_id
+        success: Whether the call succeeded
+        result: The return value (if success)
+        error: Error message (if failed)
+    """
+    call_id: str
+    success: bool
+    result: Any = None
+    error: str | None = None
+
+
+class ToolProxyClient:
+    """Client-side proxy that runs in the sandbox subprocess.
+
+    This creates callable proxies for each tool that:
+    1. Serialize the call to the request queue
+    2. Wait for the response on the response queue
+    3. Return the result or raise an exception
+    """
+
+    def __init__(
+        self,
+        request_queue: Queue,  # type: ignore[type-arg]
+        response_queue: Queue,  # type: ignore[type-arg]
+        timeout_seconds: float = 30.0,
+    ):
+        self.request_queue = request_queue
+        self.response_queue = response_queue
+        self.timeout_seconds = timeout_seconds
+        self._call_counter = 0
+
+    def create_tool_proxy(self, category: str, tool_name: str) -> Callable[..., Any]:
+        """Create a callable proxy for a tool.
+
+        Args:
+            category: Tool category
+            tool_name: Tool function name
+
+        Returns:
+            A callable that proxies to the real tool
+        """
+        def proxy(*args: Any, **kwargs: Any) -> Any:
+            # Generate unique call ID
+            self._call_counter += 1
+            call_id = f"call_{self._call_counter}"
+
+            # Send request
+            request = ToolCallRequest(
+                call_id=call_id,
+                category=category,
+                tool_name=tool_name,
+                args=args,
+                kwargs=kwargs,
+            )
+            self.request_queue.put(request)
+
+            # Wait for response (blocking in subprocess)
+            start = time.monotonic()
+            while True:
+                try:
+                    response: ToolCallResponse = self.response_queue.get(timeout=0.1)
+                    if response.call_id == call_id:
+                        if response.success:
+                            return response.result
+                        else:
+                            raise RuntimeError(f"Tool error: {response.error}")
+                except Exception:
+                    pass
+
+                if time.monotonic() - start > self.timeout_seconds:
+                    raise TimeoutError(f"Tool call timed out after {self.timeout_seconds}s")
+
+        return proxy
+
+    def build_tools_namespace(self, categories: dict[str, list[str]]) -> Any:
+        """Build a 'tools' namespace with proxy modules.
+
+        Args:
+            categories: Dict of category name -> list of tool names
+
+        Returns:
+            A namespace object with category submodules
+        """
+        class ToolModule:
+            pass
+
+        class ToolsNamespace:
+            pass
+
+        tools = ToolsNamespace()
+
+        for category, tool_names in categories.items():
+            module = ToolModule()
+            for tool_name in tool_names:
+                proxy = self.create_tool_proxy(category, tool_name)
+                setattr(module, tool_name, proxy)
+
+            # Replace hyphens with underscores for valid Python identifiers
+            attr_name = category.replace("-", "_")
+            setattr(tools, attr_name, module)
+
+        return tools
+
+
+class ToolProxyServer:
+    """Server-side proxy that runs in the main process.
+
+    This:
+    1. Listens for tool call requests from the sandbox
+    2. Executes the real tool implementation
+    3. Sends the response back
+    """
+
+    def __init__(
+        self,
+        request_queue: Queue,  # type: ignore[type-arg]
+        response_queue: Queue,  # type: ignore[type-arg]
+    ):
+        self.request_queue = request_queue
+        self.response_queue = response_queue
+        self._implementations: dict[str, Callable[..., Any]] = {}
+        self._running = False
+
+    def register_implementation(
+        self,
+        category: str,
+        tool_name: str,
+        implementation: Callable[..., Any] | Callable[..., Awaitable[Any]],
+    ) -> None:
+        """Register a tool implementation.
+
+        Args:
+            category: Tool category
+            tool_name: Tool function name
+            implementation: The actual callable (sync or async)
+        """
+        key = f"{category}.{tool_name}"
+        self._implementations[key] = implementation
+
+    async def process_one_request(self, timeout: float = 0.1) -> bool:
+        """Process a single request if available.
+
+        Args:
+            timeout: How long to wait for a request
+
+        Returns:
+            True if a request was processed, False if queue was empty
+        """
+        try:
+            request: ToolCallRequest = self.request_queue.get_nowait()
+        except Exception:
+            return False
+
+        key = f"{request.category}.{request.tool_name}"
+        impl = self._implementations.get(key)
+
+        if impl is None:
+            response = ToolCallResponse(
+                call_id=request.call_id,
+                success=False,
+                error=f"Tool not found: {key}",
+            )
+        else:
+            try:
+                # Call the implementation (handle async)
+                if asyncio.iscoroutinefunction(impl):
+                    result = await impl(*request.args, **request.kwargs)
+                else:
+                    result = impl(*request.args, **request.kwargs)
+
+                response = ToolCallResponse(
+                    call_id=request.call_id,
+                    success=True,
+                    result=result,
+                )
+            except Exception as e:
+                response = ToolCallResponse(
+                    call_id=request.call_id,
+                    success=False,
+                    error=f"{type(e).__name__}: {e}",
+                )
+
+        self.response_queue.put(response)
+        return True
+
+    async def run_until_complete(self, timeout: float = 30.0) -> None:
+        """Process requests until timeout or no more requests.
+
+        Args:
+            timeout: Maximum time to run
+        """
+        start = time.monotonic()
+        self._running = True
+
+        while self._running and (time.monotonic() - start) < timeout:
+            processed = await self.process_one_request()
+            if not processed:
+                await asyncio.sleep(0.01)  # Small sleep if no request
+
+    def stop(self) -> None:
+        """Stop the server loop."""
+        self._running = False
+
+
+def create_tool_proxy_pair() -> tuple[ToolProxyClient, ToolProxyServer]:
+    """Create a matched client/server proxy pair.
+
+    Returns:
+        Tuple of (client for sandbox, server for main process)
+    """
+    request_queue: Queue = multiprocessing.Queue()  # type: ignore[type-arg]
+    response_queue: Queue = multiprocessing.Queue()  # type: ignore[type-arg]
+
+    client = ToolProxyClient(request_queue, response_queue)
+    server = ToolProxyServer(request_queue, response_queue)
+
+    return client, server

voxagent/code/virtual_fs.py

@@ -0,0 +1,223 @@
+"""Virtual filesystem for tool discovery.
+
+Provides ls() and read() functions that allow the LLM to browse
+available tools without loading all definitions upfront.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class ToolCategory:
+    """A category of related tools.
+    
+    Attributes:
+        name: Category name (e.g., "devices", "home-assistant")
+        description: Category description
+        tools: Dict of tool filename -> tool content/definition
+    """
+    name: str
+    description: str = ""
+    tools: dict[str, str] = field(default_factory=dict)
+
+
+class ToolRegistry:
+    """Registry of tool categories and definitions.
+    
+    Manages tool registration and provides lookup for the virtual filesystem.
+    """
+    
+    def __init__(self) -> None:
+        self._categories: dict[str, ToolCategory] = {}
+    
+    def register_category(
+        self,
+        name: str,
+        description: str = "",
+        tools: dict[str, str] | None = None,
+    ) -> ToolCategory:
+        """Register a new tool category.
+        
+        Args:
+            name: Category name
+            description: Category description
+            tools: Dict of tool filename -> tool content
+            
+        Returns:
+            The created ToolCategory
+        """
+        category = ToolCategory(
+            name=name,
+            description=description,
+            tools=tools or {},
+        )
+        self._categories[name] = category
+        return category
+    
+    def get_category(self, name: str) -> ToolCategory | None:
+        """Get a category by name."""
+        return self._categories.get(name)
+    
+    def get_tool_definition(self, category: str, tool_name: str) -> str | None:
+        """Get a specific tool's definition content.
+        
+        Args:
+            category: Category name
+            tool_name: Tool filename (e.g., "registry.py")
+            
+        Returns:
+            Tool content/definition or None if not found
+        """
+        cat = self._categories.get(category)
+        if cat:
+            return cat.tools.get(tool_name)
+        return None
+    
+    def list_categories(self) -> list[str]:
+        """List all category names."""
+        return list(self._categories.keys())
+    
+    def list_tools(self, category: str) -> list[str]:
+        """List tool filenames in a category.
+        
+        Args:
+            category: Category name
+            
+        Returns:
+            List of tool filenames (e.g., ["registry.py", "control.py"])
+        """
+        cat = self._categories.get(category)
+        if cat:
+            return list(cat.tools.keys())
+        return []
+
+
+class VirtualFilesystem:
+    """Virtual filesystem for tool discovery.
+    
+    Provides ls() and read() functions that can be injected into the sandbox.
+    
+    Directory structure:
+        tools/
+        ├── __index__.md
+        ├── devices/
+        │   ├── __index__.md
+        │   ├── registry.py
+        │   └── control.py
+        └── sensors/
+            ├── __index__.md
+            └── temperature.py
+    """
+    
+    def __init__(self, registry: ToolRegistry) -> None:
+        self._registry = registry
+    
+    def ls(self, path: str) -> list[str]:
+        """List directory contents.
+        
+        Args:
+            path: Path like "tools/" or "tools/devices/"
+            
+        Returns:
+            List of entries (directories end with /, files don't)
+        """
+        path = path.rstrip("/")
+        
+        if path == "tools" or path == "":
+            # Root: list categories
+            entries = ["__index__.md"]
+            for cat in self._registry.list_categories():
+                entries.append(f"{cat}/")
+            return sorted(entries)
+        
+        if path.startswith("tools/"):
+            category = path[6:]  # Remove "tools/"
+            if category in self._registry.list_categories():
+                # Category: list tools
+                entries = ["__index__.md"]
+                for tool in self._registry.list_tools(category):
+                    entries.append(tool)
+                return sorted(entries)
+        
+        return []
+    
+    def read(self, path: str) -> str:
+        """Read file contents.
+        
+        Args:
+            path: Path like "tools/__index__.md" or "tools/devices/registry.py"
+            
+        Returns:
+            File contents or error message
+        """
+        path = path.lstrip("/")
+        
+        # Root index
+        if path == "tools/__index__.md":
+            return self._generate_root_index()
+        
+        # Category index
+        if path.startswith("tools/") and path.endswith("/__index__.md"):
+            category = path[6:-13]  # Remove "tools/" and "/__index__.md"
+            cat = self._registry.get_category(category)
+            if cat:
+                return self._generate_category_index(cat)
+            return f"Error: Category '{category}' not found"
+        
+        # Tool file
+        if path.startswith("tools/") and path.endswith(".py"):
+            parts = path[6:].split("/")  # Remove "tools/"
+            if len(parts) == 2:
+                category, tool_name = parts
+                content = self._registry.get_tool_definition(category, tool_name)
+                if content is not None:
+                    return content
+            return f"Error: Tool not found at '{path}'"
+        
+        return f"Error: File not found at '{path}'"
+    
+    def _generate_root_index(self) -> str:
+        """Generate tools/__index__.md content."""
+        lines = [
+            "# Available Tool Categories",
+            "",
+            "Browse these directories to find tools:",
+            "",
+            "| Category | Description | Tools |",
+            "|----------|-------------|-------|",
+        ]
+        for cat_name in sorted(self._registry.list_categories()):
+            cat = self._registry.get_category(cat_name)
+            if cat:
+                tool_count = len(cat.tools)
+                lines.append(
+                    f"| `{cat_name}/` | {cat.description} | {tool_count} tools |"
+                )
+        lines.extend([
+            "",
+            'Use `ls("tools/<category>/")` to see tools in a category.',
+            'Use `read("tools/<category>/<tool>.py")` to see tool details.',
+        ])
+        return "\n".join(lines)
+    
+    def _generate_category_index(self, category: ToolCategory) -> str:
+        """Generate __index__.md content for a category."""
+        lines = [f"# {category.name}", "", category.description, "", "## Tools", ""]
+        for tool_name in sorted(category.tools.keys()):
+            lines.append(f"- `{tool_name}`")
+        return "\n".join(lines)
+    
+    def get_sandbox_globals(self) -> dict[str, Any]:
+        """Get globals dict to inject into sandbox.
+        
+        Returns:
+            Dict with ls and read functions bound to this filesystem
+        """
+        return {
+            "ls": self.ls,
+            "read": self.read,
+        }
+

{voxagent-0.1.1.dist-info → voxagent-0.2.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: voxagent
-Version: 0.1.1
+Version: 0.2.1
 Summary: A lightweight, model-agnostic LLM provider abstraction with streaming and tool support
 Project-URL: Homepage, https://github.com/lensator/voxagent
 Project-URL: Documentation, https://github.com/lensator/voxagent#readme
@@ -34,6 +34,8 @@ Requires-Dist: openai>=1.0; extra == 'all'
 Requires-Dist: tiktoken>=0.5; extra == 'all'
 Provides-Extra: anthropic
 Requires-Dist: anthropic>=0.25; extra == 'anthropic'
+Provides-Extra: code
+Requires-Dist: restrictedpython>=7.0; extra == 'code'
 Provides-Extra: dev
 Requires-Dist: mypy>=1.0; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'

{voxagent-0.1.1.dist-info → voxagent-0.2.1.dist-info}/RECORD

@@ -1,10 +1,14 @@
 voxagent/__init__.py,sha256=YMYC95iwWXK26hicGYmd2erNOInrYtohwUVOuNmpTCs,3927
-voxagent/_version.py,sha256=dci_7AJwV3XNR3Hhs5EbgyENsGHyAr6FK5tHu7zs4M4,87
+voxagent/_version.py,sha256=hneVJodkPueiXrtmysAsTToF1j7vXo9HPxsiIEn-vlc,87
 voxagent/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
 voxagent/agent/__init__.py,sha256=eASoU7Zhvw8BtJ-iUqVN06S4fMLkHwDgUZbHeH2AUOM,755
 voxagent/agent/abort.py,sha256=2Wnnxq8Dcn7wQkKPHrba2o0OeOdzF4NNsl-usgE4CJw,5191
 voxagent/agent/core.py,sha256=zXDUubx6oWQCj1V997s2zJ0Xj0XCaWIPZNinTNMz2zY,30581
-voxagent/code/__init__.py,sha256=6-i-FjYxwNay7XvWt9kwwg2nk3wPNzRp54AtEBdQ13U,237
+voxagent/code/__init__.py,sha256=MzbrYReislAB-lCZEZn_lBEPGjYZyPK-c9RFCq1nSm0,1379
+voxagent/code/agent.py,sha256=ZHN4OYVVD1yI75QDjvqYOrexgh1-srH8qiBfvJhV-Pk,8884
+voxagent/code/sandbox.py,sha256=LP2cwXchDk6mtiYGRb_RmkGNoyPv5OEKQC2h4M89dC0,11669
+voxagent/code/tool_proxy.py,sha256=wZvRqXoz2SfYTHLpe8tIkpJL6b8fmlU96DSGeYw-HfM,8091
+voxagent/code/virtual_fs.py,sha256=pKZXddcshtZqoLLZ6sL2tJ7f0JbPQF_TpdDmPbpJ_qg,7088
 voxagent/mcp/__init__.py,sha256=_3Rsn7nIuivdWLv0MzpyjRGsPuCgr4LrXCge6FCb3nE,470
 voxagent/mcp/manager.py,sha256=sECOhw-f6HB6NV-mBqcgJzsEt28acdQI_O2cT-41Rxw,6606
 voxagent/mcp/tool.py,sha256=YQQqXNcanDDr5tkL1Z5OjNsDI5dWMEzm_SlJ4pOcUpk,5147
@@ -48,6 +52,6 @@ voxagent/tools/registry.py,sha256=MNJzgcmKT0AoMWIky9TJY4WVhzn5dkmjIHsUiZ3mv3U,25
 voxagent/types/__init__.py,sha256=3VunuprKKEpOR9Cg-UITHJXds_xQ-tfqQb4S7wD3nP4,933
 voxagent/types/messages.py,sha256=c6hNi9w6C8gbFoFm5fFge35vwJGywaoR_OiPQprfyVs,3494
 voxagent/types/run.py,sha256=4vYq0pCqH7_7SWbMb1SplWj4TLiE3DELDYMi0HefFmo,5071
-voxagent-0.1.1.dist-info/METADATA,sha256=ybDiX1x6IsHgK-mxSOHQhKviowAM0aNyksgcBkQ2BzU,5610
-voxagent-0.1.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-voxagent-0.1.1.dist-info/RECORD,,
+voxagent-0.2.1.dist-info/METADATA,sha256=aaQR2qswaeyZIGw_5DE_OoUSn0GO2-MFGxt33y9-Nmc,5685
+voxagent-0.2.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+voxagent-0.2.1.dist-info/RECORD,,