loom-agent 0.0.1__py3-none-any.whl

loom/core/errors.py

@@ -0,0 +1,66 @@
+from enum import Enum
+
+
+class ErrorCategory(Enum):
+    """Error classification for retry logic (T018 - US5)."""
+
+    NETWORK_ERROR = "network_error"  # httpx.TimeoutException, httpx.ConnectError - retryable
+    TIMEOUT_ERROR = "timeout_error"  # asyncio.TimeoutError - retryable
+    RATE_LIMIT_ERROR = "rate_limit_error"  # 429 responses - retryable with backoff
+    VALIDATION_ERROR = "validation_error"  # Pydantic ValidationError - non-retryable
+    PERMISSION_ERROR = "permission_error"  # PermissionDeniedError - non-retryable
+    AUTHENTICATION_ERROR = "authentication_error"  # 401/403 - non-retryable
+    SERVICE_ERROR = "service_error"  # 5xx errors - retryable
+    NOT_FOUND_ERROR = "not_found_error"  # 404, ToolNotFoundError - non-retryable
+    UNKNOWN_ERROR = "unknown_error"  # Catch-all - non-retryable by default
+
+
+class LoomException(Exception):
+    """Base exception for Loom framework."""
+
+    def __init__(self, message: str, category: ErrorCategory = ErrorCategory.UNKNOWN_ERROR) -> None:
+        super().__init__(message)
+        self.category = category
+
+
+class ToolNotFoundError(LoomException):
+    """Tool not found in registry."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message, category=ErrorCategory.NOT_FOUND_ERROR)
+
+
+class ToolValidationError(LoomException):
+    """Tool argument validation failed."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message, category=ErrorCategory.VALIDATION_ERROR)
+
+
+class PermissionDeniedError(LoomException):
+    """Permission check failed."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message, category=ErrorCategory.PERMISSION_ERROR)
+
+
+class ToolExecutionTimeout(LoomException):
+    """Tool execution exceeded timeout."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message, category=ErrorCategory.TIMEOUT_ERROR)
+
+
+class ExecutionAbortedError(LoomException):
+    """Execution aborted by user."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message, category=ErrorCategory.UNKNOWN_ERROR)
+
+
+class RecursionLimitError(LoomException):
+    """Sub-agent recursion depth exceeded (US3)."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message, category=ErrorCategory.VALIDATION_ERROR)
+

loom/core/message_queue.py

@@ -0,0 +1,167 @@
+"""Message Queue for h2A Real-Time Steering (US1)
+
+This module implements the async priority message queue that enables:
+- Real-time agent interruption and cancellation
+- Priority-based message processing
+- Graceful shutdown with partial results
+- Correlation ID tracking for multi-agent workflows
+
+Architecture: h2A async message queue (Claude Code inspired)
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Optional
+from uuid import uuid4
+
+from loom.core.types import MessageQueueItem
+from loom.core.errors import ExecutionAbortedError
+
+
+class MessageQueue:
+    """h2A async priority message queue for real-time steering.
+
+    Features:
+    - Priority-based ordering (10 = highest, 0 = lowest)
+    - FIFO within same priority level
+    - Cancel-all support for graceful shutdown
+    - Correlation ID propagation
+
+    Usage:
+        queue = MessageQueue()
+        await queue.put(MessageQueueItem(role="user", content="Task", priority=5))
+        item = await queue.get()  # Blocks until item available
+        await queue.cancel_all()  # Clear all pending items
+    """
+
+    def __init__(self, cancel_token: Optional[asyncio.Event] = None) -> None:
+        """Initialize message queue.
+
+        Args:
+            cancel_token: Optional Event to signal cancellation from outside
+        """
+        # Use asyncio.PriorityQueue for automatic priority sorting
+        # Items sorted by (priority, insertion_order) tuple
+        self._queue: asyncio.PriorityQueue = asyncio.PriorityQueue()
+        self._insertion_counter = 0  # For FIFO within same priority
+        self._cancelled = asyncio.Event()
+        self._external_cancel_token = cancel_token
+
+    async def put(self, item: MessageQueueItem) -> None:
+        """Add item to queue with priority ordering.
+
+        Args:
+            item: Message queue item with priority (0-10)
+
+        Note: Higher priority numbers are processed first.
+              Inverted for PriorityQueue (lower tuple values dequeued first).
+        """
+        if self._is_cancelled():
+            raise ExecutionAbortedError("Queue cancelled, cannot add new items")
+
+        # Invert priority for PriorityQueue (10 becomes -10, so it's dequeued first)
+        priority = -item.priority
+
+        # Use insertion counter for FIFO within same priority
+        insertion_order = self._insertion_counter
+        self._insertion_counter += 1
+
+        # PriorityQueue sorts by tuple: (priority, insertion_order, item)
+        await self._queue.put((priority, insertion_order, item))
+
+    async def get(self, timeout: Optional[float] = None) -> MessageQueueItem:
+        """Get highest priority item from queue.
+
+        Args:
+            timeout: Optional timeout in seconds (None = wait forever)
+
+        Returns:
+            MessageQueueItem: Highest priority item
+
+        Raises:
+            ExecutionAbortedError: If queue cancelled during get()
+            asyncio.TimeoutError: If timeout expires
+        """
+        try:
+            if timeout is not None:
+                priority, order, item = await asyncio.wait_for(
+                    self._queue.get(), timeout=timeout
+                )
+            else:
+                # Check cancellation before blocking
+                if self._is_cancelled():
+                    raise ExecutionAbortedError("Queue cancelled")
+
+                priority, order, item = await self._queue.get()
+
+            # Check cancellation after get (in case cancelled while waiting)
+            if self._is_cancelled():
+                # Put item back if it's cancellable
+                if item.cancellable:
+                    raise ExecutionAbortedError("Queue cancelled")
+                # Non-cancellable items still processed
+
+            return item
+
+        except asyncio.TimeoutError:
+            raise
+
+    async def cancel_all(self) -> None:
+        """Cancel all pending items and prevent new additions.
+
+        This signals graceful shutdown - current processing continues,
+        but no new items will be dequeued.
+        """
+        self._cancelled.set()
+
+        # Drain queue of cancellable items
+        drained = []
+        while not self._queue.empty():
+            try:
+                priority, order, item = self._queue.get_nowait()
+                if not item.cancellable:
+                    drained.append((priority, order, item))  # Keep non-cancellable
+            except asyncio.QueueEmpty:
+                break
+
+        # Re-add non-cancellable items
+        for priority, order, item in drained:
+            await self._queue.put((priority, order, item))
+
+    def is_empty(self) -> bool:
+        """Check if queue is empty."""
+        return self._queue.empty()
+
+    def is_cancelled(self) -> bool:
+        """Check if queue has been cancelled."""
+        return self._is_cancelled()
+
+    def _is_cancelled(self) -> bool:
+        """Internal cancellation check (includes external token)."""
+        if self._cancelled.is_set():
+            return True
+        if self._external_cancel_token and self._external_cancel_token.is_set():
+            return True
+        return False
+
+    def qsize(self) -> int:
+        """Return approximate queue size."""
+        return self._queue.qsize()
+
+    async def peek(self) -> Optional[MessageQueueItem]:
+        """Peek at highest priority item without removing it.
+
+        Returns:
+            MessageQueueItem if queue not empty, None otherwise
+        """
+        if self._queue.empty():
+            return None
+
+        # Get item
+        priority, order, item = await self._queue.get()
+
+        # Put it back
+        await self._queue.put((priority, order, item))
+
+        return item

loom/core/permission_store.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import List
+
+
+DEFAULT_DIR = Path.home() / ".loom"
+DEFAULT_PATH = DEFAULT_DIR / "config.json"
+
+
+@dataclass
+class PermissionStore:
+    """Persistent allow-list for tools (framework capability).
+
+    Schema stored at ~/.loom/config.json:
+    {
+      "allowed_tools": ["*" | "tool_name", ...]
+    }
+    """
+
+    allowed_tools: List[str] = field(default_factory=list)
+    path: Path = DEFAULT_PATH
+
+    @classmethod
+    def load_default(cls) -> "PermissionStore":
+        try:
+            if DEFAULT_PATH.exists():
+                data = json.loads(DEFAULT_PATH.read_text(encoding="utf-8"))
+                allowed = data.get("allowed_tools", [])
+                if isinstance(allowed, list):
+                    return cls(allowed_tools=[str(x) for x in allowed], path=DEFAULT_PATH)
+        except Exception:
+            pass
+        return cls(path=DEFAULT_PATH)
+
+    def is_allowed(self, tool_name: str) -> bool:
+        if "*" in self.allowed_tools:
+            return True
+        return tool_name in self.allowed_tools
+
+    def grant(self, tool_name: str) -> None:
+        if tool_name not in self.allowed_tools:
+            self.allowed_tools.append(tool_name)
+            self.allowed_tools.sort()
+
+    def revoke(self, tool_name: str) -> None:
+        try:
+            self.allowed_tools.remove(tool_name)
+        except ValueError:
+            pass
+
+    def save(self) -> None:
+        try:
+            DEFAULT_DIR.mkdir(parents=True, exist_ok=True)
+            data = {"allowed_tools": self.allowed_tools}
+            self.path.write_text(json.dumps(data, ensure_ascii=False, indent=2))
+        except Exception:
+            # best-effort; ignore IO failures
+            pass
+

loom/core/permissions.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any, Callable, Dict, Optional
+from .permission_store import PermissionStore
+
+
+class PermissionAction(str, Enum):
+    ALLOW = "allow"
+    DENY = "deny"
+    ASK = "ask"
+
+
+ConfirmHandler = Callable[[str, Dict[str, Any]], bool]
+
+
+class PermissionManager:
+    """权限网关（框架能力）：
+    - 默认策略(policy/default)
+    - 可选安全模式：启用后优先通过持久化允许列表( PermissionStore ) 进行放行；否则 ASK。
+    - 用户确认通过后可持久化授权。
+    """
+
+    def __init__(
+        self,
+        policy: Optional[Dict[str, str]] = None,
+        default: str = "deny",
+        ask_handler: Optional[ConfirmHandler] = None,
+        *,
+        safe_mode: bool = False,
+        permission_store: Optional[PermissionStore] = None,
+        persist_on_approve: bool = True,
+    ) -> None:
+        self.policy = {**(policy or {})}
+        self.default = default
+        self.ask_handler = ask_handler
+        self.safe_mode = safe_mode
+        self.permission_store = permission_store or PermissionStore.load_default()
+        self.persist_on_approve = persist_on_approve
+
+    def _policy_action(self, tool_name: str) -> PermissionAction:
+        action = self.policy.get(tool_name, self.policy.get("default", self.default))
+        try:
+            return PermissionAction(action)
+        except Exception:
+            return PermissionAction.DENY
+
+    def check(self, tool_name: str, arguments: Dict[str, Any]) -> PermissionAction:
+        # 1) Policy precedence
+        policy_action = self._policy_action(tool_name)
+        if not self.safe_mode:
+            return policy_action
+
+        # safe_mode enabled
+        if policy_action in (PermissionAction.ALLOW, PermissionAction.DENY):
+            return policy_action
+
+        # ASK or unspecified → consult store
+        if self.permission_store.is_allowed(tool_name):
+            return PermissionAction.ALLOW
+        return PermissionAction.ASK
+
+    def confirm(self, tool_name: str, arguments: Dict[str, Any]) -> bool:
+        approved = bool(self.ask_handler(tool_name, arguments)) if self.ask_handler else False
+        if approved and self.safe_mode and self.persist_on_approve and self.permission_store:
+            # persist allow for this tool
+            self.permission_store.grant(tool_name)
+            self.permission_store.save()
+        return approved

loom/core/scheduler.py

@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+from typing import Any, AsyncGenerator, Dict, Iterable, Set, Tuple
+from pathlib import Path
+
+from loom.interfaces.tool import BaseTool
+
+
+@dataclass
+class SchedulerConfig:
+    max_concurrency: int = 10
+    timeout_seconds: int = 120
+    enable_priority: bool = True
+    detect_file_conflicts: bool = True  # US4: File write conflict detection
+
+
+class Scheduler:
+    """智能调度器（并发/超时控制 + US4文件冲突检测）。"""
+
+    def __init__(self, config: SchedulerConfig | None = None) -> None:
+        self.config = config or SchedulerConfig()
+        self._semaphore = asyncio.Semaphore(self.config.max_concurrency)
+        self._file_locks: Dict[str, asyncio.Lock] = {}  # US4: Per-file locks
+
+    async def schedule_batch(
+        self, tool_calls: Iterable[Tuple[BaseTool, Dict]]
+    ) -> AsyncGenerator[Any, None]:
+        """US4: Enhanced scheduling with file conflict detection.
+
+        Groups tools into:
+        1. Concurrent-safe (parallel_safe=True) - executed in parallel
+        2. File-writing with conflicts - serialized by file path
+        3. Sequential-only (parallel_safe=False) - executed serially
+        """
+        concurrent_safe: list[Tuple[BaseTool, Dict]] = []
+        file_writers: list[Tuple[BaseTool, Dict, str]] = []  # (tool, args, file_path)
+        sequential_only: list[Tuple[BaseTool, Dict]] = []
+
+        for tool, args in tool_calls:
+            if tool.is_concurrency_safe:
+                # Check if it's a file-writing tool (US4)
+                file_path = self._detect_file_write(tool, args)
+                if file_path and self.config.detect_file_conflicts:
+                    file_writers.append((tool, args, file_path))
+                else:
+                    concurrent_safe.append((tool, args))
+            else:
+                sequential_only.append((tool, args))
+
+        # Execute concurrent-safe tools in parallel
+        if concurrent_safe:
+            async for result in self._execute_concurrent(concurrent_safe):
+                yield result
+
+        # Execute file writers with conflict detection
+        if file_writers:
+            async for result in self._execute_file_writers(file_writers):
+                yield result
+
+        # Execute sequential tools serially
+        for tool, args in sequential_only:
+            yield await self._execute_single(tool, args)
+
+    def _detect_file_write(self, tool: BaseTool, args: Dict) -> str | None:
+        """US4: Detect if tool is writing to a file.
+
+        Heuristics:
+        - Tool name contains 'write', 'edit', 'save'
+        - Args contain 'file_path', 'path', 'filename'
+
+        Returns normalized file path if detected, None otherwise.
+        """
+        tool_name_lower = tool.name.lower()
+        is_file_op = any(kw in tool_name_lower for kw in ['write', 'edit', 'save', 'create'])
+
+        if not is_file_op:
+            return None
+
+        # Extract file path from args
+        for key in ['file_path', 'path', 'filename', 'target']:
+            if key in args:
+                file_path = str(args[key])
+                # Normalize path
+                try:
+                    return str(Path(file_path).resolve())
+                except Exception:
+                    return file_path
+
+        return None
+
+    async def _execute_file_writers(
+        self, file_writers: list[Tuple[BaseTool, Dict, str]]
+    ) -> AsyncGenerator[Any, None]:
+        """US4: Execute file-writing tools with per-file serialization."""
+        async def run_with_lock(tool: BaseTool, args: Dict, file_path: str) -> Any:
+            # Get or create lock for this file
+            if file_path not in self._file_locks:
+                self._file_locks[file_path] = asyncio.Lock()
+
+            lock = self._file_locks[file_path]
+
+            async with lock:  # Serialize writes to same file
+                async with self._semaphore:  # Respect global concurrency limit
+                    return await self._execute_single(tool, args)
+
+        tasks = [asyncio.create_task(run_with_lock(t, a, fp)) for t, a, fp in file_writers]
+        for coro in asyncio.as_completed(tasks):
+            yield await coro
+
+    async def _execute_concurrent(
+        self, tool_calls: Iterable[Tuple[BaseTool, Dict]]
+    ) -> AsyncGenerator[Any, None]:
+        async def run(tool: BaseTool, args: Dict) -> Any:
+            async with self._semaphore:
+                return await self._execute_single(tool, args)
+
+        tasks = [asyncio.create_task(run(t, a)) for t, a in tool_calls]
+        for coro in asyncio.as_completed(tasks):
+            yield await coro
+
+    async def _execute_single(self, tool: BaseTool, args: Dict) -> Any:
+        return await asyncio.wait_for(tool.run(**args), timeout=self.config.timeout_seconds)
+

loom/core/steering_control.py

@@ -0,0 +1,47 @@
+"""Steering Control: Simplified abort/pause signal management.
+
+Replaces legacy EventBus with focus on cancel signals only.
+For real-time steering, use cancel_token (US1 pattern) instead.
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+
+class SteeringControl:
+    """Lightweight steering control for abort/pause signals.
+
+    Note: For cancellation, prefer using cancel_token (asyncio.Event) directly
+    with Agent.run(input, cancel_token=token). This class is kept for legacy
+    compatibility and may be removed in v5.0.0.
+    """
+
+    def __init__(self) -> None:
+        self._abort_signal = asyncio.Event()
+        self._pause_signal = asyncio.Event()
+
+    def abort(self) -> None:
+        """Signal abort request."""
+        self._abort_signal.set()
+
+    def is_aborted(self) -> bool:
+        """Check if abort was requested."""
+        return self._abort_signal.is_set()
+
+    def pause(self) -> None:
+        """Signal pause request."""
+        self._pause_signal.set()
+
+    def resume(self) -> None:
+        """Clear pause signal."""
+        self._pause_signal.clear()
+
+    def is_paused(self) -> bool:
+        """Check if paused."""
+        return self._pause_signal.is_set()
+
+    def reset(self) -> None:
+        """Reset all signals."""
+        self._abort_signal.clear()
+        self._pause_signal.clear()