pdo-agent 2.0.0__py3-none-any.whl

pdo/serve.py

@@ -0,0 +1,124 @@
+"""Serve mode: expose the PDO agent over stdio JSON-RPC (MCP-compatible).
+
+``pdo --serve`` turns PDO into an **MCP server**: any MCP client (Claude
+Desktop, Claude Code, another PDO…) can connect over stdio and call the
+``run_task`` tool, which runs a prompt through the full PDO agent — tools,
+sub-agents, codebase search and all — and returns the final answer.
+
+Protocol: newline-delimited JSON-RPC 2.0 with the MCP handshake
+(``initialize`` → ``tools/list`` → ``tools/call``), i.e. the mirror image of
+:mod:`pdo.mcp`, which is PDO acting as a *client*.
+
+Because stdin/stdout carry the protocol, serve mode never prints to stdout and
+auto-denies interactive confirmations (dangerous commands are simply refused).
+"""
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any, TextIO
+
+from . import __version__
+from .mcp import PROTOCOL_VERSION
+
+logger = logging.getLogger(__name__)
+
+_RUN_TASK_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "task": {
+            "type": "string",
+            "description": "The complete, self-contained task or question for the agent.",
+        }
+    },
+    "required": ["task"],
+}
+
+
+class PDOServer:
+    """A minimal MCP server wrapping one PDO agent."""
+
+    def __init__(self, agent: Any) -> None:
+        self._agent = agent
+
+    # --- request handling ---------------------------------------------------- #
+    def handle(self, message: dict[str, Any]) -> dict[str, Any] | None:
+        """Handle one JSON-RPC message; returns the response (None for notifications)."""
+        method = message.get("method", "")
+        msg_id = message.get("id")
+
+        if msg_id is None:  # notification (e.g. notifications/initialized)
+            return None
+        if method == "initialize":
+            return self._result(
+                msg_id,
+                {
+                    "protocolVersion": PROTOCOL_VERSION,
+                    "capabilities": {"tools": {}},
+                    "serverInfo": {"name": "pdo", "version": __version__},
+                },
+            )
+        if method == "tools/list":
+            return self._result(
+                msg_id,
+                {
+                    "tools": [
+                        {
+                            "name": "run_task",
+                            "description": (
+                                "Run a task with the PDO agent: it reasons, uses its "
+                                "tools (files, shell, web, git, codebase search, "
+                                "sub-agents, connected MCP servers) and returns the "
+                                "final answer."
+                            ),
+                            "inputSchema": _RUN_TASK_SCHEMA,
+                        }
+                    ]
+                },
+            )
+        if method == "tools/call":
+            return self._call_tool(msg_id, message.get("params") or {})
+        return self._error(msg_id, -32601, f"method not found: {method}")
+
+    def _call_tool(self, msg_id: Any, params: dict[str, Any]) -> dict[str, Any]:
+        name = params.get("name")
+        if name != "run_task":
+            return self._error(msg_id, -32602, f"unknown tool: {name}")
+        task = (params.get("arguments") or {}).get("task", "").strip()
+        if not task:
+            return self._error(msg_id, -32602, "missing required argument: task")
+        try:
+            answer = self._agent.run_turn(task)
+            is_error = False
+        except Exception as exc:  # noqa: BLE001 — report, keep serving
+            logger.exception("run_task failed")
+            answer, is_error = f"Agent error: {exc}", True
+        return self._result(
+            msg_id,
+            {"content": [{"type": "text", "text": answer}], "isError": is_error},
+        )
+
+    # --- plumbing -------------------------------------------------------------- #
+    @staticmethod
+    def _result(msg_id: Any, result: dict[str, Any]) -> dict[str, Any]:
+        return {"jsonrpc": "2.0", "id": msg_id, "result": result}
+
+    @staticmethod
+    def _error(msg_id: Any, code: int, message: str) -> dict[str, Any]:
+        return {"jsonrpc": "2.0", "id": msg_id, "error": {"code": code, "message": message}}
+
+    def serve_forever(self, stdin: TextIO, stdout: TextIO) -> None:
+        """Blocking loop: one JSON-RPC message per line until EOF."""
+        for line in stdin:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                message = json.loads(line)
+            except json.JSONDecodeError:
+                logger.warning("Ignoring non-JSON input line")
+                continue
+            response = self.handle(message)
+            if response is not None:
+                stdout.write(json.dumps(response) + "\n")
+                stdout.flush()

pdo/skills.py

@@ -0,0 +1,59 @@
+"""User-defined skills: reusable prompt templates invoked as slash commands.
+
+Each ``.md`` file in the skills directory becomes a slash command named after the
+file (``review.md`` → ``/review``). The file body is a prompt template; an
+optional first line ``description: ...`` or ``# Title`` sets the menu description.
+Use ``{{args}}`` in the template to interpolate whatever the user types after the
+command (otherwise their text is appended).
+"""
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class Skill:
+    name: str  # slash command name without the leading "/"
+    description: str
+    template: str
+
+    def render(self, args: str) -> str:
+        """Produce the prompt to send, substituting the user's arguments."""
+        if "{{args}}" in self.template:
+            return self.template.replace("{{args}}", args)
+        return self.template if not args else f"{self.template}\n\n{args}"
+
+
+def load_skills(skills_dir: Path) -> dict[str, Skill]:
+    """Load every ``*.md`` skill file from ``skills_dir`` (name → Skill)."""
+    skills: dict[str, Skill] = {}
+    if not skills_dir.exists():
+        return skills
+    for path in sorted(skills_dir.glob("*.md")):
+        try:
+            text = path.read_text(encoding="utf-8")
+        except OSError:
+            logger.warning("Could not read skill %s", path)
+            continue
+        name = path.stem.lower().lstrip("/")
+        description, template = _parse_skill(text, name)
+        skills[name] = Skill(name=name, description=description, template=template)
+    return skills
+
+
+def _parse_skill(text: str, name: str) -> tuple[str, str]:
+    lines = text.splitlines()
+    description = f"Custom skill: {name}"
+    if lines:
+        first = lines[0].strip()
+        if first.lower().startswith("description:"):
+            description = first.split(":", 1)[1].strip() or description
+            return description, "\n".join(lines[1:]).strip()
+        if first.startswith("# "):
+            description = first[2:].strip() or description
+            return description, "\n".join(lines[1:]).strip()
+    return description, text.strip()

pdo/theme.py

@@ -0,0 +1,47 @@
+"""Color themes for the terminal UI.
+
+A theme is just an accent color used across the splash, input box, prompt, tool
+bullets and footer. The accent is exposed both as a ``rich`` color name and as a
+``prompt_toolkit`` ANSI name, since the two libraries name colors differently.
+"""
+from __future__ import annotations
+
+# name -> (rich color, prompt_toolkit ansi color)
+THEMES: dict[str, tuple[str, str]] = {
+    "cyan": ("cyan", "ansicyan"),
+    "green": ("green", "ansigreen"),
+    "magenta": ("magenta", "ansimagenta"),
+    "amber": ("yellow", "ansiyellow"),
+    "blue": ("blue", "ansiblue"),
+    "mono": ("white", "ansiwhite"),
+}
+
+_DEFAULT = "cyan"
+_current = _DEFAULT
+
+
+def set_theme(name: str) -> bool:
+    """Switch the active theme. Returns False if the name is unknown."""
+    global _current
+    if name in THEMES:
+        _current = name
+        return True
+    return False
+
+
+def current_theme() -> str:
+    return _current
+
+
+def theme_names() -> list[str]:
+    return list(THEMES)
+
+
+def accent() -> str:
+    """The accent color as a rich color name."""
+    return THEMES.get(_current, THEMES[_DEFAULT])[0]
+
+
+def accent_ansi() -> str:
+    """The accent color as a prompt_toolkit ANSI color name."""
+    return THEMES.get(_current, THEMES[_DEFAULT])[1]

pdo/tools/__init__.py

@@ -0,0 +1,6 @@
+"""Built-in tools.
+
+Tool modules register themselves with the shared registry when imported. The
+registry imports them lazily (see :func:`pdo.tools.registry.get_registry`), so
+importing this package has no side effects beyond making the modules available.
+"""

pdo/tools/base.py

@@ -0,0 +1,89 @@
+"""The ``Tool`` base class and shared confirmation helper.
+
+Every tool subclasses :class:`Tool`, declares a JSON parameter schema, and is
+executed by the agent through the registry. The agent never imports a concrete
+tool, which is what keeps new tools a pure add-on.
+"""
+from __future__ import annotations
+
+import logging
+from abc import ABC, abstractmethod
+from typing import Any
+
+from rich.console import Console
+
+logger = logging.getLogger(__name__)
+
+_console = Console()
+
+
+# Process-wide confirmation override. Non-interactive modes (e.g. `pdo --serve`,
+# where stdin/stdout carry JSON-RPC) install a handler here so confirmation can
+# never block on, or write to, the protocol streams.
+_confirm_override: Any = None
+
+
+def set_confirm_override(handler) -> None:
+    """Replace interactive confirmation globally (None restores the default)."""
+    global _confirm_override
+    _confirm_override = handler
+
+
+def default_confirm(prompt: str) -> bool:
+    """Ask the user to type ``y`` to approve a sensitive action.
+
+    Returns ``False`` on EOF/Ctrl-C so that "no answer" always means "do not
+    proceed". Tools accept this as an injectable dependency so tests can supply
+    a deterministic callback instead of blocking on real input.
+    """
+    if _confirm_override is not None:
+        return bool(_confirm_override(prompt))
+    _console.print(f"[yellow]{prompt}[/yellow]")
+    try:
+        answer = _console.input("Type 'y' to confirm: ")
+    except (EOFError, KeyboardInterrupt):
+        return False
+    return answer.strip().lower() == "y"
+
+
+def truncate(text: str, limit: int = 4000) -> str:
+    """Cap tool output so a single result can't overwhelm the model context."""
+    if len(text) <= limit:
+        return text
+    return text[:limit] + f"\n… [truncated {len(text) - limit} more characters]"
+
+
+class ToolError(RuntimeError):
+    """Raised by a tool to signal a recoverable failure to the agent."""
+
+
+class Tool(ABC):
+    """Base class for all tools.
+
+    Subclasses set the class attributes ``name``, ``description`` and
+    ``parameters`` (a JSON Schema object) and implement :meth:`run`.
+    """
+
+    name: str = ""
+    description: str = ""
+    parameters: dict[str, Any] = {"type": "object", "properties": {}}
+
+    def to_openai_schema(self) -> dict[str, Any]:
+        """Return the function/tool schema in the shape the model expects."""
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description,
+                "parameters": self.parameters,
+            },
+        }
+
+    @abstractmethod
+    def run(self, **kwargs: Any) -> str:
+        """Execute the tool and return a string result for the model.
+
+        Implementations should return a human/model-readable string even on
+        failure (e.g. ``"Error: ..."``); raising is acceptable too — the
+        executor wraps every call — but returning is preferred for clarity.
+        """

pdo/tools/code.py

@@ -0,0 +1,48 @@
+"""Code execution tool.
+
+Runs Python in a *separate process* with a timeout. This isolates crashes and
+bounds runtime, but it is NOT a security sandbox — the code runs with the same
+permissions as PDO. Use it for calculations and quick data tasks.
+"""
+from __future__ import annotations
+
+import subprocess
+import sys
+from typing import Any
+
+from .base import Tool, truncate
+from .registry import register_tool
+
+
+@register_tool
+class PythonExecTool(Tool):
+    name = "python_exec"
+    description = (
+        "Execute a snippet of Python code in a separate process and return its "
+        "stdout/stderr. Good for calculations, parsing, and quick data tasks. "
+        "Print results you want to see."
+    )
+    parameters = {
+        "type": "object",
+        "properties": {
+            "code": {"type": "string", "description": "Python source to run."},
+            "timeout": {
+                "type": "integer",
+                "description": "Maximum seconds to run (default 30).",
+            },
+        },
+        "required": ["code"],
+    }
+
+    def run(self, code: str, timeout: int = 30, **_: Any) -> str:
+        try:
+            completed = subprocess.run(
+                [sys.executable, "-c", code],
+                capture_output=True,
+                text=True,
+                timeout=timeout,
+            )
+        except subprocess.TimeoutExpired:
+            return f"Error: code timed out after {timeout}s."
+        output = ((completed.stdout or "") + (completed.stderr or "")).strip()
+        return f"[exit {completed.returncode}]\n{truncate(output or '(no output)')}"

pdo/tools/data.py

@@ -0,0 +1,57 @@
+"""Database tools: query a SQLite file."""
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+from typing import Any
+
+from .base import Tool, truncate
+from .registry import register_tool
+
+_MAX_ROWS = 200
+
+
+@register_tool
+class SqliteQueryTool(Tool):
+    name = "sqlite_query"
+    description = (
+        "Run a SQL statement against a SQLite database file. SELECTs return rows; "
+        "other statements are committed and report the affected row count."
+    )
+    parameters = {
+        "type": "object",
+        "properties": {
+            "db_path": {"type": "string", "description": "Path to the .sqlite/.db file."},
+            "query": {"type": "string", "description": "The SQL statement to run."},
+            "params": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "Optional positional parameters for the query.",
+            },
+        },
+        "required": ["db_path", "query"],
+    }
+
+    def run(
+        self, db_path: str, query: str, params: list[Any] | None = None, **_: Any
+    ) -> str:
+        path = Path(db_path).expanduser()
+        if not path.exists():
+            return f"Error: database not found: {path}"
+        try:
+            connection = sqlite3.connect(str(path))
+            connection.row_factory = sqlite3.Row
+            cursor = connection.execute(query, tuple(params or []))
+            if cursor.description:  # a result-producing query (SELECT/PRAGMA)
+                columns = [d[0] for d in cursor.description]
+                rows = cursor.fetchmany(_MAX_ROWS)
+                lines = [" | ".join(columns)]
+                lines += [" | ".join(str(row[c]) for c in columns) for row in rows]
+                connection.close()
+                return truncate("\n".join(lines)) if rows else "(no rows)"
+            connection.commit()
+            affected = cursor.rowcount
+            connection.close()
+            return f"OK ({affected} row(s) affected)."
+        except sqlite3.Error as exc:
+            return f"SQLite error: {exc}"

pdo/tools/edit.py

@@ -0,0 +1,55 @@
+"""Targeted file edit tool: replace an exact snippet (safer than full rewrites)."""
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from .base import Tool, default_confirm
+from .filesystem import _resolve, _within_cwd
+from .registry import register_tool
+
+
+@register_tool
+class EditFileTool(Tool):
+    name = "edit_file"
+    description = (
+        "Replace an exact text snippet in a file with new text — safer than "
+        "rewriting the whole file. The old text must appear exactly once; add "
+        "surrounding context to make it unique."
+    )
+    parameters = {
+        "type": "object",
+        "properties": {
+            "path": {"type": "string", "description": "File to edit."},
+            "old_string": {
+                "type": "string",
+                "description": "Exact text to replace (must be unique in the file).",
+            },
+            "new_string": {"type": "string", "description": "Replacement text."},
+        },
+        "required": ["path", "old_string", "new_string"],
+    }
+
+    def __init__(self, confirm: Callable[[str], bool] = default_confirm) -> None:
+        self._confirm = confirm
+
+    def run(self, path: str, old_string: str, new_string: str, **_: Any) -> str:
+        target = _resolve(path)
+        if not target.exists():
+            return f"Error: file not found: {target}"
+        if not _within_cwd(target) and not self._confirm(
+            f"Edit file OUTSIDE the working directory {target}?"
+        ):
+            return "Cancelled: editing outside the working directory was not confirmed."
+
+        content = target.read_text(encoding="utf-8")
+        occurrences = content.count(old_string)
+        if occurrences == 0:
+            return "Error: old_string was not found in the file."
+        if occurrences > 1:
+            return (
+                f"Error: old_string is not unique ({occurrences} matches). "
+                "Add more surrounding context so it matches exactly once."
+            )
+        target.write_text(content.replace(old_string, new_string), encoding="utf-8")
+        return f"Edited {target} (1 replacement)."

pdo/tools/filesystem.py

@@ -0,0 +1,175 @@
+"""Filesystem tools: read, write, append, list and create directories.
+
+Writes are sandboxed to the current working directory by default. Writing
+outside it, or overwriting an existing file, requires explicit confirmation —
+the confirmation callback is injectable so it can be mocked in tests.
+"""
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+from .base import Tool, default_confirm
+from .registry import register_tool
+
+logger = logging.getLogger(__name__)
+
+# Guard against accidentally pasting a huge file into the model context.
+MAX_READ_CHARS = 200_000
+
+
+def _resolve(path: str) -> Path:
+    """Expand ``~`` and resolve to an absolute path."""
+    return Path(path).expanduser().resolve()
+
+
+def _within_cwd(path: Path) -> bool:
+    """Return True if ``path`` is inside the current working directory."""
+    try:
+        path.relative_to(Path.cwd().resolve())
+        return True
+    except ValueError:
+        return False
+
+
+@register_tool
+class ReadFileTool(Tool):
+    name = "read_file"
+    description = "Read and return the UTF-8 text contents of a file."
+    parameters = {
+        "type": "object",
+        "properties": {
+            "path": {"type": "string", "description": "Path to the file to read."}
+        },
+        "required": ["path"],
+    }
+
+    def run(self, path: str, **_: Any) -> str:
+        target = _resolve(path)
+        if not target.exists():
+            return f"Error: file not found: {target}"
+        if not target.is_file():
+            return f"Error: not a file: {target}"
+        data = target.read_text(encoding="utf-8", errors="replace")
+        if len(data) > MAX_READ_CHARS:
+            data = data[:MAX_READ_CHARS] + "\n... [truncated]"
+        return data
+
+
+@register_tool
+class WriteFileTool(Tool):
+    name = "write_file"
+    description = (
+        "Write text to a file (creating parent directories). Asks for "
+        "confirmation before overwriting a file or writing outside the working "
+        "directory."
+    )
+    parameters = {
+        "type": "object",
+        "properties": {
+            "path": {"type": "string", "description": "Destination file path."},
+            "content": {"type": "string", "description": "Text to write."},
+        },
+        "required": ["path", "content"],
+    }
+
+    def __init__(self, confirm: Callable[[str], bool] = default_confirm) -> None:
+        self._confirm = confirm
+
+    def run(self, path: str, content: str, **_: Any) -> str:
+        target = _resolve(path)
+        if not _within_cwd(target) and not self._confirm(
+            f"Write OUTSIDE the working directory to {target}?"
+        ):
+            return "Cancelled: writing outside the working directory was not confirmed."
+        if target.exists() and not self._confirm(f"Overwrite existing file {target}?"):
+            return "Cancelled: overwrite was not confirmed."
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(content, encoding="utf-8")
+        return f"Wrote {len(content)} characters to {target}"
+
+
+@register_tool
+class AppendFileTool(Tool):
+    name = "append_file"
+    description = (
+        "Append text to a file (creating it if needed). Asks for confirmation "
+        "before writing outside the working directory."
+    )
+    parameters = {
+        "type": "object",
+        "properties": {
+            "path": {"type": "string", "description": "Target file path."},
+            "content": {"type": "string", "description": "Text to append."},
+        },
+        "required": ["path", "content"],
+    }
+
+    def __init__(self, confirm: Callable[[str], bool] = default_confirm) -> None:
+        self._confirm = confirm
+
+    def run(self, path: str, content: str, **_: Any) -> str:
+        target = _resolve(path)
+        if not _within_cwd(target) and not self._confirm(
+            f"Append OUTSIDE the working directory to {target}?"
+        ):
+            return "Cancelled: writing outside the working directory was not confirmed."
+        target.parent.mkdir(parents=True, exist_ok=True)
+        with target.open("a", encoding="utf-8") as handle:
+            handle.write(content)
+        return f"Appended {len(content)} characters to {target}"
+
+
+@register_tool
+class ListDirTool(Tool):
+    name = "list_directory"
+    description = "List the entries of a directory (directories are marked)."
+    parameters = {
+        "type": "object",
+        "properties": {
+            "path": {
+                "type": "string",
+                "description": "Directory to list. Defaults to the current directory.",
+            }
+        },
+    }
+
+    def run(self, path: str = ".", **_: Any) -> str:
+        target = _resolve(path)
+        if not target.exists():
+            return f"Error: directory not found: {target}"
+        if not target.is_dir():
+            return f"Error: not a directory: {target}"
+        entries = sorted(target.iterdir(), key=lambda p: (p.is_file(), p.name.lower()))
+        lines = [f"{'[dir] ' if entry.is_dir() else '      '}{entry.name}" for entry in entries]
+        return "\n".join(lines) if lines else "(empty directory)"
+
+
+@register_tool
+class CreateDirTool(Tool):
+    name = "create_directory"
+    description = (
+        "Create a directory (including parents). Asks for confirmation before "
+        "creating it outside the working directory."
+    )
+    parameters = {
+        "type": "object",
+        "properties": {
+            "path": {"type": "string", "description": "Directory path to create."}
+        },
+        "required": ["path"],
+    }
+
+    def __init__(self, confirm: Callable[[str], bool] = default_confirm) -> None:
+        self._confirm = confirm
+
+    def run(self, path: str, **_: Any) -> str:
+        target = _resolve(path)
+        if not _within_cwd(target) and not self._confirm(
+            f"Create directory OUTSIDE the working directory at {target}?"
+        ):
+            return "Cancelled: creating outside the working directory was not confirmed."
+        target.mkdir(parents=True, exist_ok=True)
+        return f"Created directory {target}"