loom-agent 0.0.1__py3-none-any.whl

loom/core/system_reminders.py

@@ -0,0 +1,283 @@
+"""US7: Dynamic System Reminders
+
+Provides contextual hints and reminders to agents based on runtime state.
+
+Examples:
+- "Warning: Memory usage is high (15,234 tokens). Consider using more concise responses."
+- "Note: 3 stale todos detected. Consider cleaning up completed items."
+- "Tip: Multiple file writes detected. Use batch operations for efficiency."
+"""
+
+from __future__ import annotations
+
+from typing import List, Optional, Callable, Any
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+
+
+@dataclass
+class Reminder:
+    """A system reminder."""
+    category: str  # "memory", "performance", "todos", "errors"
+    severity: str  # "info", "warning", "critical"
+    message: str
+    metadata: dict
+
+
+class ReminderRule:
+    """Base class for reminder rules."""
+
+    def __init__(self, category: str, severity: str = "info"):
+        self.category = category
+        self.severity = severity
+
+    def check(self, context: dict) -> Optional[Reminder]:
+        """Check if reminder should be triggered.
+
+        Args:
+            context: Runtime context dict
+
+        Returns:
+            Reminder if triggered, None otherwise
+        """
+        raise NotImplementedError
+
+
+class HighMemoryRule(ReminderRule):
+    """Remind when memory usage is high."""
+
+    def __init__(self, threshold_tokens: int = 14000):
+        super().__init__("memory", "warning")
+        self.threshold_tokens = threshold_tokens
+
+    def check(self, context: dict) -> Optional[Reminder]:
+        current_tokens = context.get("current_tokens", 0)
+        max_tokens = context.get("max_tokens", 16000)
+
+        if current_tokens > self.threshold_tokens:
+            percentage = (current_tokens / max_tokens) * 100
+            return Reminder(
+                category=self.category,
+                severity=self.severity,
+                message=f"Memory usage is high ({current_tokens:,} tokens, {percentage:.1f}%). Consider using more concise responses or compressing context.",
+                metadata={
+                    "current_tokens": current_tokens,
+                    "max_tokens": max_tokens,
+                    "percentage": percentage,
+                }
+            )
+        return None
+
+
+class StaleTodosRule(ReminderRule):
+    """Remind about stale todos."""
+
+    def __init__(self, stale_threshold_hours: int = 24):
+        super().__init__("todos", "info")
+        self.stale_threshold = timedelta(hours=stale_threshold_hours)
+
+    def check(self, context: dict) -> Optional[Reminder]:
+        todos = context.get("todos", [])
+        now = datetime.now()
+
+        # Count stale completed todos
+        stale_count = 0
+        for todo in todos:
+            if todo.get("status") == "completed":
+                completed_at = todo.get("completed_at")
+                if completed_at and isinstance(completed_at, datetime):
+                    if now - completed_at > self.stale_threshold:
+                        stale_count += 1
+
+        if stale_count > 0:
+            return Reminder(
+                category=self.category,
+                severity=self.severity,
+                message=f"{stale_count} stale todo(s) detected (completed >24h ago). Consider cleaning up.",
+                metadata={"stale_count": stale_count}
+            )
+        return None
+
+
+class HighErrorRateRule(ReminderRule):
+    """Remind when error rate is high."""
+
+    def __init__(self, threshold_percentage: float = 20.0):
+        super().__init__("errors", "warning")
+        self.threshold_percentage = threshold_percentage
+
+    def check(self, context: dict) -> Optional[Reminder]:
+        metrics = context.get("metrics", {})
+        total_ops = metrics.get("total_operations", 0)
+        errors = metrics.get("total_errors", 0)
+
+        if total_ops > 0:
+            error_rate = (errors / total_ops) * 100
+            if error_rate > self.threshold_percentage:
+                return Reminder(
+                    category=self.category,
+                    severity="critical" if error_rate > 50 else "warning",
+                    message=f"High error rate detected: {errors}/{total_ops} operations failed ({error_rate:.1f}%). Check logs for details.",
+                    metadata={
+                        "error_rate": error_rate,
+                        "errors": errors,
+                        "total_ops": total_ops,
+                    }
+                )
+        return None
+
+
+class FrequentCompressionRule(ReminderRule):
+    """Remind when compression happens too frequently."""
+
+    def __init__(self, threshold_count: int = 5):
+        super().__init__("performance", "info")
+        self.threshold_count = threshold_count
+
+    def check(self, context: dict) -> Optional[Reminder]:
+        metrics = context.get("metrics", {})
+        compressions = metrics.get("compressions", 0)
+
+        if compressions >= self.threshold_count:
+            return Reminder(
+                category=self.category,
+                severity=self.severity,
+                message=f"Context compressed {compressions} times. Consider increasing max_context_tokens or using shorter prompts.",
+                metadata={"compression_count": compressions}
+            )
+        return None
+
+
+class SystemReminderManager:
+    """Manages system reminders and dynamic hint injection.
+
+    Example:
+        manager = SystemReminderManager()
+        manager.add_rule(HighMemoryRule())
+        manager.add_rule(HighErrorRateRule())
+
+        # Check for reminders
+        context = {
+            "current_tokens": 15000,
+            "max_tokens": 16000,
+            "metrics": {"total_errors": 5, "total_operations": 10}
+        }
+
+        reminders = manager.check_all(context)
+        if reminders:
+            print(manager.format_reminders(reminders))
+    """
+
+    def __init__(self):
+        """Initialize reminder manager."""
+        self.rules: List[ReminderRule] = []
+        self._default_rules()
+
+    def _default_rules(self):
+        """Add default reminder rules."""
+        self.add_rule(HighMemoryRule(threshold_tokens=14000))
+        self.add_rule(HighErrorRateRule(threshold_percentage=20.0))
+        self.add_rule(FrequentCompressionRule(threshold_count=5))
+        # StaleTodosRule disabled by default (requires todo tracking)
+
+    def add_rule(self, rule: ReminderRule) -> None:
+        """Add a reminder rule.
+
+        Args:
+            rule: ReminderRule instance
+        """
+        self.rules.append(rule)
+
+    def remove_rule(self, category: str) -> None:
+        """Remove all rules for a category.
+
+        Args:
+            category: Category to remove
+        """
+        self.rules = [r for r in self.rules if r.category != category]
+
+    def check_all(self, context: dict) -> List[Reminder]:
+        """Check all rules and return triggered reminders.
+
+        Args:
+            context: Runtime context
+
+        Returns:
+            List of triggered reminders
+        """
+        reminders = []
+        for rule in self.rules:
+            try:
+                reminder = rule.check(context)
+                if reminder:
+                    reminders.append(reminder)
+            except Exception:
+                # Don't fail if a rule raises
+                pass
+
+        return reminders
+
+    def format_reminders(self, reminders: List[Reminder]) -> str:
+        """Format reminders as human-readable text.
+
+        Args:
+            reminders: List of reminders
+
+        Returns:
+            Formatted reminder text
+        """
+        if not reminders:
+            return ""
+
+        lines = ["=== System Reminders ==="]
+
+        # Group by severity
+        critical = [r for r in reminders if r.severity == "critical"]
+        warnings = [r for r in reminders if r.severity == "warning"]
+        info = [r for r in reminders if r.severity == "info"]
+
+        for severity_list, prefix in [
+            (critical, "🚨 CRITICAL"),
+            (warnings, "⚠️  WARNING"),
+            (info, "ℹ️  INFO"),
+        ]:
+            for reminder in severity_list:
+                lines.append(f"{prefix}: {reminder.message}")
+
+        return "\n".join(lines)
+
+    def inject_into_context(
+        self,
+        context: dict,
+        existing_system_prompt: str = ""
+    ) -> str:
+        """Check reminders and inject into system prompt.
+
+        Args:
+            context: Runtime context
+            existing_system_prompt: Existing system prompt
+
+        Returns:
+            System prompt with reminders injected
+        """
+        reminders = self.check_all(context)
+
+        if not reminders:
+            return existing_system_prompt
+
+        reminder_text = self.format_reminders(reminders)
+
+        # Inject at end of system prompt
+        if existing_system_prompt:
+            return f"{existing_system_prompt}\n\n{reminder_text}"
+        else:
+            return reminder_text
+
+
+# Global instance
+_default_manager = SystemReminderManager()
+
+
+def get_reminder_manager() -> SystemReminderManager:
+    """Get the global reminder manager."""
+    return _default_manager

loom/core/tool_pipeline.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+import time
+from enum import Enum
+from typing import Any, AsyncGenerator, Dict, Iterable, List
+
+from loom.core.errors import PermissionDeniedError, ToolNotFoundError, ToolValidationError
+from loom.core.types import ToolCall, ToolResult
+from loom.interfaces.tool import BaseTool
+from loom.core.scheduler import Scheduler
+from loom.core.permissions import PermissionManager, PermissionAction
+from loom.callbacks.metrics import MetricsCollector
+
+
+class ExecutionStage(str, Enum):
+    DISCOVER = "discover"
+    VALIDATE = "validate"
+    AUTHORIZE = "authorize"
+    CHECK_CANCEL = "check_cancel"
+    EXECUTE = "execute"
+    FORMAT = "format"
+
+
+class ToolExecutionPipeline:
+    """最小可用的六阶段工具执行流水线（Discover→...→Format）。"""
+
+    def __init__(
+        self,
+        tools: Dict[str, BaseTool],
+        scheduler: Scheduler | None = None,
+        permission_manager: PermissionManager | None = None,
+        metrics: MetricsCollector | None = None,
+    ) -> None:
+        self.tools = tools
+        self.scheduler = scheduler or Scheduler()
+        self._stage_metrics: Dict[str, float] = {}
+        self.permission_manager = permission_manager or PermissionManager(policy={"default": "allow"})
+        self.metrics = metrics or MetricsCollector()
+
+    async def execute_calls(self, tool_calls: Iterable[ToolCall]) -> AsyncGenerator[ToolResult, None]:
+        for call in tool_calls:
+            try:
+                tool = await self._stage_discover(call)
+                args = await self._stage_validate(tool, call)
+                await self._stage_authorize(tool, call, args)
+                # check_cancel: 由上层 EventBus 注入，此处留空
+                result = await self._stage_execute(tool, args, call)
+                tr = await self._stage_format(result, call)
+                self.metrics.metrics.tool_calls += 1
+                yield tr
+            except Exception as e:  # 简化：归一化错误
+                self.metrics.metrics.tool_calls += 1
+                self.metrics.metrics.total_errors += 1
+                yield ToolResult(
+                    tool_call_id=call.id,
+                    status="error",
+                    content=str(e),
+                    metadata={"stage_breakdown": self._stage_metrics.copy()},
+                )
+            finally:
+                self._stage_metrics.clear()
+
+    async def _stage_discover(self, tool_call: ToolCall) -> BaseTool:
+        start = time.time()
+        if tool_call.name not in self.tools:
+            raise ToolNotFoundError(f"Tool '{tool_call.name}' not registered")
+        tool = self.tools[tool_call.name]
+        self._stage_metrics[ExecutionStage.DISCOVER.value] = time.time() - start
+        return tool
+
+    async def _stage_validate(self, tool: BaseTool, tool_call: ToolCall) -> Dict[str, Any]:
+        start = time.time()
+        if not getattr(tool, "args_schema", None):
+            args = tool_call.arguments
+        else:
+            try:
+                args_model = tool.args_schema(**tool_call.arguments)
+                args = args_model.model_dump()
+            except Exception as e:  # pydantic 验证错误
+                raise ToolValidationError(str(e))
+        self._stage_metrics[ExecutionStage.VALIDATE.value] = time.time() - start
+        return args
+
+    async def _stage_authorize(self, tool: BaseTool, tool_call: ToolCall, args: Dict[str, Any]) -> None:
+        start = time.time()
+        action = self.permission_manager.check(tool.name, tool_call.arguments)
+        if action == PermissionAction.DENY:
+            raise PermissionDeniedError(f"Permission denied for tool '{tool.name}'")
+        if action == PermissionAction.ASK:
+            confirmed = self.permission_manager.confirm(tool.name, args)
+            if not confirmed:
+                raise PermissionDeniedError(f"User denied permission for tool '{tool.name}'")
+        self._stage_metrics[ExecutionStage.AUTHORIZE.value] = time.time() - start
+
+    async def _stage_execute(self, tool: BaseTool, args: Dict[str, Any], call: ToolCall) -> Any:
+        start = time.time()
+        # 使用调度器包装执行
+        result = None
+        async for r in self.scheduler.schedule_batch([(tool, args)]):
+            result = r
+        self._stage_metrics[ExecutionStage.EXECUTE.value] = time.time() - start
+        return result
+
+    async def _stage_format(self, result: Any, call: ToolCall) -> ToolResult:
+        start = time.time()
+        tr = ToolResult(
+            tool_call_id=call.id,
+            status="success",
+            content=str(result) if result is not None else "",
+            metadata={"stage_breakdown": self._stage_metrics.copy()},
+        )
+        self._stage_metrics[ExecutionStage.FORMAT.value] = time.time() - start
+        return tr

loom/core/types.py

@@ -0,0 +1,269 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import Any, Dict, List, Optional
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, Field
+
+
+@dataclass
+class Message:
+    role: str  # user | assistant | system | tool
+    content: str
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    tool_call_id: Optional[str] = None
+
+
+@dataclass
+class ToolCall:
+    id: str
+    name: str
+    arguments: Dict[str, Any]
+
+
+@dataclass
+class ToolResult:
+    tool_call_id: str
+    status: str  # success | error | warning
+    content: str
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class StreamEvent:
+    type: str  # text_delta | tool_calls_start | tool_result | agent_finish | error | aborted
+    content: Optional[str] = None
+    tool_calls: Optional[List[ToolCall]] = None
+    result: Optional[ToolResult] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+# =============================================================================
+# Phase 2: Foundation Types for Claude Code Enhancements (v4.0.0)
+# =============================================================================
+
+
+# -----------------------------------------------------------------------------
+# T011: MessageQueueItem - US1 Real-Time Steering
+# -----------------------------------------------------------------------------
+class MessageQueueItem(BaseModel):
+    """Message queue item for h2A async message queue (US1)."""
+
+    id: UUID = Field(default_factory=uuid4, description="Unique message ID")
+    role: str = Field(..., description="Message role: user | assistant | system | tool")
+    content: str = Field(..., description="Message content")
+    priority: int = Field(default=5, ge=0, le=10, description="Priority 0-10 (10=highest)")
+    timestamp: datetime = Field(default_factory=datetime.utcnow, description="Creation timestamp")
+    cancellable: bool = Field(default=True, description="Can this message be cancelled?")
+    correlation_id: Optional[str] = Field(default=None, description="Request correlation ID")
+    metadata: Dict[str, Any] = Field(default_factory=dict, description="Additional metadata")
+
+
+# -----------------------------------------------------------------------------
+# T012: CompressionMetadata - US2 Context Compression
+# -----------------------------------------------------------------------------
+class CompressionMetadata(BaseModel):
+    """Metadata for AU2 8-segment compression (US2)."""
+
+    original_message_count: int = Field(..., ge=1, description="Messages before compression")
+    compressed_message_count: int = Field(..., ge=1, description="Messages after compression")
+    original_token_count: int = Field(..., ge=1, description="Tokens before compression")
+    compressed_token_count: int = Field(..., ge=1, description="Tokens after compression")
+    compression_ratio: float = Field(..., ge=0.0, le=1.0, description="Reduction ratio (0.75 = 75%)")
+    key_topics: List[str] = Field(default_factory=list, description="Extracted key topics")
+    compression_method: str = Field(default="au2_8segment", description="Algorithm used")
+    timestamp: datetime = Field(default_factory=datetime.utcnow, description="Compression time")
+
+
+# -----------------------------------------------------------------------------
+# T013: SubAgentContext - US3 Sub-Agent Isolation
+# -----------------------------------------------------------------------------
+class SubAgentStatus(str, Enum):
+    """Sub-agent execution status."""
+
+    PENDING = "pending"
+    RUNNING = "running"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    TIMEOUT = "timeout"
+    CANCELLED = "cancelled"
+
+
+class SubAgentContext(BaseModel):
+    """Context for I2A isolated sub-agent (US3)."""
+
+    agent_id: UUID = Field(default_factory=uuid4, description="Sub-agent unique ID")
+    parent_agent_id: Optional[UUID] = Field(default=None, description="Parent agent ID")
+    agent_type: str = Field(default="general", description="AgentSpec type reference")
+    tool_whitelist: Optional[List[str]] = Field(default=None, description="Allowed tools (None = all)")
+    max_iterations: int = Field(default=50, ge=1, le=100, description="Max loop iterations")
+    timeout_seconds: int = Field(default=300, ge=1, le=600, description="Max execution time")
+    status: SubAgentStatus = Field(default=SubAgentStatus.PENDING, description="Current status")
+    execution_depth: int = Field(default=0, ge=0, le=3, description="Nesting level")
+    parent_correlation_id: Optional[str] = Field(default=None, description="Parent's correlation ID")
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+
+
+# -----------------------------------------------------------------------------
+# T014: ToolExecutionStage - US4 Tool Pipeline
+# -----------------------------------------------------------------------------
+class ExecutionStage(str, Enum):
+    """6-stage tool execution pipeline (MH1)."""
+
+    DISCOVER = "discover"
+    VALIDATE = "validate"
+    AUTHORIZE = "authorize"
+    CHECK_CANCEL = "check_cancel"
+    EXECUTE = "execute"
+    FORMAT = "format"
+
+
+class StageStatus(str, Enum):
+    """Status of pipeline stage."""
+
+    PENDING = "pending"
+    SUCCESS = "success"
+    FAILED = "failed"
+    SKIPPED = "skipped"
+
+
+class ToolExecutionStageInfo(BaseModel):
+    """Information about single pipeline stage."""
+
+    stage_name: ExecutionStage = Field(..., description="Stage identifier")
+    stage_status: StageStatus = Field(..., description="Stage result")
+    start_time: Optional[datetime] = Field(default=None, description="Stage start")
+    end_time: Optional[datetime] = Field(default=None, description="Stage end")
+    duration_ms: Optional[float] = Field(default=None, description="Duration in milliseconds")
+    error: Optional[str] = Field(default=None, description="Error message if failed")
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+
+
+# -----------------------------------------------------------------------------
+# T015: CircuitBreakerState - US5 Error Handling & Resilience
+# -----------------------------------------------------------------------------
+class CircuitState(str, Enum):
+    """Circuit breaker state machine."""
+
+    CLOSED = "closed"  # Normal operation
+    OPEN = "open"  # Rejecting requests
+    HALF_OPEN = "half_open"  # Testing recovery
+
+
+class CircuitBreakerState(BaseModel):
+    """Circuit breaker state for service protection (US5)."""
+
+    service_name: str = Field(..., description="Protected service identifier")
+    state: CircuitState = Field(default=CircuitState.CLOSED, description="Current state")
+    failure_count: int = Field(default=0, ge=0, description="Consecutive failures")
+    success_count: int = Field(default=0, ge=0, description="Consecutive successes")
+    failure_threshold: int = Field(default=5, ge=1, description="Failures to open circuit")
+    success_threshold: int = Field(default=2, ge=1, description="Successes to close circuit")
+    timeout_seconds: int = Field(default=60, ge=1, description="Timeout in OPEN state")
+    last_failure_time: Optional[datetime] = Field(default=None)
+    last_success_time: Optional[datetime] = Field(default=None)
+
+
+# -----------------------------------------------------------------------------
+# T016: LongTermMemory - US6 Three-Tier Memory System
+# -----------------------------------------------------------------------------
+class LongTermMemory(BaseModel):
+    """Long-term memory stored in .loom/CLAUDE.md (US6)."""
+
+    project_path: str = Field(..., description="Root project directory")
+    memory_file_path: str = Field(..., description="Path to .loom/CLAUDE.md")
+    sections: Dict[str, str] = Field(
+        default_factory=dict,
+        description="Markdown sections: code_style, architecture_decisions, user_preferences, etc.",
+    )
+    last_updated: datetime = Field(default_factory=datetime.utcnow)
+    checksum: Optional[str] = Field(default=None, description="MD5 checksum for integrity")
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+
+
+# -----------------------------------------------------------------------------
+# T017: AgentEvent Types - Enhanced Events for Callbacks
+# -----------------------------------------------------------------------------
+class AgentEventType(str, Enum):
+    """Enhanced agent event types."""
+
+    TEXT_DELTA = "text_delta"
+    TOOL_CALL = "tool_call"
+    TOOL_RESULT = "tool_result"
+    COMPRESSION_START = "compression_start"
+    COMPRESSION_COMPLETE = "compression_complete"
+    SUBAGENT_SPAWNED = "subagent_spawned"
+    SUBAGENT_COMPLETED = "subagent_completed"
+    ERROR = "error"
+    COMPLETION = "completion"
+
+
+class BaseAgentEvent(BaseModel):
+    """Base class for all agent events."""
+
+    event_type: AgentEventType = Field(..., description="Event type identifier")
+    correlation_id: Optional[str] = Field(default=None, description="Request correlation ID")
+    timestamp: datetime = Field(default_factory=datetime.utcnow)
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+
+
+class TextDeltaEvent(BaseAgentEvent):
+    """Streaming text delta event."""
+
+    event_type: AgentEventType = Field(default=AgentEventType.TEXT_DELTA)
+    content: str = Field(..., description="Text delta content")
+
+
+class ToolCallEvent(BaseAgentEvent):
+    """Tool call initiated event."""
+
+    event_type: AgentEventType = Field(default=AgentEventType.TOOL_CALL)
+    tool_call_id: str = Field(..., description="Tool call ID")
+    tool_name: str = Field(..., description="Tool name")
+    arguments: Dict[str, Any] = Field(..., description="Tool arguments")
+
+
+class ToolResultEvent(BaseAgentEvent):
+    """Tool execution result event."""
+
+    event_type: AgentEventType = Field(default=AgentEventType.TOOL_RESULT)
+    tool_call_id: str = Field(..., description="Tool call ID")
+    status: str = Field(..., description="success | error | warning")
+    content: str = Field(..., description="Result content")
+    stages: List[ToolExecutionStageInfo] = Field(default_factory=list, description="Pipeline stages")
+
+
+class CompressionEvent(BaseAgentEvent):
+    """Context compression event."""
+
+    event_type: AgentEventType = Field(default=AgentEventType.COMPRESSION_COMPLETE)
+    compression_metadata: CompressionMetadata = Field(..., description="Compression details")
+
+
+class SubAgentSpawnedEvent(BaseAgentEvent):
+    """Sub-agent spawned event."""
+
+    event_type: AgentEventType = Field(default=AgentEventType.SUBAGENT_SPAWNED)
+    subagent_context: SubAgentContext = Field(..., description="Sub-agent details")
+
+
+class ErrorEvent(BaseAgentEvent):
+    """Error event."""
+
+    event_type: AgentEventType = Field(default=AgentEventType.ERROR)
+    error_message: str = Field(..., description="Error description")
+    error_category: Optional[str] = Field(default=None, description="ErrorCategory enum value")
+    recoverable: bool = Field(default=False, description="Is error recoverable?")
+
+
+class CompletionEvent(BaseAgentEvent):
+    """Agent completion event."""
+
+    event_type: AgentEventType = Field(default=AgentEventType.COMPLETION)
+    final_content: str = Field(..., description="Final response")
+    model_used: Optional[str] = Field(default=None, description="Model identifier (if fallback occurred)")
+