agent-loop-guard-runtime 0.6.0a2__py3-none-any.whl

app/db/session.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from collections.abc import Generator
+
+from fastapi import Request
+from sqlalchemy import create_engine, event
+from sqlalchemy.orm import Session, sessionmaker
+from sqlalchemy.pool import StaticPool
+
+from app.core.config import AppConfig
+from app.db.models import Base
+from app.db.repository import ensure_seed_data
+from app.platform.migrations import migrate_database
+
+
+def build_engine(config: AppConfig):
+    config.ensure_storage_parent()
+    kwargs = {"future": True}
+    if config.storage_url.startswith("sqlite"):
+        kwargs["connect_args"] = {"check_same_thread": False}
+        if config.storage_url == "sqlite:///:memory:":
+            kwargs["poolclass"] = StaticPool
+    engine = create_engine(config.storage_url, **kwargs)
+    if config.storage_url.startswith("sqlite"):
+        @event.listens_for(engine, "connect")
+        def _sqlite_foreign_keys(dbapi_connection, _connection_record) -> None:
+            cursor = dbapi_connection.cursor()
+            cursor.execute("PRAGMA foreign_keys=ON")
+            cursor.close()
+
+    return engine
+
+
+def build_session_factory(engine) -> sessionmaker[Session]:
+    return sessionmaker(bind=engine, autoflush=False, expire_on_commit=False, future=True)
+
+
+def init_db(engine, config: AppConfig) -> None:
+    migrate_database(engine, config.storage_url)
+    # create_all is retained as a compatibility safety net for pre-v0.2 databases.
+    Base.metadata.create_all(engine)
+    if config.storage_url.startswith("sqlite"):
+        with engine.begin() as conn:
+            conn.exec_driver_sql("PRAGMA journal_mode=WAL")
+            conn.exec_driver_sql("PRAGMA foreign_keys=ON")
+    factory = build_session_factory(engine)
+    with factory() as db:
+        ensure_seed_data(db, config)
+
+
+def get_db(request: Request) -> Generator[Session, None, None]:
+    session_factory = request.app.state.SessionLocal
+    db = session_factory()
+    try:
+        yield db
+    finally:
+        db.close()

app/main.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse, Response
+from fastapi.staticfiles import StaticFiles
+
+from app.api.admin_routes import router as admin_router
+from app.api.anthropic_routes import router as anthropic_router
+from app.api.mcp_routes import router as mcp_router
+from app.api.openai_routes import router as openai_router
+from app.api.replay_routes import router as replay_router
+from app.api.ui_routes import router as ui_router
+from app.core.config import AppConfig
+from app.db.session import build_engine, build_session_factory, init_db
+
+
+def create_app(config: AppConfig | None = None) -> FastAPI:
+    config = config or AppConfig.from_env()
+    engine = build_engine(config)
+    init_db(engine, config)
+
+    app = FastAPI(
+        title="Agent Loop Guard",
+        version="0.6.0a1",
+        description="Local runtime guard for coding agents.",
+    )
+    app.state.config = config
+    app.state.engine = engine
+    app.state.SessionLocal = build_session_factory(engine)
+    app.state.mcp_upstream_sessions = {}
+
+    @app.middleware("http")
+    async def body_limit(request: Request, call_next):
+        content_length = request.headers.get("content-length")
+        if content_length and int(content_length) > config.body_limit_bytes:
+            return JSONResponse({"error": "Request body too large."}, status_code=413)
+        return await call_next(request)
+
+    @app.head("/")
+    async def connectivity_probe() -> Response:
+        return Response(status_code=204)
+
+    app.include_router(openai_router)
+    app.include_router(anthropic_router)
+    app.include_router(admin_router)
+    app.include_router(replay_router)
+    app.include_router(mcp_router)
+
+    if config.admin_ui:
+        static_dir = Path(__file__).resolve().parent / "static"
+        app.mount("/static", StaticFiles(directory=str(static_dir)), name="static")
+        app.include_router(ui_router)
+
+    return app
+
+
+app = create_app()

app/mcp/__init__.py

@@ -0,0 +1 @@
+"""MCP Permission Firewall."""

app/mcp/gateway.py

@@ -0,0 +1,230 @@
+from __future__ import annotations
+
+import json
+import secrets
+from dataclasses import dataclass
+from typing import Any
+
+from jsonschema import ValidationError, validate
+
+from app.db.models import MCPSession
+from app.db.repository import Repository
+from app.mcp.policy import MCPDecision, MCPPolicyEngine
+
+
+@dataclass(slots=True)
+class CallInterception:
+    forward: bool
+    message: dict[str, Any]
+    response: dict[str, Any] | None
+    decision: MCPDecision | None
+
+
+def jsonrpc_error(request_id: Any, code: int, message: str, data: dict | None = None) -> dict:
+    error: dict[str, Any] = {"code": code, "message": message}
+    if data:
+        error["data"] = data
+    return {"jsonrpc": "2.0", "id": request_id, "error": error}
+
+
+def tool_error(request_id: Any, message: str, data: dict | None = None) -> dict:
+    payload: dict[str, Any] = {
+        "content": [{"type": "text", "text": message}],
+        "isError": True,
+    }
+    if data:
+        payload["structuredContent"] = data
+    return {"jsonrpc": "2.0", "id": request_id, "result": payload}
+
+
+class MCPGateway:
+    def __init__(
+        self,
+        repo: Repository,
+        policy: MCPPolicyEngine,
+        server_id: str,
+        session_id: str | None = None,
+        approval_timeout_seconds: int = 30,
+    ):
+        self.repo = repo
+        self.policy = policy
+        self.server_id = server_id
+        self.session_id = session_id
+        self.approval_timeout_seconds = approval_timeout_seconds
+
+    def ensure_session(
+        self, *, client_name: str | None = None, protocol_version: str | None = None
+    ) -> str:
+        if self.session_id and self.repo.db.get(MCPSession, self.session_id):
+            return self.session_id
+        session_id = f"mcp_{secrets.token_urlsafe(18)}"
+        self.repo.start_mcp_session(
+            self.server_id,
+            client_name=client_name,
+            protocol_version=protocol_version,
+            mode=str(self.policy.data.get("mode", "enforce")),
+            session_id=session_id,
+        )
+        self.session_id = session_id
+        return session_id
+
+    def filter_tools(self, response: dict[str, Any]) -> dict[str, Any]:
+        result = response.get("result")
+        if not isinstance(result, dict) or not isinstance(result.get("tools"), list):
+            return response
+        tools = [
+            tool
+            for tool in result["tools"]
+            if isinstance(tool, dict)
+            and self.policy.visible_tool(self.server_id, str(tool.get("name") or ""))
+        ]
+        result["tools"] = tools
+        if self.session_id:
+            self.repo.record_mcp_tools(self.session_id, self.server_id, tools)
+        return response
+
+    def intercept(self, message: dict[str, Any]) -> CallInterception:
+        if message.get("method") != "tools/call":
+            return CallInterception(True, message, None, None)
+        request_id = message.get("id")
+        params = message.get("params") if isinstance(message.get("params"), dict) else {}
+        tool_name = str(params.get("name") or "")
+        arguments = params.get("arguments") if isinstance(params.get("arguments"), dict) else {}
+        schema = self.repo.mcp_tool_schema(self.server_id, tool_name)
+        if schema:
+            try:
+                validate(instance=arguments, schema=schema)
+            except ValidationError as exc:
+                return CallInterception(
+                    False,
+                    message,
+                    tool_error(request_id, "Tool arguments failed JSON Schema validation.", {"path": list(exc.path)}),
+                    None,
+                )
+
+        decision = self.policy.evaluate(self.server_id, tool_name, arguments)
+        approved = None
+        if decision.action == "confirm":
+            approved = self.repo.consume_mcp_approval(
+                self.server_id, tool_name, decision.argument_hash, self.session_id
+            )
+            if approved:
+                decision.action = "allow"
+                decision.reason = f"Approved by user ({approved.scope})."
+
+        event = self.repo.record_mcp_decision(
+            server_id=self.server_id,
+            session_id=self.session_id,
+            request_id=request_id,
+            tool_name=tool_name,
+            argument_hash=decision.argument_hash,
+            policy_version=decision.policy_version,
+            action=decision.action,
+            reason=decision.reason,
+            rule_id=decision.rule_id,
+            mode=decision.mode,
+            attributes={
+                "risk_tags": decision.risk_tags,
+                "transformed_fields": decision.transformed_fields,
+            },
+        )
+
+        if decision.action == "confirm":
+            approval = self.repo.create_mcp_approval(
+                event.id, decision.argument_hash, self.approval_timeout_seconds
+            )
+            return CallInterception(
+                False,
+                message,
+                tool_error(
+                    request_id,
+                    "User approval is required. Approve the request and retry the same call.",
+                    {"approval_id": approval.id, "action": "confirm"},
+                ),
+                decision,
+            )
+        if not decision.allowed:
+            return CallInterception(
+                False,
+                message,
+                tool_error(request_id, decision.reason, {"action": decision.action, "rule_id": decision.rule_id}),
+                decision,
+            )
+
+        transformed = json.loads(json.dumps(message))
+        transformed.setdefault("params", {})["arguments"] = decision.arguments
+        return CallInterception(True, transformed, None, decision)
+
+
+MOCK_TOOLS = [
+    {
+        "name": "read_file",
+        "description": "Read a file from the demo workspace.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {"path": {"type": "string"}},
+            "required": ["path"],
+            "additionalProperties": False,
+        },
+    },
+    {
+        "name": "write_file",
+        "description": "Write a file in the demo workspace.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {"path": {"type": "string"}, "content": {"type": "string"}},
+            "required": ["path", "content"],
+            "additionalProperties": False,
+        },
+    },
+    {
+        "name": "delete_file",
+        "description": "Delete a file in the demo workspace.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {"path": {"type": "string"}},
+            "required": ["path"],
+            "additionalProperties": False,
+        },
+    },
+]
+
+
+def mock_response(message: dict[str, Any]) -> dict[str, Any] | None:
+    request_id = message.get("id")
+    method = message.get("method")
+    if request_id is None:
+        return None
+    if method == "initialize":
+        requested = (message.get("params") or {}).get("protocolVersion")
+        version = requested if requested == "2025-11-25" else "2025-11-25"
+        return {
+            "jsonrpc": "2.0",
+            "id": request_id,
+            "result": {
+                "protocolVersion": version,
+                "capabilities": {"tools": {"listChanged": False}},
+                "serverInfo": {"name": "Agent Loop Guard mock filesystem", "version": "0.2.0"},
+            },
+        }
+    if method == "tools/list":
+        return {"jsonrpc": "2.0", "id": request_id, "result": {"tools": MOCK_TOOLS}}
+    if method == "tools/call":
+        params = message.get("params") or {}
+        name = params.get("name")
+        arguments = params.get("arguments") or {}
+        return {
+            "jsonrpc": "2.0",
+            "id": request_id,
+            "result": {
+                "content": [
+                    {
+                        "type": "text",
+                        "text": f"Mock {name} completed for {arguments.get('path', 'no path')}.",
+                    }
+                ],
+                "structuredContent": {"tool": name, "status": "ok"},
+                "isError": False,
+            },
+        }
+    return jsonrpc_error(request_id, -32601, f"Method not found: {method}")

app/mcp/policy.py

@@ -0,0 +1,281 @@
+from __future__ import annotations
+
+import fnmatch
+import hashlib
+import json
+import shlex
+import time
+from collections import defaultdict, deque
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlparse
+
+import yaml
+
+ALLOWED_ACTIONS = {"allow", "deny", "confirm", "transform", "rate_limit", "shadow_deny"}
+PATH_KEYS = {"path", "file", "filepath", "file_path", "directory", "cwd", "root"}
+
+
+class MCPPolicyError(ValueError):
+    pass
+
+
+@dataclass(slots=True)
+class MCPDecision:
+    action: str
+    reason: str
+    rule_id: str
+    policy_version: str
+    arguments: dict[str, Any]
+    argument_hash: str
+    mode: str = "enforce"
+    risk_tags: list[str] = field(default_factory=list)
+    transformed_fields: list[str] = field(default_factory=list)
+
+    @property
+    def allowed(self) -> bool:
+        return self.action in {"allow", "transform", "shadow_deny"}
+
+
+def argument_fingerprint(arguments: dict[str, Any]) -> str:
+    normalized = json.dumps(arguments, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
+    return hashlib.sha256(normalized.encode("utf-8")).hexdigest()
+
+
+def validate_policy(data: dict[str, Any]) -> list[str]:
+    errors: list[str] = []
+    if int(data.get("version", 0)) < 1:
+        errors.append("version must be a positive integer")
+    default_action = str(data.get("default_action", "confirm"))
+    if default_action not in ALLOWED_ACTIONS:
+        errors.append(f"unsupported default_action: {default_action}")
+    servers = data.get("servers", {})
+    if not isinstance(servers, dict):
+        errors.append("servers must be an object")
+        return errors
+    for server_id, server in servers.items():
+        if not isinstance(server, dict):
+            errors.append(f"servers.{server_id} must be an object")
+            continue
+        for tool_name, rule in (server.get("tools") or {}).items():
+            if not isinstance(rule, dict):
+                errors.append(f"servers.{server_id}.tools.{tool_name} must be an object")
+                continue
+            action = str(rule.get("action", default_action))
+            if action not in ALLOWED_ACTIONS:
+                errors.append(f"servers.{server_id}.tools.{tool_name}: unsupported action {action}")
+    return errors
+
+
+def load_policy(path: str | Path | None = None) -> tuple[dict[str, Any], Path | None]:
+    if path is None:
+        return default_policy(), None
+    policy_path = Path(path)
+    if not policy_path.exists():
+        return default_policy(), policy_path
+    with policy_path.open(encoding="utf-8") as handle:
+        data = yaml.safe_load(handle) or {}
+    errors = validate_policy(data)
+    if errors:
+        raise MCPPolicyError("; ".join(errors))
+    return data, policy_path
+
+
+def default_policy() -> dict[str, Any]:
+    return {
+        "version": 1,
+        "default_action": "confirm",
+        "mode": "enforce",
+        "hide_denied_tools": True,
+        "servers": {
+            "filesystem": {
+                "tools": {
+                    "read_file": {"action": "allow", "paths": ["./**"]},
+                    "write_file": {"action": "confirm", "paths": ["./**"]},
+                    "delete_file": {"action": "deny"},
+                }
+            }
+        },
+    }
+
+
+class MCPPolicyEngine:
+    def __init__(self, path: str | Path | None = None, *, project_root: str | Path | None = None):
+        self.path = Path(path) if path else None
+        self.project_root = Path(project_root or Path.cwd()).resolve()
+        self.data, _ = load_policy(self.path)
+        self._mtime = self.path.stat().st_mtime_ns if self.path and self.path.exists() else 0
+        self._rate_windows: dict[str, deque[float]] = defaultdict(deque)
+
+    @property
+    def version(self) -> str:
+        digest = hashlib.sha256(
+            json.dumps(self.data, sort_keys=True, separators=(",", ":")).encode("utf-8")
+        ).hexdigest()[:12]
+        return f"v{self.data.get('version', 1)}:{digest}"
+
+    def reload_if_changed(self) -> bool:
+        if not self.path or not self.path.exists():
+            return False
+        mtime = self.path.stat().st_mtime_ns
+        if mtime == self._mtime:
+            return False
+        self.data, _ = load_policy(self.path)
+        self._mtime = mtime
+        return True
+
+    def rule_for(self, server_id: str, tool_name: str) -> tuple[dict[str, Any], str]:
+        server = (self.data.get("servers") or {}).get(server_id, {})
+        tools = server.get("tools") or {}
+        if tool_name in tools:
+            return dict(tools[tool_name]), f"{server_id}.tools.{tool_name}"
+        for group_name, group in (server.get("groups") or {}).items():
+            patterns = group.get("tools") or []
+            if any(fnmatch.fnmatchcase(tool_name, str(pattern)) for pattern in patterns):
+                return dict(group), f"{server_id}.groups.{group_name}"
+        action = server.get("default_action", self.data.get("default_action", "confirm"))
+        return {"action": action}, f"{server_id}.default"
+
+    def visible_tool(self, server_id: str, tool_name: str) -> bool:
+        rule, _ = self.rule_for(server_id, tool_name)
+        action = str(rule.get("action", "confirm"))
+        return not (bool(self.data.get("hide_denied_tools", True)) and action == "deny")
+
+    def evaluate(self, server_id: str, tool_name: str, arguments: dict[str, Any]) -> MCPDecision:
+        self.reload_if_changed()
+        rule, rule_id = self.rule_for(server_id, tool_name)
+        args = json.loads(json.dumps(arguments))
+        action = str(rule.get("action", self.data.get("default_action", "confirm")))
+        mode = str(self.data.get("mode", "enforce"))
+        risks: list[str] = []
+        transformed: list[str] = []
+
+        reason = f"Matched {rule_id}."
+        path_error = self._check_paths(rule, args)
+        if path_error:
+            action, reason = "deny", path_error
+            risks.append("filesystem")
+
+        command_error = self._check_command(rule, args)
+        if command_error:
+            action, reason = "deny", command_error
+            risks.append("shell")
+
+        host_error = self._check_host(rule, args)
+        if host_error:
+            action, reason = "deny", host_error
+            risks.append("network")
+
+        sql_error = self._check_sql(rule, args)
+        if sql_error:
+            action, reason = "deny", sql_error
+            risks.append("database")
+
+        payload_limit = int(rule.get("max_payload_bytes", 0) or 0)
+        if payload_limit and len(json.dumps(args).encode("utf-8")) > payload_limit:
+            action, reason = "deny", "Payload exceeds the configured byte limit."
+            risks.append("large_payload")
+
+        if action == "transform":
+            for key in rule.get("remove_fields", []):
+                if key in args:
+                    args.pop(key)
+                    transformed.append(str(key))
+            if "max_limit" in rule and isinstance(args.get("limit"), int):
+                bounded = min(args["limit"], int(rule["max_limit"]))
+                if bounded != args["limit"]:
+                    args["limit"] = bounded
+                    transformed.append("limit")
+
+        if action == "rate_limit":
+            action, reason = self._rate_limit(server_id, tool_name, rule)
+
+        if mode == "shadow" and action in {"deny", "confirm"}:
+            action = "shadow_deny"
+            reason = f"Shadow mode: {reason}"
+
+        return MCPDecision(
+            action=action,
+            reason=reason,
+            rule_id=rule_id,
+            policy_version=self.version,
+            arguments=args,
+            argument_hash=argument_fingerprint(args),
+            mode=mode,
+            risk_tags=sorted(set(risks)),
+            transformed_fields=transformed,
+        )
+
+    def _check_paths(self, rule: dict[str, Any], arguments: dict[str, Any]) -> str | None:
+        patterns = [str(item) for item in rule.get("paths", [])]
+        if not patterns:
+            return None
+        for key, value in arguments.items():
+            if key.lower() not in PATH_KEYS or not isinstance(value, str):
+                continue
+            candidate = Path(value)
+            resolved = (self.project_root / candidate).resolve() if not candidate.is_absolute() else candidate.resolve()
+            try:
+                relative = resolved.relative_to(self.project_root).as_posix()
+            except ValueError:
+                return f"Path escapes project root: {value}"
+            normalized = f"./{relative}"
+            if not any(fnmatch.fnmatchcase(normalized, pattern) for pattern in patterns):
+                return f"Path is outside allowed patterns: {value}"
+        return None
+
+    @staticmethod
+    def _check_command(rule: dict[str, Any], arguments: dict[str, Any]) -> str | None:
+        patterns = [str(item) for item in rule.get("deny_patterns", [])]
+        if not patterns:
+            return None
+        raw = arguments.get("argv", arguments.get("command"))
+        if isinstance(raw, list):
+            command = shlex.join(str(item) for item in raw)
+        elif isinstance(raw, str):
+            command = raw
+        else:
+            return None
+        if any(fnmatch.fnmatch(command, pattern) or pattern in command for pattern in patterns):
+            return "Command matched a denied pattern."
+        return None
+
+    @staticmethod
+    def _check_host(rule: dict[str, Any], arguments: dict[str, Any]) -> str | None:
+        hosts = [str(item).lower() for item in rule.get("hosts", [])]
+        if not hosts:
+            return None
+        url = arguments.get("url") or arguments.get("uri")
+        if not isinstance(url, str):
+            return None
+        host = (urlparse(url).hostname or "").lower()
+        if not any(fnmatch.fnmatchcase(host, pattern) for pattern in hosts):
+            return f"URL host is not allowed: {host or 'missing'}"
+        return None
+
+    @staticmethod
+    def _check_sql(rule: dict[str, Any], arguments: dict[str, Any]) -> str | None:
+        operations = [str(item).upper() for item in rule.get("sql_operations", [])]
+        query = arguments.get("query") or arguments.get("sql")
+        if not operations or not isinstance(query, str):
+            return None
+        operation = query.lstrip().split(None, 1)[0].upper() if query.strip() else ""
+        if operation not in operations:
+            return f"SQL operation is not allowed: {operation or 'empty'}"
+        return None
+
+    def _rate_limit(
+        self, server_id: str, tool_name: str, rule: dict[str, Any]
+    ) -> tuple[str, str]:
+        now = time.monotonic()
+        window_seconds = max(1, int(rule.get("window_seconds", 60)))
+        limit = max(1, int(rule.get("limit", 10)))
+        key = f"{server_id}:{tool_name}"
+        window = self._rate_windows[key]
+        while window and window[0] <= now - window_seconds:
+            window.popleft()
+        if len(window) >= limit:
+            return "deny", "Rate limit exceeded."
+        window.append(now)
+        return "allow", "Allowed within rate limit."

app/mcp/presets/development.yml

@@ -0,0 +1,25 @@
+version: 1
+mode: enforce
+default_action: confirm
+hide_denied_tools: true
+servers:
+  filesystem:
+    tools:
+      read_file: {action: allow, paths: ["./**"]}
+      write_file: {action: confirm, paths: ["./**"]}
+      delete_file: {action: deny}
+  shell:
+    tools:
+      execute_command:
+        action: confirm
+        deny_patterns: ["rm -rf", "curl * | sh", "git push*"]
+  http:
+    tools:
+      fetch:
+        action: allow
+        hosts: ["api.github.com", "pypi.org", "registry.npmjs.org"]
+  database:
+    tools:
+      query:
+        action: allow
+        sql_operations: ["SELECT", "EXPLAIN", "PRAGMA"]

app/mcp/presets/filesystem.yml

@@ -0,0 +1,18 @@
+version: 1
+mode: enforce
+default_action: confirm
+hide_denied_tools: true
+servers:
+  filesystem:
+    tools:
+      read_file:
+        action: allow
+        paths: ["./**"]
+      list_directory:
+        action: allow
+        paths: ["./**"]
+      write_file:
+        action: confirm
+        paths: ["./**"]
+      delete_file:
+        action: deny