tunacode-cli 0.0.55__py3-none-any.whl → 0.0.78.6__py3-none-any.whl

tunacode/core/agents/main.py

@@ -1,12 +1,22 @@
 """Module: tunacode.core.agents.main
 
-Main agent functionality and coordination for the TunaCode CLI.
+Refactored main agent functionality with focused responsibility classes.
 Handles agent creation, configuration, and request processing.
 
 CLAUDE_ANCHOR[main-agent-module]: Primary agent orchestration and lifecycle management
+
+This is a refactored version of old main.py that:
+- Eliminates StateFacade in favor of direct SessionState access
+- Extracts intervention logic into focused classes
+- Centralizes prompts in prompts.py module
 """
 
-from typing import TYPE_CHECKING, Awaitable, Callable, Optional
+from __future__ import annotations
+
+import json
+import uuid
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Awaitable, Callable, Optional
 
 from pydantic_ai import Agent
 
@@ -16,445 +26,587 @@ if TYPE_CHECKING:
 from tunacode.core.logging.logger import get_logger
 from tunacode.core.state import StateManager
 from tunacode.exceptions import ToolBatchingJSONError, UserAbortError
-from tunacode.services.mcp import get_mcp_servers
+from tunacode.services.mcp import (  # re-exported by design
+    cleanup_mcp_servers,
+    get_mcp_servers,
+    register_mcp_agent,
+)
+from tunacode.tools.react import ReactTool
 from tunacode.types import (
     AgentRun,
     ModelName,
     ToolCallback,
     UsageTrackerProtocol,
 )
+from tunacode.ui import console as ui
 from tunacode.ui.tool_descriptions import get_batch_description
 
-# Import agent components
-from .agent_components import (
-    AgentRunWithState,
-    AgentRunWrapper,
-    ResponseState,
-    SimpleResult,
-    ToolBuffer,
-    _process_node,
-    check_task_completion,
-    create_empty_response_message,
-    create_fallback_response,
-    create_progress_summary,
-    create_user_message,
-    execute_tools_parallel,
-    extract_and_execute_tool_calls,
-    format_fallback_output,
-    get_model_messages,
-    get_or_create_agent,
-    get_recent_tools_context,
-    get_tool_summary,
-    parse_json_tool_calls,
-    patch_tool_messages,
-)
+from . import agent_components as ac
+from .prompts import format_clarification, format_iteration_limit, format_no_progress
 
-# Import streaming types with fallback for older versions
-try:
-    from pydantic_ai.messages import PartDeltaEvent, TextPartDelta
-
-    STREAMING_AVAILABLE = True
-except ImportError:
-    PartDeltaEvent = None
-    TextPartDelta = None
-    STREAMING_AVAILABLE = False
-
-# Configure logging
 logger = get_logger(__name__)
 
 __all__ = [
-    "ToolBuffer",
-    "check_task_completion",
-    "extract_and_execute_tool_calls",
-    "get_model_messages",
-    "parse_json_tool_calls",
-    "patch_tool_messages",
-    "get_mcp_servers",
-    "check_query_satisfaction",
     "process_request",
-    "get_or_create_agent",
-    "_process_node",
-    "ResponseState",
-    "SimpleResult",
-    "AgentRunWrapper",
-    "AgentRunWithState",
-    "execute_tools_parallel",
+    "get_mcp_servers",
+    "cleanup_mcp_servers",
+    "register_mcp_agent",
     "get_agent_tool",
+    "check_query_satisfaction",
 ]
 
 
-def get_agent_tool() -> tuple[type[Agent], type["Tool"]]:
-    """Lazy import for Agent and Tool to avoid circular imports."""
-    from pydantic_ai import Agent, Tool
-
-    return Agent, Tool
-
-
-async def check_query_satisfaction(
-    agent: Agent,
-    original_query: str,
-    response: str,
-    state_manager: StateManager,
-) -> bool:
-    """Check if the response satisfies the original query."""
-    return True  # Agent uses TUNACODE_TASK_COMPLETE marker
-
-
-async def process_request(
-    message: str,
-    model: ModelName,
-    state_manager: StateManager,
-    tool_callback: Optional[ToolCallback] = None,
-    streaming_callback: Optional[Callable[[str], Awaitable[None]]] = None,
-    usage_tracker: Optional[UsageTrackerProtocol] = None,
-    fallback_enabled: bool = True,
-) -> AgentRun:
-    """
-    Process a single request to the agent.
-
-    CLAUDE_ANCHOR[process-request-entry]: Main entry point for all agent requests
-
-    Args:
-        message: The user's request
-        model: The model to use
-        state_manager: State manager instance
-        tool_callback: Optional callback for tool execution
-        streaming_callback: Optional callback for streaming responses
-        usage_tracker: Optional usage tracker
-        fallback_enabled: Whether to enable fallback responses
-
-    Returns:
-        AgentRun or wrapper with result
-    """
-    # Get or create agent for the model
-    agent = get_or_create_agent(model, state_manager)
-
-    # Create a unique request ID for debugging
-    import uuid
-
-    request_id = str(uuid.uuid4())[:8]
-
-    # Reset state for new request
-    state_manager.session.current_iteration = 0
-    state_manager.session.iteration_count = 0
-    state_manager.session.tool_calls = []
+@dataclass
+class AgentConfig:
+    """Configuration for agent behavior."""
 
-    # Initialize batch counter if not exists
-    if not hasattr(state_manager.session, "batch_counter"):
-        state_manager.session.batch_counter = 0
+    max_iterations: int = 15
+    unproductive_limit: int = 3
+    forced_react_interval: int = 2
+    forced_react_limit: int = 5
+    debug_metrics: bool = False
 
-    # Create tool buffer for parallel execution
-    tool_buffer = ToolBuffer()
 
-    # Track iterations and productivity
-    max_iterations = state_manager.session.user_config.get("settings", {}).get("max_iterations", 15)
-    unproductive_iterations = 0
-    last_productive_iteration = 0
+@dataclass(slots=True)
+class RequestContext:
+    """Context for a single request."""
 
-    # Track response state
-    response_state = ResponseState()
+    request_id: str
+    max_iterations: int
+    debug_metrics: bool
 
-    try:
-        # Get message history from session messages
-        # Create a copy of the message history to avoid modifying the original
-        message_history = list(state_manager.session.messages)
-
-        async with agent.iter(message, message_history=message_history) as agent_run:
-            # Process nodes iteratively
-            i = 1
-            async for node in agent_run:
-                state_manager.session.current_iteration = i
-                state_manager.session.iteration_count = i
-
-                # Handle token-level streaming for model request nodes
-                Agent, _ = get_agent_tool()
-                if streaming_callback and STREAMING_AVAILABLE and Agent.is_model_request_node(node):
-                    async with node.stream(agent_run.ctx) as request_stream:
-                        async for event in request_stream:
-                            if isinstance(event, PartDeltaEvent) and isinstance(
-                                event.delta, TextPartDelta
-                            ):
-                                # Stream individual token deltas
-                                if event.delta.content_delta and streaming_callback:
-                                    await streaming_callback(event.delta.content_delta)
-
-                empty_response, empty_reason = await _process_node(
-                    node,
-                    tool_callback,
-                    state_manager,
-                    tool_buffer,
-                    streaming_callback,
-                    usage_tracker,
-                    response_state,
-                )
 
-                # Handle empty response
-                if empty_response:
-                    if not hasattr(state_manager.session, "consecutive_empty_responses"):
-                        state_manager.session.consecutive_empty_responses = 0
-                    state_manager.session.consecutive_empty_responses += 1
-
-                    if state_manager.session.consecutive_empty_responses >= 1:
-                        force_action_content = create_empty_response_message(
-                            message,
-                            empty_reason,
-                            state_manager.session.tool_calls,
-                            i,
-                            state_manager,
-                        )
-                        create_user_message(force_action_content, state_manager)
+class EmptyResponseHandler:
+    """Handles tracking and intervention for empty responses."""
 
-                        if state_manager.session.show_thoughts:
-                            from tunacode.ui import console as ui
+    def __init__(self, state_manager: StateManager) -> None:
+        self.state_manager = state_manager
 
-                            await ui.warning(
-                                "\n⚠️ EMPTY RESPONSE FAILURE - AGGRESSIVE RETRY TRIGGERED"
-                            )
-                            await ui.muted(f"   Reason: {empty_reason}")
-                            await ui.muted(
-                                f"   Recent tools: {get_recent_tools_context(state_manager.session.tool_calls)}"
-                            )
-                            await ui.muted("   Injecting 'YOU FAILED TRY HARDER' prompt")
+    def track(self, is_empty: bool) -> None:
+        """Track empty response and increment counter if empty."""
+        if is_empty:
+            current = getattr(self.state_manager.session, "consecutive_empty_responses", 0)
+            setattr(self.state_manager.session, "consecutive_empty_responses", current + 1)
+        else:
+            setattr(self.state_manager.session, "consecutive_empty_responses", 0)
 
-                        state_manager.session.consecutive_empty_responses = 0
-                else:
-                    if hasattr(state_manager.session, "consecutive_empty_responses"):
-                        state_manager.session.consecutive_empty_responses = 0
+    def should_intervene(self) -> bool:
+        """Check if intervention is needed (>= 1 consecutive empty)."""
+        return getattr(self.state_manager.session, "consecutive_empty_responses", 0) >= 1
 
-                if hasattr(node, "result") and node.result and hasattr(node.result, "output"):
-                    if node.result.output:
-                        response_state.has_user_response = True
+    async def prompt_action(self, message: str, reason: str, iteration: int) -> None:
+        """Delegate to agent_components.handle_empty_response."""
 
-                # Track productivity - check if any tools were used in this iteration
-                iteration_had_tools = False
-                if hasattr(node, "model_response"):
-                    for part in node.model_response.parts:
-                        if hasattr(part, "part_kind") and part.part_kind == "tool-call":
-                            iteration_had_tools = True
-                            break
-
-                if iteration_had_tools:
-                    # Reset unproductive counter
-                    unproductive_iterations = 0
-                    last_productive_iteration = i
-                else:
-                    # Increment unproductive counter
-                    unproductive_iterations += 1
-
-                # After 3 unproductive iterations, force action
-                if unproductive_iterations >= 3 and not response_state.task_completed:
-                    no_progress_content = f"""ALERT: No tools executed for {unproductive_iterations} iterations.
-
-Last productive iteration: {last_productive_iteration}
-Current iteration: {i}/{max_iterations}
-Task: {message[:200]}...
+        # Create a minimal state-like object for compatibility
+        class StateProxy:
+            def __init__(self, sm: StateManager) -> None:
+                self.sm = sm
+                self.show_thoughts = bool(getattr(sm.session, "show_thoughts", False))
 
-You're describing actions but not executing them. You MUST:
+        state_proxy = StateProxy(self.state_manager)
+        await ac.handle_empty_response(message, reason, iteration, state_proxy)
+        # Clear after intervention
+        setattr(self.state_manager.session, "consecutive_empty_responses", 0)
 
-1. If task is COMPLETE: Start response with TUNACODE_TASK_COMPLETE
-2. If task needs work: Execute a tool RIGHT NOW (grep, read_file, bash, etc.)
-3. If stuck: Explain the specific blocker
 
-NO MORE DESCRIPTIONS. Take ACTION or mark COMPLETE."""
+class IterationManager:
+    """Manages iteration tracking, productivity monitoring, and limit handling."""
 
-                    create_user_message(no_progress_content, state_manager)
+    def __init__(self, state_manager: StateManager, config: AgentConfig) -> None:
+        self.state_manager = state_manager
+        self.config = config
+        self.unproductive_iterations = 0
+        self.last_productive_iteration = 0
 
-                    if state_manager.session.show_thoughts:
-                        from tunacode.ui import console as ui
+    def track_productivity(self, had_tool_use: bool, iteration: int) -> None:
+        """Track productivity based on tool usage."""
+        if had_tool_use:
+            self.unproductive_iterations = 0
+            self.last_productive_iteration = iteration
+        else:
+            self.unproductive_iterations += 1
 
-                        await ui.warning(
-                            f"⚠️ NO PROGRESS: {unproductive_iterations} iterations without tool usage"
-                        )
+    def should_force_action(self, response_state: ac.ResponseState) -> bool:
+        """Check if action should be forced due to unproductivity."""
+        return (
+            self.unproductive_iterations >= self.config.unproductive_limit
+            and not response_state.task_completed
+        )
 
-                    unproductive_iterations = 0
+    async def handle_iteration_limit(
+        self, iteration: int, response_state: ac.ResponseState
+    ) -> None:
+        """Handle reaching iteration limit."""
+        if iteration >= self.config.max_iterations and not response_state.task_completed:
+            _, tools_str = ac.create_progress_summary(
+                getattr(self.state_manager.session, "tool_calls", [])
+            )
+            limit_message = format_iteration_limit(self.config.max_iterations, iteration, tools_str)
+            ac.create_user_message(limit_message, self.state_manager)
+
+            if getattr(self.state_manager.session, "show_thoughts", False):
+                await ui.muted(
+                    f"\nITERATION LIMIT: Awaiting user guidance at "
+                    f"{self.config.max_iterations} iterations"
+                )
 
-                # REMOVED: Recursive satisfaction check that caused empty responses
-                # The agent now decides completion using TUNACODE_TASK_COMPLETE marker
-                # This eliminates recursive agent calls and gives control back to the agent
+            response_state.awaiting_user_guidance = True
+
+    def update_counters(self, iteration: int) -> None:
+        """Update session iteration counters."""
+        self.state_manager.session.current_iteration = iteration
+        self.state_manager.session.iteration_count = iteration
+
+    async def force_action_if_unproductive(
+        self, message: str, iteration: int, response_state: ac.ResponseState
+    ) -> None:
+        """Force action if unproductive iterations exceeded."""
+        if not self.should_force_action(response_state):
+            return
+
+        no_progress_message = format_no_progress(
+            message,
+            self.unproductive_iterations,
+            self.last_productive_iteration,
+            iteration,
+            self.config.max_iterations,
+        )
+        ac.create_user_message(no_progress_message, self.state_manager)
 
-                # Store original query for reference
-                if not hasattr(state_manager.session, "original_query"):
-                    state_manager.session.original_query = message
+        if getattr(self.state_manager.session, "show_thoughts", False):
+            await ui.warning(
+                f"NO PROGRESS: {self.unproductive_iterations} iterations without tool usage"
+            )
 
-                # Display iteration progress if thoughts are enabled
-                if state_manager.session.show_thoughts:
-                    from tunacode.ui import console as ui
+        # Reset after nudge
+        self.unproductive_iterations = 0
 
-                    await ui.muted(f"\nITERATION: {i}/{max_iterations} (Request ID: {request_id})")
+    async def ask_for_clarification(self, iteration: int) -> None:
+        """Ask user for clarification."""
+        _, tools_used_str = ac.create_progress_summary(
+            getattr(self.state_manager.session, "tool_calls", [])
+        )
+        original_query = getattr(self.state_manager.session, "original_query", "your request")
+        clarification_message = format_clarification(original_query, iteration, tools_used_str)
+        ac.create_user_message(clarification_message, self.state_manager)
+
+        if getattr(self.state_manager.session, "show_thoughts", False):
+            await ui.muted("\nSEEKING CLARIFICATION: Asking user for guidance on task progress")
+
+
+class ReactSnapshotManager:
+    """Manages forced react snapshots and guidance injection."""
+
+    def __init__(
+        self, state_manager: StateManager, react_tool: ReactTool, config: AgentConfig
+    ) -> None:
+        self.state_manager = state_manager
+        self.react_tool = react_tool
+        self.config = config
+
+    def should_snapshot(self, iteration: int) -> bool:
+        """Check if snapshot should be taken."""
+        if iteration < self.config.forced_react_interval:
+            return False
+        if iteration % self.config.forced_react_interval != 0:
+            return False
+
+        forced_calls = getattr(self.state_manager.session, "react_forced_calls", 0)
+        return forced_calls < self.config.forced_react_limit
+
+    async def capture_snapshot(self, iteration: int, agent_run_ctx: Any, show_debug: bool) -> None:
+        """Capture react snapshot and inject guidance."""
+        if not self.should_snapshot(iteration):
+            return
+
+        try:
+            await self.react_tool.execute(
+                action="think",
+                thoughts=f"Auto snapshot after iteration {iteration}",
+                next_action="continue",
+            )
+
+            # Increment forced calls counter
+            forced_calls = getattr(self.state_manager.session, "react_forced_calls", 0)
+            self.state_manager.session.react_forced_calls = forced_calls + 1
+
+            # Build guidance from last tool call
+            timeline = self.state_manager.session.react_scratchpad.get("timeline", [])
+            latest = timeline[-1] if timeline else {"thoughts": "?", "next_action": "?"}
+            summary = latest.get("thoughts", "")
+
+            tool_calls = getattr(self.state_manager.session, "tool_calls", [])
+            if tool_calls:
+                last_tool = tool_calls[-1]
+                tool_name = last_tool.get("tool", "tool")
+                args = last_tool.get("args", {})
+                if isinstance(args, str):
+                    try:
+                        args = json.loads(args)
+                    except (ValueError, TypeError):
+                        args = {}
+
+                detail = ""
+                if tool_name == "grep" and isinstance(args, dict):
+                    pattern = args.get("pattern")
+                    detail = (
+                        f"Review grep results for pattern '{pattern}'"
+                        if pattern
+                        else "Review grep results"
+                    )
+                elif tool_name == "read_file" and isinstance(args, dict):
+                    path = args.get("file_path") or args.get("filepath")
+                    detail = (
+                        f"Extract key notes from {path}" if path else "Summarize read_file output"
+                    )
+                else:
+                    detail = f"Act on {tool_name} findings"
+            else:
+                detail = "Plan your first lookup"
+
+            guidance_entry = (
+                f"React snapshot {forced_calls + 1}/{self.config.forced_react_limit} "
+                f"at iteration {iteration}: {summary}. Next: {detail}"
+            )
+
+            # Append and trim guidance
+            self.state_manager.session.react_guidance.append(guidance_entry)
+            if len(self.state_manager.session.react_guidance) > self.config.forced_react_limit:
+                self.state_manager.session.react_guidance = (
+                    self.state_manager.session.react_guidance[-self.config.forced_react_limit :]
+                )
 
-                    # Show summary of tools used so far
-                    if state_manager.session.tool_calls:
-                        tool_summary = get_tool_summary(state_manager.session.tool_calls)
-                        summary_str = ", ".join(
-                            [f"{name}: {count}" for name, count in tool_summary.items()]
-                        )
-                        await ui.muted(f"TOOLS USED: {summary_str}")
+            # CRITICAL: Inject into agent_run.ctx.messages so next LLM call sees guidance
+            if agent_run_ctx is not None:
+                ctx_messages = getattr(agent_run_ctx, "messages", None)
+                if isinstance(ctx_messages, list):
+                    ModelRequest, _, SystemPromptPart = ac.get_model_messages()
+                    system_part = SystemPromptPart(
+                        content=f"[React Guidance] {guidance_entry}",
+                        part_kind="system-prompt",
+                    )
+                    # CLAUDE_ANCHOR[react-system-injection]
+                    # Append synthetic system message so LLM receives react guidance next turn
+                    ctx_messages.append(ModelRequest(parts=[system_part], kind="request"))
+
+            if show_debug:
+                await ui.muted("\n[react → LLM] BEGIN\n" + guidance_entry + "\n[react → LLM] END\n")
+        except Exception:
+            logger.debug("Forced react snapshot failed", exc_info=True)
+
+
+class RequestOrchestrator:
+    """Orchestrates the main request processing loop."""
+
+    def __init__(
+        self,
+        message: str,
+        model: ModelName,
+        state_manager: StateManager,
+        tool_callback: Optional[ToolCallback],
+        streaming_callback: Optional[Callable[[str], Awaitable[None]]],
+        usage_tracker: Optional[UsageTrackerProtocol],
+    ) -> None:
+        self.message = message
+        self.model = model
+        self.state_manager = state_manager
+        self.tool_callback = tool_callback
+        self.streaming_callback = streaming_callback
+        self.usage_tracker = usage_tracker
+
+        # Initialize config from session settings
+        user_config = getattr(state_manager.session, "user_config", {}) or {}
+        settings = user_config.get("settings", {})
+        self.config = AgentConfig(
+            max_iterations=int(settings.get("max_iterations", 15)),
+            unproductive_limit=3,
+            forced_react_interval=2,
+            forced_react_limit=5,
+            debug_metrics=bool(settings.get("debug_metrics", False)),
+        )
 
-                # User clarification: Ask user for guidance when explicitly awaiting
-                if response_state.awaiting_user_guidance:
-                    _, tools_used_str = create_progress_summary(state_manager.session.tool_calls)
+        # Initialize managers
+        self.empty_handler = EmptyResponseHandler(state_manager)
+        self.iteration_manager = IterationManager(state_manager, self.config)
+        self.react_manager = ReactSnapshotManager(
+            state_manager, ReactTool(state_manager=state_manager), self.config
+        )
 
-                    clarification_content = f"""I need clarification to continue.
+    def _init_request_context(self) -> RequestContext:
+        """Initialize request context with ID and config."""
+        req_id = str(uuid.uuid4())[:8]
+        setattr(self.state_manager.session, "request_id", req_id)
 
-Original request: {getattr(state_manager.session, "original_query", "your request")}
+        return RequestContext(
+            request_id=req_id,
+            max_iterations=self.config.max_iterations,
+            debug_metrics=self.config.debug_metrics,
+        )
 
-Progress so far:
-- Iterations: {i}
-- Tools used: {tools_used_str}
+    def _reset_session_state(self) -> None:
+        """Reset/initialize fields needed for a new run."""
+        self.state_manager.session.current_iteration = 0
+        self.state_manager.session.iteration_count = 0
+        self.state_manager.session.tool_calls = []
+        self.state_manager.session.react_forced_calls = 0
+        self.state_manager.session.react_guidance = []
+
+        # Counter used by other subsystems; initialize if absent
+        if not hasattr(self.state_manager.session, "batch_counter"):
+            self.state_manager.session.batch_counter = 0
+
+        # Track empty response streaks
+        setattr(self.state_manager.session, "consecutive_empty_responses", 0)
+
+        setattr(self.state_manager.session, "original_query", "")
+
+    def _set_original_query_once(self, query: str) -> None:
+        """Set original query if not already set."""
+        if not getattr(self.state_manager.session, "original_query", None):
+            setattr(self.state_manager.session, "original_query", query)
+
+    async def run(self) -> AgentRun:
+        """Run the main request processing loop."""
+        ctx = self._init_request_context()
+        self._reset_session_state()
+        self._set_original_query_once(self.message)
+
+        # Acquire agent
+        agent = ac.get_or_create_agent(self.model, self.state_manager)
+
+        # Prepare history snapshot
+        message_history = list(getattr(self.state_manager.session, "messages", []))
+
+        # Per-request trackers
+        tool_buffer = ac.ToolBuffer()
+        response_state = ac.ResponseState()
+
+        try:
+            async with agent.iter(self.message, message_history=message_history) as agent_run:
+                i = 1
+                async for node in agent_run:
+                    self.iteration_manager.update_counters(i)
+
+                    # Optional token streaming
+                    await _maybe_stream_node_tokens(
+                        node,
+                        agent_run.ctx,
+                        self.state_manager,
+                        self.streaming_callback,
+                        ctx.request_id,
+                        i,
+                    )
+
+                    # Core node processing
+                    empty_response, empty_reason = await ac._process_node(  # noqa: SLF001
+                        node,
+                        self.tool_callback,
+                        self.state_manager,
+                        tool_buffer,
+                        self.streaming_callback,
+                        self.usage_tracker,
+                        response_state,
+                    )
+
+                    # Handle empty response
+                    self.empty_handler.track(empty_response)
+                    if empty_response and self.empty_handler.should_intervene():
+                        await self.empty_handler.prompt_action(self.message, empty_reason, i)
+
+                    # Track whether we produced visible user output this iteration
+                    if getattr(getattr(node, "result", None), "output", None):
+                        response_state.has_user_response = True
 
-If the task is complete, I should respond with TUNACODE_TASK_COMPLETE.
-Otherwise, please provide specific guidance on what to do next."""
+                    # Productivity tracking
+                    had_tool_use = _iteration_had_tool_use(node)
+                    self.iteration_manager.track_productivity(had_tool_use, i)
 
-                    create_user_message(clarification_content, state_manager)
+                    # Force action if unproductive
+                    await self.iteration_manager.force_action_if_unproductive(
+                        self.message, i, response_state
+                    )
 
-                    if state_manager.session.show_thoughts:
-                        from tunacode.ui import console as ui
+                    # Force react snapshot
+                    show_thoughts = bool(
+                        getattr(self.state_manager.session, "show_thoughts", False)
+                    )
+                    await self.react_manager.capture_snapshot(i, agent_run.ctx, show_thoughts)
 
+                    # Optional debug progress
+                    if show_thoughts:
                         await ui.muted(
-                            "\n🤔 SEEKING CLARIFICATION: Asking user for guidance on task progress"
+                            f"\nITERATION: {i}/{ctx.max_iterations} (Request ID: {ctx.request_id})"
                         )
+                        tool_summary = ac.get_tool_summary(
+                            getattr(self.state_manager.session, "tool_calls", [])
+                        )
+                        if tool_summary:
+                            summary_str = ", ".join(
+                                f"{name}: {count}" for name, count in tool_summary.items()
+                            )
+                            await ui.muted(f"TOOLS USED: {summary_str}")
+
+                    # Ask for clarification if agent requested it
+                    if response_state.awaiting_user_guidance:
+                        await self.iteration_manager.ask_for_clarification(i)
+
+                    # Early completion
+                    if response_state.task_completed:
+                        if show_thoughts:
+                            await ui.success("Task completed successfully")
+                        break
+
+                    # Handle iteration limit
+                    await self.iteration_manager.handle_iteration_limit(i, response_state)
+
+                    i += 1
+
+                await _finalize_buffered_tasks(tool_buffer, self.tool_callback, self.state_manager)
+
+                # Return wrapper that carries response_state
+                return ac.AgentRunWithState(agent_run, response_state)
+
+        except UserAbortError:
+            raise
+        except ToolBatchingJSONError as e:
+            logger.error("Tool batching JSON error [req=%s]: %s", ctx.request_id, e, exc_info=True)
+            ac.patch_tool_messages(
+                f"Tool batching failed: {str(e)[:100]}...", state_manager=self.state_manager
+            )
+            raise
+        except Exception as e:
+            # Attach request/iteration context for observability
+            safe_iter = getattr(self.state_manager.session, "current_iteration", "?")
+            logger.error(
+                "Error in process_request [req=%s iter=%s]: %s",
+                ctx.request_id,
+                safe_iter,
+                e,
+                exc_info=True,
+            )
+            ac.patch_tool_messages(
+                f"Request processing failed: {str(e)[:100]}...",
+                state_manager=self.state_manager,
+            )
+            raise
+
+
+# Utility functions
+
+
+async def _maybe_stream_node_tokens(
+    node: Any,
+    agent_run_ctx: Any,
+    state_manager: StateManager,
+    streaming_cb: Optional[Callable[[str], Awaitable[None]]],
+    request_id: str,
+    iteration_index: int,
+) -> None:
+    """Stream tokens from model request nodes if callback provided.
 
-                    response_state.awaiting_user_guidance = True
+    Reference: main.py lines 146-161
+    """
+    if not streaming_cb:
+        return
 
-                # Check if task is explicitly completed
-                if response_state.task_completed:
-                    if state_manager.session.show_thoughts:
-                        from tunacode.ui import console as ui
+    # Delegate to component streaming helper
+    if Agent.is_model_request_node(node):  # type: ignore[attr-defined]
+        await ac.stream_model_request_node(
+            node, agent_run_ctx, state_manager, streaming_cb, request_id, iteration_index
+        )
 
-                        await ui.success("Task completed successfully")
-                    break
 
-                if i >= max_iterations and not response_state.task_completed:
-                    _, tools_str = create_progress_summary(state_manager.session.tool_calls)
-                    tools_str = tools_str if tools_str != "No tools used yet" else "No tools used"
+def _iteration_had_tool_use(node: Any) -> bool:
+    """Inspect the node to see if model responded with any tool-call parts.
 
-                    extend_content = f"""I've reached the iteration limit ({max_iterations}).
+    Reference: main.py lines 164-171
+    """
+    if hasattr(node, "model_response"):
+        for part in getattr(node.model_response, "parts", []):
+            # pydantic-ai annotates tool calls; be resilient to attr differences
+            if getattr(part, "part_kind", None) == "tool-call":
+                return True
+    return False
 
-Progress summary:
-- Tools used: {tools_str}
-- Iterations completed: {i}
 
-The task appears incomplete. Would you like me to:
-1. Continue working (I can extend the limit)
-2. Summarize what I've done and stop
-3. Try a different approach
+async def _finalize_buffered_tasks(
+    tool_buffer: ac.ToolBuffer,
+    tool_callback: Optional[ToolCallback],
+    state_manager: StateManager,
+) -> None:
+    """Finalize and execute any buffered read-only tasks."""
+    if not tool_callback or not tool_buffer.has_tasks():
+        return
 
-Please let me know how to proceed."""
+    buffered_tasks = tool_buffer.flush()
 
-                    create_user_message(extend_content, state_manager)
+    # Update spinner message (best-effort)
+    try:
+        tool_names = [part.tool_name for part, _ in buffered_tasks]
+        batch_msg = get_batch_description(len(buffered_tasks), tool_names)
+        await ui.update_spinner_message(
+            f"[bold #00d7ff]{batch_msg}...[/bold #00d7ff]", state_manager
+        )
+    except Exception:
+        # UI is best-effort; never fail request because of display
+        logger.debug("UI batch prelude failed (non-fatal)", exc_info=True)
 
-                    if state_manager.session.show_thoughts:
-                        from tunacode.ui import console as ui
+    # Execute
+    await ac.execute_tools_parallel(buffered_tasks, tool_callback)
 
-                        await ui.muted(
-                            f"\n📊 ITERATION LIMIT: Asking user for guidance at {max_iterations} iterations"
-                        )
+    # Reset spinner message (best-effort)
+    try:
+        from tunacode.constants import UI_THINKING_MESSAGE  # local import OK (rare path)
 
-                    max_iterations += 5
-                    response_state.awaiting_user_guidance = True
+        await ui.update_spinner_message(UI_THINKING_MESSAGE, state_manager)
+    except Exception:
+        logger.debug("UI batch epilogue failed (non-fatal)", exc_info=True)
 
-                # Increment iteration counter
-                i += 1
 
-            # Final flush: execute any remaining buffered read-only tools
-            if tool_callback and tool_buffer.has_tasks():
-                import time
+def get_agent_tool() -> tuple[type[Agent], type["Tool"]]:
+    """Return Agent and Tool classes without importing at module load time.
 
-                from tunacode.ui import console as ui
+    Reference: main.py lines 354-359
+    """
+    from pydantic_ai import Agent as AgentCls
+    from pydantic_ai import Tool as ToolCls
 
-                buffered_tasks = tool_buffer.flush()
-                start_time = time.time()
+    return AgentCls, ToolCls
 
-                # Update spinner message for final batch execution
-                tool_names = [part.tool_name for part, _ in buffered_tasks]
-                batch_msg = get_batch_description(len(buffered_tasks), tool_names)
-                await ui.update_spinner_message(
-                    f"[bold #00d7ff]{batch_msg}...[/bold #00d7ff]", state_manager
-                )
 
-                await ui.muted("\n" + "=" * 60)
-                await ui.muted(
-                    f"🚀 FINAL BATCH: Executing {len(buffered_tasks)} buffered read-only tools"
-                )
-                await ui.muted("=" * 60)
-
-                for idx, (part, node) in enumerate(buffered_tasks, 1):
-                    tool_desc = f"  [{idx}] {part.tool_name}"
-                    if hasattr(part, "args") and isinstance(part.args, dict):
-                        if part.tool_name == "read_file" and "file_path" in part.args:
-                            tool_desc += f" → {part.args['file_path']}"
-                        elif part.tool_name == "grep" and "pattern" in part.args:
-                            tool_desc += f" → pattern: '{part.args['pattern']}'"
-                            if "include_files" in part.args:
-                                tool_desc += f", files: '{part.args['include_files']}'"
-                        elif part.tool_name == "list_dir" and "directory" in part.args:
-                            tool_desc += f" → {part.args['directory']}"
-                        elif part.tool_name == "glob" and "pattern" in part.args:
-                            tool_desc += f" → pattern: '{part.args['pattern']}'"
-                    await ui.muted(tool_desc)
-                await ui.muted("=" * 60)
-
-                await execute_tools_parallel(buffered_tasks, tool_callback)
-
-                elapsed_time = (time.time() - start_time) * 1000
-                sequential_estimate = len(buffered_tasks) * 100
-                speedup = sequential_estimate / elapsed_time if elapsed_time > 0 else 1.0
+async def check_query_satisfaction(
+    agent: Agent,
+    original_query: str,
+    response: str,
+    state_manager: StateManager,
+) -> bool:
+    """Legacy hook for compatibility; completion still signaled via DONE marker."""
+    return True
 
-                await ui.muted(
-                    f"✅ Final batch completed in {elapsed_time:.0f}ms "
-                    f"(~{speedup:.1f}x faster than sequential)\n"
-                )
 
-                # Reset spinner back to thinking
-                from tunacode.constants import UI_THINKING_MESSAGE
+# Main entry point
 
-                await ui.update_spinner_message(UI_THINKING_MESSAGE, state_manager)
 
-            # If we need to add a fallback response, create a wrapper
-            if (
-                not response_state.has_user_response
-                and not response_state.task_completed
-                and i >= max_iterations
-                and fallback_enabled
-            ):
-                patch_tool_messages("Task incomplete", state_manager=state_manager)
-                response_state.has_final_synthesis = True
+async def process_request(
+    message: str,
+    model: ModelName,
+    state_manager: StateManager,
+    tool_callback: Optional[ToolCallback] = None,
+    streaming_callback: Optional[Callable[[str], Awaitable[None]]] = None,
+    usage_tracker: Optional[UsageTrackerProtocol] = None,
+) -> AgentRun:
+    """
+    Process a single request to the agent.
 
-                verbosity = state_manager.session.user_config.get("settings", {}).get(
-                    "fallback_verbosity", "normal"
-                )
-                fallback = create_fallback_response(
-                    i,
-                    max_iterations,
-                    state_manager.session.tool_calls,
-                    state_manager.session.messages,
-                    verbosity,
-                )
-                comprehensive_output = format_fallback_output(fallback)
+    CLAUDE_ANCHOR[process-request-entry]: Main entry point for all agent requests
 
-                wrapper = AgentRunWrapper(
-                    agent_run, SimpleResult(comprehensive_output), response_state
-                )
-                return wrapper
-
-            # For non-fallback cases, we still need to handle the response_state
-            # Create a minimal wrapper just to add response_state
-            state_wrapper = AgentRunWithState(agent_run, response_state)
-            return state_wrapper
-
-    except UserAbortError:
-        raise
-    except ToolBatchingJSONError as e:
-        logger.error(f"Tool batching JSON error: {e}", exc_info=True)
-        # Patch orphaned tool messages with error
-        patch_tool_messages(f"Tool batching failed: {str(e)[:100]}...", state_manager=state_manager)
-        # Re-raise to be handled by caller
-        raise
-    except Exception as e:
-        logger.error(f"Error in process_request: {e}", exc_info=True)
-        # Patch orphaned tool messages with generic error
-        patch_tool_messages(
-            f"Request processing failed: {str(e)[:100]}...", state_manager=state_manager
-        )
-        # Re-raise to be handled by caller
-        raise
+    """
+    orchestrator = RequestOrchestrator(
+        message,
+        model,
+        state_manager,
+        tool_callback,
+        streaming_callback,
+        usage_tracker,
+    )
+    return await orchestrator.run()