pdo-agent 2.0.0__py3-none-any.whl

pdo/tools/git.py

@@ -0,0 +1,44 @@
+"""Git tool: run git commands in the working directory."""
+from __future__ import annotations
+
+import shlex
+import subprocess
+from typing import Any
+
+from .base import Tool, truncate
+from .registry import register_tool
+
+
+@register_tool
+class GitTool(Tool):
+    name = "git"
+    description = (
+        "Run a git command in the working directory and return its output "
+        "(e.g. 'status --short', 'diff', 'log --oneline -10', "
+        "'commit -m \"message\"'). Network commands like push use your "
+        "existing credentials."
+    )
+    parameters = {
+        "type": "object",
+        "properties": {
+            "args": {
+                "type": "string",
+                "description": "Arguments passed to git, e.g. 'status --short'.",
+            }
+        },
+        "required": ["args"],
+    }
+
+    def run(self, args: str, **_: Any) -> str:
+        try:
+            argv = ["git", *shlex.split(args)]
+        except ValueError as exc:
+            return f"Error parsing git arguments: {exc}"
+        try:
+            completed = subprocess.run(argv, capture_output=True, text=True, timeout=60)
+        except FileNotFoundError:
+            return "Error: git is not installed or not on PATH."
+        except subprocess.TimeoutExpired:
+            return "Error: git command timed out."
+        output = ((completed.stdout or "") + (completed.stderr or "")).strip()
+        return f"[exit {completed.returncode}]\n{truncate(output or '(no output)')}"

pdo/tools/memory.py

@@ -0,0 +1,70 @@
+"""Memory tools: save, search and delete facts in the local JSON store.
+
+These thin wrappers expose :class:`pdo.agent.memory.MemoryStore` to the model so
+it can remember useful facts and preferences across turns and sessions.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from ..agent.memory import get_memory_store
+from .base import Tool
+from .registry import register_tool
+
+
+@register_tool
+class MemorySaveTool(Tool):
+    name = "memory_save"
+    description = "Save a useful fact or user preference to long-term memory."
+    parameters = {
+        "type": "object",
+        "properties": {
+            "text": {"type": "string", "description": "The fact to remember."},
+            "tags": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "Optional tags to aid later search.",
+            },
+        },
+        "required": ["text"],
+    }
+
+    def run(self, text: str, tags: list[str] | None = None, **_: Any) -> str:
+        fact_id = get_memory_store().save_fact(text, tags or [])
+        return f"Saved memory {fact_id}."
+
+
+@register_tool
+class MemorySearchTool(Tool):
+    name = "memory_search"
+    description = "Search long-term memory for facts matching a keyword query."
+    parameters = {
+        "type": "object",
+        "properties": {
+            "query": {"type": "string", "description": "Keyword(s) to search for."}
+        },
+        "required": ["query"],
+    }
+
+    def run(self, query: str, **_: Any) -> str:
+        hits = get_memory_store().search_facts(query)
+        if not hits:
+            return "No memories matched that query."
+        return "\n".join(f"[{hit['id']}] {hit['text']}" for hit in hits)
+
+
+@register_tool
+class MemoryDeleteTool(Tool):
+    name = "memory_delete"
+    description = "Delete a memory by its id."
+    parameters = {
+        "type": "object",
+        "properties": {
+            "id": {"type": "string", "description": "The id of the memory to delete."}
+        },
+        "required": ["id"],
+    }
+
+    def run(self, id: str, **_: Any) -> str:  # noqa: A002 — matches the schema field name
+        deleted = get_memory_store().delete_fact(id)
+        return "Deleted." if deleted else "No memory with that id."

pdo/tools/rag.py

@@ -0,0 +1,60 @@
+"""Codebase retrieval tool backed by the BM25 index in :mod:`pdo.rag`."""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from ..rag import build_index, load_index, search
+from .base import Tool, truncate
+from .registry import register_tool
+
+# Snippet size cap per result so a handful of hits can't flood the context.
+_SNIPPET_CHARS = 1200
+
+
+@register_tool
+class CodebaseSearchTool(Tool):
+    name = "codebase_search"
+    description = (
+        "Semantic-ish search over the indexed codebase in the current directory: "
+        "returns the most relevant code/document chunks for a natural-language "
+        "query, with path:line references. Builds the index on first use; the "
+        "user can refresh it with /index."
+    )
+    parameters = {
+        "type": "object",
+        "properties": {
+            "query": {
+                "type": "string",
+                "description": "What to look for (identifiers, phrases, concepts).",
+            },
+            "top_k": {
+                "type": "integer",
+                "description": "How many chunks to return (default 5).",
+            },
+        },
+        "required": ["query"],
+    }
+
+    def run(self, query: str, top_k: int = 5, **_: Any) -> str:
+        root = Path.cwd()
+        index = load_index(root)
+        if index is None or index.root != str(root.resolve()):
+            index = build_index(root)
+        if not index.chunks:
+            return "The index is empty — no indexable files found here."
+
+        results = search(index, query, top_k=max(1, min(top_k, 20)))
+        if not results:
+            return "No relevant chunks found for that query."
+
+        blocks = []
+        for result in results:
+            chunk = result.chunk
+            snippet = chunk.text
+            if len(snippet) > _SNIPPET_CHARS:
+                snippet = snippet[:_SNIPPET_CHARS] + "\n… [truncated]"
+            blocks.append(
+                f"[{chunk.path}:{chunk.start}-{chunk.end}] (score {result.score:.1f})\n{snippet}"
+            )
+        return truncate("\n\n---\n\n".join(blocks), 8000)

pdo/tools/registry.py

@@ -0,0 +1,203 @@
+"""The single tool registry.
+
+Tools auto-register here via the :func:`register_tool` class decorator when
+their module is imported. :func:`get_registry` lazily imports the built-in tool
+modules the first time it is called, so the rest of the app only ever sees a
+fully populated registry and never imports individual tools.
+"""
+from __future__ import annotations
+
+import importlib.util
+import inspect
+import logging
+import sys
+from pathlib import Path
+from threading import Lock
+
+from .base import Tool
+
+logger = logging.getLogger(__name__)
+
+# Entry-point group third-party packages can register tools under.
+PLUGIN_ENTRYPOINT_GROUP = "pdo.plugins"
+
+# Names of tools that were added by plugins (for display/introspection).
+_plugin_tool_names: list[str] = []
+
+
+class ToolRegistry:
+    """An ordered collection of tools keyed by name."""
+
+    def __init__(self) -> None:
+        self._tools: dict[str, Tool] = {}
+
+    def register(self, tool: Tool) -> None:
+        if not tool.name:
+            raise ValueError(f"{type(tool).__name__} must define a non-empty 'name'")
+        if tool.name in self._tools:
+            logger.warning("Overwriting already-registered tool %r", tool.name)
+        self._tools[tool.name] = tool
+
+    def get(self, name: str) -> Tool:
+        if name not in self._tools:
+            raise KeyError(name)
+        return self._tools[name]
+
+    def has(self, name: str) -> bool:
+        return name in self._tools
+
+    def all(self) -> list[Tool]:
+        return list(self._tools.values())
+
+    def names(self) -> list[str]:
+        return sorted(self._tools)
+
+    def schemas(self) -> list[dict]:
+        """Return every tool's JSON schema for the model's ``tools`` parameter."""
+        return [tool.to_openai_schema() for tool in self._tools.values()]
+
+
+# Module-level singleton. Tools register into this instance at import time.
+_registry = ToolRegistry()
+_loaded = False
+_load_lock = Lock()
+
+
+def register_tool(cls: type[Tool]) -> type[Tool]:
+    """Class decorator: instantiate a ``Tool`` subclass and register it.
+
+    Subclasses must be constructible with no required arguments (inject
+    dependencies via keyword arguments with sensible defaults).
+    """
+    _registry.register(cls())
+    return cls
+
+
+def get_registry() -> ToolRegistry:
+    """Return the shared registry, importing built-in and plugin tools on first use."""
+    global _loaded
+    if not _loaded:
+        with _load_lock:
+            if not _loaded:
+                # Importing these modules triggers their @register_tool decorators.
+                from . import (  # noqa: F401
+                    code,
+                    data,
+                    edit,
+                    filesystem,
+                    git,
+                    memory,
+                    rag,
+                    search,
+                    shell,
+                    web,
+                )
+
+                load_plugins(_registry)
+                _loaded = True
+    return _registry
+
+
+def plugin_tool_names() -> list[str]:
+    """Return the names of tools contributed by plugins."""
+    return list(_plugin_tool_names)
+
+
+def load_plugins(registry: ToolRegistry) -> None:
+    """Discover and register external tool plugins (directory + entry points)."""
+    from ..config import get_plugins_dir
+
+    try:
+        discover_directory_plugins(registry, get_plugins_dir())
+    except Exception:  # noqa: BLE001 — discovery must never crash startup
+        logger.exception("Directory plugin discovery failed")
+    try:
+        discover_entrypoint_plugins(registry)
+    except Exception:  # noqa: BLE001
+        logger.exception("Entry-point plugin discovery failed")
+
+
+def discover_directory_plugins(registry: ToolRegistry, plugins_dir: Path) -> None:
+    """Import every ``*.py`` file in ``plugins_dir`` and register its tools.
+
+    Each file is loaded in isolation; a broken plugin is logged and skipped so
+    it can't take down the rest of PDO.
+    """
+    if not plugins_dir.exists():
+        return
+    for path in sorted(plugins_dir.glob("*.py")):
+        if path.name.startswith("_"):
+            continue
+        try:
+            module = _import_file(path)
+            _register_module_tools(registry, module)
+        except Exception:  # noqa: BLE001
+            logger.exception("Failed to load plugin file %s", path)
+
+
+def discover_entrypoint_plugins(registry: ToolRegistry) -> None:
+    """Load tools advertised by installed packages under the plugin entry-point group.
+
+    An entry point may resolve to a ``Tool`` subclass (registered directly) or a
+    callable ``register(registry)`` that adds its own tools.
+    """
+    try:
+        from importlib.metadata import entry_points
+
+        eps = entry_points()
+        group = (
+            eps.select(group=PLUGIN_ENTRYPOINT_GROUP)
+            if hasattr(eps, "select")
+            else eps.get(PLUGIN_ENTRYPOINT_GROUP, [])  # Python <3.10 mapping API
+        )
+    except Exception:  # noqa: BLE001
+        logger.exception("Could not read plugin entry points")
+        return
+
+    for entry_point in group:
+        try:
+            obj = entry_point.load()
+        except Exception:  # noqa: BLE001
+            logger.exception("Failed to load plugin entry point %s", entry_point.name)
+            continue
+        _register_plugin_object(registry, obj)
+
+
+def _import_file(path: Path):
+    """Import a standalone .py file under a unique module name and return it."""
+    name = f"pdo_plugin_{path.stem}"
+    spec = importlib.util.spec_from_file_location(name, path)
+    if spec is None or spec.loader is None:
+        raise ImportError(f"cannot load plugin spec for {path}")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[name] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+def _register_module_tools(registry: ToolRegistry, module) -> None:
+    """Register every concrete ``Tool`` subclass *defined in* ``module``."""
+    for _, obj in inspect.getmembers(module, inspect.isclass):
+        if (
+            issubclass(obj, Tool)
+            and obj is not Tool
+            and not inspect.isabstract(obj)
+            and obj.__module__ == module.__name__  # ignore imported base/others
+        ):
+            _register_plugin_object(registry, obj)
+
+
+def _register_plugin_object(registry: ToolRegistry, obj) -> None:
+    """Register a plugin-provided Tool subclass or a register(registry) callable."""
+    if inspect.isclass(obj) and issubclass(obj, Tool) and obj is not Tool:
+        try:
+            tool = obj()
+        except Exception:  # noqa: BLE001
+            logger.exception("Could not instantiate plugin tool %s", obj)
+            return
+        if tool.name and not registry.has(tool.name):
+            registry.register(tool)
+            _plugin_tool_names.append(tool.name)
+            logger.info("Loaded plugin tool %r", tool.name)
+    elif callable(obj):
+        obj(registry)

pdo/tools/search.py

@@ -0,0 +1,83 @@
+"""Code-search tools: glob for files and grep file contents."""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any
+
+from .base import Tool, truncate
+from .registry import register_tool
+
+# Directories that are noise for code search; skipped by grep.
+_SKIP_DIRS = {".git", ".venv", "venv", "node_modules", "__pycache__", ".ruff_cache", ".pytest_cache"}
+_MAX_HITS = 200
+
+
+def _skipped(path: Path) -> bool:
+    return any(part in _SKIP_DIRS for part in path.parts)
+
+
+@register_tool
+class GlobTool(Tool):
+    name = "glob_files"
+    description = "Find files matching a glob pattern (e.g. '**/*.py') under a directory."
+    parameters = {
+        "type": "object",
+        "properties": {
+            "pattern": {"type": "string", "description": "Glob pattern, e.g. '**/*.md'."},
+            "path": {"type": "string", "description": "Base directory (default current)."},
+        },
+        "required": ["pattern"],
+    }
+
+    def run(self, pattern: str, path: str = ".", **_: Any) -> str:
+        base = Path(path).expanduser()
+        if not base.exists():
+            return f"Error: path not found: {base}"
+        matches = [
+            str(p) for p in sorted(base.glob(pattern)) if p.is_file() and not _skipped(p)
+        ][:500]
+        return truncate("\n".join(matches)) if matches else "No files matched."
+
+
+@register_tool
+class GrepTool(Tool):
+    name = "search_files"
+    description = (
+        "Search file contents for a regular expression and return matching "
+        "'path:line: text'. Skips common noise directories (.git, .venv, …)."
+    )
+    parameters = {
+        "type": "object",
+        "properties": {
+            "pattern": {"type": "string", "description": "Regular expression to search for."},
+            "path": {"type": "string", "description": "Base directory (default current)."},
+            "glob": {
+                "type": "string",
+                "description": "Limit to files matching this glob (default '**/*').",
+            },
+        },
+        "required": ["pattern"],
+    }
+
+    def run(self, pattern: str, path: str = ".", glob: str = "**/*", **_: Any) -> str:
+        base = Path(path).expanduser()
+        try:
+            regex = re.compile(pattern)
+        except re.error as exc:
+            return f"Invalid regular expression: {exc}"
+
+        hits: list[str] = []
+        for file in base.glob(glob):
+            if not file.is_file() or _skipped(file):
+                continue
+            try:
+                content = file.read_text("utf-8", "ignore")
+            except OSError:
+                continue
+            for lineno, line in enumerate(content.splitlines(), 1):
+                if regex.search(line):
+                    hits.append(f"{file}:{lineno}: {line.strip()[:200]}")
+                    if len(hits) >= _MAX_HITS:
+                        return truncate("\n".join(hits) + "\n… [more matches omitted]")
+        return truncate("\n".join(hits)) if hits else "No matches found."

pdo/tools/shell.py

@@ -0,0 +1,125 @@
+"""Shell execution tool with a configurable dangerous-command detector.
+
+The detector is a pure function (:func:`is_dangerous`) so it can be unit tested
+in isolation. Anything it flags requires an explicit, typed confirmation before
+the command runs.
+"""
+from __future__ import annotations
+
+import logging
+import re
+import subprocess
+from collections.abc import Callable, Sequence
+from typing import Any
+
+from .base import Tool, default_confirm
+from .registry import register_tool
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_TIMEOUT = 60
+
+# Exact substrings that are unambiguously destructive. Kept separate from the
+# regex patterns so operators can extend either independently.
+DEFAULT_DENYLIST: tuple[str, ...] = (
+    "rm -rf /",
+    "rm -rf /*",
+    ":(){:|:&};:",
+    "mkfs",
+    "dd if=",
+    "> /dev/sda",
+)
+
+# (pattern, human-readable reason) pairs describing dangerous command shapes.
+DANGEROUS_PATTERNS: tuple[tuple[str, str], ...] = (
+    (r"\brm\b\s+(?:-\S+\s+)*-\S*r", "recursive delete (rm -r)"),
+    (r"\brm\b.*\*", "wildcard delete (rm ... *)"),
+    (r"\bsudo\b", "elevated privileges (sudo)"),
+    (r"\bshutdown\b", "system shutdown"),
+    (r"\breboot\b", "system reboot"),
+    (r"\bhalt\b", "system halt"),
+    (r"\bmkfs\b", "disk format (mkfs)"),
+    (r"\bfdisk\b", "disk partitioning (fdisk)"),
+    (r"\bmkswap\b", "swap creation (mkswap)"),
+    (r"\bdd\b\s+if=", "raw disk write (dd)"),
+    (r":\(\)\s*\{.*\}\s*;\s*:", "fork bomb"),
+    (r">\s*/dev/sd[a-z]", "writing to a disk device"),
+    (r"\bchmod\b\s+-R\s+0?00", "recursive permission wipe (chmod -R 000)"),
+)
+
+
+def is_dangerous(
+    command: str, denylist: Sequence[str] | None = None
+) -> tuple[bool, str | None]:
+    """Classify ``command`` as dangerous or not.
+
+    Returns a ``(dangerous, reason)`` tuple. The reason is a short, human-
+    readable explanation suitable for a confirmation prompt.
+    """
+    text = command.strip()
+    lowered = text.lower()
+
+    for token in (denylist if denylist is not None else DEFAULT_DENYLIST):
+        if token.lower() in lowered:
+            return True, f"matches denylist entry {token!r}"
+
+    for pattern, reason in DANGEROUS_PATTERNS:
+        if re.search(pattern, text):
+            return True, reason
+
+    return False, None
+
+
+@register_tool
+class ShellTool(Tool):
+    name = "run_shell"
+    description = (
+        "Run a shell command and return its combined stdout/stderr and exit "
+        "code. Commands detected as dangerous require explicit user "
+        "confirmation before they run."
+    )
+    parameters = {
+        "type": "object",
+        "properties": {
+            "command": {"type": "string", "description": "The shell command to execute."},
+            "timeout": {
+                "type": "integer",
+                "description": f"Maximum seconds to wait (default {DEFAULT_TIMEOUT}).",
+            },
+        },
+        "required": ["command"],
+    }
+
+    def __init__(
+        self,
+        confirm: Callable[[str], bool] = default_confirm,
+        denylist: Sequence[str] | None = None,
+    ) -> None:
+        self._confirm = confirm
+        self._denylist = denylist
+
+    def run(self, command: str, timeout: int = DEFAULT_TIMEOUT, **_: Any) -> str:
+        dangerous, reason = is_dangerous(command, self._denylist)
+        if dangerous:
+            logger.warning("Dangerous command requested (%s): %s", reason, command)
+            if not self._confirm(
+                f"DANGEROUS command detected — {reason}:\n  {command}\nProceed?"
+            ):
+                return "Cancelled: dangerous command was not confirmed by the user."
+
+        try:
+            completed = subprocess.run(
+                command,
+                shell=True,  # noqa: S602 — running shell commands is this tool's purpose
+                capture_output=True,
+                text=True,
+                timeout=timeout,
+            )
+        except subprocess.TimeoutExpired:
+            return f"Error: command timed out after {timeout}s."
+        except Exception as exc:  # noqa: BLE001 — never crash the agent loop
+            logger.exception("Shell command failed to start")
+            return f"Error: could not run command: {exc}"
+
+        output = ((completed.stdout or "") + (completed.stderr or "")).strip()
+        return f"[exit {completed.returncode}]\n{output or '(no output)'}"