forge-agent-runtime 0.1.0__py3-none-any.whl

forge_runtime/sandbox_assets/Dockerfile

@@ -0,0 +1,51 @@
+FROM python:3.12-slim
+
+ENV DEBIAN_FRONTEND=noninteractive \
+    PIP_DISABLE_PIP_VERSION_CHECK=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \
+        bash \
+        build-essential \
+        ca-certificates \
+        coreutils \
+        curl \
+        git \
+        make \
+        nodejs \
+        npm \
+        tar \
+        wget \
+    && rm -rf /var/lib/apt/lists/*
+
+# Keep the in-container toolchain aligned with the supported project ranges.
+RUN python -m pip install --no-cache-dir \
+    "pytest>=8,<9" \
+    "pytest-asyncio>=0.23,<2" \
+    "pytest-cov>=5,<8" \
+    "ruff>=0.5" \
+    "mypy>=1.10" \
+    "coverage>=7,<8" \
+    "uv" \
+    "pydantic>=2.7,<3" \
+    "pydantic-settings>=2.2,<3" \
+    "httpx>=0.27,<1" \
+    "typer>=0.12,<1" \
+    "rich>=13.7,<15" \
+    "fastapi>=0.115,<1" \
+    "uvicorn[standard]>=0.30,<1" \
+    "agentforge-toolkit==1.1.0"
+
+ENV HOME=/tmp \
+    TMPDIR=/tmp \
+    PATH=/usr/local/bin:/usr/bin:/bin
+
+RUN mkdir -p /opt/forge-node_modules
+
+WORKDIR /workspace
+
+# The runtime overrides UID/GID and drops Linux capabilities; Docker controls bridge/offline networking,
+# and transfers a sanitized snapshot to bounded tmpfs (not a host project bind mount).
+CMD ["python", "--version"]

forge_runtime/sandbox_assets/__init__.py

@@ -0,0 +1 @@
+"""Bundled Docker build context for the Forge Runtime sandbox."""

forge_runtime/storage.py

@@ -0,0 +1,82 @@
+"""SQLite persistence for local development and single-process execution."""
+from __future__ import annotations
+
+import json
+import sqlite3
+from pathlib import Path
+from typing import Any
+
+from forge_runtime.models import RunRecord, RuntimeEvent, TaskRecord
+
+
+class SQLiteStore:
+    def __init__(self, database_url: str) -> None:
+        prefix = "sqlite:///"
+        if not database_url.startswith(prefix):
+            raise ValueError("Initial storage backend supports sqlite:/// URLs only.")
+        raw = Path(database_url[len(prefix):])
+        self.path = raw if raw.is_absolute() else (Path.cwd() / raw).resolve()
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self._initialize()
+
+    def _connect(self) -> sqlite3.Connection:
+        db = sqlite3.connect(self.path, timeout=30)
+        db.row_factory = sqlite3.Row
+        return db
+
+    def _initialize(self) -> None:
+        with self._connect() as db:
+            db.executescript("""
+                PRAGMA journal_mode=WAL;
+                CREATE TABLE IF NOT EXISTS runs (
+                  id TEXT PRIMARY KEY, goal TEXT NOT NULL, status TEXT NOT NULL,
+                  plan_json TEXT, summary TEXT, created_at TEXT NOT NULL,
+                  started_at TEXT, finished_at TEXT);
+                CREATE TABLE IF NOT EXISTS tasks (
+                  id TEXT PRIMARY KEY, run_id TEXT NOT NULL, title TEXT NOT NULL,
+                  agent TEXT NOT NULL, status TEXT NOT NULL, attempt INTEGER NOT NULL,
+                  output TEXT, error TEXT, started_at TEXT, finished_at TEXT,
+                  FOREIGN KEY(run_id) REFERENCES runs(id));
+                CREATE TABLE IF NOT EXISTS events (
+                  id TEXT PRIMARY KEY, run_id TEXT NOT NULL, task_id TEXT,
+                  level TEXT NOT NULL, event_type TEXT NOT NULL, message TEXT NOT NULL,
+                  data_json TEXT NOT NULL, created_at TEXT NOT NULL,
+                  FOREIGN KEY(run_id) REFERENCES runs(id));
+                CREATE INDEX IF NOT EXISTS idx_tasks_run ON tasks(run_id);
+                CREATE INDEX IF NOT EXISTS idx_events_run ON events(run_id, created_at);
+            """)
+
+    def save_run(self, run: RunRecord) -> None:
+        with self._connect() as db:
+            db.execute("INSERT OR REPLACE INTO runs VALUES (?,?,?,?,?,?,?,?)", (
+                run.id, run.goal, run.status.value,
+                run.plan.model_dump_json() if run.plan else None, run.summary,
+                run.created_at.isoformat(), run.started_at.isoformat() if run.started_at else None,
+                run.finished_at.isoformat() if run.finished_at else None))
+
+    def save_task(self, task: TaskRecord) -> None:
+        with self._connect() as db:
+            db.execute("INSERT OR REPLACE INTO tasks VALUES (?,?,?,?,?,?,?,?,?,?)", (
+                task.id, task.run_id, task.title, task.agent, task.status.value, task.attempt,
+                task.output, task.error, task.started_at.isoformat() if task.started_at else None,
+                task.finished_at.isoformat() if task.finished_at else None))
+
+    def add_event(self, event: RuntimeEvent) -> None:
+        with self._connect() as db:
+            db.execute("INSERT INTO events VALUES (?,?,?,?,?,?,?,?)", (
+                event.id, event.run_id, event.task_id, event.level.value, event.event_type,
+                event.message, json.dumps(event.data, default=str), event.created_at.isoformat()))
+
+    def get_run(self, run_id: str) -> dict[str, Any] | None:
+        with self._connect() as db:
+            row = db.execute("SELECT * FROM runs WHERE id=?", (run_id,)).fetchone()
+            if row is None:
+                return None
+            result = dict(row)
+            result["tasks"] = [dict(x) for x in db.execute("SELECT * FROM tasks WHERE run_id=? ORDER BY rowid", (run_id,))]
+            result["events"] = [dict(x) for x in db.execute("SELECT * FROM events WHERE run_id=? ORDER BY created_at", (run_id,))]
+            return result
+
+    def list_runs(self, limit: int = 20) -> list[dict[str, Any]]:
+        with self._connect() as db:
+            return [dict(row) for row in db.execute("SELECT id,goal,status,created_at,finished_at FROM runs ORDER BY created_at DESC LIMIT ?", (limit,))]

forge_runtime/workspace.py

@@ -0,0 +1,280 @@
+"""Capability-scoped file tools for LLM coding agents.
+
+All paths are confined to one configured workspace. There is deliberately no shell,
+process execution, network access, deletion, or arbitrary MCP execution in this module.
+"""
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path, PurePosixPath
+from typing import Any
+
+
+class WorkspaceError(RuntimeError):
+    """A workspace operation is invalid, unavailable, or not authorized."""
+
+
+class WorkspaceTools:
+    EXCLUDED_DIRS = {
+        ".git", ".venv", "venv", "node_modules", "__pycache__", ".next",
+        ".dart_tool", ".idea", ".pytest_cache", ".mypy_cache", ".ruff_cache",
+        ".forge", ".aws", ".ssh", ".secrets", ".terraform",
+        "dist", "build", "coverage", "htmlcov",
+    }
+    SENSITIVE_FILE_NAMES = {
+        ".env", ".npmrc", ".pypirc", ".netrc", ".git-credentials",
+        "id_rsa", "id_ed25519", "credentials", "credentials.json",
+        "service-account.json", "secrets.json", "secret.json",
+    }
+    SENSITIVE_SUFFIXES = {".pem", ".key", ".p12", ".pfx"}
+    MAX_READ_BYTES = 256_000
+    MAX_WRITE_BYTES = 256_000
+    MAX_SEARCH_FILES = 1_000
+    MAX_SEARCH_RESULTS = 40
+    MAX_LIST_RESULTS = 250
+
+    def __init__(self, root: Path | str = ".") -> None:
+        self.root = Path(root).expanduser().resolve()
+        if not self.root.exists() or not self.root.is_dir():
+            raise WorkspaceError(f"Workspace root is not an existing directory: {self.root}")
+
+    def _resolve(self, value: str, *, allow_root: bool = False) -> Path:
+        if not isinstance(value, str) or not value.strip():
+            raise WorkspaceError("A non-empty relative workspace path is required.")
+        normalized = value.replace("\\", "/")
+        pure = PurePosixPath(normalized)
+        if pure.is_absolute() or any(part == ".." for part in pure.parts):
+            raise WorkspaceError("Absolute paths and '..' traversal are not allowed.")
+        if pure.parts and ":" in pure.parts[0]:
+            raise WorkspaceError("Drive-qualified paths are not allowed.")
+        if any(part in self.EXCLUDED_DIRS for part in pure.parts):
+            raise WorkspaceError("This workspace path is excluded from agent access.")
+        if not pure.parts or pure.as_posix() == ".":
+            if allow_root:
+                return self.root
+            raise WorkspaceError("A file path is required.")
+        candidate = (self.root / Path(*pure.parts)).resolve()
+        try:
+            candidate.relative_to(self.root)
+        except ValueError as exc:
+            raise WorkspaceError("Resolved path escapes the configured workspace.") from exc
+        return candidate
+
+    def _is_sensitive_path(self, path: Path) -> bool:
+        try:
+            relative = path.relative_to(self.root)
+        except ValueError:
+            return True
+        parts = tuple(part.lower() for part in relative.parts)
+        if any(part in self.EXCLUDED_DIRS for part in parts):
+            return True
+        if not parts:
+            return False
+        name = parts[-1]
+        if name in self.SENSITIVE_FILE_NAMES:
+            return True
+        if name.startswith(".env.") and name != ".env.example":
+            return True
+        return Path(name).suffix.lower() in self.SENSITIVE_SUFFIXES
+
+    @staticmethod
+    def _display(path: Path, root: Path) -> str:
+        return path.relative_to(root).as_posix() or "."
+
+    def list_files(self, directory: str = ".") -> str:
+        target = self._resolve(directory, allow_root=True)
+        if not target.exists() or not target.is_dir():
+            raise WorkspaceError(f"Directory does not exist: {directory}")
+        entries: list[str] = []
+        for path in sorted(target.iterdir(), key=lambda item: (not item.is_dir(), item.name.lower())):
+            if path.name in self.EXCLUDED_DIRS or path.is_symlink() or self._is_sensitive_path(path):
+                continue
+            suffix = "/" if path.is_dir() else ""
+            entries.append(self._display(path, self.root) + suffix)
+            if len(entries) >= self.MAX_LIST_RESULTS:
+                entries.append("... result limit reached")
+                break
+        return "\n".join(entries) if entries else "(empty directory)"
+
+    def read_file(self, path: str) -> str:
+        target = self._resolve(path)
+        if self._is_sensitive_path(target):
+            raise WorkspaceError("Secret or credential files are protected from agent reads.")
+        if target.is_symlink() or not target.is_file():
+            raise WorkspaceError(f"File does not exist or is not a regular file: {path}")
+        size = target.stat().st_size
+        if size > self.MAX_READ_BYTES:
+            raise WorkspaceError(
+                f"File is {size} bytes; maximum supported read is {self.MAX_READ_BYTES} bytes."
+            )
+        try:
+            return target.read_text(encoding="utf-8")
+        except UnicodeDecodeError as exc:
+            raise WorkspaceError("Only UTF-8 text files can be read by this tool.") from exc
+
+    def search_files(self, query: str, directory: str = ".") -> str:
+        if not isinstance(query, str) or not query.strip():
+            raise WorkspaceError("Search query cannot be empty.")
+        target = self._resolve(directory, allow_root=True)
+        if not target.exists() or not target.is_dir():
+            raise WorkspaceError(f"Directory does not exist: {directory}")
+        needle = query.casefold()
+        matches: list[str] = []
+        scanned = 0
+        for base, dirs, files in os.walk(target, followlinks=False):
+            dirs[:] = [
+                name for name in dirs
+                if name not in self.EXCLUDED_DIRS and not (Path(base) / name).is_symlink()
+            ]
+            for filename in files:
+                file_path = Path(base) / filename
+                if file_path.is_symlink() or self._is_sensitive_path(file_path):
+                    continue
+                scanned += 1
+                if scanned > self.MAX_SEARCH_FILES:
+                    matches.append("... search file limit reached")
+                    return "\n".join(matches) if matches else "No matches."
+                try:
+                    if file_path.stat().st_size > 512_000:
+                        continue
+                    text = file_path.read_text(encoding="utf-8")
+                except (OSError, UnicodeDecodeError):
+                    continue
+                for line_number, line in enumerate(text.splitlines(), start=1):
+                    if needle in line.casefold():
+                        matches.append(
+                            f"{self._display(file_path, self.root)}:{line_number}: {line[:300]}"
+                        )
+                        if len(matches) >= self.MAX_SEARCH_RESULTS:
+                            matches.append("... result limit reached")
+                            return "\n".join(matches)
+        return "\n".join(matches) if matches else "No matches."
+
+    def write_file(self, path: str, content: str, *, writable: bool) -> str:
+        if not writable:
+            raise WorkspaceError(
+                "This AgentForge role is read-only. File writes are not permitted."
+            )
+        target = self._resolve(path)
+        if target.is_symlink():
+            raise WorkspaceError("Writing through symbolic links is not permitted.")
+        if self._is_sensitive_path(target):
+            raise WorkspaceError("Secret or credential files are protected from agent writes.")
+        if not isinstance(content, str):
+            raise WorkspaceError("File content must be text.")
+        encoded = content.encode("utf-8")
+        if len(encoded) > self.MAX_WRITE_BYTES:
+            raise WorkspaceError(
+                f"Write is {len(encoded)} bytes; maximum supported write is "
+                f"{self.MAX_WRITE_BYTES} bytes."
+            )
+
+        target.parent.mkdir(parents=True, exist_ok=True)
+        # Re-resolve after directory creation to catch symlink swaps in parent paths.
+        resolved_parent = target.parent.resolve()
+        try:
+            resolved_parent.relative_to(self.root)
+        except ValueError as exc:
+            raise WorkspaceError("Target parent escapes the configured workspace.") from exc
+        resolved_target = resolved_parent / target.name
+        if self._is_sensitive_path(resolved_target):
+            raise WorkspaceError("Secret or credential files are protected from agent writes.")
+        if resolved_target.exists() and resolved_target.is_symlink():
+            raise WorkspaceError("Writing through symbolic links is not permitted.")
+
+        temporary_name: str | None = None
+        try:
+            with tempfile.NamedTemporaryFile(
+                mode="wb", prefix=".forge-write-", dir=resolved_parent, delete=False
+            ) as temporary:
+                temporary.write(encoded)
+                temporary.flush()
+                os.fsync(temporary.fileno())
+                temporary_name = temporary.name
+            os.replace(temporary_name, resolved_target)
+        finally:
+            if temporary_name and os.path.exists(temporary_name):
+                os.unlink(temporary_name)
+
+        return (
+            f"Wrote {self._display(resolved_target, self.root)} "
+            f"({len(encoded)} UTF-8 bytes)."
+        )
+
+    def tool_schemas(self, *, writable: bool) -> list[dict[str, Any]]:
+        tools = [
+            {
+                "name": "workspace_list_files",
+                "description": "List files and directories inside the assigned project workspace.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {"directory": {"type": "string", "default": "."}},
+                    "additionalProperties": False,
+                },
+            },
+            {
+                "name": "workspace_read_file",
+                "description": "Read a UTF-8 text file inside the assigned project workspace.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {"path": {"type": "string"}},
+                    "required": ["path"],
+                    "additionalProperties": False,
+                },
+            },
+            {
+                "name": "workspace_search_files",
+                "description": "Search text in project files and return matching lines with paths.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "query": {"type": "string"},
+                        "directory": {"type": "string", "default": "."},
+                    },
+                    "required": ["query"],
+                    "additionalProperties": False,
+                },
+            },
+        ]
+        if writable:
+            tools.append(
+                {
+                    "name": "workspace_write_file",
+                    "description": (
+                        "Create or replace a UTF-8 text file inside the project workspace. "
+                        "Only use this for files required by the assigned task."
+                    ),
+                    "parameters": {
+                        "type": "object",
+                        "properties": {
+                            "path": {"type": "string"},
+                            "content": {"type": "string"},
+                        },
+                        "required": ["path", "content"],
+                        "additionalProperties": False,
+                    },
+                }
+            )
+        return tools
+
+    def execute_tool(self, name: str, arguments: dict[str, Any], *, writable: bool) -> str:
+        try:
+            if name == "workspace_list_files":
+                return self.list_files(str(arguments.get("directory", ".")))
+            if name == "workspace_read_file":
+                return self.read_file(str(arguments.get("path", "")))
+            if name == "workspace_search_files":
+                return self.search_files(
+                    str(arguments.get("query", "")),
+                    str(arguments.get("directory", ".")),
+                )
+            if name == "workspace_write_file":
+                return self.write_file(
+                    str(arguments.get("path", "")),
+                    str(arguments.get("content", "")),
+                    writable=writable,
+                )
+            return f"Tool error: unsupported tool name {name!r}."
+        except WorkspaceError as exc:
+            return f"Tool error: {exc}"