shotgun-sh 0.1.0.dev19__tar.gz → 0.1.0.dev22__tar.gz

{shotgun_sh-0.1.0.dev19 → shotgun_sh-0.1.0.dev22}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shotgun-sh
-Version: 0.1.0.dev19
+Version: 0.1.0.dev22
 Summary: AI-powered research, planning, and task management CLI tool
 Project-URL: Homepage, https://shotgun.sh/
 Project-URL: Repository, https://github.com/shotgun-sh/shotgun

{shotgun_sh-0.1.0.dev19 → shotgun_sh-0.1.0.dev22}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "shotgun-sh"
-version = "0.1.0.dev19"
+version = "0.1.0.dev22"
 description = "AI-powered research, planning, and task management CLI tool"
 readme = "README.md"
 license = { text = "MIT" }

{shotgun_sh-0.1.0.dev19 → shotgun_sh-0.1.0.dev22}/src/shotgun/agents/agent_manager.py

@@ -32,7 +32,7 @@ from pydantic_ai.messages import (
 from textual.message import Message
 from textual.widget import Widget
 
-from shotgun.agents.common import add_system_prompt_message
+from shotgun.agents.common import add_system_prompt_message, add_system_status_message
 
 from .export import create_export_agent
 from .history.compaction import apply_persistent_compaction
@@ -122,6 +122,7 @@ class AgentManager(Widget):
         agent_runtime_options = AgentRuntimeOptions(
             interactive_mode=self.deps.interactive_mode,
             working_directory=self.deps.working_directory,
+            is_tui_context=self.deps.is_tui_context,
             max_iterations=self.deps.max_iterations,
             queue=self.deps.queue,
             tasks=self.deps.tasks,
@@ -280,6 +281,9 @@ class AgentManager(Widget):
         # Start with persistent message history
         message_history = self.message_history
 
+        # Add a system status message so the agent knows whats going on
+        message_history = await add_system_status_message(deps, message_history)
+
         # Check if the message history already has a system prompt
         has_system_prompt = any(
             hasattr(msg, "parts")

{shotgun_sh-0.1.0.dev19 → shotgun_sh-0.1.0.dev22}/src/shotgun/agents/common.py

@@ -15,9 +15,7 @@ from pydantic_ai.agent import AgentRunResult
 from pydantic_ai.messages import (
     ModelMessage,
     ModelRequest,
-    ModelResponse,
     SystemPromptPart,
-    TextPart,
 )
 
 from shotgun.agents.config import ProviderType, get_config_manager, get_provider_model
@@ -79,13 +77,14 @@ async def add_system_status_message(
     system_state = prompt_loader.render(
         "agents/state/system_state.j2",
         codebase_understanding_graphs=codebase_understanding_graphs,
+        is_tui_context=deps.is_tui_context,
         **artifact_state,
     )
 
     message_history.append(
-        ModelResponse(
+        ModelRequest(
             parts=[
-                TextPart(content=system_state),
+                SystemPromptPart(content=system_state),
             ]
         )
     )

{shotgun_sh-0.1.0.dev19 → shotgun_sh-0.1.0.dev22}/src/shotgun/agents/models.py

@@ -60,6 +60,11 @@ class AgentRuntimeOptions(BaseModel):
         description="Working directory for agent operations",
     )
 
+    is_tui_context: bool = Field(
+        default=False,
+        description="Whether the agent is running in TUI context",
+    )
+
     max_iterations: int = Field(
         default=10,
         ge=1,

{shotgun_sh-0.1.0.dev19 → shotgun_sh-0.1.0.dev22}/src/shotgun/agents/tools/codebase/codebase_shell.py

@@ -87,7 +87,7 @@ async def codebase_shell(
                 success=False,
                 command=command,
                 args=args,
-                error="No codebase service available in context",
+                error="No codebase indexed",
             )
 
         # Security validation
@@ -129,7 +129,7 @@ async def codebase_shell(
                     success=False,
                     command=command,
                     args=args,
-                    error="No codebases available. Add a codebase first using graph management tools.",
+                    error="No codebase indexed. Index a codebase first.",
                 )
 
             # Select the appropriate graph

{shotgun_sh-0.1.0.dev19 → shotgun_sh-0.1.0.dev22}/src/shotgun/agents/tools/codebase/directory_lister.py

@@ -33,7 +33,7 @@ async def directory_lister(
                 success=False,
                 directory=directory,
                 full_path="",
-                error="No codebase service available in context",
+                error="No codebase indexed",
             )
 
         # Get the graph to find the repository path

{shotgun_sh-0.1.0.dev19 → shotgun_sh-0.1.0.dev22}/src/shotgun/agents/tools/codebase/file_read.py

@@ -33,7 +33,7 @@ async def file_read(
             return FileReadResult(
                 success=False,
                 file_path=file_path,
-                error="No codebase service available in context",
+                error="No codebase indexed",
             )
 
         # Get the graph to find the repository path

{shotgun_sh-0.1.0.dev19 → shotgun_sh-0.1.0.dev22}/src/shotgun/agents/tools/codebase/query_graph.py

@@ -31,7 +31,7 @@ async def query_graph(
             return QueryGraphResult(
                 success=False,
                 query=query,
-                error="No codebase service available in context",
+                error="No codebase indexed",
             )
 
         # Execute natural language query

{shotgun_sh-0.1.0.dev19 → shotgun_sh-0.1.0.dev22}/src/shotgun/agents/tools/codebase/retrieve_code.py

@@ -34,7 +34,7 @@ async def retrieve_code(
             return CodeSnippetResult(
                 found=False,
                 qualified_name=qualified_name,
-                error="No codebase service available in context",
+                error="No codebase indexed",
             )
 
         # Use the existing code retrieval functionality

{shotgun_sh-0.1.0.dev19 → shotgun_sh-0.1.0.dev22}/src/shotgun/prompts/agents/partials/codebase_understanding.j2

@@ -40,6 +40,15 @@ Important:
 - Always think about a plan first and communicate this plan back to the user BEFORE calling any codebase management or codebase understanding tools.
 - **GRAPH ID vs NAME**: Every graph has both a NAME (like "Shotgun2") and an ID (like "993ec896213d"). The name is for human reference only. ALL TOOLS REQUIRE THE GRAPH ID, NOT THE NAME!
 
+## User Communication Guidelines
+
+**CRITICAL**: When communicating with users about codebases:
+- NEVER mention "graph ID" to users - use the codebase name (e.g., "Shotgun2") or path (e.g., "/Users/scott/project")
+- When multiple codebases are available, ask "Which codebase would you like to analyze: Shotgun2 at /path/to/repo?"
+- Internal tools still require graph_id parameters, but don't expose these IDs to users
+- Say "the codebase 'ProjectName'" or "the codebase at /path" instead of "graph xyz123"
+- If asking users to confirm a codebase, show the name and path, not the ID
+
 **CRITICAL RULES:**
 0.  **ALWAYS USE GRAPH ID**: When calling ANY tool that requires a graph_id parameter, you MUST use the ID (e.g., "993ec896213d"), NOT the name (e.g., "Shotgun2"). The name is only for human reference.
 1.  **TOOL-ONLY ANSWERS**: You must ONLY use information from the tools provided. Do not use external knowledge.

shotgun_sh-0.1.0.dev22/src/shotgun/prompts/agents/state/codebase/codebase_graphs_available.j2

@@ -0,0 +1,19 @@
+## Codebase Graphs Available
+
+{% if codebase_understanding_graphs -%}
+
+You have access to the following codebase graphs:
+
+{% for graph in codebase_understanding_graphs -%}
+- {{ graph.name }} ID: {{ graph.graph_id }} Path: {{ graph.repo_path }}
+{% endfor -%}
+
+{% else -%}
+
+{% if is_tui_context -%}
+No codebase has been indexed yet. To enable code analysis, please tell the user to restart the TUI and follow the prompt to 'Index this codebase?' when it appears.
+{% else -%}
+No codebase has been indexed yet. If the user needs code analysis, ask them to index a codebase first.
+{% endif -%}
+
+{% endif %}

{shotgun_sh-0.1.0.dev19 → shotgun_sh-0.1.0.dev22}/src/shotgun/sdk/models.py

@@ -15,7 +15,7 @@ class ListResult(BaseModel):
     def __str__(self) -> str:
         """Format list result as plain text table."""
         if not self.graphs:
-            return "No codebases found."
+            return "No indexed codebases found."
 
         lines = [
             f"{'ID':<12} {'Name':<30} {'Status':<10} {'Files':<8} {'Path'}",

{shotgun_sh-0.1.0.dev19 → shotgun_sh-0.1.0.dev22}/src/shotgun/tui/screens/chat.py

@@ -42,6 +42,7 @@ from shotgun.tui.screens.chat_screen.history import ChatHistory
 
 from ..components.prompt_input import PromptInput
 from ..components.spinner import Spinner
+from ..utils.mode_progress import PlaceholderHints
 from .chat_screen.command_providers import (
     AgentModeProvider,
     CodebaseCommandProvider,
@@ -116,6 +117,7 @@ class ModeIndicator(Widget):
         """
         super().__init__()
         self.mode = mode
+        self.progress_checker = PlaceholderHints().progress_checker
 
     def render(self) -> str:
         """Render the mode indicator."""
@@ -137,7 +139,11 @@ class ModeIndicator(Widget):
         mode_title = mode_display.get(self.mode, self.mode.value.title())
         description = mode_description.get(self.mode, "")
 
-        return f"[bold $text-accent]{mode_title} mode[/][$foreground-muted] ({description})[/]"
+        # Check if mode has content
+        has_content = self.progress_checker.has_mode_content(self.mode)
+        status_icon = " ✓" if has_content else ""
+
+        return f"[bold $text-accent]{mode_title}{status_icon} mode[/][$foreground-muted] ({description})[/]"
 
 
 class FilteredDirectoryTree(DirectoryTree):
@@ -174,9 +180,11 @@ class CodebaseIndexPromptScreen(ModalScreen[bool]):
 
     def compose(self) -> ComposeResult:
         with Container(id="index-prompt-dialog"):
-            yield Label("Index your codebase?", id="index-prompt-title")
+            yield Label("Index this codebase?", id="index-prompt-title")
             yield Static(
-                "We found project files but no index yet. Indexing enables smarter chat."
+                f"Would you like to index the codebase at:\n{Path.cwd()}\n\n"
+                "This is required for the agent to understand your code and answer "
+                "questions about it. Without indexing, the agent cannot analyze your codebase."
             )
             with Container(id="index-prompt-buttons"):
                 yield Button(
@@ -306,24 +314,6 @@ class ChatScreen(Screen[None]):
 
     COMMANDS = {AgentModeProvider, ProviderSetupProvider, CodebaseCommandProvider}
 
-    _PLACEHOLDER_BY_MODE: dict[AgentType, str] = {
-        AgentType.RESEARCH: (
-            "Ask for investigations, e.g. research strengths and weaknesses of PydanticAI vs its rivals"
-        ),
-        AgentType.PLAN: (
-            "Describe a goal to plan, e.g. draft a rollout plan for launching our Slack automation"
-        ),
-        AgentType.TASKS: (
-            "Request actionable work, e.g. break down tasks to wire OpenTelemetry into the API"
-        ),
-        AgentType.SPECIFY: (
-            "Request detailed specifications, e.g. create a comprehensive spec for user authentication system"
-        ),
-        AgentType.EXPORT: (
-            "Request export tasks, e.g. export research findings to Markdown or convert tasks to CSV"
-        ),
-    }
-
     value = reactive("")
     mode = reactive(AgentType.RESEARCH)
     history: PromptHistory = PromptHistory()
@@ -350,6 +340,7 @@ class ChatScreen(Screen[None]):
 
         self.deps = AgentDeps(
             interactive_mode=True,
+            is_tui_context=True,
             llm_model=model_config,
             codebase_service=codebase_service,
             artifact_service=artifact_service,
@@ -357,6 +348,7 @@ class ChatScreen(Screen[None]):
         )
         self.agent_manager = AgentManager(deps=self.deps, initial_type=self.mode)
         self.command_handler = CommandHandler()
+        self.placeholder_hints = PlaceholderHints()
 
     def on_mount(self) -> None:
         self.query_one(PromptInput).focus(scroll_visible=True)
@@ -407,7 +399,10 @@ class ChatScreen(Screen[None]):
             mode_indicator.refresh()
 
             prompt_input = self.query_one(PromptInput)
-            prompt_input.placeholder = self._placeholder_for_mode(new_mode)
+            # Force new hint selection when mode changes
+            prompt_input.placeholder = self._placeholder_for_mode(
+                new_mode, force_new=True
+            )
             prompt_input.refresh()
 
     def watch_working(self, is_working: bool) -> None:
@@ -503,6 +498,14 @@ class ChatScreen(Screen[None]):
         self._clear_partial_response()
         self.messages = event.messages
 
+        # Refresh placeholder and mode indicator in case artifacts were created
+        prompt_input = self.query_one(PromptInput)
+        prompt_input.placeholder = self._placeholder_for_mode(self.mode)
+        prompt_input.refresh()
+
+        mode_indicator = self.query_one(ModeIndicator)
+        mode_indicator.refresh()
+
         # If there are file operations, add a message showing the modified files
         if event.file_operations:
             chat_history = self.query_one(ChatHistory)
@@ -577,9 +580,19 @@ class ChatScreen(Screen[None]):
         prompt_input = self.query_one(PromptInput)
         prompt_input.clear()
 
-    def _placeholder_for_mode(self, mode: AgentType) -> str:
-        """Return the placeholder text appropriate for the current mode."""
-        return self._PLACEHOLDER_BY_MODE.get(mode, "Type your message")
+    def _placeholder_for_mode(self, mode: AgentType, force_new: bool = False) -> str:
+        """Return the placeholder text appropriate for the current mode.
+
+        Args:
+            mode: The current agent mode.
+            force_new: If True, force selection of a new random hint.
+
+        Returns:
+            Dynamic placeholder hint based on mode and progress.
+        """
+        return self.placeholder_hints.get_placeholder_for_mode(
+            mode, force_new=force_new
+        )
 
     def index_codebase_command(self) -> None:
         start_path = Path.cwd()

{shotgun_sh-0.1.0.dev19 → shotgun_sh-0.1.0.dev22}/src/shotgun/tui/screens/chat_screen/history.py

@@ -204,7 +204,6 @@ class AgentResponseWidget(Widget):
         self,
         part: ToolCallPart,
     ) -> str:
-        return "*Answer to continue*"
         if isinstance(part.args, str):
             try:
                 _args = json.loads(part.args) if part.args.strip() else {}

shotgun_sh-0.1.0.dev22/src/shotgun/tui/utils/__init__.py

@@ -0,0 +1,5 @@
+"""TUI utilities package."""
+
+from .mode_progress import ModeProgressChecker, PlaceholderHints
+
+__all__ = ["ModeProgressChecker", "PlaceholderHints"]

shotgun_sh-0.1.0.dev22/src/shotgun/tui/utils/mode_progress.py

@@ -0,0 +1,224 @@
+"""Utility module for checking mode progress in .shotgun directories."""
+
+import random
+from pathlib import Path
+
+from shotgun.agents.agent_manager import AgentType
+from shotgun.artifacts.models import AgentMode
+from shotgun.utils.file_system_utils import get_shotgun_base_path
+
+
+class ModeProgressChecker:
+    """Checks progress across different agent modes based on .shotgun directory contents."""
+
+    # Minimum file size in characters to consider a mode as "started"
+    MIN_CONTENT_SIZE = 20
+
+    def __init__(self, base_path: Path | None = None):
+        """Initialize the progress checker.
+
+        Args:
+            base_path: Base path for .shotgun directory. Defaults to current directory.
+        """
+        self.base_path = base_path or get_shotgun_base_path()
+
+    def has_mode_content(self, mode: AgentType | AgentMode) -> bool:
+        """Check if a mode directory has meaningful content.
+
+        Args:
+            mode: The agent mode to check.
+
+        Returns:
+            True if the mode has at least one file with >20 characters.
+        """
+        mode_value = mode.value if hasattr(mode, "value") else str(mode)
+        mode_path = self.base_path / mode_value
+
+        if not mode_path.exists() or not mode_path.is_dir():
+            return False
+
+        # Check all subdirectories and files
+        for item in mode_path.rglob("*"):
+            if item.is_file() and not item.name.startswith("."):
+                try:
+                    content = item.read_text(encoding="utf-8")
+                    # Check if file has meaningful content
+                    if len(content.strip()) > self.MIN_CONTENT_SIZE:
+                        return True
+                except (OSError, UnicodeDecodeError):
+                    # Skip files that can't be read
+                    continue
+
+        return False
+
+    def get_next_suggested_mode(self, current_mode: AgentType) -> AgentType | None:
+        """Get the next suggested mode based on current progress.
+
+        Args:
+            current_mode: The current agent mode.
+
+        Returns:
+            The next suggested mode, or None if no suggestion.
+        """
+        mode_order = [
+            AgentType.RESEARCH,
+            AgentType.SPECIFY,
+            AgentType.TASKS,
+            AgentType.EXPORT,
+        ]
+
+        try:
+            current_index = mode_order.index(current_mode)
+        except ValueError:
+            # Mode not in standard order (e.g., PLAN mode)
+            return None
+
+        # Check if current mode has content
+        if not self.has_mode_content(current_mode):
+            # Current mode is empty, no suggestion for next mode
+            return None
+
+        # Get next mode in sequence
+        if current_index < len(mode_order) - 1:
+            return mode_order[current_index + 1]
+
+        # Export mode cycles back to Research
+        return mode_order[0]
+
+
+class PlaceholderHints:
+    """Manages dynamic placeholder hints for each mode based on progress."""
+
+    # Placeholder variations for each mode and state
+    HINTS = {
+        # Research mode
+        AgentType.RESEARCH: {
+            False: [
+                "Research a product or idea (SHIFT+TAB to cycle modes)",
+                "What would you like to explore? Start your research journey here (SHIFT+TAB to switch modes)",
+                "Dive into discovery mode - research anything that sparks curiosity (SHIFT+TAB for mode menu)",
+                "Ready to investigate? Feed me your burning questions (SHIFT+TAB to explore other modes)",
+                " 🔍 The research rabbit hole awaits! What shall we uncover? (SHIFT+TAB for mode carousel)",
+            ],
+            True: [
+                "Research complete! SHIFT+TAB to move to Specify mode",
+                "Great research! Time to specify (SHIFT+TAB to Specify mode)",
+                "Research done! Ready to create specifications (SHIFT+TAB to Specify)",
+                "Findings gathered! Move to specifications (SHIFT+TAB for Specify mode)",
+                " 🎯 Research complete! Advance to Specify mode (SHIFT+TAB)",
+            ],
+        },
+        # Specify mode
+        AgentType.SPECIFY: {
+            False: [
+                "Create detailed specifications and requirements (SHIFT+TAB to switch modes)",
+                "Define your project specifications here (SHIFT+TAB to navigate modes)",
+                "Time to get specific - write comprehensive specs (SHIFT+TAB for mode options)",
+                "Specification station: Document requirements and designs (SHIFT+TAB to change modes)",
+                " 📋 Spec-tacular time! Let's architect your ideas (SHIFT+TAB for mode magic)",
+            ],
+            True: [
+                "Specifications complete! SHIFT+TAB to create a Plan",
+                "Specs ready! Time to plan (SHIFT+TAB to Plan mode)",
+                "Requirements defined! Move to planning (SHIFT+TAB to Plan)",
+                "Specifications done! Create your roadmap (SHIFT+TAB for Plan mode)",
+                " 🚀 Specs complete! Advance to Plan mode (SHIFT+TAB)",
+            ],
+        },
+        # Tasks mode
+        AgentType.TASKS: {
+            False: [
+                "Create actionable tasks and work items (SHIFT+TAB to switch modes)",
+                "Define your task list and action items (SHIFT+TAB to explore modes)",
+                "Task creation time - build your work breakdown (SHIFT+TAB for mode selection)",
+                "The task forge awaits - create doable chunks of work (SHIFT+TAB to change modes)",
+                " ⚡ Task mode activated! Let's define what needs doing (SHIFT+TAB for mode journey)",
+            ],
+            True: [
+                "Tasks complete! SHIFT+TAB to Export mode",
+                "Task list ready! Time to export (SHIFT+TAB to Export)",
+                "Work items defined! Export your artifacts (SHIFT+TAB to Export mode)",
+                "Tasks done! Ship them out (SHIFT+TAB for Export mode)",
+                " 🎉 Tasks complete! Advance to Export mode (SHIFT+TAB)",
+            ],
+        },
+        # Export mode
+        AgentType.EXPORT: {
+            False: [
+                "Export artifacts to Claude Code, Cursor, or other tools (SHIFT+TAB to switch modes)",
+                "Ready to export! Send work to your favorite IDE (SHIFT+TAB to navigate modes)",
+                "Export central - Ship artifacts to dev tools (SHIFT+TAB for mode options)",
+                "Time to set your work free! Export anywhere (SHIFT+TAB to change modes)",
+                " 🚢 Launch pad ready! Blast artifacts to Claude Code & beyond (SHIFT+TAB for mode menu)",
+            ],
+            True: [
+                "Exports complete! SHIFT+TAB to start new Research cycle",
+                "Artifacts exported! Begin fresh research (SHIFT+TAB to Research mode)",
+                "Export done! Start a new journey (SHIFT+TAB for Research)",
+                "Work shipped! New research awaits (SHIFT+TAB to Research mode)",
+                " 🎊 Export complete! Loop back to Research (SHIFT+TAB)",
+            ],
+        },
+        # Plan mode (special case - not in main flow)
+        AgentType.PLAN: {
+            False: [
+                "Create comprehensive plans with milestones (SHIFT+TAB to switch modes)",
+                "Plan your project roadmap and milestones (SHIFT+TAB to explore modes)",
+                "Strategic planning mode - design your journey (SHIFT+TAB for mode options)",
+                "The planning parlor - where ideas become roadmaps (SHIFT+TAB to navigate)",
+                " 📅 Planning paradise! Chart your course to success (SHIFT+TAB for modes)",
+            ],
+            True: [
+                "Plan complete! SHIFT+TAB to create Tasks",
+                "Roadmap ready! Time for tasks (SHIFT+TAB to Tasks mode)",
+                "Planning done! Break it down to tasks (SHIFT+TAB to Tasks)",
+                "Strategy set! Move to task creation (SHIFT+TAB for Tasks mode)",
+                " 🗺️ Plan complete! Advance to Tasks mode (SHIFT+TAB)",
+            ],
+        },
+    }
+
+    def __init__(self, base_path: Path | None = None):
+        """Initialize the placeholder hints manager.
+
+        Args:
+            base_path: Base path for .shotgun directory.
+        """
+        self.progress_checker = ModeProgressChecker(base_path)
+        self._last_hints: dict[str, str] = {}  # Cache last selected hint per mode
+
+    def get_placeholder_for_mode(self, mode: AgentType, force_new: bool = False) -> str:
+        """Get a random placeholder hint for the given mode based on progress.
+
+        Args:
+            mode: The current agent mode.
+            force_new: If True, always select a new random hint.
+
+        Returns:
+            A randomly selected placeholder hint appropriate for the mode and progress.
+        """
+        # Determine if mode has content
+        has_content = self.progress_checker.has_mode_content(mode)
+
+        # Get hints for this mode and state
+        mode_hints = self.HINTS.get(mode, {})
+        state_hints = mode_hints.get(has_content, [])
+
+        if not state_hints:
+            # Fallback if mode not configured
+            return (
+                f"Type your message for {mode.value} mode (SHIFT+TAB to switch modes)"
+            )
+
+        # Cache key for this mode/state combination
+        cache_key = f"{mode.value}_{has_content}"
+
+        # If not forcing new and we have a cached hint, return it
+        if not force_new and cache_key in self._last_hints:
+            return self._last_hints[cache_key]
+
+        # Select a random hint
+        hint = random.choice(state_hints)  # noqa: S311 - random is fine for UI hints
+        self._last_hints[cache_key] = hint
+
+        return hint

shotgun_sh-0.1.0.dev19/src/shotgun/prompts/agents/state/codebase/codebase_graphs_available.j2

@@ -1,15 +0,0 @@
-## Codebase Graphs Available
-
-{% if codebase_understanding_graphs -%}
-
-You have access to the following codebase graphs:
-
-{% for graph in codebase_understanding_graphs -%}
-- {{ graph.name }} ID: {{ graph.graph_id }} Path: {{ graph.repo_path }}
-{% endfor -%}
-
-{% else -%}
-
-You have no access to codebase graphs. You can optionally ask the user to load a codebase if the user asked a codebase question.
-
-{% endif %}