voidx 1.0.0__py3-none-any.whl

voidx/tools/registry.py

@@ -0,0 +1,104 @@
+"""Tool registry — every tool typed, all dispatch quantified."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+from voidx.tools.base import ToolContext, ToolResult  # noqa: F401 — re-export
+from voidx.tools.file_ops import FileReadTool, FileWriteTool, FileEditTool
+from voidx.tools.lsp import (
+    LspDefinitionTool,
+    LspDiagnosticsTool,
+    LspFormatTool,
+    LspReferencesTool,
+    LspSymbolsTool,
+)
+from voidx.tools.repomap import RepoMapTool
+from voidx.tools.search import GlobTool, GrepTool
+from voidx.tools.bash import BashTool
+from voidx.tools.task_status import TaskStatusTool
+from voidx.tools.todo import TodoWriteTool
+from voidx.tools.webfetch import WebFetchTool
+from voidx.tools.websearch import WebSearchTool
+
+
+class ToolDef(BaseModel):
+    """A registered tool definition — everything the LLM needs to call it."""
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    id: str
+    description: str
+    parameters: dict  # JSON Schema for the LLM
+
+
+class ToolRegistry:
+    """Manages all available tools. No dynamic discovery — everything explicit."""
+
+    def __init__(self, settings=None) -> None:
+        self._tools: dict[str, ToolDef] = {}
+        self._instances: dict[str, object] = {}
+        self._settings = settings
+        self._register_builtins()
+
+    def _register_builtins(self) -> None:
+        for cls in [
+            FileReadTool, FileWriteTool, FileEditTool,
+            RepoMapTool,
+            GlobTool, GrepTool, BashTool,
+            TodoWriteTool,
+            LspDiagnosticsTool, LspSymbolsTool,
+            LspDefinitionTool, LspReferencesTool, LspFormatTool,
+        ]:
+            instance = cls()
+            self.register(instance.id, instance, instance.description, instance.parameters_schema())
+        wf = WebFetchTool(settings=self._settings)
+        self.register(wf.id, wf, wf.description, wf.parameters_schema())
+        # WebSearchTool needs settings for Tavily API key
+        ws = WebSearchTool(settings=self._settings)
+        self.register(ws.id, ws, ws.description, ws.parameters_schema())
+
+    def register(self, tool_id: str, instance: object, description: str, parameters: dict) -> None:
+        """Register a tool dynamically (e.g. agent tool injected at runtime)."""
+        self._tools[tool_id] = ToolDef(
+            id=tool_id, description=description, parameters=parameters,
+        )
+        self._instances[tool_id] = instance
+
+    def list(self) -> list[ToolDef]:
+        return list(self._tools.values())
+
+    def get(self, tool_id: str):
+        return self._instances.get(tool_id)
+
+    def get_def(self, tool_id: str) -> ToolDef | None:
+        return self._tools.get(tool_id)
+
+    def unregister_prefix(self, prefix: str) -> None:
+        for tool_id in [tid for tid in self._tools if tid.startswith(prefix)]:
+            self._tools.pop(tool_id, None)
+            self._instances.pop(tool_id, None)
+
+    def ids(self) -> list[str]:
+        return list(self._tools.keys())
+
+    def tools_for_llm(self) -> list[dict]:
+        """Generate OpenAI/Anthropic-compatible tool definitions."""
+        result = []
+        for t in self._tools.values():
+            result.append({
+                "type": "function",
+                "function": {
+                    "name": t.id,
+                    "description": t.description,
+                    "parameters": t.parameters,
+                    "strict": True,
+                },
+            })
+        return result
+
+    async def execute_tool(self, tool_id: str, args: dict, ctx: ToolContext) -> ToolResult:
+        """Execute a tool by id. Returns typed result."""
+        tool = self.get(tool_id)
+        if not tool:
+            return ToolResult(output=f"Unknown tool: {tool_id}. Available: {self.ids()}")
+        return await tool.execute(args, ctx)

voidx/tools/repomap.py

@@ -0,0 +1,238 @@
+"""Repo map tool — structural overview of the codebase for LLM context.
+
+Extracts function/class signatures from source files using regex-based
+parsing. Groups by file, limits output to a token budget (~4000 tokens).
+
+Supports Python by default. Extensible to other languages.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+from voidx.tools.base import BaseTool, model_to_json_schema, ToolContext, ToolResult, resolve_safe
+
+OUTPUT_TOKEN_BUDGET = 4000
+DIR_ENTRY_LIMIT = 200
+
+SKIP_DIRS = {
+    ".git", ".venv", "venv", "node_modules", "__pycache__",
+    ".pytest_cache", ".mypy_cache", ".tox", ".eggs",
+    ".idea", ".vscode", "dist", "build", "opencode",
+    ".claude", ".ruff_cache",
+}
+SKIP_SUFFIXES = {
+    ".pyc", ".pyo", ".so", ".dll", ".exe", ".bin",
+    ".png", ".jpg", ".jpeg", ".gif", ".ico", ".pdf",
+    ".zip", ".tar", ".gz", ".whl", ".egg",
+}
+
+
+class RepoMapInput(BaseModel):
+    path: str | None = Field(
+        default=None,
+        description="Subdirectory to focus on. Defaults to workspace root."
+    )
+    detail: str = Field(
+        default="overview",
+        description="'overview' = top-level symbols only, 'signatures' = all function/class signatures"
+    )
+    pattern: str | None = Field(
+        default=None,
+        description="Glob pattern to filter files, e.g. '*.py' or 'src/**/*.ts'"
+    )
+
+
+class RepoMapTool(BaseTool):
+    id = "repo_map"
+    description = (
+        "Structural map of the codebase: file tree with function/class signatures. "
+        "detail='overview' returns top-level symbols only. detail='signatures' "
+        "returns all symbols including methods. Narrow with path or pattern."
+    )
+
+    def parameters_schema(self) -> dict:
+        return model_to_json_schema(RepoMapInput)
+
+    async def execute(self, args: dict, ctx: ToolContext) -> ToolResult:
+        inp = RepoMapInput.model_validate(args)
+        base = Path(ctx.workspace)
+        if inp.path:
+            root = resolve_safe(ctx.workspace, inp.path, ctx.sandbox_extra_paths)
+            if root is None:
+                return ToolResult(output=f"Path traversal blocked: {inp.path}")
+        else:
+            root = base
+
+        if not root.exists():
+            return ToolResult(output=f"Path not found: {root}")
+
+        files = _collect_files(root, inp.pattern)
+        if not files:
+            return ToolResult(output=f"No source files found in: {root}")
+
+        detail = inp.detail
+        entries: list[str] = []
+        total_tokens = 0
+
+        for f in files:
+            rel = str(f.relative_to(base)).replace("\\", "/")
+
+            if detail == "overview":
+                symbols = _extract_top_level(f)
+            else:
+                symbols = _extract_all_symbols(f)
+
+            if symbols:
+                entry = f"{rel}:\n" + "".join(symbols)
+            else:
+                entry = f"{rel}: (no symbols)  " if detail == "signatures" else ""
+
+            est = _estimate_tokens(entry)
+            if total_tokens + est > OUTPUT_TOKEN_BUDGET:
+                remaining = len(files) - len(entries)
+                entries.append(f"\n... ({remaining} more files omitted — token limit)")
+                break
+
+            if entry:
+                entries.append(entry)
+                total_tokens += est
+
+        if not entries:
+            return ToolResult(output=f"No recognizable symbols found in: {root}")
+
+        return ToolResult(
+            title=f"Repo map: {root.relative_to(base)} ({len(entries)} files)",
+            output="\n".join(entries),
+            metadata={
+                "root": str(root.relative_to(base)),
+                "files": len(entries),
+                "detail": detail,
+            },
+        )
+
+
+# ── file collection ──────────────────────────────────────────────────────────
+
+def _collect_files(root: Path, pattern: str | None) -> list[Path]:
+    files: list[Path] = []
+
+    def _scan(dir_path: Path):
+        try:
+            entries = sorted(dir_path.iterdir(), key=lambda p: (not p.is_dir(), p.name.lower()))
+        except PermissionError:
+            return
+        for entry in entries:
+            if entry.name in SKIP_DIRS or entry.name.startswith("."):
+                continue
+            if entry.is_dir():
+                _scan(entry)
+            elif entry.is_file():
+                if entry.suffix in SKIP_SUFFIXES:
+                    continue
+                if pattern and not entry.match(pattern):
+                    continue
+                if _is_source(entry):
+                    files.append(entry)
+
+    _scan(root)
+    return files
+
+
+def _is_source(path: Path) -> bool:
+    ext_map = {
+        ".py": True, ".ts": True, ".tsx": True, ".js": True, ".jsx": True,
+        ".go": True, ".rs": True, ".java": True, ".kt": True, ".swift": True,
+        ".c": True, ".h": True, ".cpp": True, ".hpp": True, ".rb": True,
+        ".php": True, ".css": True, ".scss": True, ".less": True,
+        ".sql": True, ".sh": True, ".bash": True, ".zsh": True,
+        ".yaml": True, ".yml": True, ".toml": True, ".json": True,
+        ".md": True, ".txt": True, ".cfg": True, ".ini": True,
+        ".dockerfile": True, ".makefile": True, ".mk": True,
+    }
+    name = path.name.lower()
+    if name == "dockerfile" or name == "makefile":
+        return True
+    return ext_map.get(path.suffix, False)
+
+
+# ── Python symbol extraction ─────────────────────────────────────────────────
+
+
+def _extract_all_symbols(f: Path) -> list[str]:
+    if f.suffix == ".py":
+        return _extract_python_symbols(f)
+    return _extract_generic(f)
+
+
+def _extract_top_level(f: Path) -> list[str]:
+    if f.suffix == ".py":
+        return _extract_python_symbols(f, top_level_only=True)
+    return _extract_generic(f)
+
+
+def _extract_python_symbols(f: Path, top_level_only: bool = False) -> list[str]:
+    try:
+        text = f.read_text(encoding="utf-8", errors="replace")
+    except Exception:
+        return []
+
+    lines: list[str] = []
+    decorator: str | None = None
+
+    _RE_COMBINED = re.compile(
+        r"^(\s*)class\s+(\w+)\s*(?:\(([^)]*?)\))?\s*:"
+        r"|^(\s*)(?:async\s+)?def\s+(\w+)\s*\(([^)]*)\)\s*(?:->[^:]+?)?\s*:"
+        r"|^[ \t]*@(\w+)",
+        re.MULTILINE,
+    )
+
+    for match in _RE_COMBINED.finditer(text):
+        indent = match.group(1) or match.group(4) or ""
+        level = len(indent) // 4 if indent else 0
+
+        if match.group(0).startswith("@"):
+            decorator = match.group(7) or ""
+            continue
+
+        is_class = match.group(2) is not None
+        func_name = match.group(5)
+        name = match.group(2) or func_name
+        args = match.group(3) or match.group(6) or ""
+
+        if top_level_only and level > 0:
+            continue
+
+        prefix = "  " * level
+        if is_class:
+            tag = ""
+            if decorator:
+                tag = f"@{decorator}\n{prefix}"
+                decorator = None
+            base = f"({match.group(3)})" if match.group(3) else ""
+            lines.append(f"{prefix}{tag}class {name}{base}\n")
+        else:
+            tag = ""
+            if decorator:
+                tag = f"@{decorator} "
+                decorator = None
+            if match.group(0).lstrip().startswith("async"):
+                tag = "async "
+            lines.append(f"{prefix}{tag}def {name}({args})\n")
+
+    return lines
+
+
+def _extract_generic(f: Path) -> list[str]:
+    """Minimal extraction for non-Python files: just report the file."""
+    return []
+
+
+# ── token estimation ─────────────────────────────────────────────────────────
+
+def _estimate_tokens(text: str) -> int:
+    """Quick token estimate: ~4 chars per token for code."""
+    return max(1, len(text) // 4)

voidx/tools/search.py

@@ -0,0 +1,162 @@
+"""Search tools — glob pattern matching, grep content search. Fast, deterministic."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+from voidx.tools.base import BaseTool, model_to_json_schema, ToolContext, ToolResult, resolve_safe
+
+
+class GlobInput(BaseModel):
+    pattern: str = Field(description="Glob pattern to match files, e.g. '**/*.py' or 'src/**/*.ts'")
+
+
+class GlobTool(BaseTool):
+    id = "glob"
+    description = (
+        "Find files by glob pattern (e.g. '**/*.py'). Returns sorted relative paths. "
+        "Skips .git, node_modules, .venv, __pycache__, and other build/dot directories."
+    )
+
+    def parameters_schema(self) -> dict:
+        return model_to_json_schema(GlobInput)
+
+    async def execute(self, args: dict, ctx: ToolContext) -> ToolResult:
+        inp = GlobInput.model_validate(args)
+        base = Path(ctx.workspace)
+        SKIP_DIRS = {".git", ".venv", "venv", "node_modules", "__pycache__", "opencode",
+                     ".pytest_cache", ".mypy_cache", ".tox", ".idea", ".vscode",
+                     "dist", "build", ".eggs"}
+
+        def _visible_path(p: Path) -> bool:
+            parts = p.relative_to(base).parts
+            for i, part in enumerate(parts):
+                if part in SKIP_DIRS:
+                    return False
+                # Allow dot-files at root level (e.g. .env, .gitignore)
+                # but skip content inside hidden directories
+                if part.startswith(".") and i < len(parts) - 1:
+                    return False
+            return True
+
+        matches = sorted(
+            str(p.relative_to(base)).replace("\\", "/")
+            for p in base.glob(inp.pattern)
+            if _visible_path(p)
+        )
+
+        if not matches:
+            return ToolResult(
+                output=f"No files matched pattern: {inp.pattern}",
+                metadata={"pattern": inp.pattern, "matches": 0},
+            )
+
+        return ToolResult(
+            title=f"Glob: {inp.pattern} → {len(matches)} files",
+            output="\n".join(matches[:200]),  # cap at 200 results
+            metadata={"pattern": inp.pattern, "matches": len(matches)},
+        )
+
+
+class GrepInput(BaseModel):
+    pattern: str = Field(description="Regular expression to search for")
+    path: str | None = Field(default=None, description="File or directory to search. Defaults to workspace root.")
+    include: str | None = Field(default=None, description="Glob pattern to filter files, e.g. '*.py'")
+
+
+class GrepTool(BaseTool):
+    id = "grep"
+    description = (
+        "Search file contents with regex. Returns file:line:content matches. "
+        "Skips .git, node_modules, binary files, and build/dot directories."
+    )
+
+    def parameters_schema(self) -> dict:
+        return model_to_json_schema(GrepInput)
+
+    async def execute(self, args: dict, ctx: ToolContext) -> ToolResult:
+        inp = GrepInput.model_validate(args)
+        base = Path(ctx.workspace)
+        search_dir = resolve_safe(ctx.workspace, inp.path, ctx.sandbox_extra_paths) if inp.path else base
+        if search_dir is None:
+            return ToolResult(output=f"Path traversal blocked: {inp.path}")
+
+        try:
+            regex = re.compile(inp.pattern)
+        except re.error as e:
+            return ToolResult(output=f"Invalid regex: {e}")
+
+        results: list[str] = []
+        count = 0
+        scanned = 0
+
+        # Directories to never enter
+        SKIP_DIRS = {".git", ".venv", "venv", "node_modules", "__pycache__",
+                     ".pytest_cache", ".mypy_cache", ".tox", "opencode",
+                     ".idea", ".vscode", "dist", "build", ".eggs"}
+
+        # Binary/text suffixes to skip
+        SKIP_SUFFIXES = {".pyc", ".pyo", ".so", ".dll", ".exe", ".bin",
+                         ".png", ".jpg", ".jpeg", ".gif", ".ico", ".pdf",
+                         ".zip", ".tar", ".gz", ".whl", ".egg"}
+
+        def should_skip_dir(p: Path) -> bool:
+            return p.name in SKIP_DIRS or p.name.startswith(".")
+
+        def iter_files(dir_path: Path):
+            nonlocal scanned
+            try:
+                for entry in dir_path.iterdir():
+                    if should_skip_dir(entry):
+                        continue
+                    if entry.is_dir():
+                        yield from iter_files(entry)
+                    elif entry.is_file():
+                        if entry.suffix in SKIP_SUFFIXES:
+                            continue
+                        if inp.include and not entry.match(inp.include):
+                            continue
+                        scanned += 1
+                        yield entry
+            except PermissionError:
+                pass
+
+        if search_dir.is_file():
+            files = [search_dir]
+        elif search_dir.is_dir():
+            files = iter_files(search_dir)
+        else:
+            return ToolResult(output=f"Path not found: {inp.path}")
+
+        for f in files:
+            if scanned > 5000:
+                results.append(f"... (stopped after scanning {scanned} files)")
+                break
+
+            try:
+                for i, line in enumerate(f.read_text(encoding="utf-8", errors="replace").split("\n"), 1):
+                    if regex.search(line):
+                        rel = str(f.relative_to(base)).replace("\\", "/")
+                        results.append(f"{rel}:{i}:{line.strip()[:200]}")
+                        count += 1
+                        if count >= 100:
+                            break
+                if count >= 100:
+                    break
+            except Exception:
+                continue
+
+        if not results:
+            return ToolResult(
+                output=f"No matches found for: {inp.pattern}",
+                metadata={"pattern": inp.pattern, "matches": 0},
+            )
+
+        return ToolResult(
+            title=f"Grep: {inp.pattern} → {count} matches",
+            output="\n".join(results),
+            metadata={"pattern": inp.pattern, "matches": count},
+        )

voidx/tools/task_status.py

@@ -0,0 +1,57 @@
+"""TaskStatus tool — check worker-role progress. Claude Code aligned."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+from voidx.tools.base import BaseTool, model_to_json_schema, ToolContext, ToolResult
+
+
+class TaskStatusInput(BaseModel):
+    task_id: str | None = Field(
+        default=None,
+        description="Specific task ID to check. If omitted, lists all tasks."
+    )
+
+
+class TaskStatusTool(BaseTool):
+    id = "task_status"
+    description = (
+        "Check child-agent task status. Returns status (pending/running/completed/error), "
+        "current step, elapsed time, and recent output preview. "
+        "Without task_id, lists all tasks."
+    )
+
+    def __init__(self, tracker=None):
+        super().__init__()
+        self._tracker = tracker
+
+    def parameters_schema(self) -> dict:
+        return model_to_json_schema(TaskStatusInput)
+
+    async def execute(self, args: dict, ctx: ToolContext) -> ToolResult:
+        inp = TaskStatusInput.model_validate(args)
+
+        if not self._tracker:
+            return ToolResult(output="Task tracker not available.")
+
+        if inp.task_id:
+            task = self._tracker.get(inp.task_id)
+            if not task:
+                return ToolResult(output=f"Task not found: {inp.task_id}")
+            return ToolResult(
+                title=f"Task {inp.task_id}: {task.status}",
+                output=self._tracker.format_status(),
+                metadata={
+                    "task_id": task.id, "agent": task.agent,
+                    "status": task.status, "step": task.step,
+                },
+            )
+
+        output = self._tracker.format_status()
+        running = self._tracker.list_running()
+        return ToolResult(
+            title=f"Tasks: {len(running)} running, {len(self._tracker._tasks)} total",
+            output=output,
+            metadata={"running": len(running), "total": len(self._tracker._tasks)},
+        )

voidx/tools/task_tracker.py

@@ -0,0 +1,81 @@
+"""Task tracker — shared state for running worker-role status."""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import Literal
+
+TaskStatus = Literal["pending", "running", "completed", "error", "cancelled"]
+
+
+@dataclass
+class TaskState:
+    id: str
+    agent: str
+    description: str
+    status: TaskStatus = "pending"
+    step: int = 0
+    max_steps: int = 0
+    last_output: str = ""  # most recent text preview
+    created_at: float = field(default_factory=time.time)
+    updated_at: float = field(default_factory=time.time)
+
+
+class TaskTracker:
+    """Thread-safe registry for running worker-role tasks."""
+
+    def __init__(self):
+        self._tasks: dict[str, TaskState] = {}
+        self._todos: list = []  # type: ignore[type-arg]
+
+    def start(self, task_id: str, agent: str, description: str, max_steps: int = 25) -> TaskState:
+        state = TaskState(
+            id=task_id, agent=agent, description=description,
+            status="running", max_steps=max_steps,
+        )
+        self._tasks[task_id] = state
+        return state
+
+    def update(self, task_id: str, **kwargs):
+        if task_id in self._tasks:
+            for k, v in kwargs.items():
+                if hasattr(self._tasks[task_id], k):
+                    setattr(self._tasks[task_id], k, v)
+            self._tasks[task_id].updated_at = time.time()
+
+    def finish(self, task_id: str, status: TaskStatus = "completed"):
+        if task_id in self._tasks:
+            self._tasks[task_id].status = status
+            self._tasks[task_id].updated_at = time.time()
+
+    def get(self, task_id: str) -> TaskState | None:
+        return self._tasks.get(task_id)
+
+    def list_all(self) -> list[TaskState]:
+        return list(self._tasks.values())
+
+    def list_running(self) -> list[TaskState]:
+        return [t for t in self._tasks.values() if t.status in ("pending", "running")]
+
+    def remove(self, task_id: str):
+        self._tasks.pop(task_id, None)
+
+    def format_status(self) -> str:
+        """Format all tasks as a status report string."""
+        tasks = self.list_all()
+        if not tasks:
+            return "No worker-role tasks."
+
+        lines = []
+        for t in tasks:
+            icon = {"pending": "○", "running": "◐", "completed": "●", "error": "✕", "cancelled": "◌"}[t.status]
+            elapsed = int(time.time() - t.created_at)
+            step_info = f"step {t.step}/{t.max_steps}" if t.max_steps else ""
+            preview = t.last_output[:100] if t.last_output else ""
+            lines.append(
+                f"{icon} [{t.id}] {t.agent} — {t.status} ({step_info}, {elapsed}s)\n"
+                f"   {t.description[:120]}\n"
+                + (f"   last: {preview}" if preview else "")
+            )
+        return "\n".join(lines)