tunacode-cli 0.0.76__py3-none-any.whl → 0.0.76.1__py3-none-any.whl

tunacode/cli/main.py

@@ -30,6 +30,9 @@ def main(
     wizard: bool = typer.Option(
         False, "--wizard", help="Run interactive setup wizard for guided configuration."
     ),
+    show_config: bool = typer.Option(
+        False, "--show-config", help="Show configuration dashboard and exit."
+    ),
     baseurl: str = typer.Option(
         None, "--baseurl", help="API base URL (e.g., https://openrouter.ai/api/v1)"
     ),
@@ -49,6 +52,13 @@ def main(
             await ui.version()
             return
 
+        if show_config:
+            from tunacode.ui.config_dashboard import show_config_dashboard
+
+            await ui.banner()
+            show_config_dashboard()
+            return
+
         await ui.banner()
 
         # Start update check in background

tunacode/cli/repl.py

@@ -320,7 +320,9 @@ async def process_request(text: str, state_manager: StateManager, output: bool =
         if enable_streaming:
             await ui.spinner(False, state_manager.session.spinner, state_manager)
             state_manager.session.is_streaming_active = True
-            streaming_panel = ui.StreamingAgentPanel()
+            streaming_panel = ui.StreamingAgentPanel(
+                debug=bool(state_manager.session.show_thoughts)
+            )
             await streaming_panel.start()
             state_manager.session.streaming_panel = streaming_panel
 
@@ -337,6 +339,20 @@ async def process_request(text: str, state_manager: StateManager, output: bool =
                 await streaming_panel.stop()
                 state_manager.session.streaming_panel = None
                 state_manager.session.is_streaming_active = False
+                # Emit source-side streaming diagnostics if thoughts are enabled
+                if state_manager.session.show_thoughts:
+                    try:
+                        raw = getattr(state_manager.session, "_debug_raw_stream_accum", "") or ""
+                        events = getattr(state_manager.session, "_debug_events", []) or []
+                        raw_first5 = repr(raw[:5])
+                        await ui.muted(
+                            f"[debug] raw_stream_first5={raw_first5} total_len={len(raw)}"
+                        )
+                        for line in events:
+                            await ui.muted(line)
+                    except Exception:
+                        # Don't let diagnostics break normal flow
+                        pass
         else:
             res = await agent.process_request(
                 text,

tunacode/configuration/defaults.py

@@ -5,7 +5,7 @@ Default configuration values for the TunaCode CLI.
 Provides sensible defaults for user configuration and environment variables.
 """
 
-from tunacode.constants import GUIDE_FILE_NAME, ToolName
+from tunacode.constants import GUIDE_FILE_NAME
 from tunacode.types import UserConfig
 
 DEFAULT_USER_CONFIG: UserConfig = {
@@ -19,7 +19,7 @@ DEFAULT_USER_CONFIG: UserConfig = {
     "settings": {
         "max_retries": 10,
         "max_iterations": 40,
-        "tool_ignore": [ToolName.READ_FILE],
+        "tool_ignore": [],
         "guide_file": GUIDE_FILE_NAME,
         "fallback_response": True,
         "fallback_verbosity": "normal",  # Options: minimal, normal, detailed

tunacode/configuration/key_descriptions.py

@@ -0,0 +1,275 @@
+"""
+Module: tunacode.configuration.key_descriptions
+
+Educational descriptions and examples for configuration keys to help users
+understand what each setting does and how to configure it properly.
+"""
+
+from dataclasses import dataclass
+from typing import Any, Dict, Optional
+
+
+@dataclass
+class KeyDescription:
+    """Description of a configuration key with examples and help text."""
+
+    name: str
+    description: str
+    example: Any
+    help_text: str
+    category: str
+    is_sensitive: bool = False
+    service_type: Optional[str] = None  # For API keys: "openai", "anthropic", etc.
+
+
+# Configuration key descriptions organized by category
+CONFIG_KEY_DESCRIPTIONS: Dict[str, KeyDescription] = {
+    # Root level keys
+    "default_model": KeyDescription(
+        name="default_model",
+        description="Which AI model TunaCode uses by default",
+        example="openrouter:openai/gpt-4.1",
+        help_text="Format: provider:model-name. Examples: openai:gpt-4, anthropic:claude-3-sonnet, google:gemini-pro",
+        category="AI Models",
+    ),
+    "skip_git_safety": KeyDescription(
+        name="skip_git_safety",
+        description="Skip Git safety checks when making changes",
+        example=True,
+        help_text="When true, TunaCode won't create safety branches before making changes. Use with caution!",
+        category="Safety Settings",
+    ),
+    # Environment variables (API Keys)
+    "env.OPENAI_API_KEY": KeyDescription(
+        name="OPENAI_API_KEY",
+        description="Your OpenAI API key for GPT models",
+        example="sk-proj-abc123...",
+        help_text="Get this from https://platform.openai.com/api-keys. Required for OpenAI models like GPT-4.",
+        category="API Keys",
+        is_sensitive=True,
+        service_type="openai",
+    ),
+    "env.ANTHROPIC_API_KEY": KeyDescription(
+        name="ANTHROPIC_API_KEY",
+        description="Your Anthropic API key for Claude models",
+        example="sk-ant-api03-abc123...",
+        help_text="Get this from https://console.anthropic.com/. Required for Claude models.",
+        category="API Keys",
+        is_sensitive=True,
+        service_type="anthropic",
+    ),
+    "env.OPENROUTER_API_KEY": KeyDescription(
+        name="OPENROUTER_API_KEY",
+        description="Your OpenRouter API key for accessing multiple models",
+        example="sk-or-v1-abc123...",
+        help_text="Get this from https://openrouter.ai/keys. Gives access to many different AI models.",
+        category="API Keys",
+        is_sensitive=True,
+        service_type="openrouter",
+    ),
+    "env.GEMINI_API_KEY": KeyDescription(
+        name="GEMINI_API_KEY",
+        description="Your Google Gemini API key",
+        example="AIza123...",
+        help_text="Get this from Google AI Studio. Required for Gemini models.",
+        category="API Keys",
+        is_sensitive=True,
+        service_type="google",
+    ),
+    "env.OPENAI_BASE_URL": KeyDescription(
+        name="OPENAI_BASE_URL",
+        description="Custom API endpoint for OpenAI-compatible services",
+        example="https://api.cerebras.ai/v1",
+        help_text="Use this to connect to local models (LM Studio, Ollama) or alternative providers like Cerebras.",
+        category="API Configuration",
+    ),
+    # Settings
+    "settings.max_retries": KeyDescription(
+        name="max_retries",
+        description="How many times to retry failed API calls",
+        example=10,
+        help_text="Higher values = more resilient to temporary API issues, but slower when APIs are down.",
+        category="Behavior Settings",
+    ),
+    "settings.max_iterations": KeyDescription(
+        name="max_iterations",
+        description="Maximum conversation turns before stopping",
+        example=40,
+        help_text="Prevents infinite loops. TunaCode will stop after this many back-and-forth exchanges.",
+        category="Behavior Settings",
+    ),
+    "settings.tool_ignore": KeyDescription(
+        name="tool_ignore",
+        description="List of tools TunaCode should not use",
+        example=["read_file", "write_file"],
+        help_text="Useful for restricting what TunaCode can do. Empty list means all tools are available.",
+        category="Tool Configuration",
+    ),
+    "settings.guide_file": KeyDescription(
+        name="guide_file",
+        description="Name of your project guide file",
+        example="TUNACODE.md",
+        help_text="TunaCode looks for this file to understand your project. Usually TUNACODE.md or README.md.",
+        category="Project Settings",
+    ),
+    "settings.fallback_response": KeyDescription(
+        name="fallback_response",
+        description="Whether to provide a response when tools fail",
+        example=True,
+        help_text="When true, TunaCode will try to help even if some tools don't work properly.",
+        category="Behavior Settings",
+    ),
+    "settings.fallback_verbosity": KeyDescription(
+        name="fallback_verbosity",
+        description="How detailed fallback responses should be",
+        example="normal",
+        help_text="Options: minimal, normal, detailed. Controls how much TunaCode explains when things go wrong.",
+        category="Behavior Settings",
+    ),
+    "settings.context_window_size": KeyDescription(
+        name="context_window_size",
+        description="Maximum tokens TunaCode can use in one conversation",
+        example=200000,
+        help_text="Larger values = TunaCode remembers more context, but costs more. Adjust based on your model's limits.",
+        category="Performance Settings",
+    ),
+    "settings.enable_streaming": KeyDescription(
+        name="enable_streaming",
+        description="Show AI responses as they're generated",
+        example=True,
+        help_text="When true, you see responses appear word-by-word. When false, you wait for complete responses.",
+        category="User Experience",
+    ),
+    # Ripgrep settings
+    "settings.ripgrep.use_bundled": KeyDescription(
+        name="ripgrep.use_bundled",
+        description="Use TunaCode's built-in ripgrep instead of system version",
+        example=False,
+        help_text="Usually false is better - uses your system's ripgrep which may be newer/faster.",
+        category="Search Settings",
+    ),
+    "settings.ripgrep.timeout": KeyDescription(
+        name="ripgrep.timeout",
+        description="How long to wait for search results (seconds)",
+        example=10,
+        help_text="Prevents searches from hanging. Increase for very large codebases.",
+        category="Search Settings",
+    ),
+    "settings.ripgrep.max_buffer_size": KeyDescription(
+        name="ripgrep.max_buffer_size",
+        description="Maximum size of search results (bytes)",
+        example=1048576,
+        help_text="1MB by default. Prevents memory issues with huge search results.",
+        category="Search Settings",
+    ),
+    "settings.ripgrep.max_results": KeyDescription(
+        name="ripgrep.max_results",
+        description="Maximum number of search results to return",
+        example=100,
+        help_text="Prevents overwhelming output. Increase if you need more comprehensive search results.",
+        category="Search Settings",
+    ),
+    "settings.ripgrep.enable_metrics": KeyDescription(
+        name="ripgrep.enable_metrics",
+        description="Collect performance data about searches",
+        example=False,
+        help_text="Enable for debugging search performance. Usually not needed.",
+        category="Search Settings",
+    ),
+    "settings.ripgrep.debug": KeyDescription(
+        name="ripgrep.debug",
+        description="Show detailed search debugging information",
+        example=False,
+        help_text="Enable for troubleshooting search issues. Creates verbose output.",
+        category="Search Settings",
+    ),
+    # Tutorial/onboarding settings
+    "settings.enable_tutorial": KeyDescription(
+        name="enable_tutorial",
+        description="Show tutorial prompts for new users",
+        example=True,
+        help_text="Helps new users learn TunaCode. Disable once you're comfortable with the tool.",
+        category="User Experience",
+    ),
+    "settings.first_installation_date": KeyDescription(
+        name="first_installation_date",
+        description="When TunaCode was first installed",
+        example="2025-09-11T11:50:40.167105",
+        help_text="Automatically set. Used for tracking usage patterns and showing relevant tips.",
+        category="System Information",
+    ),
+    "settings.tutorial_declined": KeyDescription(
+        name="tutorial_declined",
+        description="Whether user declined the tutorial",
+        example=True,
+        help_text="Automatically set when you skip the tutorial. Prevents repeated tutorial prompts.",
+        category="User Experience",
+    ),
+    # MCP Servers
+    "mcpServers": KeyDescription(
+        name="mcpServers",
+        description="Model Context Protocol server configurations",
+        example={},
+        help_text="Advanced feature for connecting external tools and services. Usually empty for basic usage.",
+        category="Advanced Features",
+    ),
+}
+
+
+def get_key_description(key_path: str) -> Optional[KeyDescription]:
+    """Get description for a configuration key by its path."""
+    return CONFIG_KEY_DESCRIPTIONS.get(key_path)
+
+
+def get_service_type_for_api_key(key_name: str) -> Optional[str]:
+    """Determine the service type for an API key."""
+    service_mapping = {
+        "OPENAI_API_KEY": "openai",
+        "ANTHROPIC_API_KEY": "anthropic",
+        "OPENROUTER_API_KEY": "openrouter",
+        "GEMINI_API_KEY": "google",
+    }
+    return service_mapping.get(key_name)
+
+
+def get_categories() -> Dict[str, list[KeyDescription]]:
+    """Get all configuration keys organized by category."""
+    categories: Dict[str, list[KeyDescription]] = {}
+
+    for desc in CONFIG_KEY_DESCRIPTIONS.values():
+        if desc.category not in categories:
+            categories[desc.category] = []
+        categories[desc.category].append(desc)
+
+    return categories
+
+
+def get_configuration_glossary() -> str:
+    """Generate a glossary of configuration terms for the help section."""
+    glossary = """
+[bold]Configuration Key Glossary[/bold]
+
+[cyan]What are configuration keys?[/cyan]
+Configuration keys are setting names (like 'default_model', 'max_retries') that control how TunaCode behaves.
+Think of them like preferences in any app - they let you customize TunaCode to work the way you want.
+
+[cyan]Key Categories:[/cyan]
+• [yellow]AI Models[/yellow]: Which AI to use (GPT-4, Claude, etc.)
+• [yellow]API Keys[/yellow]: Your credentials for AI services
+• [yellow]Behavior Settings[/yellow]: How TunaCode acts (retries, iterations, etc.)
+• [yellow]Tool Configuration[/yellow]: Which tools TunaCode can use
+• [yellow]Performance Settings[/yellow]: Memory and speed optimizations
+• [yellow]User Experience[/yellow]: Interface and tutorial preferences
+
+[cyan]Common Examples:[/cyan]
+• default_model → Which AI model to use by default
+• max_retries → How many times to retry failed requests
+• OPENAI_API_KEY → Your OpenAI account credentials
+• tool_ignore → List of tools TunaCode shouldn't use
+• context_window_size → How much conversation history to remember
+
+[cyan]Default vs Custom:[/cyan]
+• 📋 Default: TunaCode's built-in settings (work for most people)
+• 🔧 Custom: Settings you've changed to fit your needs
+"""
+    return glossary.strip()

tunacode/constants.py

@@ -9,7 +9,7 @@ from enum import Enum
 
 # Application info
 APP_NAME = "TunaCode"
-APP_VERSION = "0.0.76"
+APP_VERSION = "0.0.76.1"
 
 
 # File patterns

tunacode/core/agents/agent_components/node_processor.py

@@ -209,11 +209,32 @@ async def _process_node(
         # Stream content to callback if provided
         # Use this as fallback when true token streaming is not available
         if streaming_callback and not STREAMING_AVAILABLE:
+            # Basic diagnostics for first-chunk behavior in fallback streaming
+            first_emitted = False
+            raw_accum = ""
             for part in node.model_response.parts:
                 if hasattr(part, "content") and isinstance(part.content, str):
-                    content = part.content.strip()
-                    if content and not content.startswith('{"thought"'):
-                        # Stream non-JSON content (actual response content)
+                    content = part.content
+                    # Only check for empty content and JSON thoughts, don't strip whitespace
+                    # as it may remove important leading spaces/characters
+                    if content and not content.lstrip().startswith('{"thought"'):
+                        if not first_emitted:
+                            try:
+                                import time as _t
+
+                                ts_ns = _t.perf_counter_ns()
+                            except Exception:
+                                ts_ns = 0
+                            # We cannot guarantee session access here; log via logger only
+                            logger.debug(
+                                "[src-fallback] first_chunk ts_ns=%s chunk_repr=%r len=%d",
+                                ts_ns,
+                                content[:5],
+                                len(content),
+                            )
+                            first_emitted = True
+                        raw_accum += content
+                        # Stream the original content without stripping
                         if streaming_callback:
                             await streaming_callback(content)
 

tunacode/core/agents/agent_components/streaming.py

@@ -0,0 +1,268 @@
+"""Streaming instrumentation and handling for agent model request nodes.
+
+This module encapsulates verbose streaming + logging logic used during
+token-level streaming from the LLM provider. It updates session debug fields
+and streams deltas to the provided callback while being resilient to errors.
+"""
+
+from __future__ import annotations
+
+from typing import Awaitable, Callable, Optional
+
+from tunacode.core.logging.logger import get_logger
+from tunacode.core.state import StateManager
+
+# Import streaming types with fallback for older versions
+try:  # pragma: no cover - import guard for pydantic_ai streaming types
+    from pydantic_ai.messages import PartDeltaEvent, TextPartDelta  # type: ignore
+
+    STREAMING_AVAILABLE = True
+except Exception:  # pragma: no cover - fallback when streaming types unavailable
+    PartDeltaEvent = None  # type: ignore
+    TextPartDelta = None  # type: ignore
+    STREAMING_AVAILABLE = False
+
+
+logger = get_logger(__name__)
+
+
+async def stream_model_request_node(
+    node,
+    agent_run_ctx,
+    state_manager: StateManager,
+    streaming_callback: Optional[Callable[[str], Awaitable[None]]],
+    request_id: str,
+    iteration_index: int,
+) -> None:
+    """Stream token deltas for a model request node with detailed instrumentation.
+
+    This function mirrors the prior inline logic in main.py but is extracted to
+    keep main.py lean. It performs up to one retry on streaming failure and then
+    degrades to non-streaming for that node.
+    """
+    if not (STREAMING_AVAILABLE and streaming_callback):
+        return
+
+    # Gracefully handle streaming errors from LLM provider
+    for attempt in range(2):  # simple retry once, then degrade gracefully
+        try:
+            async with node.stream(agent_run_ctx) as request_stream:
+                # Initialize per-node debug accumulators
+                state_manager.session._debug_raw_stream_accum = ""
+                state_manager.session._debug_events = []
+                first_delta_logged = False
+                debug_event_count = 0
+                first_delta_seen = False
+                seeded_prefix_sent = False
+                pre_first_delta_text: Optional[str] = None
+
+                # Helper to extract text from a possible final-result object
+                def _extract_text(obj) -> Optional[str]:
+                    try:
+                        if obj is None:
+                            return None
+                        if isinstance(obj, str):
+                            return obj
+                        # Common attributes that may hold text
+                        for attr in ("output", "text", "content", "message"):
+                            v = getattr(obj, attr, None)
+                            if isinstance(v, str) and v:
+                                return v
+                        # Parts-based result
+                        parts = getattr(obj, "parts", None)
+                        if isinstance(parts, (list, tuple)) and parts:
+                            texts: list[str] = []
+                            for p in parts:
+                                c = getattr(p, "content", None)
+                                if isinstance(c, str) and c:
+                                    texts.append(c)
+                            if texts:
+                                return "".join(texts)
+                        # Nested .result or .response
+                        for attr in ("result", "response", "final"):
+                            v = getattr(obj, attr, None)
+                            t = _extract_text(v)
+                            if t:
+                                return t
+                    except Exception:
+                        return None
+                    return None
+
+                # Mark stream open
+                try:
+                    import time as _t
+
+                    state_manager.session._debug_events.append(
+                        f"[src] stream_opened ts_ns={_t.perf_counter_ns()}"
+                    )
+                except Exception:
+                    pass
+
+                async for event in request_stream:
+                    debug_event_count += 1
+                    # Log first few raw event types for diagnosis
+                    if debug_event_count <= 5:
+                        try:
+                            etype = type(event).__name__
+                            d = getattr(event, "delta", None)
+                            dtype = type(d).__name__ if d is not None else None
+                            c = getattr(d, "content_delta", None) if d is not None else None
+                            clen = len(c) if isinstance(c, str) else None
+                            cpreview = repr(c[:5]) if isinstance(c, str) else None
+                            # Probe common fields on non-delta events to see if they contain text
+                            r = getattr(event, "result", None)
+                            rtype = type(r).__name__ if r is not None else None
+                            rpreview = None
+                            rplen = None
+                            # Also inspect event.part if present (e.g., PartStartEvent)
+                            p = getattr(event, "part", None)
+                            ptype = type(p).__name__ if p is not None else None
+                            pkind = getattr(p, "part_kind", None)
+                            pcontent = getattr(p, "content", None)
+                            ppreview = repr(pcontent[:20]) if isinstance(pcontent, str) else None
+                            pplen = len(pcontent) if isinstance(pcontent, str) else None
+                            try:
+                                if isinstance(r, str):
+                                    rpreview = repr(r[:20])
+                                    rplen = len(r)
+                                elif r is not None:
+                                    # Try a few common shapes: .output, .text, .parts
+                                    r_output = getattr(r, "output", None)
+                                    r_text = getattr(r, "text", None)
+                                    r_parts = getattr(r, "parts", None)
+                                    if isinstance(r_output, str):
+                                        rpreview = repr(r_output[:20])
+                                        rplen = len(r_output)
+                                    elif isinstance(r_text, str):
+                                        rpreview = repr(r_text[:20])
+                                        rplen = len(r_text)
+                                    elif isinstance(r_parts, (list, tuple)) and r_parts:
+                                        # render a compact preview of first textual part
+                                        for _rp in r_parts:
+                                            rc = getattr(_rp, "content", None)
+                                            if isinstance(rc, str) and rc:
+                                                rpreview = repr(rc[:20])
+                                                rplen = len(rc)
+                                                break
+                            except Exception:
+                                pass
+                            state_manager.session._debug_events.append(
+                                f"[src] event[{debug_event_count}] etype={etype} d={dtype} clen={clen} cprev={cpreview} rtype={rtype} rprev={rpreview} rlen={rplen} ptype={ptype} pkind={pkind} pprev={ppreview} plen={pplen}"
+                            )
+                        except Exception:
+                            pass
+
+                    # Attempt to capture pre-first-delta text from non-delta events
+                    if not first_delta_seen:
+                        try:
+                            # event might be a PartStartEvent with .part.content
+                            if hasattr(event, "part") and hasattr(event.part, "content"):
+                                pc = event.part.content
+                                if isinstance(pc, str) and pc and not pc.lstrip().startswith("\n"):
+                                    # capture a short potential prefix
+                                    pre_first_delta_text = pc[:100] if len(pc) > 100 else pc
+                        except Exception:
+                            pass
+
+                    # Handle delta events
+                    if PartDeltaEvent and isinstance(event, PartDeltaEvent):
+                        if isinstance(event.delta, TextPartDelta):
+                            if event.delta.content_delta is not None and streaming_callback:
+                                # Seed prefix logic before the first true delta
+                                if not first_delta_seen:
+                                    first_delta_seen = True
+                                    try:
+                                        delta_text = event.delta.content_delta or ""
+                                        # Only seed when we have a short, safe candidate
+                                        if (
+                                            pre_first_delta_text
+                                            and len(pre_first_delta_text) <= 100
+                                            and not seeded_prefix_sent
+                                        ):
+                                            # If delta contains the candidate, emit the prefix up to that point
+                                            probe = pre_first_delta_text[:20]
+                                            idx = pre_first_delta_text.find(probe)
+                                            if idx > 0:
+                                                prefix = pre_first_delta_text[:idx]
+                                                if prefix:
+                                                    await streaming_callback(prefix)
+                                                    seeded_prefix_sent = True
+                                                    state_manager.session._debug_events.append(
+                                                        f"[src] seeded_prefix idx={idx} len={len(prefix)} preview={repr(prefix)}"
+                                                    )
+                                            elif idx == -1:
+                                                # Delta text does not appear in pre-text; emit the pre-text directly as a seed
+                                                # Safe for short pre-text (e.g., first word) to avoid duplication
+                                                if pre_first_delta_text.strip():
+                                                    await streaming_callback(pre_first_delta_text)
+                                                    seeded_prefix_sent = True
+                                                    state_manager.session._debug_events.append(
+                                                        f"[src] seeded_prefix_direct len={len(pre_first_delta_text)} preview={repr(pre_first_delta_text)}"
+                                                    )
+                                            else:
+                                                # idx == 0 means pre-text is already the start of delta; skip
+                                                state_manager.session._debug_events.append(
+                                                    f"[src] seed_skip idx={idx} delta_len={len(delta_text)}"
+                                                )
+                                    except Exception:
+                                        pass
+                                    finally:
+                                        pre_first_delta_text = None
+
+                                # Record first-delta instrumentation
+                                if not first_delta_logged:
+                                    try:
+                                        import time as _t
+
+                                        ts_ns = _t.perf_counter_ns()
+                                    except Exception:
+                                        ts_ns = 0
+                                    # Store debug event summary for later display
+                                    state_manager.session._debug_events.append(
+                                        f"[src] first_delta_received ts_ns={ts_ns} chunk_repr={repr(event.delta.content_delta[:5] if event.delta.content_delta else '')} len={len(event.delta.content_delta or '')}"
+                                    )
+                                    first_delta_logged = True
+
+                                # Accumulate full raw stream for comparison and forward delta
+                                delta_text = event.delta.content_delta or ""
+                                state_manager.session._debug_raw_stream_accum += delta_text
+                                await streaming_callback(delta_text)
+                        else:
+                            # Log empty or non-text deltas encountered
+                            state_manager.session._debug_events.append(
+                                "[src] empty_or_nontext_delta_skipped"
+                            )
+                    else:
+                        # Capture any final result text for diagnostics
+                        try:
+                            final_text = _extract_text(getattr(event, "result", None))
+                            if final_text:
+                                state_manager.session._debug_events.append(
+                                    f"[src] final_text_preview len={len(final_text)} preview={repr(final_text[:20])}"
+                                )
+                        except Exception:
+                            pass
+            # Successful streaming; exit retry loop
+            break
+        except Exception as stream_err:
+            # Log with context and optionally notify UI, then retry once
+            logger.warning(
+                "Streaming error (attempt %s/2) req=%s iter=%s: %s",
+                attempt + 1,
+                request_id,
+                iteration_index,
+                stream_err,
+                exc_info=True,
+            )
+            if getattr(state_manager.session, "show_thoughts", False):
+                from tunacode.ui import console as ui
+
+                await ui.warning("Streaming failed; retrying once then falling back")
+
+            # On second failure, degrade gracefully (no streaming)
+            if attempt == 1:
+                if getattr(state_manager.session, "show_thoughts", False):
+                    from tunacode.ui import console as ui
+
+                    await ui.muted("Switching to non-streaming processing for this node")
+                break