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

tunacode/cli/commands/implementations/debug.py

@@ -122,7 +122,7 @@ class FixCommand(SimpleCommand):
     )
 
     async def execute(self, args: List[str], context: CommandContext) -> None:
-        from tunacode.core.agents.main import patch_tool_messages
+        from tunacode.core.agents import patch_tool_messages
 
         # Count current messages
         before_count = len(context.state_manager.session.messages)
@@ -152,7 +152,7 @@ class ParseToolsCommand(SimpleCommand):
     )
 
     async def execute(self, args: List[str], context: CommandContext) -> None:
-        from tunacode.core.agents.main import extract_and_execute_tool_calls
+        from tunacode.core.agents import extract_and_execute_tool_calls
 
         # Find the last model response in messages
         messages = context.state_manager.session.messages

tunacode/cli/commands/implementations/system.py

@@ -40,7 +40,7 @@ class ClearCommand(SimpleCommand):
 
     async def execute(self, args: List[str], context: CommandContext) -> None:
         # Patch any orphaned tool calls before clearing
-        from tunacode.core.agents.main import patch_tool_messages
+        from tunacode.core.agents import patch_tool_messages
 
         patch_tool_messages("Conversation cleared", context.state_manager)
 

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

@@ -14,8 +14,8 @@ from pydantic_ai.exceptions import UnexpectedModelBehavior
 
 from tunacode.configuration.models import ModelRegistry
 from tunacode.constants import DEFAULT_CONTEXT_WINDOW
-from tunacode.core.agents import main as agent
-from tunacode.core.agents.main import patch_tool_messages
+from tunacode.core import agents as agent
+from tunacode.core.agents import patch_tool_messages
 from tunacode.core.token_usage.api_response_parser import ApiResponseParser
 from tunacode.core.token_usage.cost_calculator import CostCalculator
 from tunacode.core.token_usage.usage_tracker import UsageTracker
@@ -238,7 +238,7 @@ async def _handle_plan_approval(state_manager, original_request=None):
                 action()
                 if key == "a" and original_request:
                     await ui.info("🚀 Executing implementation...")
-                    await process_request(
+                    await execute_repl_request(
                         _transform_to_implementation_request(original_request),
                         state_manager,
                         output=True,
@@ -259,16 +259,16 @@ _command_registry.register_all_default_commands()
 
 async def _handle_command(command: str, state_manager: StateManager) -> CommandResult:
     """Handles a command string using the command registry."""
-    context = CommandContext(state_manager=state_manager, process_request=process_request)
+    context = CommandContext(state_manager=state_manager, process_request=execute_repl_request)
     try:
-        _command_registry.set_process_request_callback(process_request)
+        _command_registry.set_process_request_callback(execute_repl_request)
         return await _command_registry.execute(command, context)
     except ValidationError as e:
         await ui.error(str(e))
         return None
 
 
-async def process_request(text: str, state_manager: StateManager, output: bool = True):
+async def execute_repl_request(text: str, state_manager: StateManager, output: bool = True):
     """Process input using the agent, handling cancellation safely."""
     import uuid
 
@@ -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,
@@ -396,6 +412,10 @@ async def process_request(text: str, state_manager: StateManager, output: bool =
             )
 
 
+# Backwards compatibility: exported name expected by external integrations/tests
+process_request = execute_repl_request
+
+
 async def warm_code_index():
     """Pre-warm the code index in background for faster directory operations."""
     try:
@@ -517,7 +537,7 @@ async def repl(state_manager: StateManager):
                 state_manager.session.operation_cancelled = False
 
             state_manager.session.current_task = get_app().create_background_task(
-                process_request(line, state_manager)
+                execute_repl_request(line, state_manager)
             )
             await state_manager.session.current_task
 

tunacode/cli/repl_components/error_recovery.py

@@ -6,6 +6,7 @@ Error recovery utilities for the REPL.
 
 import logging
 
+import tunacode.core.agents as agent_api
 from tunacode.types import StateManager
 from tunacode.ui import console as ui
 
@@ -130,13 +131,12 @@ async def attempt_tool_recovery(e: Exception, state_manager: StateManager) -> bo
         )
 
         try:
-            from tunacode.core.agents.main import extract_and_execute_tool_calls
 
             def tool_callback_with_state(tool_part, _node):
                 return tool_handler(tool_part, state_manager)
 
             # This function now returns the number of tools found
-            tools_found = await extract_and_execute_tool_calls(
+            tools_found = await agent_api.extract_and_execute_tool_calls(
                 content_to_parse, tool_callback_with_state, state_manager
             )
 

tunacode/cli/repl_components/tool_executor.py

@@ -9,7 +9,7 @@ from asyncio.exceptions import CancelledError
 
 from prompt_toolkit.application import run_in_terminal
 
-from tunacode.core.agents.main import patch_tool_messages
+from tunacode.core.agents import patch_tool_messages
 from tunacode.core.tool_handler import ToolHandler
 from tunacode.exceptions import UserAbortError
 from tunacode.types import StateManager

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.2"
 
 
 # File patterns
@@ -44,6 +44,7 @@ class ToolName(str, Enum):
     LIST_DIR = "list_dir"
     GLOB = "glob"
     TODO = "todo"
+    REACT = "react"
     EXIT_PLAN_MODE = "exit_plan_mode"
 
 
@@ -57,6 +58,7 @@ TOOL_GREP = ToolName.GREP
 TOOL_LIST_DIR = ToolName.LIST_DIR
 TOOL_GLOB = ToolName.GLOB
 TOOL_TODO = ToolName.TODO
+TOOL_REACT = ToolName.REACT
 TOOL_EXIT_PLAN_MODE = ToolName.EXIT_PLAN_MODE
 
 # Tool categorization
@@ -65,6 +67,7 @@ READ_ONLY_TOOLS = [
     ToolName.GREP,
     ToolName.LIST_DIR,
     ToolName.GLOB,
+    ToolName.REACT,
     ToolName.EXIT_PLAN_MODE,
 ]
 WRITE_TOOLS = [ToolName.WRITE_FILE, ToolName.UPDATE_FILE]

tunacode/core/agents/__init__.py

@@ -1,8 +1,45 @@
-"""Agent helper modules."""
+"""Public entry points for TunaCode agent orchestration."""
 
-from .main import get_or_create_agent, process_request
+from . import main as main
+from .agent_components import (
+    AgentRunWithState,
+    AgentRunWrapper,
+    ResponseState,
+    SimpleResult,
+    ToolBuffer,
+    _process_node,
+    check_task_completion,
+    execute_tools_parallel,
+    extract_and_execute_tool_calls,
+    get_model_messages,
+    get_or_create_agent,
+    parse_json_tool_calls,
+    patch_tool_messages,
+)
+from .main import (
+    check_query_satisfaction,
+    get_agent_tool,
+    get_mcp_servers,
+    process_request,
+)
 
 __all__ = [
     "process_request",
     "get_or_create_agent",
+    "extract_and_execute_tool_calls",
+    "parse_json_tool_calls",
+    "get_model_messages",
+    "patch_tool_messages",
+    "_process_node",
+    "ResponseState",
+    "SimpleResult",
+    "AgentRunWrapper",
+    "AgentRunWithState",
+    "ToolBuffer",
+    "check_task_completion",
+    "execute_tools_parallel",
+    "get_mcp_servers",
+    "check_query_satisfaction",
+    "get_agent_tool",
+    "main",
 ]

tunacode/core/agents/agent_components/__init__.py

@@ -1,5 +1,7 @@
 """Agent components package for modular agent functionality."""
 
+from tunacode.ui.tool_descriptions import get_batch_description
+
 from .agent_config import get_or_create_agent
 from .agent_helpers import (
     create_empty_response_message,
@@ -17,6 +19,7 @@ from .message_handler import get_model_messages, patch_tool_messages
 from .node_processor import _process_node
 from .response_state import ResponseState
 from .result_wrapper import AgentRunWithState, AgentRunWrapper, SimpleResult
+from .streaming import stream_model_request_node
 from .task_completion import check_task_completion
 from .tool_buffer import ToolBuffer
 from .tool_executor import execute_tools_parallel
@@ -44,4 +47,6 @@ __all__ = [
     "get_tool_description",
     "get_tool_summary",
     "get_user_prompt_part_class",
+    "stream_model_request_node",
+    "get_batch_description",
 ]

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)