limbo-code 0.1.0__py3-none-any.whl

limbo/skills.py

@@ -0,0 +1,89 @@
+"""Skill support: discover and load SKILL.md skills.
+
+A skill is a directory containing a ``SKILL.md`` file with YAML-ish
+frontmatter (``name``, ``description``) followed by the instruction body —
+the same convention used by Claude Code and pi.
+
+Discovery paths (later sources win on name collisions):
+- user:    ``~/.limbo/skills/<name>/SKILL.md``
+- project: ``<workdir>/.agents/skills/<name>/SKILL.md``
+
+Skills are invoked through slash commands: ``/<name> [args]`` injects the
+skill body (plus args) as the turn's prompt.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+DEFAULT_USER_SKILLS_DIR = Path.home() / ".limbo" / "skills"
+PROJECT_SKILLS_DIR = ".agents/skills"
+
+
+@dataclass(frozen=True)
+class Skill:
+    name: str
+    description: str
+    body: str
+    path: Path
+
+
+def parse_skill_md(text: str, fallback_name: str) -> tuple[str, str, str]:
+    """Parse SKILL.md content into (name, description, body).
+
+    Frontmatter is a simple ``---`` delimited block of ``key: value`` lines.
+    Without frontmatter, the fallback name is used and the whole file is the
+    body.
+    """
+    if text.startswith("---"):
+        end = text.find("\n---", 3)
+        if end != -1:
+            header = text[3:end]
+            body = text[end + 4 :].lstrip("\n")
+            name = fallback_name
+            description = ""
+            for line in header.splitlines():
+                key, sep, value = line.partition(":")
+                if not sep:
+                    continue
+                key = key.strip()
+                value = value.strip()
+                if key == "name" and value:
+                    name = value
+                elif key == "description":
+                    description = value
+            return name, description, body
+    return fallback_name, "", text
+
+
+def _load_skills_from(skills_dir: Path) -> list[Skill]:
+    skills: list[Skill] = []
+    if not skills_dir.is_dir():
+        return skills
+    for path in sorted(skills_dir.glob("*/SKILL.md")):
+        try:
+            text = path.read_text(encoding="utf-8")
+        except OSError:
+            continue
+        name, description, body = parse_skill_md(text, fallback_name=path.parent.name)
+        skills.append(
+            Skill(name=name, description=description, body=body, path=path)
+        )
+    return skills
+
+
+def discover_skills(
+    workdir: Path, user_dir: Path | None = None
+) -> list[Skill]:
+    """Discover skills from the user dir and the project (.agents/skills).
+
+    Project skills override user skills with the same name. Sorted by name.
+    """
+    user_dir = user_dir if user_dir is not None else DEFAULT_USER_SKILLS_DIR
+    by_name: dict[str, Skill] = {}
+    for skill in _load_skills_from(user_dir):
+        by_name[skill.name] = skill
+    for skill in _load_skills_from(workdir / PROJECT_SKILLS_DIR):
+        by_name[skill.name] = skill
+    return [by_name[name] for name in sorted(by_name)]

limbo/tools/__init__.py

@@ -0,0 +1 @@
+"""Limbo tools package."""

limbo/tools/base.py

@@ -0,0 +1,102 @@
+"""Base class and shared helpers for tools.
+
+The base module owns the rituals every tool used to repeat: workdir-safe
+path resolution (raising ``ToolError`` instead of returning union types)
+and the output truncation policy.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Any
+
+from limbo.models import ToolResult
+
+MAX_OUTPUT_BYTES = 512 * 1024
+
+
+class ToolError(Exception):
+    """Raised by tool helpers; ``BaseTool.execute`` turns it into an error result."""
+
+
+class BaseTool(ABC):
+    """Abstract base class for all Limbo tools.
+
+    Subclasses implement ``run``; ``execute`` is the public entry point and
+    converts ``ToolError`` into an error ``ToolResult`` uniformly.
+    """
+
+    name: str
+    description: str
+    parameters: dict[str, Any]
+
+    def __init__(self, workdir: Path):
+        self.workdir = workdir.resolve()
+
+    def execute(self, arguments: dict[str, Any]) -> ToolResult:
+        try:
+            return self.run(arguments)
+        except ToolError as e:
+            return ToolResult(success=False, error=str(e))
+
+    @abstractmethod
+    def run(self, arguments: dict[str, Any]) -> ToolResult:
+        ...
+
+    # -- path resolution -------------------------------------------------------
+
+    def resolve(self, raw_path: str, *, strict: bool = True) -> Path:
+        """Resolve ``raw_path`` under the workdir, enforcing the boundary.
+
+        Raises ``ToolError`` for paths outside the workdir, unresolvable
+        paths, and (when ``strict``) broken symlinks.
+        """
+        raw = self.workdir / raw_path
+        try:
+            target = raw.resolve(strict=False)
+        except (OSError, RuntimeError) as e:
+            raise ToolError(f"Invalid path: {e}") from e
+
+        if not is_within_workdir(target, self.workdir):
+            raise ToolError("Path is outside working directory.")
+
+        if strict and raw.is_symlink() and not target.exists():
+            raise ToolError("Invalid path: broken symlink")
+
+        return target
+
+    def resolve_existing(
+        self, raw_path: str, *, noun: str = "Path", kind: str = "any"
+    ) -> Path:
+        """Resolve a path that must exist. ``kind``: any | file | dir."""
+        target = self.resolve(raw_path)
+        if not target.exists():
+            raise ToolError(f"{noun} not found: {raw_path}")
+        if kind == "file" and not target.is_file():
+            raise ToolError(f"Not a file: {raw_path}")
+        if kind == "dir" and not target.is_dir():
+            raise ToolError(f"Not a directory: {raw_path}")
+        return target
+
+    def resolve_creatable(self, raw_path: str) -> Path:
+        """Resolve a path that may not exist yet (e.g. for writing)."""
+        return self.resolve(raw_path, strict=False)
+
+def is_within_workdir(path: Path, workdir: Path) -> bool:
+    """Return True if resolved path is inside or equal to workdir."""
+    try:
+        path.resolve().relative_to(workdir.resolve())
+        return True
+    except ValueError:
+        return False
+
+
+def truncate_output(
+    output: str, *, limit: int = MAX_OUTPUT_BYTES, suffix: str = "\n[Output truncated.]"
+) -> str:
+    """Truncate ``output`` to ``limit`` bytes (UTF-8 safe) and append ``suffix``."""
+    encoded = output.encode("utf-8", errors="replace")
+    if len(encoded) <= limit:
+        return output
+    return encoded[:limit].decode("utf-8", errors="replace") + suffix

limbo/tools/bash.py

@@ -0,0 +1,172 @@
+"""Execute bash commands tool."""
+
+from __future__ import annotations
+
+import re
+import shlex
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from limbo.config import DEFAULT_DANGEROUS_COMMANDS
+from limbo.models import ToolResult
+from limbo.tools.base import MAX_OUTPUT_BYTES, BaseTool, truncate_output
+
+DEFAULT_TIMEOUT = 30.0
+MAX_TIMEOUT = 300.0
+
+
+class BashTool(BaseTool):
+    name = "bash"
+    description = (
+        "Execute a bash command in the current working directory. Returns stdout and stderr. "
+        "WARNING: bash is not sandboxed and can access files outside the workdir. "
+        "Commands matching dangerous patterns (e.g. rm, git reset --hard) are "
+        "rejected outright. The filter is heuristic only: "
+        "subshells, command substitution, variable indirection, options before the command "
+        "name, and variable assignments before the command name "
+        "(e.g. 'bash -c rm -rf /', '$(rm ...)', 'git -C /foo reset --hard', "
+        "or 'VAR=1 rm -rf /') can bypass it."
+    )
+    parameters = {
+        "type": "object",
+        "properties": {
+            "command": {"type": "string", "description": "Bash command to execute"},
+            "timeout": {
+                "type": "number",
+                "description": "Timeout in seconds (optional, default 30, maximum 300)",
+            },
+        },
+        "required": ["command"],
+    }
+
+    def __init__(self, workdir: Path, dangerous_patterns: list[str] | None = None):
+        super().__init__(workdir)
+        self.dangerous_patterns = dangerous_patterns or list(
+            DEFAULT_DANGEROUS_COMMANDS
+        )
+
+    def run(self, arguments: dict[str, Any]) -> ToolResult:
+        command = arguments.get("command", "")
+        timeout = arguments.get("timeout", DEFAULT_TIMEOUT)
+
+        if not command:
+            return ToolResult(success=False, error="No command provided.")
+
+        if is_dangerous(command, self.dangerous_patterns):
+            return ToolResult(
+                success=False,
+                error=f"Command blocked by safety policy: {command}",
+            )
+
+        # Cap the effective timeout so a huge value cannot block the worker
+        # indefinitely. The cap is documented in the tool schema above.
+        try:
+            requested_timeout = float(timeout)
+        except (TypeError, ValueError):
+            return ToolResult(success=False, error=f"Invalid timeout: {timeout}")
+        effective_timeout = min(requested_timeout, MAX_TIMEOUT)
+
+        shell = shutil.which("bash") or "/bin/bash"
+
+        try:
+            proc = subprocess.run(
+                [shell, "-c", command],
+                capture_output=True,
+                text=True,
+                errors="replace",
+                timeout=effective_timeout,
+                cwd=str(self.workdir),
+            )
+        except subprocess.TimeoutExpired:
+            return ToolResult(
+                success=False,
+                error=f"Command timed out after {effective_timeout}s.",
+            )
+        except Exception as e:  # noqa: BLE001
+            return ToolResult(success=False, error=f"Execution failed: {e}")
+
+        output = proc.stdout
+        if proc.stderr:
+            output += ("\n" if output else "") + f"[stderr]\n{proc.stderr}"
+
+        output = truncate_output(
+            output,
+            suffix=(
+                f"\n\n[output truncated: exceeded {MAX_OUTPUT_BYTES} byte limit]"
+            ),
+        )
+
+        if proc.returncode != 0:
+            exit_msg = f"Command failed with exit code {proc.returncode}."
+            output = f"{exit_msg}\n{output}" if output else exit_msg
+            return ToolResult(
+                success=False,
+                output=output,
+                error=exit_msg,
+            )
+
+        return ToolResult(success=True, output=output or "")
+
+
+_CONTROL_OPERATOR_RE = re.compile(r"(;|&&|&|\|\||\|)")
+
+
+def _tokenize_command(command: str) -> list[str]:
+    """Split a command into tokens, treating shell control operators as separate tokens."""
+    raw_tokens = shlex.split(command)
+    tokens: list[str] = []
+    for raw in raw_tokens:
+        for part in _CONTROL_OPERATOR_RE.split(raw):
+            if part:
+                tokens.append(part)
+    return tokens
+
+
+def is_dangerous(command: str, patterns: list[str]) -> bool:
+    """Return True if command matches a dangerous pattern.
+
+    Single-token patterns are matched only in command-name positions: the first
+    token of the command or the first token after a shell control operator
+    (``;``, ``&&``, ``&``, ``||``, ``|``). Multi-token patterns are matched
+    against the leading tokens starting at each command position.
+
+    .. warning::
+        This check is heuristic only. It tokenizes the top-level command, so
+        subshells (``bash -c ...``), command substitution (``$(rm ...)``),
+        variable indirection, variable assignments before a command name
+        (``VAR=1 rm -rf /``), and options between the command name and the
+        matched tokens (``git -C /foo reset --hard``) can bypass it.
+    """
+    tokens = _tokenize_command(command)
+    control_operators = {";", "&&", "&", "||", "|"}
+    command_starts = [0]
+    for i in range(1, len(tokens)):
+        if tokens[i - 1] in control_operators:
+            command_starts.append(i)
+
+    for pattern in patterns:
+        if not pattern:
+            continue
+        pattern_tokens = _tokenize_command(pattern)
+        for start in command_starts:
+            if start >= len(tokens):
+                continue
+            if len(pattern_tokens) == 1:
+                name = pattern_tokens[0]
+                token = tokens[start]
+                if token == name or Path(token).name == name:
+                    return True
+            else:
+                first_pattern = pattern_tokens[0]
+                first_token = tokens[start]
+                first_matches = (
+                    first_token == first_pattern
+                    or Path(first_token).name == Path(first_pattern).name
+                )
+                if first_matches and tokens[
+                    start + 1 : start + len(pattern_tokens)
+                ] == pattern_tokens[1:]:
+                    return True
+    return False

limbo/tools/edit.py

@@ -0,0 +1,70 @@
+"""Surgical file edit tool."""
+
+from __future__ import annotations
+
+import difflib
+from typing import Any
+
+from limbo.models import ToolResult
+from limbo.tools.base import BaseTool
+
+
+class EditTool(BaseTool):
+    name = "edit"
+    description = (
+        "Make surgical edits to a file by replacing exact text. old_text must match exactly. "
+        "The displayed diff may not clearly indicate trailing-newline changes."
+    )
+    parameters = {
+        "type": "object",
+        "properties": {
+            "path": {"type": "string", "description": "Path to the file"},
+            "old_text": {
+                "type": "string",
+                "description": "Exact text to find and replace",
+            },
+            "new_text": {
+                "type": "string",
+                "description": "New text to replace with",
+            },
+        },
+        "required": ["path", "old_text", "new_text"],
+    }
+
+    def run(self, arguments: dict[str, Any]) -> ToolResult:
+        raw_path = arguments.get("path", "")
+        old_text = arguments.get("old_text", "")
+        new_text = arguments.get("new_text", "")
+        target = self.resolve_existing(raw_path, noun="File")
+
+        try:
+            content = target.read_text(encoding="utf-8")
+        except OSError as e:
+            return ToolResult(success=False, error=f"Could not read file: {e}")
+
+        if old_text == "":
+            return ToolResult(success=False, error="old_text cannot be empty.")
+
+        occurrences = content.count(old_text)
+        if occurrences == 0:
+            return ToolResult(success=False, error=f"old_text not found in {raw_path}.")
+        if occurrences > 1:
+            return ToolResult(success=False, error=f"Text must be unique in {raw_path}.")
+
+        new_content = content.replace(old_text, new_text, 1)
+        if new_content == content:
+            return ToolResult(success=False, error=f"No changes to {raw_path}.")
+
+        diff = self._make_diff(content, new_content)
+
+        try:
+            target.write_text(new_content, encoding="utf-8")
+        except OSError as e:
+            return ToolResult(success=False, error=f"Could not write file: {e}")
+
+        return ToolResult(success=True, output=f"Edited {raw_path}.\n{diff}")
+
+    def _make_diff(self, old: str, new: str) -> str:
+        return "".join(
+            difflib.unified_diff(old.splitlines(), new.splitlines(), lineterm="\n")
+        )

limbo/tools/find.py

@@ -0,0 +1,71 @@
+"""Find files by glob pattern tool."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from limbo.models import ToolResult
+from limbo.tools.base import (
+    BaseTool,
+    is_within_workdir,
+    truncate_output,
+)
+from limbo.tools.ignore import GitignoreMatcher
+
+MAX_RESULTS = 1000
+
+
+class FindTool(BaseTool):
+    name = "find"
+    description = (
+        "Find files by glob pattern. Respects the root .gitignore only. "
+        "The built-in matcher is minimal and does not support nested .gitignore "
+        "files or advanced glob/negation rules."
+    )
+    parameters = {
+        "type": "object",
+        "properties": {
+            "pattern": {"type": "string", "description": "Glob pattern"},
+            "path": {"type": "string", "description": "Directory to search"},
+            "limit": {"type": "integer", "description": "Max results"},
+        },
+        "required": ["pattern"],
+    }
+
+    def run(self, arguments: dict[str, Any]) -> ToolResult:
+        pattern = arguments.get("pattern", "")
+        path = arguments.get("path", ".")
+        limit = arguments.get("limit", MAX_RESULTS)
+
+        target = self.resolve_existing(path)
+
+        try:
+            # ``glob`` may traverse directory symlinks before we can filter them;
+            # we resolve and enforce the workdir boundary below.
+            matches = sorted(target.glob(pattern))
+        except ValueError as e:
+            return ToolResult(success=False, error=f"Invalid glob pattern: {e}")
+
+        matcher = GitignoreMatcher(self.workdir)
+
+        results = []
+        for p in matches:
+            try:
+                resolved = p.resolve()
+            except OSError:
+                continue
+            if not resolved.is_file():
+                continue
+            if not is_within_workdir(resolved, self.workdir):
+                continue
+            rel = str(p.relative_to(self.workdir))
+            if matcher.is_ignored(rel):
+                continue
+            results.append(rel)
+            if len(results) >= limit:
+                break
+
+        output = "\n".join(results)
+        output = truncate_output(output)
+
+        return ToolResult(success=True, output=output or "No matches.")

limbo/tools/grep.py

@@ -0,0 +1,182 @@
+"""Search file contents tool."""
+
+from __future__ import annotations
+
+import fnmatch
+import re
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from limbo.models import ToolResult
+from limbo.tools.base import (
+    BaseTool,
+    is_within_workdir,
+    truncate_output,
+)
+from limbo.tools.ignore import GitignoreMatcher
+
+MAX_MATCHES = 100
+
+
+class GrepTool(BaseTool):
+    name = "grep"
+    description = (
+        "Search file contents for a pattern. Respects .gitignore (basic rules). "
+        "Install ripgrep for full gitignore, glob, and context-line support. "
+        "The Python fallback does not support `**` recursive glob patterns."
+    )
+    parameters = {
+        "type": "object",
+        "properties": {
+            "pattern": {"type": "string", "description": "Search pattern"},
+            "path": {"type": "string", "description": "Directory or file to search"},
+            "glob": {
+                "type": "string",
+                "description": "Filter files by glob (Python fallback does not support `**`)",
+            },
+            "ignore_case": {"type": "boolean", "description": "Case-insensitive"},
+            "fixed_string": {"type": "boolean", "description": "Literal string"},
+            "context": {"type": "integer", "description": "Lines before/after match"},
+            "limit": {
+                "type": "integer",
+                "description": (
+                    "Max matches (per file with ripgrep,"
+                    " total across files in Python fallback)"
+                ),
+            },
+        },
+        "required": ["pattern"],
+    }
+
+    def run(self, arguments: dict[str, Any]) -> ToolResult:
+        pattern = arguments.get("pattern", "")
+        path = arguments.get("path", ".")
+        glob = arguments.get("glob")
+        ignore_case = arguments.get("ignore_case", False)
+        fixed_string = arguments.get("fixed_string", False)
+        context = arguments.get("context", 0)
+        limit = arguments.get("limit", MAX_MATCHES)
+
+        target = self.resolve_existing(path)
+
+        rg = self._find_rg()
+        if rg:
+            return self._run_rg(
+                rg, target, pattern, glob, ignore_case, fixed_string, context, limit
+            )
+        return self._run_python_regex(
+            target, pattern, glob, ignore_case, fixed_string, context, limit
+        )
+
+    def _find_rg(self) -> str | None:
+        import shutil
+
+        return shutil.which("rg")
+
+    def _run_rg(
+        self,
+        rg: str,
+        target: Path,
+        pattern: str,
+        glob: str | None,
+        ignore_case: bool,
+        fixed_string: bool,
+        context: int,
+        limit: int,
+    ) -> ToolResult:
+        cmd = [rg, "--line-number", "--no-heading", "--color=never", "--no-require-git"]
+        if ignore_case:
+            cmd.append("--ignore-case")
+        if fixed_string:
+            cmd.append("--fixed-strings")
+        if context:
+            cmd.extend(["-C", str(context)])
+        if glob:
+            cmd.extend(["-g", glob])
+        # Emit workdir-relative paths, consistent with the Python fallback and find.
+        rel_target = target.relative_to(self.workdir)
+        cmd.extend(["--max-count", str(limit), "--", pattern, str(rel_target)])
+
+        try:
+            proc = subprocess.run(
+                cmd,
+                capture_output=True,
+                text=True,
+                timeout=30,
+                cwd=str(self.workdir),
+            )
+        except subprocess.TimeoutExpired:
+            return ToolResult(success=False, error="grep timed out.")
+        except FileNotFoundError:
+            return ToolResult(success=False, error="ripgrep not found.")
+
+        output = proc.stdout
+        output = truncate_output(output)
+
+        return ToolResult(success=True, output=output or "No matches.")
+
+    def _run_python_regex(
+        self,
+        target: Path,
+        pattern: str,
+        glob: str | None,
+        ignore_case: bool,
+        fixed_string: bool,
+        context: int,
+        limit: int,
+    ) -> ToolResult:
+        # Fallback path: supports pattern/glob/ignore_case/fixed_string/limit.
+        # Context lines are only available through ripgrep.
+        if context:
+            return ToolResult(
+                success=False,
+                error="Context lines require ripgrep. Install ripgrep or omit 'context'.",
+            )
+
+        flags = re.IGNORECASE if ignore_case else 0
+        try:
+            compiled = re.compile(
+                re.escape(pattern) if fixed_string else pattern, flags
+            )
+        except re.error as e:
+            return ToolResult(success=False, error=f"Invalid regex: {e}")
+
+        matches = []
+        matcher = GitignoreMatcher(self.workdir)
+        # ``rglob`` may traverse directory symlinks before we can filter them;
+        # we resolve and enforce the workdir boundary for each candidate.
+        files = [target] if target.is_file() else target.rglob("*")
+        count = 0
+        for f in files:
+            # Resolve symlinks and enforce the workdir boundary before reading.
+            resolved = f.resolve()
+            if not is_within_workdir(resolved, self.workdir):
+                continue
+            if not resolved.is_file():
+                continue
+            try:
+                rel = resolved.relative_to(self.workdir)
+            except ValueError:
+                continue
+            rel_str = str(rel)
+            if matcher.is_ignored(rel_str):
+                continue
+            if glob is not None and not fnmatch.fnmatch(rel_str, glob):
+                continue
+            try:
+                text = resolved.read_text(encoding="utf-8", errors="replace")
+            except OSError:
+                continue
+            for lineno, line in enumerate(text.splitlines(), start=1):
+                if compiled.search(line):
+                    matches.append(f"{rel}:{lineno}:{line}")
+                    count += 1
+                    if count >= limit:
+                        break
+            if count >= limit:
+                break
+
+        output = "\n".join(matches)
+        output = truncate_output(output)
+        return ToolResult(success=True, output=output or "No matches.")