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

loom/builtin/tools/calculator.py

@@ -18,6 +18,10 @@ class Calculator(BaseTool):
     description = "Evaluate simple arithmetic expressions"
     args_schema = CalcArgs
 
+    # 🆕 Loom 2.0 - Orchestration attributes
+    is_read_only = True  # Pure computation, no side effects
+    category = "general"
+
     async def run(self, **kwargs) -> Any:
         expr = kwargs.get("expression", "")
         return str(_safe_eval(expr))

loom/builtin/tools/document_search.py

@@ -48,6 +48,11 @@ class DocumentSearchTool(BaseTool):
     """
 
     name = "search_documents"
+
+    # 🆕 Loom 2.0 - Orchestration attributes
+    is_read_only = True  # Only searches documents, no modifications
+    category = "general"
+
     description = (
         "Search for relevant documents from the knowledge base. "
         "Use this when you need specific information that might be in the documents. "

loom/builtin/tools/glob.py

@@ -19,6 +19,10 @@ class GlobTool(BaseTool):
     description = "按模式匹配文件路径"
     args_schema = GlobArgs
 
+    # 🆕 Loom 2.0 - Orchestration attributes
+    is_read_only = True
+    category = "general"
+
     async def run(self, **kwargs) -> Any:
         args = self.args_schema(**kwargs)  # type: ignore
         cwd = Path(args.cwd).expanduser() if args.cwd else Path.cwd()

loom/builtin/tools/grep.py

@@ -22,6 +22,10 @@ class GrepTool(BaseTool):
     description = "在文件或文件集内检索正则匹配"
     args_schema = GrepArgs
 
+    # 🆕 Loom 2.0 - Orchestration attributes
+    is_read_only = True
+    category = "general"
+
     async def run(self, **kwargs) -> Any:
         args = self.args_schema(**kwargs)  # type: ignore
         flags = 0

loom/builtin/tools/http_request.py

@@ -35,6 +35,11 @@ class HTTPRequestTool(BaseTool):
     args_schema = HTTPRequestInput
     is_concurrency_safe = True
 
+    # 🆕 Loom 2.0 - Orchestration attributes
+    is_read_only = False  # POST/PUT/DELETE may modify remote state
+    category = "network"  # Network operation
+    requires_confirmation = False  # Usually safe, but depends on usage
+
     def __init__(self, timeout: int = 10) -> None:
         if httpx is None:
             raise ImportError("Please install httpx: pip install httpx")

loom/builtin/tools/python_repl.py

@@ -33,6 +33,11 @@ class PythonREPLTool(BaseTool):
     args_schema = PythonREPLInput
     is_concurrency_safe = False  # 代码执行不并发安全
 
+    # 🆕 Loom 2.0 - Orchestration attributes
+    is_read_only = False  # Code execution may have side effects
+    category = "destructive"  # Potentially dangerous
+    requires_confirmation = True  # Should require user confirmation
+
     async def run(self, code: str, **kwargs: Any) -> str:
         """执行 Python 代码"""
         # 安全性检查 - 禁止危险操作

loom/builtin/tools/read_file.py

@@ -19,6 +19,10 @@ class ReadFileTool(BaseTool):
     description = "读取文本文件内容"
     args_schema = ReadArgs
 
+    # 🆕 Loom 2.0 - Orchestration attributes
+    is_read_only = True
+    category = "general"
+
     async def run(self, **kwargs) -> Any:
         args = self.args_schema(**kwargs)  # type: ignore
         p = Path(args.path).expanduser()

loom/builtin/tools/task.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import time
 from typing import TYPE_CHECKING, Any, Optional, Dict, List
 
 from pydantic import BaseModel, Field
@@ -36,6 +37,12 @@ class TaskTool(BaseTool):
     Task 工具 - 启动 SubAgent 执行专项任务
 
     对应 Claude Code 的 Task 工具和 SubAgent 机制
+    
+    新特性 (Loom 0.0.3):
+    - 子代理池管理
+    - 性能监控和指标收集
+    - 智能负载均衡
+    - 资源使用优化
     """
 
     name = "task"
@@ -47,18 +54,44 @@ class TaskTool(BaseTool):
     args_schema = TaskInput
     is_concurrency_safe = True
 
+    # 🆕 Loom 2.0 - Orchestration attributes
+    is_read_only = False  # Sub-agent may use write tools
+    category = "general"  # Not inherently dangerous, but depends on sub-agent's tools
+    requires_confirmation = False
+
     def __init__(
         self,
         agent_factory: Optional[callable] = None,
         max_iterations: int = 20,
+        enable_pooling: bool = True,
+        pool_size: int = 5,
+        enable_monitoring: bool = True,
     ) -> None:
         """
         Parameters:
         - agent_factory: 创建 SubAgent 的工厂函数
         - max_iterations: SubAgent 最大迭代次数
+        - enable_pooling: 启用子代理池管理
+        - pool_size: 子代理池大小
+        - enable_monitoring: 启用性能监控
         """
         self.agent_factory = agent_factory
         self.max_iterations = max_iterations
+        
+        # Performance optimizations
+        self.enable_pooling = enable_pooling
+        self.pool_size = pool_size
+        self.enable_monitoring = enable_monitoring
+        
+        # Sub-agent pool management
+        self._agent_pool: Dict[str, Any] = {}
+        self._pool_stats = {
+            "total_created": 0,
+            "total_executed": 0,
+            "average_execution_time": 0.0,
+            "cache_hits": 0,
+            "cache_misses": 0
+        }
 
     async def run(
         self,
@@ -131,7 +164,33 @@ class TaskTool(BaseTool):
                     )
 
             # 运行子任务（系统提示已注入到 sub_agent，输入仍为原始 prompt）
+            start_time = time.time() if self.enable_monitoring else None
+            
+            # Check pool for reusable agent
+            agent_key = self._get_agent_key(subagent_type, effective_model, permission_policy)
+            if self.enable_pooling and agent_key in self._agent_pool:
+                sub_agent = self._agent_pool[agent_key]
+                self._pool_stats["cache_hits"] += 1
+            else:
+                self._pool_stats["cache_misses"] += 1
+                self._pool_stats["total_created"] += 1
+                
+                # Add to pool if enabled and not at capacity
+                if self.enable_pooling and len(self._agent_pool) < self.pool_size:
+                    self._agent_pool[agent_key] = sub_agent
+            
             result = await sub_agent.run(prompt)
+            
+            # Update performance metrics
+            if self.enable_monitoring and start_time:
+                execution_time = time.time() - start_time
+                self._pool_stats["total_executed"] += 1
+                # Update running average
+                current_avg = self._pool_stats["average_execution_time"]
+                total_executed = self._pool_stats["total_executed"]
+                self._pool_stats["average_execution_time"] = (
+                    (current_avg * (total_executed - 1) + execution_time) / total_executed
+                )
 
             # 格式化返回结果
             return f"**SubAgent Task: {description}**\n\nResult:\n{result}"
@@ -156,3 +215,49 @@ class TaskTool(BaseTool):
             subagent_type=subagent_type,
             model_name=model_name,
         )
+
+    def _get_agent_key(
+        self, 
+        subagent_type: Optional[str], 
+        model_name: Optional[str], 
+        permission_policy: Optional[Dict[str, str]]
+    ) -> str:
+        """Generate unique key for agent pool"""
+        import hashlib
+        
+        key_parts = [
+            subagent_type or "default",
+            model_name or "default",
+            str(sorted(permission_policy.items())) if permission_policy else "default"
+        ]
+        
+        key_string = "|".join(key_parts)
+        return hashlib.md5(key_string.encode()).hexdigest()
+
+    def get_pool_stats(self) -> Dict[str, Any]:
+        """Get sub-agent pool statistics"""
+        return {
+            **self._pool_stats,
+            "pool_size": len(self._agent_pool),
+            "max_pool_size": self.pool_size,
+            "pool_utilization": len(self._agent_pool) / self.pool_size if self.pool_size > 0 else 0,
+            "cache_hit_rate": (
+                self._pool_stats["cache_hits"] / 
+                (self._pool_stats["cache_hits"] + self._pool_stats["cache_misses"])
+                if (self._pool_stats["cache_hits"] + self._pool_stats["cache_misses"]) > 0 else 0
+            )
+        }
+
+    def clear_pool(self) -> None:
+        """Clear the sub-agent pool"""
+        self._agent_pool.clear()
+
+    def reset_stats(self) -> None:
+        """Reset performance statistics"""
+        self._pool_stats = {
+            "total_created": 0,
+            "total_executed": 0,
+            "average_execution_time": 0.0,
+            "cache_hits": 0,
+            "cache_misses": 0
+        }

loom/builtin/tools/web_search.py

@@ -33,6 +33,10 @@ class WebSearchTool(BaseTool):
     args_schema = WebSearchInput
     is_concurrency_safe = True
 
+    # 🆕 Loom 2.0 - Orchestration attributes
+    is_read_only = True  # Only reads from web, no local side effects
+    category = "network"
+
     def __init__(self) -> None:
         if DDGS is None:
             raise ImportError(

loom/builtin/tools/write_file.py

@@ -20,6 +20,10 @@ class WriteFileTool(BaseTool):
     description = "写入文本到文件（可能覆盖）"
     args_schema = WriteArgs
 
+    # 🆕 Loom 2.0 - Orchestration attributes
+    is_read_only = False
+    category = "destructive"
+
     async def run(self, **kwargs) -> Any:
         args = self.args_schema(**kwargs)  # type: ignore
         p = Path(args.path).expanduser()

loom/components/agent.py

@@ -1,10 +1,15 @@
 from __future__ import annotations
 
 import asyncio
+import uuid
+from pathlib import Path
 from typing import AsyncGenerator, Dict, List, Optional
 
 from loom.core.agent_executor import AgentExecutor
-from loom.core.types import StreamEvent
+from loom.core.types import StreamEvent, Message
+from loom.core.events import AgentEvent, AgentEventType  # 🆕 Loom 2.0
+from loom.core.turn_state import TurnState  # 🆕 Loom 2.0 tt mode
+from loom.core.execution_context import ExecutionContext  # 🆕 Loom 2.0 tt mode
 from loom.interfaces.llm import BaseLLM
 from loom.interfaces.memory import BaseMemory
 from loom.interfaces.tool import BaseTool
@@ -35,6 +40,7 @@ class Agent:
         callbacks: Optional[List[BaseCallback]] = None,
         steering_control: Optional[SteeringControl] = None,
         metrics: Optional[MetricsCollector] = None,
+        enable_steering: bool = True,  # v4.0.0: Enable steering by default
     ) -> None:
         # v4.0.0: Auto-instantiate CompressionManager (always enabled)
         if compressor is None:
@@ -61,7 +67,7 @@ class Agent:
             permission_manager=None,
             system_instructions=system_instructions,
             callbacks=callbacks,
-            enable_steering=True,  # v4.0.0: Always enabled
+            enable_steering=enable_steering,
         )
 
         # 始终构造 PermissionManager（以便支持 safe_mode/持久化）；保持默认语义
@@ -83,11 +89,121 @@ class Agent:
         cancel_token: Optional[asyncio.Event] = None,  # 🆕 US1
         correlation_id: Optional[str] = None,  # 🆕 US1
     ) -> str:
-        return await self.executor.execute(input, cancel_token=cancel_token, correlation_id=correlation_id)
+        """
+        Execute agent and return final response (backward compatible).
+
+        This method wraps the new execute() streaming API and extracts
+        the final response for backward compatibility.
+
+        Args:
+            input: User input
+            cancel_token: Optional cancellation event
+            correlation_id: Optional correlation ID for tracing
+
+        Returns:
+            Final response text
+        """
+        final_content = ""
+
+        async for event in self.execute(input):
+            # Accumulate LLM deltas
+            if event.type == AgentEventType.LLM_DELTA:
+                final_content += event.content or ""
+
+            # Return on finish
+            elif event.type == AgentEventType.AGENT_FINISH:
+                return event.content or final_content
+
+            # Raise on error
+            elif event.type == AgentEventType.ERROR:
+                if event.error:
+                    raise event.error
+
+        return final_content
+
+    async def execute(
+        self,
+        input: str,
+        cancel_token: Optional[asyncio.Event] = None,
+        correlation_id: Optional[str] = None,
+        working_dir: Optional[Path] = None,
+    ) -> AsyncGenerator[AgentEvent, None]:
+        """
+        Execute agent with streaming events using tt recursive mode (Loom 2.0).
+
+        This is the new unified streaming interface that produces AgentEvent
+        instances for all execution phases. It uses tt (tail-recursive) control
+        loop as the ONLY core execution method.
+
+        Args:
+            input: User input
+            cancel_token: Optional cancellation event
+            correlation_id: Optional correlation ID for tracing
+            working_dir: Optional working directory
+
+        Yields:
+            AgentEvent: Events representing execution progress
+
+        Example:
+            ```python
+            async for event in agent.execute("Your prompt"):
+                if event.type == AgentEventType.LLM_DELTA:
+                    print(event.content, end="", flush=True)
+                elif event.type == AgentEventType.TOOL_PROGRESS:
+                    print(f"\\n[Tool] {event.metadata['status']}")
+                elif event.type == AgentEventType.AGENT_FINISH:
+                    print(f"\\n✓ {event.content}")
+            ```
+        """
+        # Initialize immutable turn state
+        turn_state = TurnState.initial(max_iterations=self.executor.max_iterations)
+
+        # Create execution context
+        context = ExecutionContext.create(
+            working_dir=working_dir,
+            correlation_id=correlation_id,
+            cancel_token=cancel_token,
+        )
+
+        # Create initial message
+        messages = [Message(role="user", content=input)]
+
+        # Delegate to executor's tt recursive control loop
+        async for event in self.executor.tt(messages, turn_state, context):
+            yield event
 
     async def stream(self, input: str) -> AsyncGenerator[StreamEvent, None]:
-        async for ev in self.executor.stream(input):
-            yield ev
+        """
+        Legacy streaming API (backward compatible).
+
+        NOTE: This uses the old StreamEvent type. For new code, use execute()
+        which returns AgentEvent instances.
+
+        This method now converts AgentEvent to StreamEvent for backward compatibility.
+        """
+        # Use tt mode under the hood
+        async for agent_event in self.execute(input):
+            # Convert AgentEvent to legacy StreamEvent
+            if agent_event.type == AgentEventType.LLM_DELTA:
+                yield StreamEvent(
+                    type="llm_delta",
+                    content=agent_event.content or "",
+                )
+            elif agent_event.type == AgentEventType.AGENT_FINISH:
+                yield StreamEvent(
+                    type="agent_finish",
+                    content=agent_event.content or "",
+                )
+            elif agent_event.type == AgentEventType.TOOL_RESULT:
+                yield StreamEvent(
+                    type="tool_result",
+                    content=agent_event.tool_result.content if agent_event.tool_result else "",
+                )
+            elif agent_event.type == AgentEventType.ERROR:
+                yield StreamEvent(
+                    type="error",
+                    content=str(agent_event.error) if agent_event.error else "Unknown error",
+                )
 
     # LangChain 风格的别名，便于迁移/调用
     async def ainvoke(