python-agent-harness 1.5.0__py3-none-any.whl

python_agent_harness/tools/grep.py

@@ -0,0 +1,149 @@
+"""Grep tool: git grep, then rg, then plain grep.
+
+Grep mirrors `gptel-agent-harness-tools--grep`: git grep (passing the
+regex via `-e`), then rg, then plain grep.  Oversized results are
+spilled to a temp file (see `filesystem._spool`), so no matches are
+ever silently lost.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+
+from .base import Tool, ToolContext
+from .filesystem import _git_root, _spool
+
+
+class Grep(Tool):
+    name = "Grep"
+    description = (
+        "Search file contents with a regular expression. "
+        "Use this for content search; use Glob for filename search. "
+        "Oversized results are spilled to a temp file (see the 'Stored in:' "
+        "path); use Read to view the full output."
+    )
+    parameters = {
+        "type": "object",
+        "properties": {
+            "regex": {"type": "string", "description": "Regular expression to search for"},
+            "path": {"type": "string", "description": "File or directory to search in"},
+            "glob": {"type": "string", "description": "Optional file pattern filter (e.g. *.py)"},
+            "context_lines": {
+                "type": "integer",
+                "description": "Lines of context (0-15)",
+                "maximum": 15,
+            },
+        },
+        "required": ["regex", "path"],
+    }
+
+    def run(self, args: dict, ctx: ToolContext) -> str:
+        regex = args["regex"]
+        path = os.path.abspath(args["path"])
+        if not os.path.isdir(path) and not os.path.isfile(path):
+            return f"Error: path {args['path']} is not readable"
+        glob = args.get("glob")
+        context = args.get("context_lines")
+        if context is not None:
+            context = max(0, min(15, int(context)))
+
+        git_root = _git_root(path) if os.path.isdir(path) else None
+        if git_root:
+            rel = os.path.relpath(path, git_root)
+            pathspec = rel
+            if glob and os.path.isdir(path):
+                pathspec = os.path.join(rel, glob).replace(os.sep, "/")
+            cmd = [
+                "git",
+                "grep",
+                "--line-number",
+                "--no-color",
+                "--max-count=1000",
+                "--untracked",
+                "-P",
+                "-e",
+                regex,
+                "--",
+                pathspec,
+            ]
+            if context:
+                cmd = cmd[:3] + [f"-C{context}"] + cmd[3:]
+            try:
+                proc = subprocess.run(
+                    cmd,
+                    cwd=git_root,
+                    capture_output=True,
+                    text=True,
+                    encoding="utf-8",
+                    errors="replace",
+                    timeout=60,
+                )
+            except (OSError, subprocess.TimeoutExpired):
+                proc = None
+            if proc is not None and proc.returncode in (0, 1):
+                return _grep_out(proc, "git")
+        if shutil.which("rg"):
+            cmd = [
+                "rg",
+                "--sort=modified",
+                "--max-count=1000",
+                "--heading",
+                "--line-number",
+                "-e",
+                regex,
+                path,
+            ]
+            if context:
+                cmd = cmd[:1] + [f"--context={context}"] + cmd[1:]
+            if glob:
+                cmd = cmd[:1] + [f"--glob={glob}"] + cmd[1:]
+            try:
+                proc = subprocess.run(
+                    cmd,
+                    capture_output=True,
+                    text=True,
+                    encoding="utf-8",
+                    errors="replace",
+                    timeout=60,
+                )
+            except (OSError, subprocess.TimeoutExpired):
+                proc = None
+            if proc is not None and proc.returncode in (0, 1):
+                return _grep_out(proc, "rg")
+        if shutil.which("grep"):
+            cmd = [
+                "grep",
+                "--recursive",
+                "--max-count=1000",
+                "--line-number",
+                "--regexp",
+                regex,
+                path,
+            ]
+            if context:
+                cmd = cmd[:1] + [f"--context={context}"] + cmd[1:]
+            if glob:
+                cmd = cmd[:1] + [f"--include={glob}"] + cmd[1:]
+            try:
+                proc = subprocess.run(
+                    cmd,
+                    capture_output=True,
+                    text=True,
+                    encoding="utf-8",
+                    errors="replace",
+                    timeout=60,
+                )
+            except (OSError, subprocess.TimeoutExpired):
+                proc = None
+            if proc is not None:
+                return _grep_out(proc, "grep")
+        return "Error: ripgrep/grep/git-grep not available, this tool cannot be used"
+
+
+def _grep_out(proc: subprocess.CompletedProcess, backend: str) -> str:
+    text = proc.stdout
+    if proc.returncode >= 2:
+        text = f"Error: search failed with exit-code {proc.returncode}.  Tool output:\n\n{text}"
+    return _spool(text, "grep")

python_agent_harness/tools/insert.py

@@ -0,0 +1,61 @@
+"""Insert tool: insert text at a line number in an existing file.
+
+Records a unified diff for the TUI so the change is visible in the
+conversation panel like any other file edit.
+"""
+
+from __future__ import annotations
+
+import os
+
+from ..diffrender import unified_diff
+from .base import Tool, ToolContext
+
+
+class Insert(Tool):
+    name = "Insert"
+    description = (
+        "Insert text at a specific line number in an existing file. "
+        "line_number 0 = beginning, -1 = end."
+    )
+    parameters = {
+        "type": "object",
+        "properties": {
+            "path": {"type": "string", "description": "File path"},
+            "line_number": {
+                "type": "integer",
+                "description": "Line after which to insert (0=start, -1=end)",
+            },
+            "new_str": {"type": "string", "description": "Text to insert"},
+        },
+        "required": ["path", "line_number", "new_str"],
+    }
+
+    def run(self, args: dict, ctx: ToolContext) -> str:
+        path = os.path.realpath(os.path.abspath(args["path"]))
+        try:
+            with open(path, encoding="utf-8") as f:
+                old_content = f.read()
+                lines = old_content.splitlines(keepends=True)
+        except OSError as e:
+            return f"Error: cannot read {path}: {e}"
+        ln = int(args["line_number"])
+        new_str = args["new_str"]
+        if not new_str.endswith("\n"):
+            new_str += "\n"
+        if ln == -1 or ln >= len(lines):
+            lines.append(new_str)
+        elif ln == 0:
+            lines.insert(0, new_str)
+        else:
+            lines.insert(ln, new_str)
+        new_content = "".join(lines)
+        try:
+            with open(path, "w", encoding="utf-8") as f:
+                f.write(new_content)
+        except OSError as e:
+            return f"Error: {e}"
+        diff_text = unified_diff(old_content, new_content, path)
+        if diff_text:
+            ctx.record_diff(diff_text)
+        return f"Successfully inserted text at line {ln} in {path}"

python_agent_harness/tools/mcp.py

@@ -0,0 +1,203 @@
+"""MCP tool adapter: MCP server tools as normal harness tools.
+
+An MCP server's tools become :class:`Tool` instances named
+``mcp__<server>__<tool>`` (unambiguous namespacing — two servers can
+both expose ``search`` without colliding).  The agent loop never sees
+MCP: these tools go through the same ToolRegistry as built-ins, so the
+agent's existing retry / supervision / sanitization machinery applies
+unchanged.
+
+Results are normalized to the harness's string tool-result form
+(:func:`normalize_mcp_result`), and every MCP failure surfaces as a
+plain ``Error: ...`` string — never an SDK exception — so the agent
+sees::
+
+    Tool mcp__github__search failed: connection refused
+
+Concurrency mirrors the harness policy: servers configured with
+``parallel = true`` run their tools in the background (a
+``PendingToolResult``, like Bash/Agent); the default is conservative
+serial execution.  The harness, not the MCP protocol, retains authority
+over this.
+"""
+
+from __future__ import annotations
+
+import json
+import threading
+from typing import Any
+
+from ..mcp.manager import MCPManager, MCPToolSpec
+from .base import PendingToolResult, Tool, ToolContext
+
+MCP_PREFIX = "mcp__"
+
+
+def mcp_tool_name(server: str, tool: str) -> str:
+    """The namespaced harness name for an MCP tool."""
+    return f"{MCP_PREFIX}{server}__{tool}"
+
+
+def normalize_mcp_result(result: dict[str, Any]) -> str:
+    """MCP CallToolResult (plain dict) → harness tool-result string.
+
+    Maps the MCP content blocks onto the harness's single-string tool
+    result: text blocks become text; image/audio/resource blocks become
+    readable placeholders (the payload is base64 and must not flood the
+    context); structured content is JSON-serialized.  A server-reported
+    error becomes an ``Error: ...`` string.
+    """
+    if result.get("is_error"):
+        text = _render_content(result)
+        return (
+            f"Error: MCP tool reported an error: {text}"
+            if text
+            else ("Error: MCP tool reported an error")
+        )
+    text = _render_content(result)
+    structured = result.get("structured_content")
+    if structured is not None:
+        rendered = json.dumps(structured, ensure_ascii=False, default=str)
+        text = f"{text}\n{rendered}" if text else rendered
+    return text if text else "(no result)"
+
+
+def _render_content(result: dict[str, Any]) -> str:
+    parts: list[str] = []
+    for block in result.get("content") or []:
+        rendered = _render_block(block) if isinstance(block, dict) else str(block)
+        if rendered:
+            parts.append(rendered)
+    return "\n".join(parts)
+
+
+def _render_block(block: dict[str, Any]) -> str:
+    kind = block.get("type")
+    if kind == "text":
+        return str(block.get("text", ""))
+    if kind == "image":
+        data = block.get("data") or ""
+        return (
+            f"[image omitted: mimeType={block.get('mime_type')}, {len(data)} chars of base64 data]"
+        )
+    if kind == "audio":
+        data = block.get("data") or ""
+        return (
+            f"[audio omitted: mimeType={block.get('mime_type')}, {len(data)} chars of base64 data]"
+        )
+    if kind == "resource":
+        return _render_resource(block)
+    if kind == "embedded_resource":
+        resource = block.get("resource")
+        inner = _render_resource(resource) if isinstance(resource, dict) else str(resource)
+        return f"[embedded resource: {inner}]"
+    return str(block)
+
+
+def _render_resource(resource: dict[str, Any]) -> str:
+    uri = resource.get("uri") or "(no uri)"
+    if resource.get("type") == "text_resource" and resource.get("text"):
+        return f"[resource {uri}]\n{resource['text']}"
+    data = resource.get("data")
+    if data:
+        return (
+            f"[resource {uri} omitted: mimeType={resource.get('mime_type')}, "
+            f"{len(str(data))} chars]"
+        )
+    return f"[resource {uri}]"
+
+
+class MCPTool(Tool):
+    """A tool exposed by an MCP server, namespaced ``mcp__<server>__<tool>``.
+
+    ``run`` executes through the manager: serial by default, or in the
+    background (``PendingToolResult``) when the server is configured
+    with ``parallel = true``.
+    """
+
+    def __init__(
+        self,
+        spec: MCPToolSpec,
+        manager: MCPManager,
+        *,
+        parallel: bool = False,
+        timeout: float | None = None,
+    ) -> None:
+        self.server_name = spec.server
+        self.mcp_name = spec.name
+        self._manager = manager
+        self._parallel = parallel
+        self._timeout = timeout
+        self.name = mcp_tool_name(spec.server, spec.name)
+        self.description = spec.description or f"MCP tool {spec.name} (server {spec.server})"
+        schema = spec.input_schema if isinstance(spec.input_schema, dict) else {}
+        self.parameters = _schema_from_input(schema)
+
+    def run(self, args: dict[str, Any], ctx: ToolContext) -> str | PendingToolResult:
+        if not self._parallel:
+            return self._execute(args, ctx)
+        pending = PendingToolResult()
+        threading.Thread(
+            target=lambda: pending.deliver(self._execute(args, ctx)),
+            daemon=True,
+        ).start()
+        return pending
+
+    def _execute(self, args: dict[str, Any], ctx: ToolContext | None) -> str:
+        # The session's cancel event is polled by the manager while the
+        # SDK call is in flight, so Ctrl-C unblocks a hung server call
+        # instead of wedging the loop thread (serial) or the background
+        # worker (parallel).
+        cancel_check = None
+        if ctx is not None:
+            event = ctx.cancel_event
+            if event is not None and hasattr(event, "is_set"):
+                cancel_check = event.is_set
+        try:
+            result = self._manager.call_tool(
+                self.server_name,
+                self.mcp_name,
+                args or {},
+                timeout=self._timeout,
+                cancel_check=cancel_check,
+            )
+        except Exception as e:  # noqa: BLE001 - errors become tool results
+            return f"Error: tool {self.name} failed — {e}"
+        return normalize_mcp_result(result)
+
+
+def _schema_from_input(schema: dict[str, Any]) -> dict[str, Any]:
+    """MCP input schema → harness JSON-schema parameters.
+
+    The schema is passed through as-is (it already is a JSON object
+    schema); only the container is normalized so a schema without
+    ``properties``/``required`` still serializes cleanly.
+    """
+    parameters: dict[str, Any] = {"type": "object"}
+    properties = schema.get("properties")
+    if isinstance(properties, dict):
+        parameters["properties"] = properties
+    required = schema.get("required")
+    if isinstance(required, list) and required:
+        parameters["required"] = [str(r) for r in required]
+    return parameters
+
+
+def mcp_tools_from_manager(manager: MCPManager) -> list[MCPTool]:
+    """Build harness tools for every tool discovered by MANAGER.
+
+    Concurrency flags come from the server config (``parallel``); a
+    per-server timeout is applied to every call when configured.
+    """
+    tools: list[MCPTool] = []
+    for spec in manager.tool_specs():
+        server_config = manager.config.servers.get(spec.server)
+        tools.append(
+            MCPTool(
+                spec,
+                manager,
+                parallel=bool(server_config and server_config.parallel),
+                timeout=server_config.timeout if server_config else None,
+            )
+        )
+    return tools

python_agent_harness/tools/mkdir.py

@@ -0,0 +1,30 @@
+"""Mkdir tool: create a directory (including parents)."""
+
+from __future__ import annotations
+
+import os
+
+from .base import Tool, ToolContext
+
+
+class Mkdir(Tool):
+    name = "Mkdir"
+    description = "Create a new directory (including parents)."
+    parameters = {
+        "type": "object",
+        "properties": {
+            "parent": {"type": "string", "description": "Parent directory"},
+            "name": {"type": "string", "description": "Directory name to create"},
+        },
+        "required": ["parent", "name"],
+    }
+
+    def run(self, args: dict, ctx: ToolContext) -> str:
+        parent = args["parent"]
+        name = args["name"]
+        path = os.path.realpath(os.path.abspath(os.path.join(parent, name)))
+        try:
+            os.makedirs(path, exist_ok=True)
+            return f"Directory {name} created/verified in {parent}"
+        except OSError as e:
+            return f"Error: {e}"

python_agent_harness/tools/planexit.py

@@ -0,0 +1,45 @@
+"""PlanExit tool: ask the user to approve switching from plan to build.
+
+Synchronous (mirrors gptel's PlanExit tool, which is NOT ``:async t``):
+``run`` blocks until the user answers and returns the outcome as a
+plain string — it executes one at a time, in call order, like every
+other non-Bash/non-Agent tool.
+"""
+
+from __future__ import annotations
+
+from .base import Tool, ToolContext
+
+DESCRIPTION = (
+    "Use this tool when you have completed the planning phase and are "
+    "ready to exit plan mode.\n\n"
+    "This tool will ask the user whether they want to switch to the build "
+    "agent and start implementing the plan. Do NOT use the Question tool "
+    'to ask "Is this plan okay?" — that is what this tool is for.\n\n'
+    "Call this tool:\n"
+    "- After you have written a complete plan to the plan file\n"
+    "- After you have clarified any questions with the user\n"
+    "- When you are confident the plan is ready for implementation\n\n"
+    "Do NOT call this tool:\n"
+    "- Before you have created or finalized the plan\n"
+    "- If you still have unanswered questions about the implementation\n"
+    "- If the user has indicated they want to continue planning\n\n"
+    "On approval, the session switches to build mode (file edits become "
+    "allowed) and you should proceed to execute the approved plan. On "
+    "rejection, you remain in the read-only plan phase and should continue "
+    "refining the plan."
+)
+
+
+class PlanExit(Tool):
+    name = "PlanExit"
+    description = DESCRIPTION
+    parameters = {"type": "object", "properties": {}}
+
+    def run(self, args: dict, ctx: ToolContext) -> str:
+        # containment boundary: a failure in the approval prompt
+        # becomes an error string for the model, never a crash
+        try:
+            return ctx.plan_exit()
+        except Exception as e:  # noqa: BLE001 - error string for the model
+            return f"Error: PlanExit failed — {e}"

python_agent_harness/tools/question.py

@@ -0,0 +1,70 @@
+"""Question tool: ask the user one or more questions during execution.
+
+Synchronous (mirrors gptel's Question tool, which is NOT ``:async t``):
+``run`` blocks until the user answers and returns the answers as a
+plain string — it executes one at a time, in call order, like every
+other non-Bash/non-Agent tool.
+"""
+
+from __future__ import annotations
+
+from .base import Tool, ToolContext
+
+DESCRIPTION = (
+    "Ask the user one or more questions during execution.\n\n"
+    "Use this tool when you need to:\n"
+    "1. Gather user preferences or requirements\n"
+    "2. Clarify ambiguous instructions\n"
+    "3. Get decisions on implementation choices as you work\n"
+    "4. Offer choices to the user about what direction to take\n\n"
+    "Each question can have predefined options for the user to select from. "
+    'By default, a "Type your own answer" option is added; set custom to '
+    "false to disable it. Set multiple to true to allow selecting more than "
+    "one option.\n\n"
+    "If no options are provided, the user will be prompted for free-text "
+    "input.\n\n"
+    "If you recommend a specific option, make that the first option in the "
+    'list and add "(Recommended)" at the end of the label.'
+)
+
+PARAMETERS = {
+    "type": "object",
+    "properties": {
+        "questions": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "properties": {
+                    "question": {"type": "string"},
+                    "options": {"type": "array", "items": {"type": "string"}},
+                    "multiple": {"type": "boolean"},
+                    "custom": {"type": "boolean"},
+                },
+                "required": ["question"],
+            },
+        }
+    },
+    "required": ["questions"],
+}
+
+
+class Question(Tool):
+    name = "Question"
+    description = DESCRIPTION
+    parameters = PARAMETERS
+
+    def run(self, args: dict, ctx: ToolContext) -> str:
+        raw = args.get("questions")
+        if isinstance(raw, list):
+            questions = raw
+        elif isinstance(raw, dict) and isinstance(raw.get("questions"), list):
+            questions = raw["questions"]
+        else:
+            return "Error: questions must be an array"
+
+        # containment boundary: a failure in the interactive prompt
+        # becomes an error string for the model, never a crash
+        try:
+            return ctx.ask_questions(questions)
+        except Exception as e:  # noqa: BLE001 - error string for the model
+            return f"Error: Question failed — {e}"

python_agent_harness/tools/read.py

@@ -0,0 +1,104 @@
+"""Read tool: whole-file reads with a size limit, streamed line ranges.
+
+Read mirrors `gptel-agent--read-file-lines`: whole-file reads are
+refused above READ_SIZE_LIMIT (400 KB, matching
+`gptel-agent-read-file-size-threshold`), and line ranges are streamed
+instead of loading the whole file into memory.  Oversized range
+results are spilled to a temp file like Glob/Grep results, so nothing
+is ever silently truncated.
+"""
+
+from __future__ import annotations
+
+import os
+
+from .base import Tool, ToolContext
+from .filesystem import READ_SIZE_LIMIT, _spool
+
+
+class Read(Tool):
+    name = "Read"
+    description = (
+        "Read file contents between specified line numbers `start_line` and "
+        "`end_line`, with both ends included.\n\n"
+        'Consider using the "Grep" tool to find the right range to read first.\n\n'
+        "Reads the whole file if the line range is not provided.\n\n"
+        f"Files over {READ_SIZE_LIMIT // 1024} KB in size can only be read by "
+        "specifying a line range.\n"
+        "Very large line ranges are spilled to a temp file (see the 'Stored "
+        "in:' path); use Read to view the full output."
+    )
+    parameters = {
+        "type": "object",
+        "properties": {
+            "file_path": {"type": "string", "description": "The path to the file to be read"},
+            "start_line": {
+                "type": "integer",
+                "description": "The line to start reading from, defaults to the start of the file",
+            },
+            "end_line": {
+                "type": "integer",
+                "description": "The line up to which to read, defaults to the end of the file.",
+            },
+        },
+        "required": ["file_path"],
+    }
+
+    def run(self, args: dict, ctx: ToolContext) -> str:
+        path = args["file_path"]
+        full = os.path.realpath(os.path.abspath(path))
+        if os.path.isdir(full):
+            return f"Error: cannot read {path}: is a directory"
+        try:
+            size = os.path.getsize(full)
+        except OSError as e:
+            return f"Error: cannot read {path}: {e}"
+        start = args.get("start_line")
+        end = args.get("end_line")
+        if start is None and end is None:
+            if size > READ_SIZE_LIMIT:
+                return (
+                    f"Error: File is too large ({size // 1024} KB > "
+                    f"{READ_SIZE_LIMIT // 1024} KB). Please specify a line "
+                    "range to read"
+                )
+            try:
+                with open(full, encoding="utf-8", errors="replace") as f:
+                    return f.read()
+            except OSError as e:
+                return f"Error: cannot read {path}: {e}"
+        start = int(start or 1)
+        if start < 1:
+            start = 1
+        if end is not None:
+            end = int(end)
+            if start > end:
+                return f"Error: start_line {start} > end_line {end}"
+        # Stream the file line by line instead of loading it whole, so
+        # huge files can be read in ranges with constant memory.
+        selected: list[str] = []
+        total: int | None = None  # exact line count once EOF is reached
+        reached_eof = True
+        try:
+            with open(full, encoding="utf-8", errors="replace") as f:
+                for lineno, line in enumerate(f, 1):
+                    if end is not None and lineno > end:
+                        reached_eof = False
+                        break
+                    total = lineno
+                    if lineno >= start:
+                        selected.append(line)
+        except OSError as e:
+            return f"Error: cannot read {path}: {e}"
+        if end is not None and reached_eof and total is not None:
+            end = min(end, total)  # clamp to the real file end
+        if total is None:
+            total = 0  # empty file
+        if start > total:
+            return f"Error: start_line {start} > end_line {end if end is not None else total}"
+        end_eff = end if end is not None else total
+        if total is not None and reached_eof:
+            header = f"Showing lines {start}-{end_eff} of {total}:\n\n"
+        else:
+            header = f"Showing lines {start}-{end_eff}:\n\n"
+        return _spool(header + "".join(selected), "read")