agent_os_kernel 3.1.0__py3-none-any.whl

agent_os/integrations/rbac.py

@@ -0,0 +1,143 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""
+Role-Based Access Control (RBAC) for Agent OS.
+
+Provides role assignment, policy lookup, and permission checking for agents.
+"""
+
+from enum import Enum
+
+import yaml
+
+from agent_os.integrations.base import GovernancePolicy
+
+
+class Role(Enum):
+    """Standard roles for agent access control."""
+    READER = "reader"
+    WRITER = "writer"
+    ADMIN = "admin"
+    AUDITOR = "auditor"
+
+
+# Action permissions per role
+_ROLE_PERMISSIONS: dict[Role, set[str]] = {
+    Role.READER: {"read"},
+    Role.WRITER: {"read", "write", "search"},
+    Role.ADMIN: {"read", "write", "search", "admin", "delete", "audit"},
+    Role.AUDITOR: {"read", "search", "audit"},
+}
+
+# Default policy templates per role
+_DEFAULT_POLICIES: dict[Role, GovernancePolicy] = {
+    Role.READER: GovernancePolicy(
+        max_tool_calls=0,
+        allowed_tools=[],
+        require_human_approval=True,
+    ),
+    Role.WRITER: GovernancePolicy(
+        max_tool_calls=5,
+        allowed_tools=["read", "write", "search"],
+        require_human_approval=False,
+    ),
+    Role.ADMIN: GovernancePolicy(
+        max_tool_calls=50,
+        allowed_tools=[],
+        max_tokens=16384,
+        require_human_approval=False,
+    ),
+    Role.AUDITOR: GovernancePolicy(
+        max_tool_calls=5,
+        allowed_tools=["read", "search", "audit"],
+        log_all_calls=True,
+        require_human_approval=False,
+    ),
+}
+
+DEFAULT_ROLE = Role.READER
+
+
+class RBACManager:
+    """Manages role-based access control for agents.
+
+    Assigns roles to agents, resolves governance policies per role,
+    and checks action permissions. Unknown agents receive the READER role.
+    """
+
+    def __init__(self) -> None:
+        self._roles: dict[str, Role] = {}
+        self._custom_policies: dict[Role, GovernancePolicy] = {}
+        self._custom_permissions: dict[Role, set[str]] = {}
+
+    def assign_role(self, agent_id: str, role: Role) -> None:
+        """Assign a role to an agent."""
+        self._roles[agent_id] = role
+
+    def get_role(self, agent_id: str) -> Role:
+        """Return the role for an agent, defaulting to READER."""
+        return self._roles.get(agent_id, DEFAULT_ROLE)
+
+    def get_policy(self, agent_id: str) -> GovernancePolicy:
+        """Return the governance policy template for an agent's role."""
+        role = self.get_role(agent_id)
+        if role in self._custom_policies:
+            return self._custom_policies[role]
+        return _DEFAULT_POLICIES[role]
+
+    def has_permission(self, agent_id: str, action: str) -> bool:
+        """Check whether an agent is permitted to perform an action."""
+        role = self.get_role(agent_id)
+        perms = self._custom_permissions.get(role, _ROLE_PERMISSIONS.get(role, set()))
+        return action in perms
+
+    def remove_role(self, agent_id: str) -> None:
+        """Remove a role assignment, reverting the agent to the default role."""
+        self._roles.pop(agent_id, None)
+
+    # ── YAML serialisation ────────────────────────────────────
+
+    def to_yaml(self, path: str) -> None:
+        """Save current role assignments and custom definitions to a YAML file."""
+        data: dict[str, object] = {
+            "assignments": {aid: role.value for aid, role in self._roles.items()},
+        }
+        if self._custom_policies:
+            data["custom_policies"] = {
+                role.value: yaml.safe_load(policy.to_yaml())
+                for role, policy in self._custom_policies.items()
+            }
+        if self._custom_permissions:
+            data["custom_permissions"] = {
+                role.value: sorted(perms)
+                for role, perms in self._custom_permissions.items()
+            }
+        with open(path, "w", encoding="utf-8") as f:
+            yaml.dump(data, f, default_flow_style=False, sort_keys=False)
+
+    @classmethod
+    def from_yaml(cls, path: str) -> "RBACManager":
+        """Load an RBACManager from a YAML file."""
+        with open(path, encoding="utf-8") as f:
+            data = yaml.safe_load(f)
+        if not isinstance(data, dict):
+            raise ValueError(f"Expected a YAML mapping, got {type(data).__name__}")
+
+        mgr = cls()
+
+        # Role assignments
+        for agent_id, role_value in data.get("assignments", {}).items():
+            mgr.assign_role(agent_id, Role(role_value))
+
+        # Custom policies
+        for role_value, policy_dict in data.get("custom_policies", {}).items():
+            role = Role(role_value)
+            yaml_str = yaml.dump(policy_dict, default_flow_style=False)
+            mgr._custom_policies[role] = GovernancePolicy.from_yaml(yaml_str)
+
+        # Custom permissions
+        for role_value, perms_list in data.get("custom_permissions", {}).items():
+            role = Role(role_value)
+            mgr._custom_permissions[role] = set(perms_list)
+
+        return mgr

agent_os/integrations/registry.py

@@ -0,0 +1,113 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""
+Adapter Registry with Auto-Discovery
+
+Provides a central registry for framework adapters, with support for
+manual registration, decorator-based registration, and automatic
+discovery of BaseIntegration subclasses.
+"""
+
+import importlib
+import inspect
+import logging
+import pkgutil
+
+logger = logging.getLogger(__name__)
+
+from .base import BaseIntegration
+
+
+class AdapterRegistry:
+    """Singleton registry for framework adapters."""
+
+    _instance: "AdapterRegistry | None" = None
+    _adapters: dict[str, type[BaseIntegration]]
+
+    def __new__(cls) -> "AdapterRegistry":
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+            cls._instance._adapters = {}
+        return cls._instance
+
+    def register(self, name: str, adapter_class: type[BaseIntegration]) -> None:
+        """Register an adapter class under the given name.
+
+        Raises:
+            ValueError: If *name* is already registered.
+            TypeError: If *adapter_class* is not a BaseIntegration subclass.
+        """
+        if not (isinstance(adapter_class, type) and issubclass(adapter_class, BaseIntegration)):
+            raise TypeError(
+                f"adapter_class must be a subclass of BaseIntegration, "
+                f"got {adapter_class!r}"
+            )
+        if name in self._adapters:
+            raise ValueError(f"Adapter '{name}' is already registered")
+        self._adapters[name] = adapter_class
+
+    def get(self, name: str) -> type[BaseIntegration]:
+        """Return the adapter class registered under *name*.
+
+        Raises:
+            KeyError: If no adapter is registered with that name.
+        """
+        try:
+            return self._adapters[name]
+        except KeyError:
+            raise KeyError(f"No adapter registered with name '{name}'") from None
+
+    def list_adapters(self) -> list[str]:
+        """Return sorted list of registered adapter names."""
+        return sorted(self._adapters)
+
+    def clear(self) -> None:
+        """Remove all registered adapters (useful for testing)."""
+        self._adapters.clear()
+
+    @classmethod
+    def auto_discover(cls) -> "AdapterRegistry":
+        """Scan the integrations package and register all BaseIntegration subclasses.
+
+        Each subclass is registered under its class name.  Returns the
+        (singleton) registry instance.
+        """
+        registry = cls()
+        package = importlib.import_module("agent_os.integrations")
+        package_path = package.__path__
+
+        for _importer, modname, _ispkg in pkgutil.iter_modules(package_path):
+            if modname.startswith("_"):
+                continue
+            full_name = f"agent_os.integrations.{modname}"
+            try:
+                mod = importlib.import_module(full_name)
+            except Exception:  # noqa: BLE001 — optional adapter may not be installed
+                logger.debug("Failed to import adapter module %s", full_name, exc_info=True)
+                continue
+            for _attr_name, obj in inspect.getmembers(mod, inspect.isclass):
+                if (
+                    issubclass(obj, BaseIntegration)
+                    and obj is not BaseIntegration
+                    and obj.__name__ not in registry._adapters
+                ):
+                    registry._adapters[obj.__name__] = obj
+
+        return registry
+
+
+def register_adapter(name: str):
+    """Class decorator that registers an adapter in the global registry.
+
+    Usage::
+
+        @register_adapter("my_framework")
+        class MyAdapter(BaseIntegration):
+            ...
+    """
+
+    def decorator(cls: type[BaseIntegration]) -> type[BaseIntegration]:
+        AdapterRegistry().register(name, cls)
+        return cls
+
+    return decorator

agent_os/integrations/scope_guard.py

@@ -0,0 +1,303 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""Scope Guard — prevents agent actions from exceeding configured scope limits.
+
+Evaluates file count, line count, and scope drift against per-agent
+configuration to produce PASS / SOFT_FAIL / HARD_FAIL decisions.
+Integrates with the PolicyEngine for governance audit trails.
+
+Usage::
+
+    from agent_os.integrations.scope_guard import ScopeGuard, ScopeConfig
+
+    config = ScopeConfig(max_files=10, max_lines=500)
+    guard = ScopeGuard()
+    result = guard.evaluate(
+        agent_id="implementer",
+        config=config,
+        changed_files=["src/main.py", "tests/test_main.py"],
+        insertions=120,
+        deletions=30,
+    )
+    print(result.decision)  # "PASS"
+"""
+
+from __future__ import annotations
+
+import logging
+import subprocess
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ScopeConfig:
+    """Per-agent scope configuration.
+
+    Attributes:
+        max_files: Maximum number of files an agent may change.
+        max_lines: Maximum total lines (insertions + deletions) allowed.
+        mode: Guard mode — ``"on"`` (default) to enforce, ``"off"`` to skip.
+        drift_detection: Whether to evaluate drift indicators.
+    """
+
+    max_files: int = 10
+    max_lines: int = 500
+    mode: str = "on"
+    drift_detection: bool = True
+
+
+@dataclass
+class ScopeEvaluation:
+    """Result of a scope guard evaluation.
+
+    Attributes:
+        decision: One of ``"PASS"``, ``"SOFT_FAIL"``, ``"HARD_FAIL"``.
+        files_changed: Number of files changed.
+        lines_changed: Total lines changed (insertions + deletions).
+        max_files: Configured file limit.
+        max_lines: Configured line limit.
+        drift_indicators: Drift indicator dicts passed in for audit.
+        reason: Human-readable explanation of the decision.
+        excess_files: File paths that exceed the file limit.
+    """
+
+    decision: str
+    files_changed: int
+    lines_changed: int
+    max_files: int
+    max_lines: int
+    drift_indicators: list[dict[str, Any]] = field(default_factory=list)
+    reason: str = ""
+    excess_files: list[str] = field(default_factory=list)
+
+
+def _escalate(current: str, proposed: str) -> str:
+    """Return the more severe of two decisions."""
+    severity = {"PASS": 0, "SOFT_FAIL": 1, "HARD_FAIL": 2}
+    if severity.get(proposed, 0) > severity.get(current, 0):
+        return proposed
+    return current
+
+
+def _get_diff_stats(
+    repo_path: str, base_branch: str = "main"
+) -> tuple[list[str], int, int]:
+    """Return ``(changed_files, insertions, deletions)`` via ``git diff --numstat``.
+
+    Args:
+        repo_path: Path to a git repository or worktree.
+        base_branch: Branch to diff against.
+
+    Returns:
+        Tuple of (file paths, total insertions, total deletions).
+    """
+    try:
+        result = subprocess.run(
+            ["git", "diff", "--numstat", base_branch],
+            cwd=repo_path,
+            capture_output=True,
+            text=True,
+            timeout=30,
+        )
+    except (subprocess.TimeoutExpired, FileNotFoundError) as exc:
+        logger.warning("_get_diff_stats failed: %s", exc)
+        return [], 0, 0
+
+    files: list[str] = []
+    insertions = 0
+    deletions = 0
+    for line in result.stdout.strip().splitlines():
+        parts = line.split("\t")
+        if len(parts) == 3:
+            ins = int(parts[0]) if parts[0] != "-" else 0
+            dels = int(parts[1]) if parts[1] != "-" else 0
+            insertions += ins
+            deletions += dels
+            files.append(parts[2])
+    return files, insertions, deletions
+
+
+class ScopeGuard:
+    """Evaluates whether agent changes are within configured scope limits.
+
+    Optionally records governance audit events through a *policy_engine*.
+    The policy engine, when provided, must expose a
+    ``record_event(event: dict)`` method.
+
+    Args:
+        policy_engine: Optional governance policy engine for audit trails.
+    """
+
+    def __init__(self, policy_engine: Optional[Any] = None) -> None:
+        self._policy_engine = policy_engine
+
+    # ── public API ──────────────────────────────────────────
+
+    def evaluate(
+        self,
+        agent_id: str,
+        config: ScopeConfig,
+        changed_files: list[str],
+        insertions: int,
+        deletions: int,
+        drift_indicators: Optional[list[dict[str, Any]]] = None,
+    ) -> ScopeEvaluation:
+        """Evaluate whether an agent's changes are within scope.
+
+        Decision logic:
+            1. ``config.mode == "off"`` → always ``PASS``.
+            2. files > ``max_files × 2`` **or** lines > ``max_lines × 2`` → ``HARD_FAIL``.
+            3. files > ``max_files`` **or** lines > ``max_lines`` → ``SOFT_FAIL``.
+            4. Any drift indicator with ``severity == "warning"`` → ``SOFT_FAIL``.
+            5. Otherwise → ``PASS``.
+
+        Args:
+            agent_id: Unique agent identifier.
+            config: Scope configuration for this agent.
+            changed_files: List of changed file paths.
+            insertions: Total lines added.
+            deletions: Total lines removed.
+            drift_indicators: Optional list of drift indicator dicts.  Each
+                dict may contain ``severity`` (``"info"`` | ``"warning"``).
+
+        Returns:
+            A :class:`ScopeEvaluation` with the decision and supporting data.
+        """
+        max_files = config.max_files
+        max_lines = config.max_lines
+        files_changed = len(changed_files)
+        lines_changed = insertions + deletions
+        drift_indicators = drift_indicators or []
+
+        # Mode "off" → always pass
+        if config.mode == "off":
+            evaluation = ScopeEvaluation(
+                decision="PASS",
+                files_changed=files_changed,
+                lines_changed=lines_changed,
+                max_files=max_files,
+                max_lines=max_lines,
+                reason="Scope guard disabled (mode=off)",
+            )
+            self._record(agent_id, evaluation)
+            return evaluation
+
+        reasons: list[str] = []
+        decision = "PASS"
+
+        # Check file count
+        if max_files > 0 and files_changed > max_files:
+            if files_changed > max_files * 2:
+                decision = "HARD_FAIL"
+                reasons.append(
+                    f"files changed ({files_changed}) exceeds 2× limit "
+                    f"({max_files * 2})"
+                )
+            else:
+                decision = _escalate(decision, "SOFT_FAIL")
+                reasons.append(
+                    f"files changed ({files_changed}) exceeds limit ({max_files})"
+                )
+
+        # Check line count
+        if max_lines > 0 and lines_changed > max_lines:
+            if lines_changed > max_lines * 2:
+                decision = "HARD_FAIL"
+                reasons.append(
+                    f"lines changed ({lines_changed}) exceeds 2× limit "
+                    f"({max_lines * 2})"
+                )
+            else:
+                decision = _escalate(decision, "SOFT_FAIL")
+                reasons.append(
+                    f"lines changed ({lines_changed}) exceeds limit ({max_lines})"
+                )
+
+        # Check drift indicators
+        if config.drift_detection and drift_indicators:
+            warnings = [
+                d for d in drift_indicators if d.get("severity") == "warning"
+            ]
+            if warnings:
+                decision = _escalate(decision, "SOFT_FAIL")
+                reasons.append(
+                    f"{len(warnings)} scope drift warning(s) detected"
+                )
+
+        # Excess files for downstream remediation
+        excess_files: list[str] = []
+        if max_files > 0 and files_changed > max_files:
+            excess_files = changed_files[max_files:]
+
+        reason = "; ".join(reasons) if reasons else "All scope checks passed"
+
+        evaluation = ScopeEvaluation(
+            decision=decision,
+            files_changed=files_changed,
+            lines_changed=lines_changed,
+            max_files=max_files,
+            max_lines=max_lines,
+            drift_indicators=drift_indicators,
+            reason=reason,
+            excess_files=excess_files,
+        )
+
+        self._record(agent_id, evaluation)
+        return evaluation
+
+    def evaluate_from_git(
+        self,
+        agent_id: str,
+        config: ScopeConfig,
+        repo_path: str,
+        base_branch: str = "main",
+        drift_indicators: Optional[list[dict[str, Any]]] = None,
+    ) -> ScopeEvaluation:
+        """Convenience wrapper that reads diff stats from *repo_path*.
+
+        Args:
+            agent_id: Unique agent identifier.
+            config: Scope configuration.
+            repo_path: Path to the git repository.
+            base_branch: Branch to diff against (default ``"main"``).
+            drift_indicators: Optional drift indicator dicts.
+
+        Returns:
+            A :class:`ScopeEvaluation`.
+        """
+        changed_files, insertions, deletions = _get_diff_stats(
+            repo_path, base_branch
+        )
+        return self.evaluate(
+            agent_id=agent_id,
+            config=config,
+            changed_files=changed_files,
+            insertions=insertions,
+            deletions=deletions,
+            drift_indicators=drift_indicators,
+        )
+
+    # ── internal helpers ────────────────────────────────────
+
+    def _record(self, agent_id: str, evaluation: ScopeEvaluation) -> None:
+        """Record the evaluation as an audit event if a policy engine is set."""
+        if self._policy_engine is None:
+            return
+        try:
+            self._policy_engine.record_event(
+                {
+                    "type": "scope_evaluation",
+                    "agent_id": agent_id,
+                    "decision": evaluation.decision,
+                    "files_changed": evaluation.files_changed,
+                    "max_files": evaluation.max_files,
+                    "lines_changed": evaluation.lines_changed,
+                    "max_lines": evaluation.max_lines,
+                    "reason": evaluation.reason,
+                }
+            )
+        except Exception:  # pragma: no cover — best-effort audit
+            logger.exception("Failed to record scope evaluation event")