tunacode-cli 0.0.18__py3-none-any.whl → 0.0.19__py3-none-any.whl

tunacode/cli/commands.py

@@ -167,6 +167,39 @@ class ThoughtsCommand(SimpleCommand):
         await ui.success(f"Thought display {status}")
 
 
+class ArchitectCommand(SimpleCommand):
+    """Toggle architect mode for task planning and orchestration."""
+
+    def __init__(self):
+        super().__init__(
+            CommandSpec(
+                name="architect",
+                aliases=["/architect"],
+                description="Toggle architect mode (task planning & orchestration)",
+                category=CommandCategory.DEBUG,
+            )
+        )
+
+    async def execute(self, args: List[str], context: CommandContext) -> None:
+        state = context.state_manager.session
+        if args:
+            arg = args[0].lower()
+            if arg in {"on", "1", "true"}:
+                state.architect_mode = True
+            elif arg in {"off", "0", "false"}:
+                state.architect_mode = False
+            else:
+                await ui.error("Usage: /architect [on|off]")
+                return
+        else:
+            state.architect_mode = not getattr(state, 'architect_mode', False)
+        status = "ON" if state.architect_mode else "OFF"
+        if state.architect_mode:
+            await ui.success(f"Architect mode {status} - Requests will be planned before execution")
+        else:
+            await ui.success(f"Architect mode {status} - Using direct execution")
+
+
 class IterationsCommand(SimpleCommand):
     """Configure maximum agent iterations for ReAct reasoning."""
 
@@ -720,6 +753,7 @@ class CommandRegistry:
             YoloCommand,
             DumpCommand,
             ThoughtsCommand,
+            ArchitectCommand,
             IterationsCommand,
             ClearCommand,
             FixCommand,

tunacode/cli/repl.py

@@ -17,6 +17,7 @@ from pydantic_ai.exceptions import UnexpectedModelBehavior
 from tunacode.configuration.settings import ApplicationSettings
 from tunacode.core.agents import main as agent
 from tunacode.core.agents.main import patch_tool_messages
+from tunacode.core.agents.orchestrator import OrchestratorAgent
 from tunacode.core.tool_handler import ToolHandler
 from tunacode.exceptions import AgentError, UserAbortError, ValidationError
 from tunacode.ui import console as ui
@@ -160,41 +161,69 @@ async def process_request(text: str, state_manager: StateManager, output: bool =
         True, state_manager.session.spinner, state_manager
     )
     try:
-        # Expand @file references before sending to the agent
-        try:
-            from tunacode.utils.text_utils import expand_file_refs
-
-            text = expand_file_refs(text)
-        except ValueError as e:
-            await ui.error(str(e))
-            return
-
         # Patch any orphaned tool calls from previous requests before proceeding
         patch_tool_messages("Tool execution was interrupted", state_manager)
 
+        # Track message start for thoughts display
+        start_idx = len(state_manager.session.messages)
+
         # Create a partial function that includes state_manager
         def tool_callback_with_state(part, node):
             return _tool_handler(part, node, state_manager)
 
-        start_idx = len(state_manager.session.messages)
-        res = await agent.process_request(
-            state_manager.session.current_model,
-            text,
-            state_manager,
-            tool_callback=tool_callback_with_state,
-        )
-        if output:
-            if state_manager.session.show_thoughts:
-                new_msgs = state_manager.session.messages[start_idx:]
-                for msg in new_msgs:
-                    if isinstance(msg, dict) and "thought" in msg:
-                        await ui.muted(f"THOUGHT: {msg['thought']}")
-            # Check if result exists and has output
-            if hasattr(res, "result") and res.result is not None and hasattr(res.result, "output"):
-                await ui.agent(res.result.output)
-            else:
-                # Fallback: show that the request was processed
-                await ui.muted("Request completed")
+        # Check if architect mode is enabled
+        if getattr(state_manager.session, 'architect_mode', False):
+            # Expand @file references before sending to the orchestrator
+            try:
+                from tunacode.utils.text_utils import expand_file_refs
+
+                text = expand_file_refs(text)
+            except ValueError as e:
+                await ui.error(str(e))
+                return
+            # Use orchestrator for planning and execution
+            orchestrator = OrchestratorAgent(state_manager)
+            results = await orchestrator.run(text, state_manager.session.current_model)
+            
+            if output:
+                # Process results from all sub-agents
+                for res in results:
+                    # Check if result exists and has output
+                    if hasattr(res, "result") and res.result is not None and hasattr(res.result, "output"):
+                        await ui.agent(res.result.output)
+                
+                if not results:
+                    # Fallback: show that the request was processed
+                    await ui.muted("Request completed")
+        else:
+            # Expand @file references before sending to the agent
+            try:
+                from tunacode.utils.text_utils import expand_file_refs
+
+                text = expand_file_refs(text)
+            except ValueError as e:
+                await ui.error(str(e))
+                return
+            
+            # Use normal agent processing
+            res = await agent.process_request(
+                state_manager.session.current_model,
+                text,
+                state_manager,
+                tool_callback=tool_callback_with_state,
+            )
+            if output:
+                if state_manager.session.show_thoughts:
+                    new_msgs = state_manager.session.messages[start_idx:]
+                    for msg in new_msgs:
+                        if isinstance(msg, dict) and "thought" in msg:
+                            await ui.muted(f"THOUGHT: {msg['thought']}")
+                # Check if result exists and has output
+                if hasattr(res, "result") and res.result is not None and hasattr(res.result, "output"):
+                    await ui.agent(res.result.output)
+                else:
+                    # Fallback: show that the request was processed
+                    await ui.muted("Request completed")
     except CancelledError:
         await ui.muted("Request cancelled")
     except UserAbortError:

tunacode/constants.py

@@ -7,7 +7,7 @@ Centralizes all magic strings, UI text, error messages, and application constant
 
 # Application info
 APP_NAME = "TunaCode"
-APP_VERSION = "0.0.18"
+APP_VERSION = "0.0.19"
 
 # File patterns
 GUIDE_FILE_PATTERN = "{name}.md"

tunacode/core/agents/__init__.py

@@ -0,0 +1,12 @@
+"""Agent helper modules."""
+
+from .main import get_or_create_agent, process_request
+from .orchestrator import OrchestratorAgent
+from .readonly import ReadOnlyAgent
+
+__all__ = [
+    "process_request",
+    "get_or_create_agent",
+    "OrchestratorAgent",
+    "ReadOnlyAgent",
+]

tunacode/core/agents/main.py

@@ -134,7 +134,7 @@ def get_or_create_agent(model: ModelName, state_manager: StateManager) -> Pydant
         import os
         from pathlib import Path
 
-        prompt_path = Path(__file__).parent.parent.parent / "prompts" / "system.txt"
+        prompt_path = Path(__file__).parent.parent.parent / "prompts" / "system.md"
         try:
             with open(prompt_path, "r", encoding="utf-8") as f:
                 system_prompt = f.read().strip()

tunacode/core/agents/orchestrator.py

@@ -0,0 +1,99 @@
+"""Agent orchestration scaffolding.
+
+This module defines an ``OrchestratorAgent`` class that demonstrates how
+higher level planning and delegation could be layered on top of the existing
+``process_request`` workflow.  The goal is to keep orchestration logic isolated
+from the core agent implementation while reusing all current tooling and state
+handling provided by ``main.process_request``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import itertools
+from typing import List
+
+from ...types import AgentRun, ModelName
+from ..llm.planner import make_plan
+from ..state import StateManager
+from . import main as agent_main
+from .planner_schema import Task
+from .readonly import ReadOnlyAgent
+
+
+class OrchestratorAgent:
+    """Plan and run a sequence of sub-agent tasks."""
+
+    def __init__(self, state_manager: StateManager):
+        self.state = state_manager
+
+    async def plan(self, request: str, model: ModelName) -> List[Task]:
+        """Plan tasks for a user request using the planner LLM."""
+
+        return await make_plan(request, model, self.state)
+
+    async def _run_sub_task(self, task: Task, model: ModelName) -> AgentRun:
+        """Execute a single task using an appropriate sub-agent."""
+        from rich.console import Console
+
+        console = Console()
+
+        # Show which task is being executed
+        task_type = "WRITE" if task.mutate else "READ"
+        console.print(f"\n[dim][Task {task.id}] {task_type}[/dim]")
+        console.print(f"[dim]  → {task.description}[/dim]")
+
+        if task.mutate:
+            agent_main.get_or_create_agent(model, self.state)
+            result = await agent_main.process_request(model, task.description, self.state)
+        else:
+            agent = ReadOnlyAgent(model, self.state)
+            result = await agent.process_request(task.description)
+
+        console.print(f"[dim][Task {task.id}] Complete[/dim]")
+        return result
+
+    async def run(self, request: str, model: ModelName | None = None) -> List[AgentRun]:
+        """Plan and execute a user request.
+
+        Parameters
+        ----------
+        request:
+            The high level user request to process.
+        model:
+            Optional model name to use for sub agents.  Defaults to the current
+            session model.
+        """
+        from rich.console import Console
+
+        console = Console()
+        model = model or self.state.session.current_model
+
+        # Show orchestrator is starting
+        console.print(
+            "\n[cyan]Orchestrator Mode: Analyzing request and creating execution plan...[/cyan]"
+        )
+
+        tasks = await self.plan(request, model)
+
+        # Show execution is starting
+        console.print(f"\n[cyan]Executing plan with {len(tasks)} tasks...[/cyan]")
+
+        results: List[AgentRun] = []
+        for mutate_flag, group in itertools.groupby(tasks, key=lambda t: t.mutate):
+            if mutate_flag:
+                for t in group:
+                    results.append(await self._run_sub_task(t, model))
+            else:
+                # Show parallel execution
+                task_list = list(group)
+                if len(task_list) > 1:
+                    console.print(
+                        f"\n[dim][Parallel Execution] Running {len(task_list)} read-only tasks concurrently...[/dim]"
+                    )
+                coros = [self._run_sub_task(t, model) for t in task_list]
+                results.extend(await asyncio.gather(*coros))
+
+        console.print("\n[green]Orchestrator completed all tasks successfully![/green]")
+
+        return results

tunacode/core/agents/planner_schema.py

@@ -0,0 +1,9 @@
+from pydantic import BaseModel, Field
+
+
+class Task(BaseModel):
+    """Single sub-task generated by the planner."""
+
+    id: int = Field(..., description="1-based task index in execution order")
+    description: str = Field(..., description="What the sub-agent must do")
+    mutate: bool = Field(..., description="True if the task changes code")

tunacode/core/agents/readonly.py

@@ -0,0 +1,51 @@
+"""Read-only agent implementation for non-mutating operations."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ...tools.grep import grep
+from ...tools.read_file import read_file
+from ...types import AgentRun, ModelName
+from ..state import StateManager
+
+if TYPE_CHECKING:
+    from ...types import PydanticAgent
+
+
+class ReadOnlyAgent:
+    """Agent configured with read-only tools for analysis tasks."""
+
+    def __init__(self, model: ModelName, state_manager: StateManager):
+        self.model = model
+        self.state_manager = state_manager
+        self._agent: PydanticAgent | None = None
+
+    def _get_agent(self) -> PydanticAgent:
+        """Lazily create the agent with read-only tools."""
+        if self._agent is None:
+            from .main import get_agent_tool
+
+            Agent, Tool = get_agent_tool()
+
+            # Create agent with only read-only tools
+            self._agent = Agent(
+                model=self.model,
+                system_prompt="You are a read-only assistant. You can analyze and read files but cannot modify them.",
+                tools=[
+                    Tool(read_file),
+                    Tool(grep),
+                ],
+            )
+        return self._agent
+
+    async def process_request(self, request: str) -> AgentRun:
+        """Process a request using only read-only tools."""
+        agent = self._get_agent()
+
+        # Use iter() like main.py does to get the full run context
+        async with agent.iter(request) as agent_run:
+            async for _ in agent_run:
+                pass  # Let it complete
+
+        return agent_run

tunacode/core/background/manager.py

@@ -0,0 +1,36 @@
+"""Asynchronous background task management utilities."""
+
+from __future__ import annotations
+
+import asyncio
+import uuid
+from collections import defaultdict
+from typing import Awaitable, Callable, Dict, List
+
+
+class BackgroundTaskManager:
+    """Simple manager for background asyncio tasks."""
+
+    def __init__(self) -> None:
+        self.tasks: Dict[str, asyncio.Task] = {}
+        self.listeners: Dict[str, List[Callable[[asyncio.Task], None]]] = defaultdict(list)
+
+    def spawn(self, coro: Awaitable, *, name: str | None = None) -> str:
+        task_id = name or uuid.uuid4().hex[:8]
+        task = asyncio.create_task(coro, name=task_id)
+        self.tasks[task_id] = task
+        task.add_done_callback(self._notify)
+        return task_id
+
+    def _notify(self, task: asyncio.Task) -> None:
+        for cb in self.listeners.get(task.get_name(), []):
+            cb(task)
+
+    async def shutdown(self) -> None:
+        for task in self.tasks.values():
+            task.cancel()
+        if self.tasks:
+            await asyncio.gather(*self.tasks.values(), return_exceptions=True)
+
+
+BG_MANAGER = BackgroundTaskManager()

tunacode/core/llm/planner.py

@@ -0,0 +1,63 @@
+import json
+from typing import List
+
+from ...types import ModelName
+from ..agents.planner_schema import Task
+from ..state import StateManager
+
+_SYSTEM = """You are a senior software project planner.
+
+Your job is to break down a USER_REQUEST into a logical sequence of tasks.
+
+Guidelines:
+1. Use the FEWEST tasks possible - combine related operations
+2. Order tasks logically - reads before writes, understand before modify
+3. Mark read-only tasks (reading files, searching, analyzing) as mutate: false
+4. Mark modifying tasks (writing, updating, creating files) as mutate: true
+5. Write clear, actionable descriptions
+
+Each task MUST have:
+- id: Sequential number starting from 1
+- description: Clear description of what needs to be done
+- mutate: true if the task modifies files/code, false if it only reads/analyzes
+
+Return ONLY a valid JSON array of tasks, no other text.
+Example:
+[
+  {"id": 1, "description": "Read the main.py file to understand the structure", "mutate": false},
+  {"id": 2, "description": "Update the function to handle edge cases", "mutate": true}
+]"""
+
+
+async def make_plan(request: str, model: ModelName, state_manager: StateManager) -> List[Task]:
+    """Generate an execution plan from a user request using TunaCode's LLM infrastructure."""
+    # Lazy import to avoid circular dependencies
+    from rich.console import Console
+
+    from ..agents.main import get_agent_tool
+
+    console = Console()
+    Agent, _ = get_agent_tool()
+
+    # Show planning is starting
+    console.print("\n[dim][Planning] Breaking down request into tasks...[/dim]")
+
+    # Create a simple planning agent
+    planner = Agent(
+        model=model,
+        system_prompt=_SYSTEM,
+        result_type=List[Task],
+    )
+
+    # Get the plan from the agent
+    result = await planner.run(request)
+    tasks = result.data
+
+    # Display the plan
+    console.print(f"[dim][Planning] Generated {len(tasks)} tasks:[/dim]")
+    for task in tasks:
+        task_type = "WRITE" if task.mutate else "READ"
+        console.print(f"[dim]  Task {task.id}: {task_type} - {task.description}[/dim]")
+    console.print("")
+
+    return tasks

tunacode/prompts/system.txt

@@ -1,93 +1,203 @@
-You are "TunaCode", a senior software developer AI assistant operating within the user's terminal (CLI).
+Here’s an updated version of your **TunaCode prompt**, restructured and improved based on the 26 prompting principles from the ATLAS paper:
 
-**CRITICAL: YOU HAVE TOOLS! YOU MUST USE THEM!**
+---
 
-YOU ARE NOT A CHATBOT! YOU ARE AN AGENT WITH TOOLS!
-When users ask ANYTHING about code/files/systems, you MUST use tools IMMEDIATELY!
+\###Instruction###
 
-**YOUR TOOLS (USE THESE CONSTANTLY):**
+You are **"TunaCode"**, a **senior software developer AI assistant operating inside the user's terminal (CLI)**.
 
-1. `run_command(command: str)` - Execute ANY shell command
-2. `read_file(filepath: str)` - Read file contents  
-3. `write_file(filepath: str, content: str)` - Create new files
-4. `update_file(filepath: str, target: str, patch: str)` - Modify existing files
+**YOU ARE NOT A CHATBOT. YOU ARE AN OPERATIONAL AGENT WITH TOOLS.**
 
-**REAL EXAMPLES WITH ACTUAL COMMANDS AND FILES:**
+Your task is to **execute real actions** via tools and **report observations** after every tool use.
 
-User: "What's in the tools directory?"
-WRONG: "The tools directory contains tool implementations..."
-CORRECT: Use `run_command("ls -la tools/")` which shows:
-- tools/base.py
-- tools/read_file.py
-- tools/run_command.py
-- tools/update_file.py
-- tools/write_file.py
+You MUST follow these rules:
 
-User: "Show me the main entry point"
-WRONG: "The main entry point is typically in..."
-CORRECT: Use `read_file("cli/main.py")` to see the actual code
+---
 
-User: "What models are configured?"
-WRONG: "You can configure models in the settings..."
-CORRECT: Use `read_file("configuration/models.py")` or `run_command("grep -r 'model' configuration/")`
+\###Tool Access Rules###
 
-User: "Fix the import in agents/main.py"
-WRONG: "To fix the import, you should..."
-CORRECT: Use `read_file("core/agents/main.py")` then `update_file("core/agents/main.py", "from tunacode.old_module", "from tunacode.new_module")`
+You HAVE the following tools available. USE THEM IMMEDIATELY and CONSTANTLY:
 
-User: "What commands are available?"
-WRONG: "The available commands include..."
-CORRECT: Use `read_file("cli/commands.py")` or `run_command("grep -E 'class.*Command' cli/commands.py")`
+* `run_command(command: str)` — Execute any shell command
+* `read_file(filepath: str)` — Read any file
+* `write_file(filepath: str, content: str)` — Create or write any file
+* `update_file(filepath: str, target: str, patch: str)` — Update existing files
 
-User: "Check the project structure"
-WRONG: "The project is organized with..."
-CORRECT: Use `run_command("find . -type f -name '*.py' | grep -E '(cli|core|tools|services)' | sort")`
+---
 
-User: "What's the current version?"
-WRONG: "The version is probably..."
-CORRECT: Use `read_file("constants.py")` and look for APP_VERSION, or `run_command("grep -n 'APP_VERSION' constants.py")`
+\###Mandatory Operating Principles###
 
-User: "Create a new tool"
-WRONG: "To create a new tool, you need to..."
-CORRECT: First `read_file("tools/base.py")` to see the base class, then `write_file("tools/my_new_tool.py", "from tunacode.tools.base import BaseTool\n\nclass MyTool(BaseTool):...")`
+1. **TOOLS FIRST, ALWAYS**: Start every response with tool usage—**no assumptions**.
+2. **USE REAL PATHS**: Files live in `/cli/`, `/core/`, `/tools/`, `/services/`, `/configuration/`, `/utils/`, or `/ui/`.
+3. **CHAIN TOOLS**: First explore (`run_command`), then read (`read_file`), then modify (`update_file`, `write_file`).
+4. **ACT IMMEDIATELY**: Don’t describe what to do—**just do it**.
+5. **NO GUESSING**: Verify file existence with `run_command("ls path/")` before reading or writing.
+6. **ASSUME NOTHING**: Always fetch and verify before responding.
 
-**MANDATORY RULES:**
+---
 
-1. **TOOLS FIRST, ALWAYS**: Your FIRST response to ANY request should use tools
-2. **USE REAL PATHS**: Files are in directories like cli/, core/, tools/, services/, configuration/, ui/, utils/
-3. **CHAIN TOOLS**: First explore with `run_command`, then read with `read_file`, then modify
-4. **NO GUESSING**: Always verify file existence with `run_command("ls path/")` before reading
-5. **ACT IMMEDIATELY**: Don't explain what you would do - just do it with tools
+\###Prompt Design Style###
 
-**COMMON USEFUL COMMANDS:**
-- `run_command("find . -name '*.py' -type f")` - Find all Python files
-- `run_command("grep -r 'class' --include='*.py'")` - Find all classes
-- `run_command("ls -la")` - List current directory
-- `run_command("pwd")` - Show current directory
-- `run_command("cat pyproject.toml | grep -A5 dependencies")` - Check dependencies
+* Be **blunt and direct**. Avoid soft language (e.g., “please,” “let me,” “I think”).
+* **Use role-specific language**: you are a CLI-level senior engineer, not a tutor or assistant.
+* Write using affirmative imperatives: *Do this. Check that. Show me.*
+* Ask for clarification if needed: “Specify the path.” / “Which class do you mean?”
+* Break complex requests into sequenced tool actions.
 
-## ReAct Pattern: Reasoning and Acting
+---
 
-Follow this pattern for complex tasks:
+\###Example Prompts (Correct vs Incorrect)###
 
-1. **THINK**: Output {"thought": "I need to understand the task..."} to reason about what to do
-2. **ACT**: Use tools to gather information or make changes  
-3. **OBSERVE**: Analyze tool outputs with {"thought": "The output shows..."} 
-4. **ITERATE**: Continue thinking and acting until the task is complete
+**User**: What's in the tools directory?
+✅ `run_command("ls -la tools/")`
+❌ "The tools directory likely includes..."
 
-Examples:
-- {"thought": "User wants me to analyze a file. I should first read it to understand its contents."}
-- Use read_file tool
-- {"thought": "The file contains Python code. I can see it needs optimization in the loop section."}
-- Use update_file tool
+**User**: Fix the import in `core/agents/main.py`
+✅ `read_file("core/agents/main.py")`, then `update_file("core/agents/main.py", "from old_module", "from new_module")`
+❌ "To fix the import, modify the code to..."
 
-**Key principles:**
-- Always think before acting
-- Use tools immediately after thinking
-- Reason about tool outputs before continuing
-- Break complex tasks into logical steps
+**User**: What commands are available?
+✅ `run_command("grep -E 'class.*Command' cli/commands.py")`
+❌ "Available commands usually include..."
 
-USE YOUR TOOLS NOW!
+---
 
-If asked, you were created by the grifter tunahors 
+\###Meta Behavior###
+
+Use the **ReAct** (Reasoning + Action) framework:
+
+* {"thought": "I need to inspect the file before modifying."}
+* → run tool
+* {"thought": "I see the old import. Now I'll patch it."}
+* → update file
+* {"thought": "Patch complete. Ready for next instruction."}
+
+---
+
+\###Reminder###
+
+You were created by **tunahors**.
+You are not a chatbot.
+You are an autonomous code execution agent.
+You will be penalized for failing to use tools.
+Ensure your answer is unbiased and avoids relying on stereotypes.
+
+---
+
+\###Example###
+
+```plaintext
+User: What’s the current app version?
+
+THINK: {"thought": "I should search for APP_VERSION in the constants file."}
+ACT: run_command("grep -n 'APP_VERSION' constants.py")
+OBSERVE: {"thought": "Found APP_VERSION at line 12."}
+ACT: read_file("constants.py")
+OBSERVE: {"thought": "APP_VERSION is set to '2.4.1'. This is the current version."}
+RESPONSE: "Current version is 2.4.1 (from constants.py)"
+```
+
+---
+
+Let me know if you want the prompt styled differently for docs, API agents, or GUI assistants.
+Here’s an updated version of your **TunaCode prompt**, restructured and improved based on the 26 prompting principles from the ATLAS paper:
+
+---
+
+\###Instruction###
+
+You are **"TunaCode"**, a **senior software developer AI assistant operating inside the user's terminal (CLI)**.
+
+**YOU ARE NOT A CHATBOT. YOU ARE AN OPERATIONAL AGENT WITH TOOLS.**
+
+Your task is to **execute real actions** via tools and **report observations** after every tool use.
+
+You MUST follow these rules:
+
+---
+
+\###Tool Access Rules###
+
+You HAVE the following tools available. USE THEM IMMEDIATELY and CONSTANTLY:
+
+* `run_command(command: str)` — Execute any shell command
+* `read_file(filepath: str)` — Read any file
+* `write_file(filepath: str, content: str)` — Create or write any file
+* `update_file(filepath: str, target: str, patch: str)` — Update existing files
+
+---
+
+\###Mandatory Operating Principles###
+
+1. **TOOLS FIRST, ALWAYS**: Start every response with tool usage—**no assumptions**.
+2. **USE REAL PATHS**: Files live in `/cli/`, `/core/`, `/tools/`, `/services/`, `/configuration/`, `/utils/`, or `/ui/`.
+3. **CHAIN TOOLS**: First explore (`run_command`), then read (`read_file`), then modify (`update_file`, `write_file`).
+4. **ACT IMMEDIATELY**: Don’t describe what to do—**just do it**.
+5. **NO GUESSING**: Verify file existence with `run_command("ls path/")` before reading or writing.
+6. **ASSUME NOTHING**: Always fetch and verify before responding.
+
+---
+
+\###Prompt Design Style###
+
+* Be **blunt and direct**. Avoid soft language (e.g., “please,” “let me,” “I think”).
+* **Use role-specific language**: you are a CLI-level senior engineer, not a tutor or assistant.
+* Write using affirmative imperatives: *Do this. Check that. Show me.*
+* Ask for clarification if needed: “Specify the path.” / “Which class do you mean?”
+* Break complex requests into sequenced tool actions.
+
+---
+
+\###Example Prompts (Correct vs Incorrect)###
+
+**User**: What's in the tools directory?
+✅ `run_command("ls -la tools/")`
+❌ "The tools directory likely includes..."
+
+**User**: Fix the import in `core/agents/main.py`
+✅ `read_file("core/agents/main.py")`, then `update_file("core/agents/main.py", "from old_module", "from new_module")`
+❌ "To fix the import, modify the code to..."
+
+**User**: What commands are available?
+✅ `run_command("grep -E 'class.*Command' cli/commands.py")`
+❌ "Available commands usually include..."
+
+---
+
+\###Meta Behavior###
+
+Use the **ReAct** (Reasoning + Action) framework:
+
+* {"thought": "I need to inspect the file before modifying."}
+* → run tool
+* {"thought": "I see the old import. Now I'll patch it."}
+* → update file
+* {"thought": "Patch complete. Ready for next instruction."}
+
+---
+
+\###Reminder###
+
+You were created by **tunahors**.
+You are not a chatbot.
+You are an autonomous code execution agent.
+You will be penalized for failing to use tools.
+Ensure your answer is unbiased and avoids relying on stereotypes.
+
+---
+
+\###Example###
+
+```plaintext
+User: What’s the current app version?
+
+THINK: {"thought": "I should search for APP_VERSION in the constants file."}
+ACT: run_command("grep -n 'APP_VERSION' constants.py")
+OBSERVE: {"thought": "Found APP_VERSION at line 12."}
+ACT: read_file("constants.py")
+OBSERVE: {"thought": "APP_VERSION is set to '2.4.1'. This is the current version."}
+RESPONSE: "Current version is 2.4.1 (from constants.py)"
+```
+
+---
 

{tunacode_cli-0.0.18.dist-info → tunacode_cli-0.0.19.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tunacode-cli
-Version: 0.0.18
+Version: 0.0.19
 Summary: Your agentic CLI developer.
 Author-email: larock22 <noreply@github.com>
 License-Expression: MIT
@@ -58,16 +58,20 @@ Dynamic: license-file
 
 ---
 
-### Recent Updates (v0.0.15)
-
-- **🐚 Shell Command Support**: Execute shell commands directly with `!command` or open interactive shell with `!`
-- **🔧 Enhanced Bash Tool**: Advanced bash execution with timeouts, working directory, and environment variables
-- **🔧 JSON Tool Parsing Fallback**: Automatic recovery when API providers fail with structured tool calling
-- **⚡ Enhanced Reliability**: Fixed parameter naming issues that caused tool schema errors
-- **🔄 Configuration Management**: New `/refresh` command to reload config without restart
-- **🧠 Improved ReAct Reasoning**: Enhanced iteration limits (now defaults to 20) and better thought processing
-- **🛠️ New Debug Commands**: `/parsetools` for manual JSON parsing, `/iterations` for controlling reasoning depth
-- **📊 Better Error Recovery**: Multiple fallback mechanisms for various failure scenarios
+### Recent Updates (v0.0.18)
+
+- **Advanced Agent Orchestration**: New orchestrator system for complex multi-step tasks with planning visibility
+- **Background Task Manager**: Asynchronous background processing for long-running operations
+- **Read-Only Agent**: Specialized agent for safe codebase exploration without modification risks
+- **Planning Transparency**: See the AI's planning process before execution with detailed task breakdowns
+- **Shell Command Support**: Execute shell commands directly with `!command` or open interactive shell with `!`
+- **Enhanced Bash Tool**: Advanced bash execution with timeouts, working directory, and environment variables
+- **JSON Tool Parsing Fallback**: Automatic recovery when API providers fail with structured tool calling
+- **Enhanced Reliability**: Fixed parameter naming issues that caused tool schema errors
+- **Configuration Management**: New `/refresh` command to reload config without restart
+- **Improved ReAct Reasoning**: Enhanced iteration limits (now defaults to 20) and better thought processing
+- **New Debug Commands**: `/parsetools` for manual JSON parsing, `/iterations` for controlling reasoning depth
+- **Better Error Recovery**: Multiple fallback mechanisms for various failure scenarios
 
 ### Core Features
 
@@ -401,7 +405,14 @@ src/tunacode/
 │
 ├── core/                 # Core Application Logic
 │   ├── agents/           # AI Agent System
-│   │   └── main.py       # Primary agent implementation (pydantic-ai)
+│   │   ├── main.py       # Primary agent implementation (pydantic-ai)
+│   │   ├── orchestrator.py # Complex task orchestration and planning
+│   │   ├── planner_schema.py # Planning data models
+│   │   └── readonly.py   # Read-only agent for safe exploration
+│   ├── background/       # Background Task Management
+│   │   └── manager.py    # Async background task execution
+│   ├── llm/              # LLM Integration
+│   │   └── planner.py    # LLM-based task planning
 │   ├── setup/            # Application Setup & Initialization
 │   │   ├── agent_setup.py     # Agent configuration
 │   │   ├── base.py           # Setup step base class
@@ -450,7 +461,7 @@ src/tunacode/
 ├── exceptions.py      # Custom exceptions
 ├── types.py           # Type definitions
 └── prompts/
-    └── system.txt     # System prompts for AI agent
+    └── system.md      # System prompts for AI agent
 ```
 
 ### Key Components
@@ -459,6 +470,8 @@ src/tunacode/
 | -------------------- | ------------------------ | ------------------------------- |
 | **CLI Layer**        | Command parsing and REPL | `cli/main.py`, `cli/repl.py`    |
 | **Agent System**     | AI-powered assistance    | `core/agents/main.py`           |
+| **Orchestrator**     | Complex task planning    | `core/agents/orchestrator.py`   |
+| **Background Tasks** | Async task execution     | `core/background/manager.py`    |
 | **Tool System**      | File/command operations  | `tools/*.py`                    |
 | **State Management** | Session state tracking   | `core/state.py`                 |
 | **UI Framework**     | Rich terminal interface  | `ui/output.py`, `ui/console.py` |
@@ -523,6 +536,9 @@ While TunaCode builds on the foundation of sidekick-cli, we've made several arch
 
 - **JSON Tool Parsing Fallback**: Added fallback parsing for when API providers fail with structured tool calling
 - **Parallel Search Tools**: New `bash` and `grep` tools with parallel execution for codebase navigation
+- **Agent Orchestration**: Advanced orchestrator for complex multi-step tasks with planning transparency
+- **Background Processing**: Asynchronous task manager for long-running operations
+- **Read-Only Agent**: Safe exploration mode that prevents accidental modifications
 - **ReAct Reasoning**: Implemented ReAct (Reasoning + Acting) patterns with configurable iteration limits
 - **Dynamic Configuration**: Added `/refresh` command and modified configuration management
 - **Safety Changes**: Removed automatic git commits and `/undo` command - requires explicit git usage

{tunacode_cli-0.0.18.dist-info → tunacode_cli-0.0.19.dist-info}/RECORD

@@ -1,14 +1,14 @@
 tunacode/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-tunacode/constants.py,sha256=yUpXwyNffwbcdiQMNrX58wieycOu8UjDx1AzBVXYVRE,3799
+tunacode/constants.py,sha256=lKJ1MWdr9gsJkokPQG2YDD_jC-wLb2gVDyc9iChRY3g,3799
 tunacode/context.py,sha256=9FQ2vf9qY4bcRufKtR0g0eOzB8hZ4aesOfFGy_JOMzQ,2634
 tunacode/exceptions.py,sha256=_Dyj6cC0868dMABekdQHXCg5XhucJumbGUMXaSDzgB4,2645
 tunacode/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 tunacode/setup.py,sha256=dYn0NeAxtNIDSogWEmGSyjb9wsr8AonZ8vAo5sw9NIw,1909
 tunacode/types.py,sha256=5mMJDgFqVcKzhtHh9unPISBFqkeNje6KISGUpRkqRjY,7146
 tunacode/cli/__init__.py,sha256=zgs0UbAck8hfvhYsWhWOfBe5oK09ug2De1r4RuQZREA,55
-tunacode/cli/commands.py,sha256=tTsEKXZqFx-xdTn3DqKsrz_gNC6_5Z4Bq_biXrfIBc0,29513
+tunacode/cli/commands.py,sha256=ZsIfNStLeVAENXzz1bvJUa3IThpeDrc_xjS0eT9wauM,30798
 tunacode/cli/main.py,sha256=C3hBF9RGADz8wtdhKngwM-IjMeLA8MhttYnXiGb-L9g,1870
-tunacode/cli/repl.py,sha256=RqI8AnFuKsdhvgI_zKaRBiIi50xEt1hoHoe6Bd3OSlI,11941
+tunacode/cli/repl.py,sha256=t4lSv5rIZeqWQptUAsBhnLQty2znFKX_2csaNEkuVdU,13375
 tunacode/cli/textual_app.py,sha256=1GNyYacMqCgIgYl1G2B5sIoksIAzKiGuPJ-wxHhzu5I,12951
 tunacode/cli/textual_bridge.py,sha256=DcIbIbYBW4rDKMTWDqAKgWv7PtxZYBKGUcYo7uLSzuM,6175
 tunacode/configuration/__init__.py,sha256=MbVXy8bGu0yKehzgdgZ_mfWlYGvIdb1dY2Ly75nfuPE,17
@@ -18,8 +18,15 @@ tunacode/configuration/settings.py,sha256=lm2ov8rG1t4C5JIXMOhIKik5FAsjpuLVYtFmnE
 tunacode/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 tunacode/core/state.py,sha256=n1claG-gVVDMBCCS8cDmgas4XbKLJJwKRc-8CtXeTS8,1376
 tunacode/core/tool_handler.py,sha256=OKx7jM8pml6pSEnoARu33_uBY8awJBqvhbVeBn6T4ow,1804
-tunacode/core/agents/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-tunacode/core/agents/main.py,sha256=m9HYOQn-vo2WMdZcltuHHQevLnEEf8f-w5j2jDm8skw,14224
+tunacode/core/agents/__init__.py,sha256=TiXwymGRNMuOqQaRLpNCAt7bZArg8rkadIRs4Nw21SQ,275
+tunacode/core/agents/main.py,sha256=ZryliG4T9SAgJ1ppeplFrTlDLxh0KRW4dnNhxCoSdBM,14223
+tunacode/core/agents/orchestrator.py,sha256=5CjHpyB1FlHe2-xJXM1M9ruaFu9gJ_9Izev4mlOOPrw,3578
+tunacode/core/agents/planner_schema.py,sha256=pu2ehQVALjiJ5HJD7EN6xuZHCknsrXO9z0xHuVdlKW8,345
+tunacode/core/agents/readonly.py,sha256=NOPfqPWu53fJy77k5uqwKWmZ6yzqnDOZpBeQjGy0AG8,1624
+tunacode/core/background/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tunacode/core/background/manager.py,sha256=rJdl3eDLTQwjbT7VhxXcJbZopCNR3M8ZGMbmeVnwwMc,1126
+tunacode/core/llm/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tunacode/core/llm/planner.py,sha256=Vv0CIn4oS3wzdWZs6WY8R-ALzBWaHtR40Wx-_xW3gmc,2123
 tunacode/core/setup/__init__.py,sha256=lzdpY6rIGf9DDlDBDGFvQZaSOQeFsNglHbkpq1-GtU8,376
 tunacode/core/setup/agent_setup.py,sha256=trELO8cPnWo36BBnYmXDEnDPdhBg0p-VLnx9A8hSSSQ,1401
 tunacode/core/setup/base.py,sha256=cbyT2-xK2mWgH4EO17VfM_OM2bj0kT895NW2jSXbe3c,968
@@ -27,7 +34,7 @@ tunacode/core/setup/config_setup.py,sha256=BZPQjJSVsIF3bIP2TteRf8NsQCnVBnx1Jdxzr
 tunacode/core/setup/coordinator.py,sha256=oVTN2xIeJERXitVJpkIk9tDGLs1D1bxIRmaogJwZJFI,2049
 tunacode/core/setup/environment_setup.py,sha256=n3IrObKEynHZSwtUJ1FddMg2C4sHz7ca42awemImV8s,2225
 tunacode/core/setup/git_safety_setup.py,sha256=T7hwIf3u3Tq3QtIdUAfuHI6vclMfm2Sqcml5l6x02oA,6799
-tunacode/prompts/system.txt,sha256=wZkP3vTv4h8ukBUkCZ9yR-oZt-ZcdvIRPxl1uN3AHIk,4030
+tunacode/prompts/system.txt,sha256=VEt0PKne0AzHbFkA4IuyCYQkX6AInWeYZOL4NyeJHNw,6939
 tunacode/services/__init__.py,sha256=w_E8QK6RnvKSvU866eDe8BCRV26rAm4d3R-Yg06OWCU,19
 tunacode/services/mcp.py,sha256=R48X73KQjQ9vwhBrtbWHSBl-4K99QXmbIhh5J_1Gezo,3046
 tunacode/tools/__init__.py,sha256=oDcxl7uoi1s9TPz2WNsjHH7xTKL6jM78WlrGbh-9SYQ,318
@@ -60,9 +67,9 @@ tunacode/utils/ripgrep.py,sha256=AXUs2FFt0A7KBV996deS8wreIlUzKOlAHJmwrcAr4No,583
 tunacode/utils/system.py,sha256=FSoibTIH0eybs4oNzbYyufIiV6gb77QaeY2yGqW39AY,11381
 tunacode/utils/text_utils.py,sha256=B9M1cuLTm_SSsr15WNHF6j7WdLWPvWzKZV0Lvfgdbjg,2458
 tunacode/utils/user_configuration.py,sha256=IGvUH37wWtZ4M5xpukZEWYhtuKKyKcl6DaeObGXdleU,2610
-tunacode_cli-0.0.18.dist-info/licenses/LICENSE,sha256=Btzdu2kIoMbdSp6OyCLupB1aRgpTCJ_szMimgEnpkkE,1056
-tunacode_cli-0.0.18.dist-info/METADATA,sha256=gSvYPIonpAUDFNbHkUEEgD7QwwadVFgBEhNTuF2kE9o,17273
-tunacode_cli-0.0.18.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-tunacode_cli-0.0.18.dist-info/entry_points.txt,sha256=hbkytikj4dGu6rizPuAd_DGUPBGF191RTnhr9wdhORY,51
-tunacode_cli-0.0.18.dist-info/top_level.txt,sha256=lKy2P6BWNi5XSA4DHFvyjQ14V26lDZctwdmhEJrxQbU,9
-tunacode_cli-0.0.18.dist-info/RECORD,,
+tunacode_cli-0.0.19.dist-info/licenses/LICENSE,sha256=Btzdu2kIoMbdSp6OyCLupB1aRgpTCJ_szMimgEnpkkE,1056
+tunacode_cli-0.0.19.dist-info/METADATA,sha256=jVuQw3PkNoA5abzuow9C1lunjBrAJqkD_VHsMBA8MYQ,18552
+tunacode_cli-0.0.19.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+tunacode_cli-0.0.19.dist-info/entry_points.txt,sha256=hbkytikj4dGu6rizPuAd_DGUPBGF191RTnhr9wdhORY,51
+tunacode_cli-0.0.19.dist-info/top_level.txt,sha256=lKy2P6BWNi5XSA4DHFvyjQ14V26lDZctwdmhEJrxQbU,9
+tunacode_cli-0.0.19.dist-info/RECORD,,