loom-agent 0.0.1__py3-none-any.whl → 0.0.3__py3-none-any.whl

loom/security/models.py

@@ -0,0 +1,85 @@
+"""
+Security Models
+
+Data models for security validation results.
+"""
+
+from enum import Enum
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+
+class RiskLevel(str, Enum):
+    """Security risk levels for tool execution."""
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+    CRITICAL = "critical"
+
+    def __lt__(self, other):
+        """Allow comparison of risk levels."""
+        order = {
+            RiskLevel.LOW: 0,
+            RiskLevel.MEDIUM: 1,
+            RiskLevel.HIGH: 2,
+            RiskLevel.CRITICAL: 3
+        }
+        return order[self] < order[other]
+
+    def __gt__(self, other):
+        order = {
+            RiskLevel.LOW: 0,
+            RiskLevel.MEDIUM: 1,
+            RiskLevel.HIGH: 2,
+            RiskLevel.CRITICAL: 3
+        }
+        return order[self] > order[other]
+
+
+@dataclass
+class SecurityDecision:
+    """
+    Result of security validation.
+
+    Attributes:
+        allow: Whether the operation is allowed
+        risk_level: Assessed risk level
+        reason: Human-readable reason for decision
+        failed_layers: List of security layers that failed
+        warnings: Non-blocking warnings
+    """
+    allow: bool
+    risk_level: RiskLevel
+    reason: str
+    failed_layers: List[str] = field(default_factory=list)
+    warnings: List[str] = field(default_factory=list)
+
+    @property
+    def is_safe(self) -> bool:
+        """Check if decision is safe to execute."""
+        return self.allow and self.risk_level in [RiskLevel.LOW, RiskLevel.MEDIUM]
+
+    def __repr__(self) -> str:
+        status = "ALLOWED" if self.allow else "BLOCKED"
+        return f"SecurityDecision({status}, risk={self.risk_level.value}, reason='{self.reason}')"
+
+
+@dataclass
+class PathSecurityResult:
+    """
+    Result of path security validation.
+
+    Attributes:
+        is_safe: Whether the path is safe to access
+        normalized_path: Resolved absolute path
+        warnings: Non-critical warnings
+        violations: Security violations found
+    """
+    is_safe: bool
+    normalized_path: str
+    warnings: List[str] = field(default_factory=list)
+    violations: List[str] = field(default_factory=list)
+
+    def __repr__(self) -> str:
+        status = "SAFE" if self.is_safe else "UNSAFE"
+        return f"PathSecurityResult({status}, violations={len(self.violations)})"

loom/security/path_validator.py

@@ -0,0 +1,128 @@
+"""
+Path Security Validator
+
+Validates file paths for security issues like path traversal and system path access.
+"""
+
+from pathlib import Path
+from typing import List, Optional
+from loom.security.models import PathSecurityResult
+
+
+# System paths that should never be accessed
+SYSTEM_PATHS = [
+    "/etc",
+    "/sys",
+    "/proc",
+    "/dev",
+    "/boot",
+    "/root",
+    "/var/log",
+    "/bin",
+    "/sbin",
+    "/usr/bin",
+    "/usr/sbin",
+]
+
+
+class PathSecurityValidator:
+    """
+    Validate file paths for security issues.
+
+    Checks for:
+    - Path traversal attacks (../)
+    - Absolute paths outside working directory
+    - System path access
+    - Invalid path constructions
+
+    Example:
+        ```python
+        validator = PathSecurityValidator(working_dir=Path("/Users/project"))
+
+        # Safe path
+        result = validator.validate_path("src/main.py")
+        assert result.is_safe
+
+        # Path traversal attempt
+        result = validator.validate_path("../../etc/passwd")
+        assert not result.is_safe
+        ```
+    """
+
+    def __init__(self, working_dir: Optional[Path] = None):
+        """
+        Initialize path validator.
+
+        Args:
+            working_dir: Working directory to enforce boundaries (defaults to cwd)
+        """
+        self.working_dir = (working_dir or Path.cwd()).resolve()
+
+    def validate_path(self, path: str) -> PathSecurityResult:
+        """
+        Validate a file path for security issues.
+
+        Args:
+            path: File path to validate
+
+        Returns:
+            PathSecurityResult with validation outcome
+        """
+        violations: List[str] = []
+        warnings: List[str] = []
+        normalized_path = path
+
+        # Check 1: Detect explicit path traversal
+        if ".." in path:
+            violations.append("Path traversal detected (..)")
+
+        # Check 2: Resolve and validate boundaries
+        try:
+            # Handle both relative and absolute paths
+            if Path(path).is_absolute():
+                resolved = Path(path).resolve()
+            else:
+                resolved = (self.working_dir / path).resolve()
+
+            normalized_path = str(resolved)
+
+            # Check if within working directory
+            try:
+                resolved.relative_to(self.working_dir)
+            except ValueError:
+                violations.append(
+                    f"Path outside working directory: {resolved} "
+                    f"(working dir: {self.working_dir})"
+                )
+
+            # Check 3: System path protection
+            for sys_path in SYSTEM_PATHS:
+                if str(resolved).startswith(sys_path):
+                    violations.append(
+                        f"System path access denied: {sys_path}"
+                    )
+                    break
+
+        except Exception as e:
+            violations.append(f"Path resolution failed: {e}")
+
+        is_safe = len(violations) == 0
+
+        return PathSecurityResult(
+            is_safe=is_safe,
+            normalized_path=normalized_path,
+            warnings=warnings,
+            violations=violations
+        )
+
+    def is_safe_path(self, path: str) -> bool:
+        """
+        Quick check if path is safe.
+
+        Args:
+            path: Path to check
+
+        Returns:
+            True if path is safe
+        """
+        return self.validate_path(path).is_safe

loom/security/validator.py

@@ -0,0 +1,346 @@
+"""
+Security Validator
+
+Multi-layer security validation system for tool execution.
+"""
+
+from pathlib import Path
+from typing import Dict, List, Optional
+import time
+
+from loom.security.models import RiskLevel, SecurityDecision
+from loom.security.path_validator import PathSecurityValidator
+from loom.core.types import ToolCall
+from loom.core.permissions import PermissionManager, PermissionAction
+from loom.interfaces.tool import BaseTool
+
+
+class SecurityValidator:
+    """
+    Multi-layer security validator for tool execution.
+
+    Provides 4 layers of independent security checks:
+    1. Permission rules (policy-based access control)
+    2. Tool category validation (destructive/network/general)
+    3. Path security (traversal detection, working dir enforcement)
+    4. Sandbox support (automatic sandboxing recommendations)
+
+    Example:
+        ```python
+        validator = SecurityValidator(
+            working_dir=Path("/Users/project"),
+            allowed_categories=["general", "network"],
+            require_confirmation_for=["destructive"]
+        )
+
+        decision = await validator.validate(
+            tool_call=ToolCall(name="write_file", arguments={...}),
+            tool=WriteFileTool(),
+            context={"user_approved": False}
+        )
+
+        if decision.allow:
+            await tool.run(**tool_call.arguments)
+        else:
+            print(f"Blocked: {decision.reason}")
+        ```
+    """
+
+    def __init__(
+        self,
+        working_dir: Optional[Path] = None,
+        allowed_categories: Optional[List[str]] = None,
+        require_confirmation_for: Optional[List[str]] = None,
+        permission_manager: Optional[PermissionManager] = None,
+        enable_sandbox: bool = True
+    ):
+        """
+        Initialize security validator.
+
+        Args:
+            working_dir: Working directory for path validation
+            allowed_categories: Allowed tool categories
+            require_confirmation_for: Categories requiring confirmation
+            permission_manager: Optional permission manager
+            enable_sandbox: Enable sandbox recommendations
+        """
+        self.working_dir = working_dir or Path.cwd()
+        self.allowed_categories = allowed_categories or ["general", "network", "destructive"]
+        self.require_confirmation_for = require_confirmation_for or ["destructive"]
+        self.permission_manager = permission_manager
+        self.enable_sandbox = enable_sandbox
+
+        # Initialize sub-validators
+        self.path_validator = PathSecurityValidator(working_dir=self.working_dir)
+
+        # Audit log
+        self.audit_log: List[Dict] = []
+
+    async def validate(
+        self,
+        tool_call: ToolCall,
+        tool: BaseTool,
+        context: Optional[Dict] = None
+    ) -> SecurityDecision:
+        """
+        Validate tool execution through all 4 security layers.
+
+        Args:
+            tool_call: Tool call to validate
+            tool: Tool instance
+            context: Additional context (user_approved, etc.)
+
+        Returns:
+            SecurityDecision with allow/deny and risk assessment
+        """
+        context = context or {}
+        failed_layers: List[str] = []
+        warnings: List[str] = []
+        max_risk = RiskLevel.LOW
+
+        # Layer 1: Permission Rules
+        layer1_result = await self.layer1_permission_check(tool_call, tool, context)
+        if not layer1_result.allow:
+            failed_layers.append("permission")
+            max_risk = max(max_risk, layer1_result.risk_level)
+
+        # Layer 2: Tool Category Validation
+        layer2_result = await self.layer2_category_check(tool, context)
+        if not layer2_result.allow:
+            failed_layers.append("category")
+            max_risk = max(max_risk, layer2_result.risk_level)
+
+        # Layer 3: Path Security
+        layer3_result = await self.layer3_path_security(tool_call, tool)
+        if not layer3_result.allow:
+            failed_layers.append("path_security")
+            max_risk = max(max_risk, layer3_result.risk_level)
+
+        # Layer 4: Sandbox Support
+        layer4_result = await self.layer4_sandbox_check(tool, context)
+        if layer4_result.warnings:
+            warnings.extend(layer4_result.warnings)
+        max_risk = max(max_risk, layer4_result.risk_level)
+
+        # Aggregate decision
+        allow = len(failed_layers) == 0
+        reason = self._build_reason(failed_layers, warnings)
+
+        decision = SecurityDecision(
+            allow=allow,
+            risk_level=max_risk,
+            reason=reason,
+            failed_layers=failed_layers,
+            warnings=warnings
+        )
+
+        # Audit log
+        self._log_decision(tool_call, tool, decision)
+
+        return decision
+
+    async def layer1_permission_check(
+        self,
+        tool_call: ToolCall,
+        tool: BaseTool,
+        context: Dict
+    ) -> SecurityDecision:
+        """
+        Layer 1: Check permission policy.
+
+        Integrates with existing PermissionManager.
+        """
+        if not self.permission_manager:
+            # No permission manager - allow by default
+            return SecurityDecision(
+                allow=True,
+                risk_level=RiskLevel.LOW,
+                reason="No permission manager configured"
+            )
+
+        action = self.permission_manager.check(tool_call.name, tool_call.arguments)
+
+        if action == PermissionAction.DENY:
+            return SecurityDecision(
+                allow=False,
+                risk_level=RiskLevel.HIGH,
+                reason=f"Tool {tool_call.name} denied by permission policy"
+            )
+        elif action == PermissionAction.ASK:
+            # Check if user already approved
+            if context.get("user_approved", False):
+                return SecurityDecision(
+                    allow=True,
+                    risk_level=RiskLevel.MEDIUM,
+                    reason="User approved"
+                )
+            else:
+                return SecurityDecision(
+                    allow=False,
+                    risk_level=RiskLevel.MEDIUM,
+                    reason=f"Tool {tool_call.name} requires user confirmation"
+                )
+        else:  # ALLOW
+            return SecurityDecision(
+                allow=True,
+                risk_level=RiskLevel.LOW,
+                reason="Allowed by permission policy"
+            )
+
+    async def layer2_category_check(
+        self,
+        tool: BaseTool,
+        context: Dict
+    ) -> SecurityDecision:
+        """
+        Layer 2: Validate tool category.
+
+        - Destructive tools require confirmation
+        - Network tools checked against whitelist
+        - Unknown categories treated as high-risk
+        """
+        category = getattr(tool, "category", "unknown")
+
+        # Check if category is allowed
+        if category not in self.allowed_categories:
+            return SecurityDecision(
+                allow=False,
+                risk_level=RiskLevel.HIGH,
+                reason=f"Tool category '{category}' not in allowed categories"
+            )
+
+        # Check if confirmation required
+        if category in self.require_confirmation_for:
+            if not context.get("user_approved", False):
+                return SecurityDecision(
+                    allow=False,
+                    risk_level=RiskLevel.MEDIUM,
+                    reason=f"Category '{category}' requires user confirmation"
+                )
+
+        # Assess risk based on category
+        risk_map = {
+            "general": RiskLevel.LOW,
+            "network": RiskLevel.MEDIUM,
+            "destructive": RiskLevel.HIGH
+        }
+        risk = risk_map.get(category, RiskLevel.HIGH)
+
+        return SecurityDecision(
+            allow=True,
+            risk_level=risk,
+            reason=f"Category '{category}' allowed"
+        )
+
+    async def layer3_path_security(
+        self,
+        tool_call: ToolCall,
+        tool: BaseTool
+    ) -> SecurityDecision:
+        """
+        Layer 3: Validate file paths.
+
+        - Detect path traversal attempts (../)
+        - Enforce working directory boundaries
+        - Block system paths (/etc, /sys, etc.)
+        """
+        # Extract path arguments
+        path_args = []
+        for key in ["path", "file_path", "directory", "folder"]:
+            if key in tool_call.arguments:
+                path_args.append(tool_call.arguments[key])
+
+        # If no path arguments, skip this layer
+        if not path_args:
+            return SecurityDecision(
+                allow=True,
+                risk_level=RiskLevel.LOW,
+                reason="No path arguments to validate"
+            )
+
+        # Validate all paths
+        violations = []
+        for path in path_args:
+            result = self.path_validator.validate_path(str(path))
+            if not result.is_safe:
+                violations.extend(result.violations)
+
+        if violations:
+            return SecurityDecision(
+                allow=False,
+                risk_level=RiskLevel.CRITICAL,
+                reason=f"Path security violations: {'; '.join(violations)}"
+            )
+
+        return SecurityDecision(
+            allow=True,
+            risk_level=RiskLevel.LOW,
+            reason="All paths validated"
+        )
+
+    async def layer4_sandbox_check(
+        self,
+        tool: BaseTool,
+        context: Dict
+    ) -> SecurityDecision:
+        """
+        Layer 4: Check sandbox support.
+
+        - Recommend sandbox for safe operations
+        - Warn if sandbox unavailable for risky ops
+        """
+        warnings = []
+
+        if self.enable_sandbox:
+            # Check if tool is read-only (safe for sandbox)
+            is_read_only = getattr(tool, "is_read_only", False)
+            if is_read_only:
+                warnings.append("Consider running in sandbox for additional safety")
+
+            # Check if tool is destructive (should use sandbox)
+            category = getattr(tool, "category", "general")
+            if category == "destructive":
+                warnings.append("Destructive tool - sandbox recommended")
+
+        return SecurityDecision(
+            allow=True,  # Layer 4 never blocks, only warns
+            risk_level=RiskLevel.LOW,
+            reason="Sandbox check complete",
+            warnings=warnings
+        )
+
+    def _build_reason(self, failed_layers: List[str], warnings: List[str]) -> str:
+        """Build human-readable reason for decision."""
+        if failed_layers:
+            layers_str = ", ".join(failed_layers)
+            return f"Security check failed in layers: {layers_str}"
+        elif warnings:
+            return f"Allowed with {len(warnings)} warning(s)"
+        else:
+            return "All security checks passed"
+
+    def _log_decision(
+        self,
+        tool_call: ToolCall,
+        tool: BaseTool,
+        decision: SecurityDecision
+    ):
+        """Log security decision for audit trail."""
+        self.audit_log.append({
+            "timestamp": time.time(),
+            "tool_name": tool_call.name,
+            "tool_category": getattr(tool, "category", "unknown"),
+            "decision": decision.allow,
+            "risk_level": decision.risk_level.value,
+            "reason": decision.reason,
+            "failed_layers": decision.failed_layers,
+            "warnings": decision.warnings
+        })
+
+    def get_audit_log(self) -> List[Dict]:
+        """Get security audit log."""
+        return self.audit_log.copy()
+
+    def clear_audit_log(self):
+        """Clear audit log."""
+        self.audit_log.clear()

loom/tasks/PHASE_1_FOUNDATION/task_1.1_agent_events.md

@@ -0,0 +1,121 @@
+# Task 1.1: 创建 AgentEvent 模型
+
+**状态**: ✅ 完成
+**完成日期**: 2025-10-25
+**优先级**: P0
+**预计时间**: 1 天
+**实际时间**: 1 天
+
+---
+
+## 📋 任务概述
+
+### 目标
+
+创建统一的事件模型（AgentEvent），为 Loom 2.0 的全链路流式架构奠定基础。
+
+### 为什么需要这个任务？
+
+Loom 1.0 的问题：
+- `execute()` 返回字符串，无法获取实时进度
+- 无法区分 LLM 输出、工具执行、错误等不同事件
+- 调试困难，缺少执行过程的可观测性
+
+Loom 2.0 的解决方案：
+- 所有组件产生 `AgentEvent`
+- 24 种事件类型覆盖完整生命周期
+- 实时流式输出
+
+---
+
+## ✅ 已完成的工作
+
+### 交付物清单
+
+| 文件 | 行数 | 说明 | 状态 |
+|------|------|------|------|
+| `loom/core/events.py` | 420 | 核心事件模型 | ✅ |
+| `loom/interfaces/event_producer.py` | 120 | Protocol 定义 | ✅ |
+| `tests/unit/test_agent_events.py` | 550 | 单元测试（31 个） | ✅ |
+| `docs/agent_events_guide.md` | 650 | 使用文档 | ✅ |
+| `examples/agent_events_demo.py` | 350 | 演示代码 | ✅ |
+| **总计** | **2090** | | |
+
+### 关键特性
+
+1. **AgentEventType 枚举** - 24 种事件类型
+   - Phase Events (2)
+   - Context Events (3)
+   - RAG Events (3)
+   - LLM Events (4)
+   - Tool Events (5)
+   - Agent Events (4)
+   - Error Events (4)
+
+2. **AgentEvent 数据类**
+   - 必需字段：`type`, `timestamp`
+   - 可选字段：`phase`, `content`, `tool_call`, `tool_result`, `error`, `metadata`, `iteration`, `turn_id`
+   - 便捷构造方法：`phase_start()`, `llm_delta()`, `tool_progress()`, `tool_result()`, `agent_finish()`, `error()`
+   - 实用方法：`is_terminal()`, `is_llm_content()`, `is_tool_event()`
+
+3. **辅助类和工具**
+   - `ToolCall` - 工具调用请求模型
+   - `ToolResult` - 工具执行结果模型
+   - `EventCollector` - 事件收集和分析
+   - `EventProducer` Protocol - 事件产生器接口
+
+### 测试结果
+
+```bash
+======================== 31 passed, 1 warning in 0.16s =========================
+```
+
+- ✅ 31/31 测试通过
+- ✅ 100% 测试覆盖率
+- ✅ 包含单元测试和集成测试
+
+---
+
+## 🧪 验收标准
+
+| 标准 | 要求 | 实际 | 状态 |
+|------|------|------|------|
+| AgentEvent 模型完整 | 定义所有必需字段和方法 | 24 种事件类型 | ✅ |
+| 测试覆盖率 | ≥ 80% | 100% | ✅ |
+| 文档完整 | 使用指南 + API 文档 | 650 行文档 | ✅ |
+| 向后兼容 | 不破坏现有 API | 是（设计阶段） | ✅ |
+| 代码质量 | PEP 8, 类型提示 | 是 | ✅ |
+
+---
+
+## 📝 完成总结
+
+详见：`docs/TASK_1.1_COMPLETION_SUMMARY.md`
+
+### 关键成果
+
+1. ✅ 创建了完整的事件模型（24 种事件类型）
+2. ✅ 定义了 Protocol 接口（EventProducer 等）
+3. ✅ 编写了全面的单元测试（31 个测试，100% 通过）
+4. ✅ 提供了详细的使用文档（650+ 行）
+5. ✅ 修复了发现的问题（`__repr__` 名称冲突）
+
+### 经验教训
+
+1. **便捷构造方法很重要** - `AgentEvent.llm_delta()` 比手动创建更简洁
+2. **EventCollector 非常有用** - 简化事件处理和分析
+3. **充分的文档和示例至关重要** - 帮助理解和使用
+
+---
+
+## 🔗 相关资源
+
+- [AgentEvent 使用指南](../../../docs/agent_events_guide.md)
+- [Task 1.1 完成总结](../../../docs/TASK_1.1_COMPLETION_SUMMARY.md)
+- [演示代码](../../../examples/agent_events_demo.py)
+
+---
+
+**创建日期**: 2025-10-25
+**完成日期**: 2025-10-25
+**贡献者**: Claude Code + 用户