voidx 1.0.0__py3-none-any.whl

voidx/tools/agent.py

@@ -0,0 +1,81 @@
+"""Agent tool — start an isolated child agent with filtered context."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+from voidx.agent.agents import child_agent_descriptions_for_llm, get_agent
+from voidx.tools.base import BaseTool, ToolContext, ToolResult, model_to_json_schema
+
+
+class AgentInput(BaseModel):
+    agent: str = Field(
+        description=(
+            "Child agent to run: explore, plan, implement, or review. "
+            "Use implement only when the user explicitly asked to modify code."
+        )
+    )
+    description: str = Field(
+        description=(
+            "Complete, self-contained task description for the child agent. "
+            "Include all context it needs because it receives only a filtered "
+            "slice of the parent conversation."
+        )
+    )
+    model: str | None = Field(
+        default=None,
+        description="Optional model override for this child agent.",
+    )
+
+
+class AgentTool(BaseTool):
+    id = "agent"
+    description = (
+        "Start an isolated child agent for a delegated task. Use this for true "
+        "sub-agent work only: broad codebase exploration, implementation, review, "
+        "or planning that should run in its own context.\n\n"
+        + child_agent_descriptions_for_llm()
+        + "\n\nIMPORTANT: Provide a complete, self-contained task description. "
+        "The child agent receives only a filtered slice of the parent context plus "
+        "your task description."
+    )
+
+    def __init__(self, runner=None):
+        super().__init__()
+        self._run_child_agent = runner
+
+    def parameters_schema(self) -> dict:
+        return model_to_json_schema(AgentInput)
+
+    async def execute(self, args: dict, ctx: ToolContext) -> ToolResult:
+        inp = AgentInput.model_validate(args)
+
+        agent_def = get_agent(inp.agent)
+        if not agent_def:
+            available = [
+                a.name
+                for a in [get_agent(n) for n in ["explore", "plan", "implement", "review"]]
+                if a
+            ]
+            return ToolResult(output=f"Unknown child agent: {inp.agent}. Available: {available}")
+
+        if agent_def.name == "orchestrator":
+            return ToolResult(output="Cannot run orchestrator as a child agent.")
+
+        if not self._run_child_agent:
+            return ToolResult(
+                output=f"Child agent execution not available. Task: {inp.description[:200]}"
+            )
+
+        try:
+            output = await self._run_child_agent(agent_def, inp.description, inp.model)
+            return ToolResult(
+                title=f"{agent_def.name}: {inp.description[:60]}",
+                output=output,
+                metadata={"agent": agent_def.name, "model": inp.model or agent_def.model or "default"},
+            )
+        except Exception as exc:
+            return ToolResult(
+                output=f"Child agent '{agent_def.name}' failed: {exc}",
+                metadata={"agent": agent_def.name, "error": str(exc)},
+            )

voidx/tools/base.py

@@ -0,0 +1,86 @@
+"""Tool base — abstract contract, result types, context. No circular imports."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Any
+from collections.abc import Callable
+
+from pydantic import BaseModel, Field
+
+
+def resolve_safe(workspace: str, file_path: str, extra_paths: list[str] | None = None) -> Path | None:
+    """Resolve file path and verify it stays inside workspace (+ optional extra paths).
+
+    Returns the resolved path if safe, or None if blocked.
+    """
+    ws = Path(workspace).resolve()
+    resolved = (ws / file_path).resolve()
+
+    allowed = [ws]
+    if extra_paths:
+        for ep in extra_paths:
+            allowed.append(Path(ep).expanduser().resolve())
+
+    for base in allowed:
+        try:
+            resolved.relative_to(base)
+            return resolved
+        except ValueError:
+            continue
+    return None
+
+
+class ToolResult(BaseModel):
+    """Result from tool execution. Typed so the agent can reason about it."""
+    title: str = ""
+    output: str
+    metadata: dict = {}
+    diff: str | None = None  # unified diff for edit/write tools
+
+
+class ToolContext(BaseModel):
+    """Context passed to every tool execution. Mutable file_mtimes for staleness guard."""
+    workspace: str
+    session_id: str = "default"
+    agent: str = "build"
+    file_mtimes: dict[str, float] = Field(default_factory=dict)
+    mcp_manager: Any | None = None
+    lsp_manager: Any | None = None
+    sandbox_extra_paths: list[str] = Field(default_factory=list)
+
+    model_config = {"arbitrary_types_allowed": True}
+
+
+class BaseTool(ABC):
+    """Every tool has: id, description, typed parameters, deterministic execute."""
+
+    @property
+    @abstractmethod
+    def id(self) -> str: ...
+
+    @property
+    @abstractmethod
+    def description(self) -> str: ...
+
+    @abstractmethod
+    def parameters_schema(self) -> dict[str, Any]:
+        """Return JSON Schema dict generated from the tool's Pydantic input model."""
+        ...
+
+    @abstractmethod
+    async def execute(self, args: dict, ctx: ToolContext) -> ToolResult:
+        """Execute the tool with typed inputs. Returns typed result."""
+        ...
+
+
+def model_to_json_schema(model: type[BaseModel]) -> dict[str, Any]:
+    """Convert a Pydantic model to JSON Schema dict."""
+    schema = model.model_json_schema()
+    return {
+        "type": "object",
+        "properties": schema.get("properties", {}),
+        "required": schema.get("required", []),
+        "additionalProperties": False,
+    }

voidx/tools/bash.py

@@ -0,0 +1,105 @@
+"""Bash tool — execute shell commands, capture output. Exact, measurable."""
+
+from __future__ import annotations
+
+import asyncio
+import re
+import subprocess
+
+from pydantic import BaseModel, Field
+
+from voidx.tools.base import BaseTool, model_to_json_schema, ToolContext, ToolResult
+
+# Patterns that are always blocked regardless of permission
+_BLOCKED = [
+    (r"\bsudo\b", "sudo is blocked — privilege escalation"),
+    (r"\bchmod\s+.*[0]*7\d{2}\b", "chmod 7xx is blocked — world-writable permissions"),
+    (r"\bchmod\s+[0]*\d*7\b", "chmod with 7 is blocked"),
+    (r"\bchown\b", "chown is blocked"),
+    (r"\bchgrp\b", "chgrp is blocked"),
+    (r"\bmkfs\b", "mkfs is blocked — filesystem formatting"),
+    (r"\bdd\s+if=.*of=/dev/", "dd to /dev is blocked — raw disk write"),
+    (r">\s*/dev/sd", "write to /dev/sd* is blocked"),
+    (r"\breboot\b", "reboot is blocked"),
+    (r"\bshutdown\b", "shutdown is blocked"),
+    (r"\bpoweroff\b", "poweroff is blocked"),
+    (r"\binit\s+[06]\b", "init runlevel change is blocked"),
+    (r":\(\)\s*\{", "fork bomb pattern is blocked"),
+    (r"\bgit\s+push\s+.*(-f|--force).*(main|master)\b", "force push to main/master is blocked"),
+    (r"\bcurl\b.*\|\s*(bash|sh|/bin/bash|/bin/sh)\b", "curl piped to shell is blocked"),
+    (r"\bwget\b.*\|\s*(bash|sh|/bin/bash|/bin/sh)\b", "wget piped to shell is blocked"),
+]
+
+
+def _normalize_command(command: str) -> str:
+    """Strip common shell escapes so blocked patterns can't be bypassed."""
+    import re as _re
+    s = command.strip()
+    s = _re.sub(r"\\\s*\n", " ", s)
+    s = _re.sub(r"\\(.)", r"\1", s)
+    s = _re.sub(r"\$\([^)]*\)", "SUB", s)
+    s = _re.sub(r"`[^`]*`", "SUB", s)
+    s = _re.sub(r"''", "", s)
+    return s
+
+
+def _check_command(command: str) -> str | None:
+    """Return block reason if command matches a dangerous pattern, else None."""
+    normalized = _normalize_command(command)
+    for pattern, reason in _BLOCKED:
+        if re.search(pattern, normalized):
+            return f"Blocked: {reason}\n  command: {command.strip()[:120]}"
+    return None
+
+
+class BashInput(BaseModel):
+    command: str = Field(description="Shell command to execute")
+    timeout: int = Field(default=120, description="Timeout in seconds")
+
+
+class BashTool(BaseTool):
+    id = "bash"
+    description = "Execute a shell command in the workspace directory. Returns stdout, stderr, and exit code."
+
+    def parameters_schema(self) -> dict:
+        return model_to_json_schema(BashInput)
+
+    async def execute(self, args: dict, ctx: ToolContext) -> ToolResult:
+        inp = BashInput.model_validate(args)
+
+        blocked = _check_command(inp.command)
+        if blocked:
+            return ToolResult(output=blocked, metadata={"command": inp.command, "blocked": True})
+
+        try:
+            proc = await asyncio.create_subprocess_shell(
+                inp.command,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                cwd=ctx.workspace,
+            )
+            stdout, stderr = await asyncio.wait_for(
+                proc.communicate(), timeout=inp.timeout
+            )
+        except asyncio.TimeoutError:
+            return ToolResult(
+                output=f"Command timed out after {inp.timeout}s: {inp.command}",
+                metadata={"command": inp.command, "exit_code": -1, "timeout": True},
+            )
+
+        output_parts = []
+        if stdout:
+            output_parts.append(stdout.decode("utf-8", errors="replace"))
+        if stderr:
+            output_parts.append(f"[stderr]\n{stderr.decode('utf-8', errors='replace')}")
+
+        return ToolResult(
+            title=f"Bash: {inp.command}",
+            output="\n".join(output_parts) or "(no output)",
+            metadata={
+                "command": inp.command,
+                "exit_code": proc.returncode or 0,
+                "stdout_size": len(stdout) if stdout else 0,
+                "stderr_size": len(stderr) if stderr else 0,
+            },
+        )

voidx/tools/file_ops.py

@@ -0,0 +1,193 @@
+"""File operation tools — read, write, edit. Deterministic, typed I/O."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+from voidx.tools.base import BaseTool, model_to_json_schema, ToolContext, ToolResult, resolve_safe
+
+
+def _check_staleness(ctx: ToolContext, resolved: Path) -> str | None:
+    """Return error message if file was modified since last read, else None."""
+    key = str(resolved.resolve())
+    if key not in ctx.file_mtimes:
+        return None
+    if not resolved.exists():
+        return f"File deleted since last read: {resolved}"
+    current_mtime = resolved.stat().st_mtime
+    if current_mtime != ctx.file_mtimes[key]:
+        return (
+            f"File was modified since last read: {resolved}. "
+            "Please re-read the file before editing."
+        )
+    return None
+
+
+def _record_mtime(ctx: ToolContext, resolved: Path) -> None:
+    """Record file mtime after successful read or write."""
+    if resolved.exists():
+        ctx.file_mtimes[str(resolved.resolve())] = resolved.stat().st_mtime
+
+
+class FileReadInput(BaseModel):
+    file_path: str = Field(description="Absolute or relative path to the file")
+    offset: int | None = Field(default=None, description="Line number to start reading from (1-based)")
+    limit: int | None = Field(default=None, description="Maximum number of lines to read")
+
+
+class FileReadTool(BaseTool):
+    id = "read"
+    description = "Read a file. Returns content with line numbers. Use offset/limit for large files."
+
+    def parameters_schema(self) -> dict:
+        return model_to_json_schema(FileReadInput)
+
+    async def execute(self, args: dict, ctx: ToolContext) -> ToolResult:
+        inp = FileReadInput.model_validate(args)
+        path = resolve_safe(ctx.workspace, inp.file_path, ctx.sandbox_extra_paths)
+        if path is None:
+            return ToolResult(output=f"Path traversal blocked: {inp.file_path}", metadata={"error": True})
+        if not path.exists():
+            return ToolResult(output=f"File not found: {inp.file_path}", metadata={"error": True})
+        if path.is_dir():
+            return ToolResult(output=f"Path is a directory: {inp.file_path}", metadata={"error": True})
+
+        text = path.read_text(encoding="utf-8", errors="replace")
+        if text.endswith("\n"):
+            text = text[:-1]
+        lines = text.split("\n")
+        start = (inp.offset or 1) - 1
+        end = start + (inp.limit or len(lines))
+        sliced = lines[start:end]
+
+        numbered = []
+        for i, line in enumerate(sliced, start=start + 1):
+            numbered.append(f"{i}\t{line}")
+
+        _record_mtime(ctx, path)
+
+        return ToolResult(
+            title=f"Read {len(sliced)} lines from {inp.file_path}",
+            output="\n".join(numbered),
+            metadata={"file": inp.file_path, "lines": len(sliced), "total_lines": len(lines)},
+        )
+
+
+class FileWriteInput(BaseModel):
+    file_path: str = Field(description="Path to write the file to")
+    content: str = Field(description="Content to write")
+
+
+class FileWriteTool(BaseTool):
+    id = "write"
+    description = "Write content to a file. Creates parent directories. Overwrites existing files."
+
+    def parameters_schema(self) -> dict:
+        return model_to_json_schema(FileWriteInput)
+
+    async def execute(self, args: dict, ctx: ToolContext) -> ToolResult:
+        inp = FileWriteInput.model_validate(args)
+        path = resolve_safe(ctx.workspace, inp.file_path, ctx.sandbox_extra_paths)
+        if path is None:
+            return ToolResult(output=f"Path traversal blocked: {inp.file_path}", metadata={"error": True})
+        if path.exists():
+            stale = _check_staleness(ctx, path)
+            if stale:
+                return ToolResult(output=stale, metadata={"error": True})
+
+        old_content = ""
+        if path.exists():
+            old_content = path.read_text(encoding="utf-8", errors="replace")
+
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(inp.content, encoding="utf-8")
+        size = len(inp.content)
+        _record_mtime(ctx, path)
+
+        from voidx.ui.diff import make_file_diff
+        diff = make_file_diff(
+            inp.file_path,
+            old_content,
+            inp.content,
+            old_label=f"a/{inp.file_path}" if old_content else "/dev/null",
+            new_label=f"b/{inp.file_path}",
+        )
+
+        return ToolResult(
+            title=f"Wrote {size} bytes to {inp.file_path}",
+            output=f"File written: {inp.file_path} ({size} bytes)",
+            metadata={"file": inp.file_path, "size": size},
+            diff=diff,
+        )
+
+
+class EditEntry(BaseModel):
+    old_string: str = Field(description="Exact string to replace. Must exist at least once in the file.")
+    new_string: str = Field(description="String to replace with")
+
+
+class FileEditInput(BaseModel):
+    file_path: str = Field(description="Path to edit")
+    edits: list[EditEntry] = Field(description="List of edits to apply atomically. Use a single entry for one change.")
+
+
+class FileEditTool(BaseTool):
+    id = "edit"
+    description = (
+        "Replace strings in a single file atomically. Replaces ALL occurrences "
+        "of each old_string. Edits apply in order — later edits see earlier results."
+    )
+
+    def parameters_schema(self) -> dict:
+        return model_to_json_schema(FileEditInput)
+
+    async def execute(self, args: dict, ctx: ToolContext) -> ToolResult:
+        inp = FileEditInput.model_validate(args)
+        path = resolve_safe(ctx.workspace, inp.file_path, ctx.sandbox_extra_paths)
+        if path is None:
+            return ToolResult(output=f"Path traversal blocked: {inp.file_path}", metadata={"error": True})
+        if not path.exists():
+            return ToolResult(output=f"File not found: {inp.file_path}", metadata={"error": True})
+
+        if not inp.edits:
+            return ToolResult(
+                output="No edits provided. The 'edits' array must contain at least one entry.",
+                metadata={"error": True},
+            )
+
+        stale = _check_staleness(ctx, path)
+        if stale:
+            return ToolResult(output=stale, metadata={"error": True})
+
+        original = path.read_text(encoding="utf-8", errors="replace")
+        content = original
+
+        for i, edit in enumerate(inp.edits):
+            if not edit.old_string:
+                return ToolResult(output=f"Edit {i}: old_string must not be empty")
+            if edit.old_string == edit.new_string:
+                return ToolResult(output=f"Edit {i}: old_string and new_string must differ")
+
+            count = content.count(edit.old_string)
+            if count == 0:
+                return ToolResult(
+                    output=f"Edit {i}: old_string not found in {inp.file_path}",
+                    metadata={"error": True},
+                )
+
+            content = content.replace(edit.old_string, edit.new_string)
+
+        path.write_text(content, encoding="utf-8")
+        _record_mtime(ctx, path)
+
+        from voidx.ui.diff import make_file_diff
+        diff = make_file_diff(inp.file_path, original, content)
+
+        return ToolResult(
+            title=f"Edited {inp.file_path} ({len(inp.edits)} edits)",
+            output=f"File edited: {inp.file_path} ({len(inp.edits)} replacements)",
+            metadata={"file": inp.file_path, "replacements": len(inp.edits)},
+            diff=diff,
+        )

voidx/tools/lsp.py

@@ -0,0 +1,155 @@
+"""LSP-backed code intelligence tools."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+from voidx.lsp.errors import LspError
+from voidx.lsp.service import LspService
+from voidx.tools.base import BaseTool, ToolContext, ToolResult, model_to_json_schema, resolve_safe
+
+
+class LspDiagnosticsInput(BaseModel):
+    file_path: str | None = Field(
+        default=None,
+        description="File to check. If omitted, returns cached diagnostics for already opened files.",
+    )
+
+
+class LspSymbolsInput(BaseModel):
+    file_path: str | None = Field(default=None, description="File for document symbols.")
+    query: str = Field(default="", description="Workspace symbol query when file_path is omitted.")
+
+
+class LspPositionInput(BaseModel):
+    file_path: str = Field(description="File containing the position.")
+    line: int = Field(description="1-based line number.", ge=1)
+    character: int = Field(default=0, description="0-based character offset.", ge=0)
+
+
+class LspReferencesInput(LspPositionInput):
+    include_declaration: bool = Field(default=True, description="Include the symbol declaration in results.")
+
+
+class LspFormatInput(BaseModel):
+    file_path: str = Field(description="File to format with the configured language server.")
+
+
+class LspDiagnosticsTool(BaseTool):
+    id = "lsp_diagnostics"
+    description = "Get LSP diagnostics for a file, or cached diagnostics for opened files when file_path is omitted."
+
+    def parameters_schema(self) -> dict:
+        return model_to_json_schema(LspDiagnosticsInput)
+
+    async def execute(self, args: dict, ctx: ToolContext) -> ToolResult:
+        inp = LspDiagnosticsInput.model_validate(args)
+        service = _service(ctx)
+        if service is None:
+            return ToolResult(output="LSP manager not available.", metadata={"error": True})
+        try:
+            output = await service.diagnostics(inp.file_path)
+            return ToolResult(title="LSP diagnostics", output=output)
+        except LspError as exc:
+            return ToolResult(output=f"LSP diagnostics failed: {exc}", metadata={"error": True})
+
+
+class LspSymbolsTool(BaseTool):
+    id = "lsp_symbols"
+    description = "List document symbols for file_path, or workspace symbols for query."
+
+    def parameters_schema(self) -> dict:
+        return model_to_json_schema(LspSymbolsInput)
+
+    async def execute(self, args: dict, ctx: ToolContext) -> ToolResult:
+        inp = LspSymbolsInput.model_validate(args)
+        service = _service(ctx)
+        if service is None:
+            return ToolResult(output="LSP manager not available.", metadata={"error": True})
+        try:
+            output = await service.symbols(inp.file_path, inp.query)
+            return ToolResult(title="LSP symbols", output=output)
+        except LspError as exc:
+            return ToolResult(output=f"LSP symbols failed: {exc}", metadata={"error": True})
+
+
+class LspDefinitionTool(BaseTool):
+    id = "lsp_definition"
+    description = "Find definition locations for a symbol at file_path:line:character."
+
+    def parameters_schema(self) -> dict:
+        return model_to_json_schema(LspPositionInput)
+
+    async def execute(self, args: dict, ctx: ToolContext) -> ToolResult:
+        inp = LspPositionInput.model_validate(args)
+        service = _service(ctx)
+        if service is None:
+            return ToolResult(output="LSP manager not available.", metadata={"error": True})
+        try:
+            output = await service.definition(inp.file_path, inp.line, inp.character)
+            return ToolResult(title="LSP definition", output=output)
+        except LspError as exc:
+            return ToolResult(output=f"LSP definition failed: {exc}", metadata={"error": True})
+
+
+class LspReferencesTool(BaseTool):
+    id = "lsp_references"
+    description = "Find references for a symbol at file_path:line:character."
+
+    def parameters_schema(self) -> dict:
+        return model_to_json_schema(LspReferencesInput)
+
+    async def execute(self, args: dict, ctx: ToolContext) -> ToolResult:
+        inp = LspReferencesInput.model_validate(args)
+        service = _service(ctx)
+        if service is None:
+            return ToolResult(output="LSP manager not available.", metadata={"error": True})
+        try:
+            output = await service.references(
+                inp.file_path,
+                inp.line,
+                inp.character,
+                include_declaration=inp.include_declaration,
+            )
+            return ToolResult(title="LSP references", output=output)
+        except LspError as exc:
+            return ToolResult(output=f"LSP references failed: {exc}", metadata={"error": True})
+
+
+class LspFormatTool(BaseTool):
+    id = "lsp_format"
+    description = "Format a file with its configured language server. Writes the formatted content back to disk."
+
+    def parameters_schema(self) -> dict:
+        return model_to_json_schema(LspFormatInput)
+
+    async def execute(self, args: dict, ctx: ToolContext) -> ToolResult:
+        inp = LspFormatInput.model_validate(args)
+        manager = getattr(ctx, "lsp_manager", None)
+        if manager is None:
+            return ToolResult(output="LSP manager not available.", metadata={"error": True})
+        try:
+            changed, old_text, new_text = await manager.format_document(inp.file_path)
+        except LspError as exc:
+            return ToolResult(output=f"LSP format failed: {exc}", metadata={"error": True})
+        path = resolve_safe(ctx.workspace, inp.file_path, ctx.sandbox_extra_paths)
+        if path is not None and path.exists():
+            ctx.file_mtimes[str(path.resolve())] = path.stat().st_mtime
+        if not changed:
+            return ToolResult(output=f"No formatting changes for {inp.file_path}.")
+
+        from voidx.ui.diff import make_file_diff
+        diff = make_file_diff(inp.file_path, old_text, new_text)
+        return ToolResult(
+            title=f"Formatted {inp.file_path}",
+            output=f"File formatted: {inp.file_path}",
+            metadata={"file": inp.file_path, "size": len(new_text)},
+            diff=diff,
+        )
+
+
+def _service(ctx: ToolContext) -> LspService | None:
+    manager = getattr(ctx, "lsp_manager", None)
+    if manager is None:
+        return None
+    return LspService(manager)