forgex-cli 0.1.0__py3-none-any.whl

forgex/tools/base.py

@@ -0,0 +1,212 @@
+"""Tool framework (spec sections 10, 18, 32).
+
+Tools are the ONLY way agents touch the system. Every call passes
+through ToolExecutor, which enforces the per-agent permission matrix.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import time
+from abc import ABC, abstractmethod
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, Field, model_validator
+
+from forgex.config.schema import ForgexConfig
+from forgex.orchestration.events import EventRecorder
+from forgex.sandbox.executor import CommandExecutor
+from forgex.sandbox.permissions import Permission, PermissionSet
+from forgex.schemas.agent import AgentRole
+from forgex.schemas.error import ForgexError, PermissionDeniedError
+from forgex.schemas.event import EventType
+
+logger = logging.getLogger("forgex.tools")
+
+
+class ToolCall(BaseModel):
+    id: str = ""
+    name: str
+    arguments: dict[str, Any] = Field(default_factory=dict)
+
+    @model_validator(mode="before")
+    @classmethod
+    def _parse_arguments(cls, data: Any) -> Any:
+        if isinstance(data, dict):
+            args = data.get("arguments")
+            if isinstance(args, str):
+                try:
+                    data["arguments"] = json.loads(args) if args.strip() else {}
+                except Exception:
+                    data["arguments"] = {}
+        return data
+
+
+class ToolResult(BaseModel):
+    ok: bool = True
+    output: str = ""
+    error: str | None = None
+    data: dict[str, Any] = Field(default_factory=dict)
+    denied: bool = False
+
+
+@dataclass
+class ToolContext:
+    workspace: Path
+    config: ForgexConfig
+    executor: CommandExecutor
+    events: EventRecorder | None = None
+    approval: Callable[[str], bool] | None = None
+    run_id: str | None = None
+    agent: AgentRole | None = None
+
+
+class Tool(ABC):
+    name: str
+    description: str
+    required_permissions: set[Permission]
+
+    @abstractmethod
+    def parameters_schema(self) -> dict[str, Any]:
+        pass
+
+    @abstractmethod
+    async def execute(self, call: ToolCall, ctx: ToolContext) -> ToolResult:
+        pass
+
+
+ToolHandler = Callable[[ToolCall, ToolContext], Awaitable[ToolResult]]
+
+
+class SimpleTool(Tool):
+    def __init__(
+        self,
+        name: str,
+        handler: ToolHandler,
+        permissions: set[Permission],
+        description: str,
+        parameters: dict[str, Any],
+    ) -> None:
+        self.name = name
+        self._handler = handler
+        self.required_permissions = permissions
+        self.description = description
+        self._parameters = parameters
+
+    def parameters_schema(self) -> dict[str, Any]:
+        return self._parameters
+
+    async def execute(self, call: ToolCall, ctx: ToolContext) -> ToolResult:
+        return await self._handler(call, ctx)
+
+
+class ToolRegistry:
+    def __init__(self) -> None:
+        self._tools: dict[str, Tool] = {}
+
+    def register(self, tool: Tool) -> None:
+        self._tools[tool.name] = tool
+
+    def get(self, name: str) -> Tool | None:
+        return self._tools.get(name)
+
+    def tools(self) -> list[Tool]:
+        return list(self._tools.values())
+
+    def schemas_for(self, permissions: PermissionSet) -> list[dict[str, Any]]:
+        schemas: list[dict[str, Any]] = []
+        for tool in self._tools.values():
+            if permissions.permits(*tool.required_permissions):
+                schemas.append(
+                    {
+                        "type": "function",
+                        "function": {
+                            "name": tool.name,
+                            "description": tool.description,
+                            "parameters": tool.parameters_schema(),
+                        },
+                    }
+                )
+        return schemas
+
+
+class ToolExecutor:
+    def __init__(
+        self,
+        registry: ToolRegistry,
+        permissions: PermissionSet,
+        context: ToolContext,
+    ) -> None:
+        self._registry = registry
+        self._permissions = permissions
+        self._context = context
+
+    @property
+    def context(self) -> ToolContext:
+        return self._context
+
+    def schemas(self) -> list[dict[str, Any]]:
+        return self._registry.schemas_for(self._permissions)
+
+    async def execute(self, call: ToolCall) -> ToolResult:
+        tool = self._registry.get(call.name)
+        if tool is None:
+            return ToolResult(ok=False, error=f"Unknown tool: '{call.name}'")
+
+        if not self._permissions.permits(*tool.required_permissions):
+            reason = self._permissions.deny_reason(*tool.required_permissions) or "denied"
+            msg = f"Permission denied for tool '{call.name}': {reason}"
+            if self._context.events is not None:
+                self._context.events.record(
+                    EventType.TOOL_STARTED,
+                    {"tool": call.name, "arguments": call.arguments},
+                    run_id=self._context.run_id,
+                )
+                self._context.events.record(
+                    EventType.TOOL_COMPLETED,
+                    {"tool": call.name, "ok": False, "denied": True, "error": msg},
+                    run_id=self._context.run_id,
+                )
+            raise PermissionDeniedError(msg)
+
+        if self._context.events is not None:
+            self._context.events.record(
+                EventType.TOOL_STARTED,
+                {"tool": call.name, "arguments": call.arguments},
+                run_id=self._context.run_id,
+            )
+
+        start = time.perf_counter()
+        try:
+            result = await tool.execute(call, self._context)
+        except ForgexError as exc:
+            result = ToolResult(ok=False, error=str(exc))
+        except Exception as exc:  # noqa: BLE001
+            result = ToolResult(ok=False, error=f"Tool execution failed: {exc}")
+
+        duration = (time.perf_counter() - start) * 1000
+
+        if self._context.events is not None:
+            if result.ok and call.name in ("write_file", "create_file", "delete_file", "move_file"):
+                target = call.arguments.get("path") or call.arguments.get("destination")
+                self._context.events.record(
+                    EventType.FILE_CHANGED,
+                    {"tool": call.name, "path": target},
+                    run_id=self._context.run_id,
+                )
+            self._context.events.record(
+                EventType.TOOL_COMPLETED,
+                {
+                    "tool": call.name,
+                    "ok": result.ok,
+                    "error": result.error,
+                    "duration_ms": round(duration, 1),
+                },
+                run_id=self._context.run_id,
+            )
+
+        return result

forgex/tools/dependencies.py

@@ -0,0 +1,137 @@
+"""inspect_dependencies tool (spec section 49) — language-agnostic manifest parsing."""
+
+from __future__ import annotations
+
+import json
+import re
+import tomllib
+from pathlib import Path
+from typing import Any
+
+from forgex.sandbox.permissions import Permission
+from forgex.tools.base import SimpleTool, Tool, ToolCall, ToolContext, ToolResult
+
+
+def _dep(name: str, spec: Any, *, dev: bool, source: str) -> dict[str, Any]:
+    return {
+        "name": name,
+        "spec": spec if isinstance(spec, str) and spec else None,
+        "dev": dev,
+        "source": source,
+    }
+
+
+def _python_deps(root: Path) -> list[dict[str, Any]]:
+    deps: list[dict[str, Any]] = []
+
+    pyproject = root / "pyproject.toml"
+    if pyproject.is_file():
+        try:
+            with pyproject.open("rb") as fh:
+                data = tomllib.load(fh)
+            project = data.get("project") or {}
+            for entry in project.get("dependencies") or []:
+                name = re.split(r"[=<>!~^ ;\[]", str(entry), maxsplit=1)[0]
+                deps.append(_dep(name, str(entry), dev=False, source="pyproject.toml"))
+            for group, items in (project.get("optional-dependencies") or {}).items():
+                for entry in items:
+                    name = re.split(r"[=<>!~^ ;\[]", str(entry), maxsplit=1)[0]
+                    deps.append(_dep(name, str(entry), dev=(group == "dev"), source="pyproject.toml"))
+        except (OSError, tomllib.TOMLDecodeError):
+            pass
+
+    reqs = root / "requirements.txt"
+    if reqs.is_file():
+        try:
+            for line in reqs.read_text(encoding="utf-8", errors="replace").splitlines():
+                line = line.strip()
+                if not line or line.startswith("#"):
+                    continue
+                name = re.split(r"[=<>!~^ ;]", line, maxsplit=1)[0]
+                deps.append(_dep(name, line, dev=False, source="requirements.txt"))
+        except OSError:
+            pass
+
+    return deps
+
+
+def _node_deps(root: Path) -> list[dict[str, Any]]:
+    deps: list[dict[str, Any]] = []
+    pkg = root / "package.json"
+    if pkg.is_file():
+        try:
+            data = json.loads(pkg.read_text(encoding="utf-8"))
+            for name, spec in (data.get("dependencies") or {}).items():
+                deps.append(_dep(name, str(spec), dev=False, source="package.json"))
+            for name, spec in (data.get("devDependencies") or {}).items():
+                deps.append(_dep(name, str(spec), dev=True, source="package.json"))
+        except (OSError, json.JSONDecodeError):
+            pass
+    return deps
+
+
+def _cargo_deps(root: Path) -> list[dict[str, Any]]:
+    deps: list[dict[str, Any]] = []
+    cargo = root / "Cargo.toml"
+    if cargo.is_file():
+        try:
+            with cargo.open("rb") as fh:
+                data = tomllib.load(fh)
+            for name, spec in (data.get("dependencies") or {}).items():
+                deps.append(_dep(name, str(spec), dev=False, source="Cargo.toml"))
+            for name, spec in (data.get("dev-dependencies") or {}).items():
+                deps.append(_dep(name, str(spec), dev=True, source="Cargo.toml"))
+        except (OSError, tomllib.TOMLDecodeError):
+            pass
+    return deps
+
+
+def _go_deps(root: Path) -> list[dict[str, Any]]:
+    deps: list[dict[str, Any]] = []
+    mod = root / "go.mod"
+    if mod.is_file():
+        try:
+            content = mod.read_text(encoding="utf-8", errors="replace")
+            in_require = False
+            for line in content.splitlines():
+                line = line.strip()
+                if line.startswith("require ("):
+                    in_require = True
+                    continue
+                if in_require and line == ")":
+                    in_require = False
+                    continue
+                if in_require or line.startswith("require "):
+                    if line.startswith("require "):
+                        line = line[8:].strip()
+                    parts = line.split()
+                    if len(parts) >= 2:
+                        deps.append(_dep(parts[0], parts[1], dev=False, source="go.mod"))
+        except OSError:
+            pass
+    return deps
+
+
+async def _inspect_dependencies(call: ToolCall, ctx: ToolContext) -> ToolResult:
+    root = ctx.workspace
+    all_deps: list[dict[str, Any]] = []
+    all_deps.extend(_python_deps(root))
+    all_deps.extend(_node_deps(root))
+    all_deps.extend(_cargo_deps(root))
+    all_deps.extend(_go_deps(root))
+
+    lines = [f"{d['name']} ({d['spec'] or 'any'}) [source: {d['source']}{', dev' if d['dev'] else ''}]" for d in all_deps]
+    output = "\n".join(lines) if lines else "(no dependencies declared)"
+    return ToolResult(ok=True, output=output, data={"dependencies": all_deps})
+
+
+def create_tools() -> list[Tool]:
+    return [
+        SimpleTool(
+            name="inspect_dependencies",
+            handler=_inspect_dependencies,
+            permissions={Permission.READ},
+            description="Inspect declared project dependencies across pyproject, package.json, Cargo.toml, go.mod.",
+            parameters={"type": "object", "properties": {}, "additionalProperties": False},
+        )
+    ]

forgex/tools/filesystem.py

@@ -0,0 +1,322 @@
+"""Filesystem tools (spec sections 18, 46, 75).
+
+Every agent filesystem operation routes through resolve_in_workspace().
+Protected paths (.forgex/, .git/, workspace root) and secret files (.env*, keys)
+are guarded.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+from pathlib import Path
+
+from forgex.sandbox.permissions import Permission
+from forgex.schemas.error import PathViolationError, ToolError
+from forgex.tools.base import SimpleTool, Tool, ToolCall, ToolContext, ToolResult
+from forgex.utils.paths import resolve_in_workspace
+from forgex.utils.redact import redact_patterns
+
+IGNORED_DIRS: set[str] = {
+    ".git",
+    ".forgex",
+    "node_modules",
+    ".venv",
+    "venv",
+    "__pycache__",
+    "dist",
+    "build",
+    ".mypy_cache",
+    ".ruff_cache",
+    ".pytest_cache",
+}
+
+_SECRET_FILE_PATTERNS = [
+    ".env*",
+    "*.pem",
+    "id_rsa*",
+    "id_ed25519*",
+    ".npmrc",
+    "*.key",
+    "*credentials*",
+    "*secret*",
+]
+
+MAX_READ_BYTES = 200_000
+MAX_READ_LINES = 2000
+MAX_LIST_COUNT = 500
+
+
+def is_secret_file(name: str) -> bool:
+    lower = name.lower()
+    return any(fnmatch.fnmatch(lower, pat) for pat in _SECRET_FILE_PATTERNS)
+
+
+def _resolve_path(ctx: ToolContext, raw: str) -> Path:
+    try:
+        return resolve_in_workspace(ctx.workspace, raw)
+    except PathViolationError as exc:
+        raise ToolError(str(exc)) from exc
+    except (ValueError, OSError) as exc:
+        raise ToolError(f"invalid path: {exc}") from exc
+
+
+def _rel(ctx: ToolContext, path: Path) -> str:
+    try:
+        return str(path.relative_to(ctx.workspace))
+    except ValueError:
+        return str(path)
+
+
+def _assert_mutable(ctx: ToolContext, path: Path, raw: str) -> None:
+    if path == ctx.workspace.resolve():
+        raise ToolError("refusing to modify the workspace root")
+
+    lexical = Path(raw)
+    if not lexical.is_absolute():
+        lexical = ctx.workspace / lexical
+    if lexical.is_symlink():
+        raise ToolError(f"refusing to modify through a symlink: {raw}")
+
+    rel = Path(_rel(ctx, path))
+    top = rel.parts[0] if rel.parts else ""
+    if top in {".forgex", ".git"}:
+        raise ToolError("refusing to modify protected path (.forgex/ and .git/ are system-owned)")
+
+
+async def _list_files(call: ToolCall, ctx: ToolContext) -> ToolResult:
+    sub = str(call.arguments.get("path", ".") or ".")
+    pattern = call.arguments.get("pattern")
+    target = _resolve_path(ctx, sub)
+
+    if not target.is_dir():
+        return ToolResult(ok=False, error=f"Not a directory: {sub}")
+
+    entries: list[str] = []
+    truncated = False
+
+    for item in sorted(target.rglob("*")):
+        # Skip ignored directories
+        rel = item.relative_to(ctx.workspace)
+        parts = rel.parts
+        if any(p in IGNORED_DIRS for p in parts):
+            continue
+        if item.is_file():
+            if pattern and not fnmatch.fnmatch(item.name, pattern):
+                continue
+            entries.append(rel.as_posix())
+            if len(entries) >= MAX_LIST_COUNT:
+                truncated = True
+                break
+
+    lines = list(entries)
+    if truncated:
+        lines.append(f"... [truncated at {MAX_LIST_COUNT} entries]")
+
+    return ToolResult(
+        ok=True,
+        output="\n".join(lines) or "(empty)",
+        data={"count": len(entries), "truncated": truncated},
+    )
+
+
+async def _read_file(call: ToolCall, ctx: ToolContext) -> ToolResult:
+    path_arg = call.arguments.get("path")
+    if not path_arg:
+        return ToolResult(ok=False, error="missing required argument: path")
+
+    target = _resolve_path(ctx, str(path_arg))
+
+    if is_secret_file(target.name):
+        return ToolResult(ok=False, error=f"refusing to read secret-bearing file: {target.name}")
+
+    if not target.is_file():
+        return ToolResult(ok=False, error=f"file not found: {path_arg}")
+
+    try:
+        raw_bytes = target.read_bytes()
+    except OSError as exc:
+        return ToolResult(ok=False, error=f"failed to read file: {exc}")
+
+    # Redact patterns before processing
+    text = redact_patterns(raw_bytes[:MAX_READ_BYTES].decode("utf-8", errors="replace"))
+    lines = text.splitlines()
+
+    truncated = False
+    if len(raw_bytes) > MAX_READ_BYTES or len(lines) > MAX_READ_LINES:
+        truncated = True
+        lines = lines[:MAX_READ_LINES]
+        lines.append("... [file truncated]")
+
+    return ToolResult(
+        ok=True,
+        output="\n".join(lines),
+        data={"path": _rel(ctx, target), "lines": len(lines), "truncated": truncated},
+    )
+
+
+async def _write_file(call: ToolCall, ctx: ToolContext) -> ToolResult:
+    path_arg = call.arguments.get("path")
+    content = call.arguments.get("content")
+    if path_arg is None or content is None:
+        return ToolResult(ok=False, error="missing path or content argument")
+
+    target = _resolve_path(ctx, str(path_arg))
+    _assert_mutable(ctx, target, str(path_arg))
+
+    try:
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(str(content), encoding="utf-8")
+        return ToolResult(ok=True, output=f"wrote {len(content)} characters to {path_arg}")
+    except OSError as exc:
+        return ToolResult(ok=False, error=f"failed to write file: {exc}")
+
+
+async def _create_file(call: ToolCall, ctx: ToolContext) -> ToolResult:
+    path_arg = call.arguments.get("path")
+    content = call.arguments.get("content", "")
+    if path_arg is None:
+        return ToolResult(ok=False, error="missing path argument")
+
+    target = _resolve_path(ctx, str(path_arg))
+    _assert_mutable(ctx, target, str(path_arg))
+
+    if target.exists():
+        return ToolResult(ok=False, error=f"file already exists: {path_arg}")
+
+    try:
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(str(content), encoding="utf-8")
+        return ToolResult(ok=True, output=f"created file {path_arg}")
+    except OSError as exc:
+        return ToolResult(ok=False, error=f"failed to create file: {exc}")
+
+
+async def _delete_file(call: ToolCall, ctx: ToolContext) -> ToolResult:
+    path_arg = call.arguments.get("path")
+    if not path_arg:
+        return ToolResult(ok=False, error="missing path argument")
+
+    target = _resolve_path(ctx, str(path_arg))
+    _assert_mutable(ctx, target, str(path_arg))
+
+    if not target.exists():
+        return ToolResult(ok=False, error=f"file not found: {path_arg}")
+    if target.is_dir():
+        return ToolResult(ok=False, error=f"refusing to delete directory: {path_arg}")
+
+    try:
+        target.unlink()
+        return ToolResult(ok=True, output=f"deleted file {path_arg}")
+    except OSError as exc:
+        return ToolResult(ok=False, error=f"failed to delete file: {exc}")
+
+
+async def _move_file(call: ToolCall, ctx: ToolContext) -> ToolResult:
+    src_arg = call.arguments.get("source")
+    dst_arg = call.arguments.get("destination")
+    if not src_arg or not dst_arg:
+        return ToolResult(ok=False, error="missing source or destination argument")
+
+    src = _resolve_path(ctx, str(src_arg))
+    dst = _resolve_path(ctx, str(dst_arg))
+    _assert_mutable(ctx, src, str(src_arg))
+    _assert_mutable(ctx, dst, str(dst_arg))
+
+    if not src.exists():
+        return ToolResult(ok=False, error=f"source file not found: {src_arg}")
+
+    try:
+        dst.parent.mkdir(parents=True, exist_ok=True)
+        src.rename(dst)
+        return ToolResult(ok=True, output=f"moved {src_arg} -> {dst_arg}")
+    except OSError as exc:
+        return ToolResult(ok=False, error=f"failed to move file: {exc}")
+
+
+def create_tools() -> list[Tool]:
+    path_prop = {"type": "string", "description": "Workspace-relative file path"}
+    return [
+        SimpleTool(
+            name="list_files",
+            handler=_list_files,
+            permissions={Permission.READ},
+            description="List files in the workspace (ignores git/cache/build noise).",
+            parameters={
+                "type": "object",
+                "properties": {
+                    "path": {"type": "string", "description": "Subdirectory (default: workspace root)"},
+                    "pattern": {"type": "string", "description": "Optional glob filter on file names"},
+                },
+                "additionalProperties": False,
+            },
+        ),
+        SimpleTool(
+            name="read_file",
+            handler=_read_file,
+            permissions={Permission.READ},
+            description="Read a file (capped at 200KB / 2000 lines; secret files like .env are refused).",
+            parameters={
+                "type": "object",
+                "properties": {"path": path_prop},
+                "required": ["path"],
+                "additionalProperties": False,
+            },
+        ),
+        SimpleTool(
+            name="write_file",
+            handler=_write_file,
+            permissions={Permission.WRITE},
+            description="Write a file (overwrites; creates parent directories).",
+            parameters={
+                "type": "object",
+                "properties": {
+                    "path": path_prop,
+                    "content": {"type": "string"},
+                },
+                "required": ["path", "content"],
+                "additionalProperties": False,
+            },
+        ),
+        SimpleTool(
+            name="create_file",
+            handler=_create_file,
+            permissions={Permission.WRITE},
+            description="Create a new file; fails if it already exists.",
+            parameters={
+                "type": "object",
+                "properties": {
+                    "path": path_prop,
+                    "content": {"type": "string"},
+                },
+                "required": ["path", "content"],
+                "additionalProperties": False,
+            },
+        ),
+        SimpleTool(
+            name="delete_file",
+            handler=_delete_file,
+            permissions={Permission.DELETE},
+            description="Delete a single file (never directories).",
+            parameters={
+                "type": "object",
+                "properties": {"path": path_prop},
+                "required": ["path"],
+                "additionalProperties": False,
+            },
+        ),
+        SimpleTool(
+            name="move_file",
+            handler=_move_file,
+            permissions={Permission.WRITE},
+            description="Move or rename a file inside the workspace.",
+            parameters={
+                "type": "object",
+                "properties": {
+                    "source": path_prop,
+                    "destination": path_prop,
+                },
+                "required": ["source", "destination"],
+                "additionalProperties": False,
+            },
+        ),
+    ]