shotgun-sh 0.3.3.dev1__py3-none-any.whl → 0.4.0.dev1__py3-none-any.whl

shotgun/tui/screens/chat_screen/command_providers.py

@@ -3,7 +3,6 @@ from typing import TYPE_CHECKING, cast
 
 from textual.command import DiscoveryHit, Hit, Provider
 
-from shotgun.agents.models import AgentType
 from shotgun.codebase.models import CodebaseGraph
 from shotgun.tui.screens.chat_screen.hint_message import HintMessage
 from shotgun.tui.screens.model_picker import ModelPickerScreen
@@ -13,92 +12,6 @@ if TYPE_CHECKING:
     from shotgun.tui.screens.chat import ChatScreen
 
 
-class AgentModeProvider(Provider):
-    """Command provider for agent mode switching."""
-
-    @property
-    def chat_screen(self) -> "ChatScreen":
-        from shotgun.tui.screens.chat import ChatScreen
-
-        return cast(ChatScreen, self.screen)
-
-    def set_mode(self, mode: AgentType) -> None:
-        """Switch to research mode."""
-        self.chat_screen.mode = mode
-
-    async def discover(self) -> AsyncGenerator[DiscoveryHit, None]:
-        """Provide default mode switching commands when palette opens."""
-        yield DiscoveryHit(
-            "Switch to Research Mode",
-            lambda: self.set_mode(AgentType.RESEARCH),
-            help="🔬 Research topics with web search and synthesize findings",
-        )
-        yield DiscoveryHit(
-            "Switch to Specify Mode",
-            lambda: self.set_mode(AgentType.SPECIFY),
-            help="📝 Create detailed specifications and requirements documents",
-        )
-        yield DiscoveryHit(
-            "Switch to Plan Mode",
-            lambda: self.set_mode(AgentType.PLAN),
-            help="📋 Create comprehensive, actionable plans with milestones",
-        )
-        yield DiscoveryHit(
-            "Switch to Tasks Mode",
-            lambda: self.set_mode(AgentType.TASKS),
-            help="✅ Generate specific, actionable tasks from research and plans",
-        )
-        yield DiscoveryHit(
-            "Switch to Export Mode",
-            lambda: self.set_mode(AgentType.EXPORT),
-            help="📤 Export artifacts and findings to various formats",
-        )
-
-    async def search(self, query: str) -> AsyncGenerator[Hit, None]:
-        """Search for mode commands."""
-        matcher = self.matcher(query)
-
-        commands = [
-            (
-                "Switch to Research Mode",
-                "🔬 Research topics with web search and synthesize findings",
-                lambda: self.set_mode(AgentType.RESEARCH),
-                AgentType.RESEARCH,
-            ),
-            (
-                "Switch to Specify Mode",
-                "📝 Create detailed specifications and requirements documents",
-                lambda: self.set_mode(AgentType.SPECIFY),
-                AgentType.SPECIFY,
-            ),
-            (
-                "Switch to Plan Mode",
-                "📋 Create comprehensive, actionable plans with milestones",
-                lambda: self.set_mode(AgentType.PLAN),
-                AgentType.PLAN,
-            ),
-            (
-                "Switch to Tasks Mode",
-                "✅ Generate specific, actionable tasks from research and plans",
-                lambda: self.set_mode(AgentType.TASKS),
-                AgentType.TASKS,
-            ),
-            (
-                "Switch to Export Mode",
-                "📤 Export artifacts and findings to various formats",
-                lambda: self.set_mode(AgentType.EXPORT),
-                AgentType.EXPORT,
-            ),
-        ]
-
-        for title, help_text, callback, mode in commands:
-            if self.chat_screen.mode == mode:
-                continue
-            score = matcher.match(title)
-            if score > 0:
-                yield Hit(score, matcher.highlight(title), callback, help=help_text)
-
-
 class UsageProvider(Provider):
     """Command provider for agent mode switching."""
 

shotgun/tui/screens/chat_screen/history/agent_response.py

@@ -18,9 +18,10 @@ from .formatters import ToolFormatter
 class AgentResponseWidget(Widget):
     """Widget that displays agent responses in the chat history."""
 
-    def __init__(self, item: ModelResponse | None) -> None:
+    def __init__(self, item: ModelResponse | None, is_sub_agent: bool = False) -> None:
         super().__init__()
         self.item = item
+        self.is_sub_agent = is_sub_agent
 
     def compose(self) -> ComposeResult:
         self.display = self.item is not None
@@ -35,11 +36,14 @@ class AgentResponseWidget(Widget):
         if self.item is None:
             return ""
 
+        # Use different prefix for sub-agent responses
+        prefix = "**⏺** " if not self.is_sub_agent else "  **↳** "
+
         for idx, part in enumerate(self.item.parts):
             if isinstance(part, TextPart):
-                # Only show the circle prefix if there's actual content
+                # Only show the prefix if there's actual content
                 if part.content and part.content.strip():
-                    acc += f"**⏺** {part.content}\n\n"
+                    acc += f"{prefix}{part.content}\n\n"
             elif isinstance(part, ToolCallPart):
                 parts_str = ToolFormatter.format_tool_call_part(part)
                 if parts_str:  # Only add if there's actual content

shotgun/tui/screens/chat_screen/history/chat_history.py

@@ -8,10 +8,12 @@ from pydantic_ai.messages import (
     ModelResponse,
     UserPromptPart,
 )
+from textual import events
 from textual.app import ComposeResult
 from textual.reactive import reactive
 from textual.widget import Widget
 
+from shotgun.tui.components.prompt_input import PromptInput
 from shotgun.tui.components.vertical_tail import VerticalTail
 from shotgun.tui.screens.chat_screen.hint_message import HintMessage, HintMessageWidget
 
@@ -113,3 +115,13 @@ class ChatHistory(Widget):
 
             # Scroll to bottom to show newly added messages
             self.vertical_tail.scroll_end(animate=False)
+
+    def on_click(self, event: events.Click) -> None:
+        """Focus the prompt input when clicking on the history area."""
+        # Only handle clicks that weren't already handled by a child widget
+        if event.button == 1:  # Left click
+            results = self.screen.query(PromptInput)
+            if results:
+                prompt_input = results.first()
+                if prompt_input.display:
+                    prompt_input.focus()

shotgun/tui/screens/chat_screen/history/formatters.py

@@ -29,6 +29,53 @@ class ToolFormatter:
                 return {}
         return args if isinstance(args, dict) else {}
 
+    @classmethod
+    def _extract_key_arg(
+        cls,
+        args: dict[str, object],
+        key_arg: str,
+        tool_name: str | None = None,
+    ) -> str | None:
+        """Extract key argument value, handling nested args and special cases.
+
+        Supports:
+        - Direct key access: key_arg="query" -> args["query"]
+        - Nested access: key_arg="task" -> args["input"]["task"] (for Pydantic model inputs)
+        - Special handling for codebase_shell
+
+        Args:
+            args: Parsed tool arguments dict
+            key_arg: The key argument to extract
+            tool_name: Optional tool name for special handling
+
+        Returns:
+            The extracted value as a string, or None if not found
+        """
+        if not args or not isinstance(args, dict):
+            return None
+
+        # Special handling for codebase_shell which needs command + args
+        if tool_name == "codebase_shell" and "command" in args:
+            command = args.get("command", "")
+            cmd_args = args.get("args", [])
+            if isinstance(cmd_args, list):
+                args_str = " ".join(str(arg) for arg in cmd_args)
+            else:
+                args_str = ""
+            return f"{command} {args_str}".strip()
+
+        # Direct key access
+        if key_arg in args:
+            return str(args[key_arg])
+
+        # Try nested access through "input" (for Pydantic model inputs)
+        if "input" in args and isinstance(args["input"], dict):
+            input_dict = args["input"]
+            if key_arg in input_dict:
+                return str(input_dict[key_arg])
+
+        return None
+
     @classmethod
     def format_tool_call_part(cls, part: ToolCallPart) -> str:
         """Format a tool call part using the tool display registry."""
@@ -44,19 +91,10 @@ class ToolFormatter:
             args = cls.parse_args(part.args)
 
             # Get the key argument value
-            if args and isinstance(args, dict) and display_config.key_arg in args:
-                # Special handling for codebase_shell which needs command + args
-                if part.tool_name == "codebase_shell" and "command" in args:
-                    command = args.get("command", "")
-                    cmd_args = args.get("args", [])
-                    if isinstance(cmd_args, list):
-                        args_str = " ".join(str(arg) for arg in cmd_args)
-                    else:
-                        args_str = ""
-                    key_value = f"{command} {args_str}".strip()
-                else:
-                    key_value = str(args[display_config.key_arg])
-
+            key_value = cls._extract_key_arg(
+                args, display_config.key_arg, part.tool_name
+            )
+            if key_value:
                 # Format: "display_text: key_value"
                 return f"{display_config.display_text}: {cls.truncate(key_value)}"
             else:
@@ -95,8 +133,8 @@ class ToolFormatter:
 
             args = cls.parse_args(part.args)
             # Get the key argument value
-            if args and isinstance(args, dict) and display_config.key_arg in args:
-                key_value = str(args[display_config.key_arg])
+            key_value = cls._extract_key_arg(args, display_config.key_arg)
+            if key_value:
                 # Format: "display_text: key_value"
                 return f"{display_config.display_text}: {cls.truncate(key_value)}"
             else:

shotgun/tui/screens/chat_screen/history/partial_response.py

@@ -5,6 +5,8 @@ from textual.app import ComposeResult
 from textual.reactive import reactive
 from textual.widget import Widget
 
+from shotgun.tui.protocols import ActiveSubAgentProvider
+
 from .agent_response import AgentResponseWidget
 from .user_question import UserQuestionWidget
 
@@ -27,11 +29,19 @@ class PartialResponseWidget(Widget):  # TODO: doesn't work lol
         super().__init__()
         self.item = item
 
+    def _is_sub_agent_active(self) -> bool:
+        """Check if a sub-agent is currently active."""
+        if isinstance(self.screen, ActiveSubAgentProvider):
+            return self.screen.active_sub_agent is not None
+        return False
+
     def compose(self) -> ComposeResult:
         if self.item is None:
             pass
         elif self.item.kind == "response":
-            yield AgentResponseWidget(self.item)
+            yield AgentResponseWidget(
+                self.item, is_sub_agent=self._is_sub_agent_active()
+            )
         elif self.item.kind == "request":
             yield UserQuestionWidget(self.item)
 

shotgun/tui/screens/chat_screen/messages.py

@@ -0,0 +1,219 @@
+"""Message types for ChatScreen communication.
+
+This module defines Textual message types used for communication
+between widgets and the ChatScreen, particularly for step checkpoints
+and cascade confirmation in the Router's Planning mode.
+"""
+
+from textual.message import Message
+
+from shotgun.agents.models import AgentType
+from shotgun.agents.router.models import CascadeScope, ExecutionPlan, ExecutionStep
+
+__all__ = [
+    # Step checkpoint messages (Stage 4)
+    "StepCompleted",
+    "CheckpointContinue",
+    "CheckpointModify",
+    "CheckpointStop",
+    # Cascade confirmation messages (Stage 5)
+    "CascadeConfirmationRequired",
+    "CascadeConfirmed",
+    "CascadeDeclined",
+    # Plan approval messages (Stage 7)
+    "PlanApprovalRequired",
+    "PlanApproved",
+    "PlanRejected",
+    # Sub-agent lifecycle messages (Stage 8)
+    "SubAgentStarted",
+    "SubAgentCompleted",
+    # Plan panel messages (Stage 11)
+    "PlanUpdated",
+    "PlanPanelClosed",
+]
+
+
+class StepCompleted(Message):
+    """Posted when a plan step completes in Planning mode.
+
+    This message triggers the checkpoint UI to appear, allowing the user
+    to choose whether to continue, modify the plan, or stop execution.
+
+    Attributes:
+        step: The step that was just completed.
+        next_step: The next step to execute, or None if this was the last step.
+    """
+
+    def __init__(self, step: ExecutionStep, next_step: ExecutionStep | None) -> None:
+        super().__init__()
+        self.step = step
+        self.next_step = next_step
+
+
+class CheckpointContinue(Message):
+    """Posted when user chooses to continue to next step.
+
+    This message indicates the user wants to proceed with the next
+    step in the execution plan.
+    """
+
+
+class CheckpointModify(Message):
+    """Posted when user wants to modify the plan.
+
+    This message indicates the user wants to return to the prompt input
+    to make adjustments to the plan before continuing.
+    """
+
+
+class CheckpointStop(Message):
+    """Posted when user wants to stop execution.
+
+    This message indicates the user wants to halt execution while
+    keeping the remaining steps in the plan as pending.
+    """
+
+
+# =============================================================================
+# Cascade Confirmation Messages (Stage 5)
+# =============================================================================
+
+
+class CascadeConfirmationRequired(Message):
+    """Posted when a file with dependents was modified and needs cascade confirmation.
+
+    In Planning mode, after modifying a file like specification.md that has
+    dependent files (plan.md, tasks.md), this message triggers the cascade
+    confirmation UI to appear.
+
+    Attributes:
+        updated_file: The file that was just updated (e.g., "specification.md").
+        dependent_files: List of files that depend on the updated file.
+    """
+
+    def __init__(self, updated_file: str, dependent_files: list[str]) -> None:
+        super().__init__()
+        self.updated_file = updated_file
+        self.dependent_files = dependent_files
+
+
+class CascadeConfirmed(Message):
+    """Posted when user confirms cascade update.
+
+    This message indicates the user wants to proceed with updating
+    dependent files based on the selected scope.
+
+    Attributes:
+        scope: The scope of files to update (ALL, PLAN_ONLY, TASKS_ONLY, NONE).
+    """
+
+    def __init__(self, scope: CascadeScope) -> None:
+        super().__init__()
+        self.scope = scope
+
+
+class CascadeDeclined(Message):
+    """Posted when user declines cascade update.
+
+    This message indicates the user does not want to update dependent
+    files and will handle them manually.
+    """
+
+
+# =============================================================================
+# Plan Approval Messages (Stage 7)
+# =============================================================================
+
+
+class PlanApprovalRequired(Message):
+    """Posted when a multi-step plan is created and needs user approval.
+
+    In Planning mode, after the router creates a plan with multiple steps,
+    this message triggers the approval UI to appear.
+
+    Attributes:
+        plan: The execution plan that needs user approval.
+    """
+
+    def __init__(self, plan: ExecutionPlan) -> None:
+        super().__init__()
+        self.plan = plan
+
+
+class PlanApproved(Message):
+    """Posted when user approves the plan.
+
+    This message indicates the user wants to proceed with executing
+    the plan ("Go Ahead").
+    """
+
+
+class PlanRejected(Message):
+    """Posted when user rejects the plan to clarify/modify.
+
+    This message indicates the user wants to return to the prompt input
+    to modify or clarify the request ("No, Let Me Clarify").
+    """
+
+
+# =============================================================================
+# Sub-Agent Lifecycle Messages (Stage 8)
+# =============================================================================
+
+
+class SubAgentStarted(Message):
+    """Posted when router starts delegating to a sub-agent.
+
+    This message triggers the mode indicator to show the active sub-agent
+    in the format "📋 Planning → Research".
+
+    Attributes:
+        agent_type: The type of sub-agent that started executing.
+    """
+
+    def __init__(self, agent_type: AgentType) -> None:
+        super().__init__()
+        self.agent_type = agent_type
+
+
+class SubAgentCompleted(Message):
+    """Posted when sub-agent delegation completes.
+
+    This message triggers the mode indicator to clear the sub-agent
+    display and return to showing just the mode.
+
+    Attributes:
+        agent_type: The type of sub-agent that completed.
+    """
+
+    def __init__(self, agent_type: AgentType) -> None:
+        super().__init__()
+        self.agent_type = agent_type
+
+
+# =============================================================================
+# Plan Panel Messages (Stage 11)
+# =============================================================================
+
+
+class PlanUpdated(Message):
+    """Posted when the current plan changes.
+
+    This message triggers the plan panel to auto-show/hide based on
+    whether a plan exists.
+
+    Attributes:
+        plan: The updated execution plan, or None if plan was cleared.
+    """
+
+    def __init__(self, plan: ExecutionPlan | None) -> None:
+        super().__init__()
+        self.plan = plan
+
+
+class PlanPanelClosed(Message):
+    """Posted when user closes the plan panel with × button.
+
+    This message indicates the user wants to dismiss the plan panel
+    temporarily. The panel will reopen when the plan changes.
+    """

shotgun/tui/screens/onboarding.py

@@ -427,40 +427,45 @@ Here are some helpful resources to get you up to speed with Shotgun:
 """
 
     def _page_2_modes(self) -> str:
-        """Page 2: Explanation of the 5 modes."""
+        """Page 2: Explanation of the Router and its modes."""
         return """
-## Understanding Shotgun's 5 Modes
+## Understanding Shotgun's Router
 
-Shotgun has 5 specialized modes, each designed for specific tasks. Each mode writes to its own dedicated file in `.shotgun/`:
+Shotgun uses an intelligent **Router** that orchestrates your workflow automatically. Just describe what you need, and the Router will coordinate research, specifications, planning, and tasks for you.
 
-### 🔬 Research Mode
-Research topics with web search and synthesize findings. Perfect for gathering information and exploring new concepts.
+### Two Operating Modes
 
-**Writes to:** `.shotgun/research.md`
+The Router operates in two modes, which you can toggle with `Shift+Tab`:
 
-### 📝 Specify Mode
-Create detailed specifications and requirements documents. Great for planning features and documenting requirements.
+### 📋 Planning Mode (Default)
+- **Incremental execution**: Does one step at a time
+- **Asks clarifying questions** before complex tasks
+- **Shows plan for approval** before executing multi-step work
+- **Confirms before cascading** changes to dependent files
 
-**Writes to:** `.shotgun/specification.md`
+Best for: Complex tasks, learning the workflow, staying in control
 
-### 📋 Plan Mode
-Create comprehensive, actionable plans with milestones. Ideal for breaking down large projects into manageable steps.
+### ✍️ Drafting Mode
+- **Auto-executes** plans without stopping for approval
+- **Makes reasonable assumptions** instead of asking questions
+- **Updates all dependent files** automatically
 
-**Writes to:** `.shotgun/plan.md`
+Best for: Routine tasks, experienced users, speed-focused work
 
-### ✅ Tasks Mode
-Generate specific, actionable tasks from research and plans. Best for getting concrete next steps and action items.
-
-**Writes to:** `.shotgun/tasks.md`
+---
 
-### 📤 Export Mode
-Export artifacts and findings to various formats. Creates documentation like Claude.md (AI instructions), Agent.md (agent specs), PRDs, and other deliverables. Can write to any file in `.shotgun/` except the mode-specific files above.
+### Files Created
 
-**Writes to:** `.shotgun/Claude.md`, `.shotgun/Agent.md`, `.shotgun/PRD.md`, etc.
+The Router manages these files in `.shotgun/`:
+- `research.md` - Research findings
+- `specification.md` - Detailed specifications
+- `plan.md` - Implementation plans
+- `tasks.md` - Actionable task lists
+- `exports/` - Documentation exports
 
 ---
 
-**Tip:** You can switch between modes using `Shift+Tab` or `Ctrl+P` to open the command palette!
+**Tip:** Press `Shift+Tab` to toggle between Planning and Drafting modes!
 """
 
     def _page_3_prompts(self) -> str:
@@ -485,12 +490,11 @@ Provide relevant context about what you're trying to accomplish:
 
 > "I'm working on the payment flow. I need to add support for refunds."
 
-### 4. Use the Right Mode
-Switch to the appropriate mode for your task:
-- Use **Research** for exploration
-- Use **Specify** for requirements
-- Use **Plan** for implementation strategy
-- Use **Tasks** for actionable next steps
+### 4. Let the Router Guide You
+The Router will automatically coordinate the right workflow:
+- Describe what you want to accomplish
+- In Planning mode, it will ask clarifying questions first
+- In Drafting mode, it will execute immediately
 
 ---