yycode 0.3.2__py3-none-any.whl

tools/grep.py

@@ -0,0 +1,149 @@
+"""Python grep search tool."""
+
+import re
+from pathlib import Path
+
+from . import read_file
+
+MAX_OUTPUT_CHARS = 50_000
+SKIP_DIRS = {
+    ".git",
+    ".hg",
+    ".mypy_cache",
+    ".pytest_cache",
+    ".ruff_cache",
+    ".venv",
+    "__pycache__",
+    "node_modules",
+}
+
+
+def _iter_files(path: Path):
+    if path.is_file():
+        yield path
+        return
+    for child in path.iterdir():
+        if child.is_dir():
+            if child.name in SKIP_DIRS or child.name.startswith("."):
+                continue
+            yield from _iter_files(child)
+        elif child.is_file():
+            yield child
+
+
+def _read_text(path: Path) -> str | None:
+    try:
+        data = path.read_bytes()
+    except OSError:
+        return None
+    if b"\x00" in data:
+        return None
+    try:
+        return data.decode("utf-8")
+    except UnicodeDecodeError:
+        try:
+            return data.decode("utf-8", errors="replace")
+        except UnicodeDecodeError:
+            return None
+
+
+def _format_match_with_context(
+    relative_path: Path,
+    lines: list[str],
+    line_number: int,
+    before_context: int,
+    after_context: int,
+) -> str:
+    if before_context <= 0 and after_context <= 0:
+        return f"{relative_path}:{line_number}:{lines[line_number - 1]}"
+
+    start = max(line_number - before_context, 1)
+    end = min(line_number + after_context, len(lines))
+    section = [f"{relative_path}:{line_number}:"]
+    for current in range(start, end + 1):
+        marker = ">" if current == line_number else " "
+        section.append(f"{marker} {current}: {lines[current - 1]}")
+    return "\n".join(section)
+
+
+def grep(
+    pattern: str,
+    path: str = ".",
+    max_results: int = 100,
+    before_context: int = 0,
+    after_context: int = 0,
+    workdir: Path | str | None = None,
+) -> str:
+    """Search workspace files using Python regex matching."""
+    try:
+        workspace = read_file.workspace_for(workdir)
+        search_path = workspace.safe_path(path)
+        max_results = max(1, min(int(max_results), 500))
+        before_context = max(0, min(int(before_context), 20))
+        after_context = max(0, min(int(after_context), 20))
+        regex = re.compile(pattern)
+        matches = []
+        for file_path in _iter_files(search_path):
+            text = _read_text(file_path)
+            if text is None:
+                continue
+            relative_path = file_path.relative_to(workspace.root)
+            lines = text.splitlines()
+            for line_number, line in enumerate(lines, start=1):
+                if regex.search(line):
+                    matches.append(
+                        _format_match_with_context(
+                            relative_path,
+                            lines,
+                            line_number,
+                            before_context,
+                            after_context,
+                        )
+                    )
+                    if len(matches) >= max_results:
+                        output = "\n\n".join(matches)
+                        return output[:MAX_OUTPUT_CHARS]
+
+        output = "\n\n".join(matches)
+        return output[:MAX_OUTPUT_CHARS] if output else "No matches found."
+    except re.error as exc:
+        return f"Error: invalid regex pattern: {exc}"
+    except Exception as exc:
+        return f"Error: {exc}"
+
+
+grep_tool = {
+    "name": "grep",
+    "description": "A Python-powered grep tool for searching workspace files with regular expressions.",
+    "execution": {
+        "side_effects": "read_only",
+        "concurrency": "safe",
+        "timeout_seconds": 30,
+    },
+    "input_schema": {
+        "type": "object",
+        "properties": {
+            "pattern": {
+                "type": "string",
+                "description": "Python regular expression pattern.",
+            },
+            "path": {
+                "type": "string",
+                "description": "Workspace-relative path to search. Defaults to current workspace.",
+            },
+            "max_results": {
+                "type": "integer",
+                "description": "Maximum matches per file, capped at 500. Defaults to 100.",
+            },
+            "before_context": {
+                "type": "integer",
+                "description": "Number of lines to include before each match, capped at 20.",
+            },
+            "after_context": {
+                "type": "integer",
+                "description": "Number of lines to include after each match, capped at 20.",
+            },
+        },
+        "required": ["pattern"],
+    },
+}

tools/list_files.py

@@ -0,0 +1,90 @@
+"""List workspace files without shelling out."""
+
+import fnmatch
+from pathlib import Path
+
+from . import read_file
+
+MAX_RESULTS = 500
+SKIP_DIRS = {
+    ".git",
+    ".hg",
+    ".mypy_cache",
+    ".pytest_cache",
+    ".ruff_cache",
+    ".venv",
+    "__pycache__",
+    "node_modules",
+}
+
+
+def _iter_files(path: Path, max_depth: int | None, depth: int = 0):
+    if path.is_file():
+        yield path
+        return
+    if max_depth is not None and depth > max_depth:
+        return
+    for child in sorted(path.iterdir(), key=lambda item: (not item.is_dir(), item.name.lower())):
+        if child.is_dir():
+            if child.name in SKIP_DIRS or child.name.startswith("."):
+                continue
+            yield from _iter_files(child, max_depth, depth + 1)
+        elif child.is_file():
+            yield child
+
+
+def list_files(
+    path: str = ".",
+    pattern: str = "*",
+    max_results: int = 200,
+    max_depth: int | None = None,
+    workdir: Path | str | None = None,
+) -> str:
+    """List workspace-relative files, optionally filtered by glob pattern."""
+    try:
+        workspace = read_file.workspace_for(workdir)
+        root = workspace.safe_path(path)
+        max_results = max(1, min(int(max_results), MAX_RESULTS))
+        files = []
+        for file_path in _iter_files(root, max_depth):
+            relative_path = str(file_path.relative_to(workspace.root))
+            if fnmatch.fnmatch(relative_path, pattern) or fnmatch.fnmatch(file_path.name, pattern):
+                files.append(relative_path)
+                if len(files) >= max_results:
+                    break
+        return "\n".join(files) if files else "No files found."
+    except Exception as exc:
+        return f"Error: {exc}"
+
+
+list_files_tool = {
+    "name": "list_files",
+    "description": "List workspace files using Python glob matching without running shell commands.",
+    "execution": {
+        "side_effects": "read_only",
+        "concurrency": "safe",
+        "timeout_seconds": 30,
+    },
+    "input_schema": {
+        "type": "object",
+        "properties": {
+            "path": {
+                "type": "string",
+                "description": "Workspace-relative directory or file path. Defaults to current workspace.",
+            },
+            "pattern": {
+                "type": "string",
+                "description": "Glob pattern matched against relative paths or file names. Defaults to *.",
+            },
+            "max_results": {
+                "type": "integer",
+                "description": "Maximum number of files to return, capped at 500. Defaults to 200.",
+            },
+            "max_depth": {
+                "type": "integer",
+                "description": "Optional maximum directory depth from the requested path.",
+            },
+        },
+        "required": [],
+    },
+}

tools/list_skills.py

@@ -0,0 +1,24 @@
+"""List skills tool - tool definition only."""
+
+list_skills_tool = {
+    "name": "list_skills",
+    "description": (
+        "List available local skills with their names and descriptions. "
+        "Use this before loading a skill when you are unsure what exists."
+    ),
+    "execution": {
+        "side_effects": "read_only",
+        "concurrency": "safe",
+        "timeout_seconds": 30,
+    },
+    "input_schema": {
+        "type": "object",
+        "properties": {},
+        "required": [],
+    },
+}
+
+
+def list_skills() -> str:
+    """Dummy list_skills handler - should be bound by the graph at runtime."""
+    raise RuntimeError("list_skills tool handler should be created by SkillRegistry")

tools/load_skill.py

@@ -0,0 +1,30 @@
+"""Load skill tool - tool definition only."""
+
+load_skill_tool = {
+    "name": "load_skill",
+    "description": (
+        "Load the full content of one or more local skills by name or path. "
+        "Use this after list_skills when you need the full instructions."
+    ),
+    "execution": {
+        "side_effects": "read_only",
+        "concurrency": "safe",
+        "timeout_seconds": 30,
+    },
+    "input_schema": {
+        "type": "object",
+        "properties": {
+            "names": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "Skill names or paths to load.",
+            },
+        },
+        "required": ["names"],
+    },
+}
+
+
+def load_skill(names: list[str]) -> str:
+    """Dummy load_skill handler - should be bound by the graph at runtime."""
+    raise RuntimeError("load_skill tool handler should be created by SkillRegistry")

tools/lsp_definition.py

@@ -0,0 +1,27 @@
+"""LSP definition lookup tool."""
+
+from pathlib import Path
+
+from tools.lsp_utils import LSP_TOOL_EXECUTION, format_list, run_lsp_tool
+
+
+async def lsp_definition(path: str, line: int, character: int, workdir: Path | str | None = None) -> str:
+    """Find definitions for a Python symbol position using LSP."""
+    result = await run_lsp_tool(workdir, lambda manager: manager.definition(path, line, character))
+    return result if isinstance(result, str) else format_list("definitions", result)
+
+
+lsp_definition_tool = {
+    "name": "lsp_definition",
+    "description": "Find definition locations for a Python symbol position using LSP. Line and character are zero-based.",
+    "execution": LSP_TOOL_EXECUTION,
+    "input_schema": {
+        "type": "object",
+        "properties": {
+            "path": {"type": "string", "description": "Workspace-relative Python file path."},
+            "line": {"type": "integer", "description": "Zero-based line number."},
+            "character": {"type": "integer", "description": "Zero-based character offset."},
+        },
+        "required": ["path", "line", "character"],
+    },
+}

tools/lsp_diagnostics.py

@@ -0,0 +1,32 @@
+"""LSP diagnostics tool."""
+
+from pathlib import Path
+
+from tools.lsp_utils import LSP_TOOL_EXECUTION, format_list, run_lsp_tool
+
+
+async def lsp_diagnostics(path: str | None = None, workdir: Path | str | None = None) -> str:
+    """Return diagnostics reported by the Python LSP server when available."""
+    result = await run_lsp_tool(workdir, lambda manager: manager.diagnostics(path))
+    if isinstance(result, str):
+        return result
+    if not result:
+        return (
+            "status: unsupported\n"
+            "diagnostics: none\n"
+            "reason: pull diagnostics are not implemented in the current LSP MVP; "
+            "use verify for authoritative validation."
+        )
+    return format_list("diagnostics", result)
+
+
+lsp_diagnostics_tool = {
+    "name": "lsp_diagnostics",
+    "description": "Return Python LSP diagnostics when available. MVP may return no_results for servers without pull diagnostics.",
+    "execution": LSP_TOOL_EXECUTION,
+    "input_schema": {
+        "type": "object",
+        "properties": {"path": {"type": "string", "description": "Optional workspace-relative Python file path."}},
+        "required": [],
+    },
+}

tools/lsp_document_symbols.py

@@ -0,0 +1,23 @@
+"""LSP document symbols tool."""
+
+from pathlib import Path
+
+from tools.lsp_utils import LSP_TOOL_EXECUTION, format_list, run_lsp_tool
+
+
+async def lsp_document_symbols(path: str, workdir: Path | str | None = None) -> str:
+    """List symbols in a Python file using LSP."""
+    result = await run_lsp_tool(workdir, lambda manager: manager.document_symbols(path))
+    return result if isinstance(result, str) else format_list("symbols", result)
+
+
+lsp_document_symbols_tool = {
+    "name": "lsp_document_symbols",
+    "description": "List classes, functions, methods, and variables in a Python file using LSP semantic navigation.",
+    "execution": LSP_TOOL_EXECUTION,
+    "input_schema": {
+        "type": "object",
+        "properties": {"path": {"type": "string", "description": "Workspace-relative Python file path."}},
+        "required": ["path"],
+    },
+}

tools/lsp_hover.py

@@ -0,0 +1,29 @@
+"""LSP hover tool."""
+
+from pathlib import Path
+
+from tools.lsp_utils import LSP_TOOL_EXECUTION, run_lsp_tool
+
+
+async def lsp_hover(path: str, line: int, character: int, workdir: Path | str | None = None) -> str:
+    """Return hover text for a Python symbol position using LSP."""
+    result = await run_lsp_tool(workdir, lambda manager: manager.hover(path, line, character))
+    if isinstance(result, str) and result.startswith(("status:", "Error:")):
+        return result
+    return "hover:\n" + (str(result).strip() or "none")
+
+
+lsp_hover_tool = {
+    "name": "lsp_hover",
+    "description": "Return type/signature/documentation hover text for a Python symbol position using LSP. Line and character are zero-based.",
+    "execution": LSP_TOOL_EXECUTION,
+    "input_schema": {
+        "type": "object",
+        "properties": {
+            "path": {"type": "string", "description": "Workspace-relative Python file path."},
+            "line": {"type": "integer", "description": "Zero-based line number."},
+            "character": {"type": "integer", "description": "Zero-based character offset."},
+        },
+        "required": ["path", "line", "character"],
+    },
+}

tools/lsp_references.py

@@ -0,0 +1,37 @@
+"""LSP references lookup tool."""
+
+from pathlib import Path
+
+from tools.lsp_utils import LSP_TOOL_EXECUTION, format_list, run_lsp_tool
+
+
+async def lsp_references(
+    path: str,
+    line: int,
+    character: int,
+    include_declaration: bool = False,
+    workdir: Path | str | None = None,
+) -> str:
+    """Find references for a Python symbol position using LSP."""
+    result = await run_lsp_tool(
+        workdir,
+        lambda manager: manager.references(path, line, character, include_declaration),
+    )
+    return result if isinstance(result, str) else format_list("references", result)
+
+
+lsp_references_tool = {
+    "name": "lsp_references",
+    "description": "Find reference locations for a Python symbol position using LSP. Line and character are zero-based.",
+    "execution": LSP_TOOL_EXECUTION,
+    "input_schema": {
+        "type": "object",
+        "properties": {
+            "path": {"type": "string", "description": "Workspace-relative Python file path."},
+            "line": {"type": "integer", "description": "Zero-based line number."},
+            "character": {"type": "integer", "description": "Zero-based character offset."},
+            "include_declaration": {"type": "boolean", "description": "Whether to include the declaration location."},
+        },
+        "required": ["path", "line", "character"],
+    },
+}

tools/lsp_utils.py

@@ -0,0 +1,38 @@
+"""Shared helpers for thin LSP tool wrappers."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Awaitable, Callable, TypeVar
+
+from agent.lsp.client import LspClientError
+from agent.lsp.manager import LspUnavailable, get_lsp_manager
+
+T = TypeVar("T")
+
+
+async def run_lsp_tool(workdir: Path | str | None, action: Callable[[object], Awaitable[T]]) -> T | str:
+    """Run an LSP action with model-friendly unavailable/error output."""
+    try:
+        manager = get_lsp_manager(workdir or Path.cwd())
+        return await action(manager)
+    except LspUnavailable as exc:
+        return "status: unavailable\nreason: " + str(exc) + "\nfallback: use grep and read_file for text-based navigation"
+    except (LspClientError, TimeoutError) as exc:
+        return "status: error\nreason: " + str(exc) + "\nfallback: use grep and read_file for text-based navigation"
+    except Exception as exc:
+        return f"Error: {exc}"
+
+
+def format_list(title: str, items: list) -> str:
+    """Format LSP result items that expose format()."""
+    if not items:
+        return f"status: no_results\n{title}: none"
+    return title + ":\n" + "\n".join(f"- {item.format()}" for item in items)
+
+
+LSP_TOOL_EXECUTION = {
+    "side_effects": "read_only",
+    "concurrency": "safe",
+    "timeout_seconds": 30,
+}

tools/lsp_workspace_symbols.py

@@ -0,0 +1,23 @@
+"""LSP workspace symbols tool."""
+
+from pathlib import Path
+
+from tools.lsp_utils import LSP_TOOL_EXECUTION, format_list, run_lsp_tool
+
+
+async def lsp_workspace_symbols(query: str, workdir: Path | str | None = None) -> str:
+    """Search workspace symbols using LSP."""
+    result = await run_lsp_tool(workdir, lambda manager: manager.workspace_symbols(query))
+    return result if isinstance(result, str) else format_list("symbols", result)
+
+
+lsp_workspace_symbols_tool = {
+    "name": "lsp_workspace_symbols",
+    "description": "Search Python workspace symbols by name using LSP semantic navigation.",
+    "execution": LSP_TOOL_EXECUTION,
+    "input_schema": {
+        "type": "object",
+        "properties": {"query": {"type": "string", "description": "Symbol name or query text."}},
+        "required": ["query"],
+    },
+}

tools/read_file.py

@@ -0,0 +1,61 @@
+"""Read file tool."""
+
+from pathlib import Path
+
+from .workspace import Workspace
+
+
+def workspace_for(workdir: Path | str | None = None) -> Workspace:
+    """Return the workspace for a tool call."""
+    return Workspace(Path(workdir) if workdir is not None else Path.cwd())
+
+
+def safe_path(p: str, workdir: Path | str | None = None) -> Path:
+    """Get a safe path within the workspace."""
+    return workspace_for(workdir).safe_path(p)
+
+
+def read_file(
+    path: str,
+    limit: int = None,
+    start_line: int | None = None,
+    end_line: int | None = None,
+    workdir: Path | str | None = None,
+) -> str:
+    """Read file contents."""
+    try:
+        text = safe_path(path, workdir).read_text()
+        lines = text.splitlines()
+        if start_line is not None or end_line is not None:
+            start = max((start_line or 1) - 1, 0)
+            end = max(end_line or len(lines), 0)
+            if end < start + 1:
+                return "Error: end_line must be greater than or equal to start_line"
+            selected = lines[start:end]
+            return "\n".join(selected)[:50000]
+        if limit and limit < len(lines):
+            lines = lines[:limit] + [f"... ({len(lines) - limit} more lines)"]
+        return "\n".join(lines)[:50000]
+    except Exception as e:
+        return f"Error: {e}"
+
+
+read_file_tool = {
+    "name": "read_file",
+    "description": "Read file contents.",
+    "execution": {
+        "side_effects": "read_only",
+        "concurrency": "safe",
+        "timeout_seconds": 30,
+    },
+    "input_schema": {
+        "type": "object",
+        "properties": {
+            "path": {"type": "string"},
+            "limit": {"type": "integer"},
+            "start_line": {"type": "integer"},
+            "end_line": {"type": "integer"},
+        },
+        "required": ["path"],
+    },
+}

tools/read_many_files.py

@@ -0,0 +1,50 @@
+"""Read multiple workspace files in one tool call."""
+
+from .read_file import read_file
+
+from pathlib import Path
+
+MAX_FILES = 20
+MAX_OUTPUT_CHARS = 80_000
+
+
+def read_many_files(paths: list[str], limit: int | None = None, workdir: Path | str | None = None) -> str:
+    """Read several files and separate each result with a header."""
+    try:
+        if not paths:
+            return "Error: paths is required"
+        selected_paths = paths[:MAX_FILES]
+        sections = []
+        for path in selected_paths:
+            sections.append(f"--- {path} ---\n{read_file(path, limit=limit, workdir=workdir)}")
+        if len(paths) > MAX_FILES:
+            sections.append(f"... skipped {len(paths) - MAX_FILES} file(s); max is {MAX_FILES}")
+        return "\n\n".join(sections)[:MAX_OUTPUT_CHARS]
+    except Exception as exc:
+        return f"Error: {exc}"
+
+
+read_many_files_tool = {
+    "name": "read_many_files",
+    "description": "Read multiple workspace files at once with per-file headers.",
+    "execution": {
+        "side_effects": "read_only",
+        "concurrency": "safe",
+        "timeout_seconds": 30,
+    },
+    "input_schema": {
+        "type": "object",
+        "properties": {
+            "paths": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "Workspace-relative file paths to read, capped at 20.",
+            },
+            "limit": {
+                "type": "integer",
+                "description": "Optional maximum number of lines per file.",
+            },
+        },
+        "required": ["paths"],
+    },
+}

tools/safety.py

@@ -0,0 +1,50 @@
+"""Safety helpers for tools that need approval-style blocking."""
+
+import re
+
+
+class ApprovalRequired(Exception):
+    """Raised when an action should be blocked until user approval exists."""
+
+
+def approval_required(action: str, reason: str, risk: str, command: str = "", path: str = "") -> str:
+    """Format a stable approval_required response for tools."""
+    lines = [
+        "approval_required:",
+        f"action: {action}",
+    ]
+    if command:
+        lines.append(f"command: {command}")
+    if path:
+        lines.append(f"path: {path}")
+    lines.extend(
+        [
+            f"reason: {reason}",
+            f"risk: {risk}",
+        ]
+    )
+    return "\n".join(lines)
+
+
+DANGEROUS_COMMAND_PATTERNS = [
+    (r"\bsudo\b", "privileged_command", "sudo can run commands with elevated privileges."),
+    (r"\brm\s+.*(-r|-f|--recursive|--force)", "destructive_delete", "recursive or forced deletion can remove user work."),
+    (r"\bgit\s+reset\b", "destructive_git", "git reset can discard commits or local changes."),
+    (r"\bgit\s+checkout\b", "destructive_git", "git checkout can overwrite working tree files."),
+    (r"\bgit\s+clean\b", "destructive_git", "git clean deletes untracked files."),
+    (r"\bchmod\b|\bchown\b", "permission_change", "permission changes can break the workspace or expose files."),
+    (r">\s*/dev/", "device_write", "writing to device paths can damage the system."),
+]
+
+
+def unsafe_command_response(command: str) -> str | None:
+    """Return an approval_required message if command matches high-risk patterns."""
+    for pattern, action, reason in DANGEROUS_COMMAND_PATTERNS:
+        if re.search(pattern, command):
+            return approval_required(
+                action=action,
+                command=command,
+                reason=reason,
+                risk="This operation may be destructive or affect files outside the intended task.",
+            )
+    return None