ctrlcode 0.1.0__py3-none-any.whl

ctrlcode/agents/react_loop.py

@@ -0,0 +1,297 @@
+"""Reusable ReAct loop execution for agents and sessions."""
+
+import logging
+import json
+from typing import Any, Callable
+from dataclasses import dataclass
+
+from harnessutils import ConversationManager, Message, TextPart
+
+from ..providers.base import Provider, StreamEvent
+from ..tools.executor import ToolExecutor
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ReActResult:
+    """Result from executing a ReAct loop."""
+
+    assistant_text: str
+    tool_calls: list[dict[str, Any]]
+    usage_tokens: int
+    continuation_count: int
+
+
+class AgentReActLoop:
+    """Execute ReAct (Reason + Act) loops with tool calling."""
+
+    def __init__(self):
+        """Initialize ReAct loop executor."""
+        self.msg_id_counter = 0
+
+    def _generate_msg_id(self) -> str:
+        """Generate unique message ID."""
+        self.msg_id_counter += 1
+        return f"msg_{self.msg_id_counter}"
+
+    async def execute(
+        self,
+        provider: Provider,
+        conv_manager: ConversationManager,
+        conv_id: str,
+        tool_executor: ToolExecutor,
+        tools: list[dict[str, Any]],
+        allowed_tools: list[str] | None = None,
+        max_continuations: int = 50,
+        event_callback: Callable[[StreamEvent], None] | None = None,
+    ) -> ReActResult:
+        """
+        Execute ReAct loop with tool calling.
+
+        Args:
+            provider: LLM provider to stream from
+            conv_manager: Conversation manager
+            conv_id: Conversation ID
+            tool_executor: Tool executor for running tools
+            tools: Tool definitions to pass to LLM
+            allowed_tools: Optional list of allowed tool names (for filtering)
+            max_continuations: Maximum continuation iterations
+            event_callback: Optional callback for streaming events
+
+        Returns:
+            ReActResult with aggregated output
+        """
+        usage_tokens = 0
+        accumulated_text: list[str] = []
+        all_tool_calls: list[dict] = []
+
+        # Get current messages
+        messages = conv_manager.to_model_format(conv_id)
+
+        # First pass: stream and collect tool calls
+        assistant_text = []
+        tool_calls: list[dict] = []
+        current_tool_call: dict | None = None
+
+        async for event in provider.stream(messages, tools=tools):
+            if event_callback:
+                event_callback(event)
+
+            if event.type == "text":
+                text_chunk = event.data["text"]
+                assistant_text.append(text_chunk)
+                accumulated_text.append(text_chunk)
+
+            elif event.type == "usage":
+                usage = event.data.get("usage", {})
+                usage_tokens += usage.get("completion_tokens", 0)
+
+            elif event.type == "tool_call_start":
+                current_tool_call = {
+                    "tool": event.data["tool"],
+                    "call_id": event.data["call_id"],
+                    "input": ""
+                }
+
+            elif event.type == "tool_call_delta":
+                if current_tool_call:
+                    current_tool_call["input"] += event.data.get("delta", "")
+
+            elif event.type == "content_block_stop":
+                if current_tool_call:
+                    try:
+                        current_tool_call["input"] = json.loads(current_tool_call["input"])
+                    except json.JSONDecodeError:
+                        current_tool_call["input"] = {}
+                    tool_calls.append(current_tool_call)
+                    all_tool_calls.append(current_tool_call)
+                    current_tool_call = None
+
+        # Execute tools if any were called
+        if tool_calls and tool_executor:
+            # Add assistant message with tool use
+            assistant_msg = Message(id=self._generate_msg_id(), role="assistant")
+            if assistant_text:
+                assistant_msg.add_part(TextPart(text="".join(assistant_text)))
+            conv_manager.add_message(conv_id, assistant_msg)
+
+            # Execute all tools
+            for tool_call in tool_calls:
+                # Filter by allowed_tools if specified
+                if allowed_tools and tool_call["tool"] not in allowed_tools:
+                    logger.warning(f"Tool {tool_call['tool']} not in allowed list, skipping")
+                    continue
+
+                result = await tool_executor.execute(
+                    tool_name=tool_call["tool"],
+                    arguments=tool_call["input"],
+                    call_id=tool_call["call_id"]
+                )
+
+                # Emit tool result event
+                if event_callback:
+                    event_callback(StreamEvent(
+                        type="tool_result",
+                        data={
+                            "tool": tool_call["tool"],
+                            "success": result.success,
+                            "result": result.result if result.success else result.error
+                        }
+                    ))
+
+                # Add tool result message
+                tool_result_msg = Message(id=self._generate_msg_id(), role="user")
+                result_text = f"[Tool: {tool_call['tool']}]\n"
+                if result.success:
+                    result_text += f"Result: {result.result}"
+                else:
+                    result_text += f"Error: {result.error}"
+                tool_result_msg.add_part(TextPart(text=result_text))
+                conv_manager.add_message(conv_id, tool_result_msg)
+
+            # Continuation loop: keep calling tools until LLM stops
+            continuation_count = 0
+
+            while tool_calls and continuation_count < max_continuations:
+                continuation_count += 1
+                logger.info(f"ReAct continuation {continuation_count}/{max_continuations}")
+
+                # Add continuation prompt
+                reminder_msg = Message(id=self._generate_msg_id(), role="user")
+                reminder_msg.add_part(TextPart(
+                    text="Continue using tools to complete the task. Call more tools if needed."
+                ))
+                conv_manager.add_message(conv_id, reminder_msg)
+
+                # Get updated messages
+                messages = conv_manager.to_model_format(conv_id)
+
+                # Stream continuation
+                continuation_text = []
+                continuation_tool_calls = []
+                current_continuation_tool = None
+
+                async for event in provider.stream(messages, tools=tools):
+                    if event_callback:
+                        event_callback(event)
+
+                    if event.type == "text":
+                        continuation_text.append(event.data["text"])
+                        accumulated_text.append(event.data["text"])
+
+                    elif event.type == "usage":
+                        usage = event.data.get("usage", {})
+                        usage_tokens += usage.get("completion_tokens", 0)
+
+                    elif event.type == "tool_call_start":
+                        current_continuation_tool = {
+                            "tool": event.data["tool"],
+                            "call_id": event.data["call_id"],
+                            "input": ""
+                        }
+
+                    elif event.type == "tool_call_delta":
+                        if current_continuation_tool:
+                            current_continuation_tool["input"] += event.data.get("delta", "")
+
+                    elif event.type == "content_block_stop":
+                        if current_continuation_tool:
+                            try:
+                                current_continuation_tool["input"] = json.loads(
+                                    current_continuation_tool["input"]
+                                )
+                            except json.JSONDecodeError:
+                                current_continuation_tool["input"] = {}
+                            continuation_tool_calls.append(current_continuation_tool)
+                            all_tool_calls.append(current_continuation_tool)
+                            current_continuation_tool = None
+
+                # Add continuation assistant message
+                cont_assistant_msg = Message(id=self._generate_msg_id(), role="assistant")
+                if continuation_text:
+                    cont_assistant_msg.add_part(TextPart(text="".join(continuation_text)))
+                conv_manager.add_message(conv_id, cont_assistant_msg)
+
+                # Execute continuation tools
+                if continuation_tool_calls:
+                    for tool_call in continuation_tool_calls:
+                        # Filter by allowed_tools
+                        if allowed_tools and tool_call["tool"] not in allowed_tools:
+                            logger.warning(f"Tool {tool_call['tool']} not allowed, skipping")
+                            continue
+
+                        result = await tool_executor.execute(
+                            tool_name=tool_call["tool"],
+                            arguments=tool_call["input"],
+                            call_id=tool_call["call_id"]
+                        )
+
+                        # Emit tool result
+                        if event_callback:
+                            event_callback(StreamEvent(
+                                type="tool_result",
+                                data={
+                                    "tool": tool_call["tool"],
+                                    "success": result.success,
+                                    "result": result.result if result.success else result.error,
+                                    "continuation": True,
+                                    "continuation_index": continuation_count
+                                }
+                            ))
+
+                        # Add tool result message
+                        tool_result_msg = Message(id=self._generate_msg_id(), role="user")
+                        result_text = f"[Tool: {tool_call['tool']}]\n"
+                        if result.success:
+                            result_text += f"Result: {result.result}"
+                        else:
+                            result_text += f"Error: {result.error}"
+                        tool_result_msg.add_part(TextPart(text=result_text))
+                        conv_manager.add_message(conv_id, tool_result_msg)
+
+                    # Update tool_calls for next iteration
+                    tool_calls = continuation_tool_calls
+                else:
+                    # No more tools called, exit loop
+                    logger.info(f"ReAct loop ending after {continuation_count} continuations")
+                    break
+
+            # Emit continuation summary
+            if event_callback:
+                event_callback(StreamEvent(
+                    type="continuation_complete",
+                    data={
+                        "iterations": continuation_count,
+                        "tool_count": len(all_tool_calls)
+                    }
+                ))
+
+            # Final summary call (no tools)
+            messages = conv_manager.to_model_format(conv_id)
+            final_text = []
+
+            async for event in provider.stream(messages, tools=tools):
+                if event_callback:
+                    event_callback(event)
+
+                if event.type == "text":
+                    final_text.append(event.data["text"])
+                    accumulated_text.append(event.data["text"])
+
+                elif event.type == "usage":
+                    usage = event.data.get("usage", {})
+                    usage_tokens += usage.get("completion_tokens", 0)
+
+            # Add final assistant message
+            if final_text:
+                final_msg = Message(id=self._generate_msg_id(), role="assistant")
+                final_msg.add_part(TextPart(text="".join(final_text)))
+                conv_manager.add_message(conv_id, final_msg)
+
+        return ReActResult(
+            assistant_text="".join(accumulated_text),
+            tool_calls=all_tool_calls,
+            usage_tokens=usage_tokens,
+            continuation_count=continuation_count if tool_calls else 0
+        )

ctrlcode/agents/registry.py

@@ -0,0 +1,211 @@
+"""Agent registry for creating specialized agents."""
+
+from pathlib import Path
+from typing import Any
+
+# Note: harness-utils integration will be added when we integrate
+# For now, this is the structure/interface
+
+
+class AgentConfig:
+    """Configuration for a specialized agent."""
+
+    def __init__(
+        self,
+        name: str,
+        system_prompt_path: str,
+        tools: list[str],
+        prune_protect: int = 50_000,
+        prune_minimum: int = 25_000,
+        max_lines: int = 3000,
+        use_predictive: bool = True,
+    ):
+        """
+        Initialize agent configuration.
+
+        Args:
+            name: Agent identifier (e.g., "planner", "coder")
+            system_prompt_path: Path to agent-specific prompt file
+            tools: List of allowed tool names
+            prune_protect: Context size before pruning starts (tokens)
+            prune_minimum: Minimum context after pruning (tokens)
+            max_lines: Maximum lines in tool output
+            use_predictive: Enable predictive overflow detection
+        """
+        self.name = name
+        self.system_prompt_path = system_prompt_path
+        self.tools = tools
+        self.prune_protect = prune_protect
+        self.prune_minimum = prune_minimum
+        self.max_lines = max_lines
+        self.use_predictive = use_predictive
+
+
+class AgentRegistry:
+    """Registry of specialized agent configurations."""
+
+    def __init__(self, workspace_root: Path, tool_registry: Any):
+        """
+        Initialize agent registry.
+
+        Args:
+            workspace_root: Root directory of workspace
+            tool_registry: ToolRegistry instance
+        """
+        self.workspace = workspace_root
+        self.tools = tool_registry
+        self.prompts_dir = workspace_root / "prompts" / "agents"
+
+    def get_planner_config(self) -> AgentConfig:
+        """Get configuration for Planner agent."""
+        return AgentConfig(
+            name="planner",
+            system_prompt_path=str(self.prompts_dir / "planner.md"),
+            tools=[
+                "search_files",
+                "search_code",
+                "read_file",
+                "list_directory",
+                "task_write",
+            ],
+            prune_protect=50_000,  # Moderate - needs context for planning
+            prune_minimum=25_000,
+            max_lines=3000,
+            use_predictive=True,
+        )
+
+    def get_coder_config(self, task_id: str | None = None) -> AgentConfig:
+        """
+        Get configuration for Coder agent.
+
+        Args:
+            task_id: Optional task identifier for naming
+        """
+        name = f"coder-{task_id}" if task_id else "coder"
+
+        return AgentConfig(
+            name=name,
+            system_prompt_path=str(self.prompts_dir / "coder.md"),
+            tools=[
+                "read_file",
+                "write_file",
+                "update_file",
+                "run_command",
+                "search_code",
+            ],
+            prune_protect=100_000,  # Large - needs full context for coding
+            prune_minimum=50_000,
+            max_lines=5000,
+            use_predictive=True,
+        )
+
+    def get_reviewer_config(self) -> AgentConfig:
+        """Get configuration for Reviewer agent."""
+        return AgentConfig(
+            name="reviewer",
+            system_prompt_path=str(self.prompts_dir / "reviewer.md"),
+            tools=[
+                "read_file",
+                "run_command",
+                "search_code",
+                "task_update",
+            ],
+            prune_protect=75_000,  # Moderate-large - needs context for review
+            prune_minimum=40_000,
+            max_lines=4000,
+            use_predictive=True,
+        )
+
+    def get_executor_config(self) -> AgentConfig:
+        """Get configuration for Executor agent."""
+        return AgentConfig(
+            name="executor",
+            system_prompt_path=str(self.prompts_dir / "executor.md"),
+            tools=[
+                "run_command",
+                "fetch",
+                "query_logs",
+                "query_metrics",
+                "screenshot",
+                "dom_snapshot",
+            ],
+            prune_protect=50_000,  # Moderate - runtime validation
+            prune_minimum=25_000,
+            max_lines=3000,
+            use_predictive=True,
+        )
+
+    def get_orchestrator_config(self) -> AgentConfig:
+        """Get configuration for Orchestrator agent."""
+        return AgentConfig(
+            name="orchestrator",
+            system_prompt_path=str(self.prompts_dir / "orchestrator.md"),
+            tools=[],  # Orchestrator delegates, doesn't use tools directly
+            prune_protect=30_000,  # Small - just coordinates
+            prune_minimum=15_000,
+            max_lines=2000,
+            use_predictive=True,
+        )
+
+    def get_agent_configs(self) -> dict[str, AgentConfig]:
+        """
+        Get all agent configurations.
+
+        Returns:
+            Dict mapping agent type to AgentConfig
+        """
+        return {
+            "planner": self.get_planner_config(),
+            "coder": self.get_coder_config(),
+            "reviewer": self.get_reviewer_config(),
+            "executor": self.get_executor_config(),
+            "orchestrator": self.get_orchestrator_config(),
+        }
+
+    def load_system_prompt(self, agent_type: str) -> str:
+        """
+        Load system prompt for agent type.
+
+        Args:
+            agent_type: Agent type (planner, coder, reviewer, executor, orchestrator)
+
+        Returns:
+            System prompt content
+
+        Raises:
+            FileNotFoundError: If prompt file doesn't exist
+        """
+        config = self.get_agent_configs()[agent_type]
+        prompt_path = Path(config.system_prompt_path)
+
+        if not prompt_path.exists():
+            raise FileNotFoundError(f"Prompt file not found: {prompt_path}")
+
+        return prompt_path.read_text()
+
+    def get_allowed_tools(self, agent_type: str) -> list[str]:
+        """
+        Get list of tools allowed for agent type.
+
+        Args:
+            agent_type: Agent type
+
+        Returns:
+            List of tool names
+        """
+        config = self.get_agent_configs()[agent_type]
+        return config.tools
+
+    def validate_tool_access(self, agent_type: str, tool_name: str) -> bool:
+        """
+        Check if agent is allowed to use tool.
+
+        Args:
+            agent_type: Agent type
+            tool_name: Tool to check
+
+        Returns:
+            True if allowed, False otherwise
+        """
+        allowed_tools = self.get_allowed_tools(agent_type)
+        return tool_name in allowed_tools