shotgun-sh 0.1.0.dev25__tar.gz → 0.1.0.dev26__tar.gz

{shotgun_sh-0.1.0.dev25 → shotgun_sh-0.1.0.dev26}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shotgun-sh
-Version: 0.1.0.dev25
+Version: 0.1.0.dev26
 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.dev25 → shotgun_sh-0.1.0.dev26}/pyproject.toml

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

{shotgun_sh-0.1.0.dev25 → shotgun_sh-0.1.0.dev26}/src/shotgun/agents/agent_manager.py

@@ -37,6 +37,7 @@ from textual.widget import Widget
 
 from shotgun.agents.common import add_system_prompt_message, add_system_status_message
 from shotgun.agents.models import AgentType, FileOperation
+from shotgun.tui.screens.chat_screen.hint_message import HintMessage
 
 from .export import create_export_agent
 from .history.compaction import apply_persistent_compaction
@@ -54,7 +55,7 @@ class MessageHistoryUpdated(Message):
 
     def __init__(
         self,
-        messages: list[ModelMessage],
+        messages: list[ModelMessage | HintMessage],
         agent_type: AgentType,
         file_operations: list[FileOperation] | None = None,
     ) -> None:
@@ -143,7 +144,7 @@ class AgentManager(Widget):
         self._current_agent_type: AgentType = initial_type
 
         # Maintain shared message history
-        self.ui_message_history: list[ModelMessage] = []
+        self.ui_message_history: list[ModelMessage | HintMessage] = []
         self.message_history: list[ModelMessage] = []
         self.recently_change_files: list[FileOperation] = []
         self._stream_state: _PartialStreamState | None = None
@@ -461,8 +462,8 @@ class AgentManager(Widget):
         )
 
     def _filter_system_prompts(
-        self, messages: list[ModelMessage]
-    ) -> list[ModelMessage]:
+        self, messages: list[ModelMessage | HintMessage]
+    ) -> list[ModelMessage | HintMessage]:
         """Filter out system prompts from messages for UI display.
 
         Args:
@@ -473,8 +474,12 @@ class AgentManager(Widget):
         """
         from pydantic_ai.messages import SystemPromptPart
 
-        filtered_messages: list[ModelMessage] = []
+        filtered_messages: list[ModelMessage | HintMessage] = []
         for msg in messages:
+            if isinstance(msg, HintMessage):
+                filtered_messages.append(msg)
+                continue
+
             parts: Sequence[ModelRequestPart] | Sequence[ModelResponsePart] | None = (
                 msg.parts if hasattr(msg, "parts") else None
             )
@@ -514,6 +519,7 @@ class AgentManager(Widget):
 
         return ConversationState(
             agent_messages=self.message_history.copy(),
+            ui_messages=self.ui_message_history.copy(),
             agent_type=self._current_agent_type.value,
         )
 
@@ -524,10 +530,16 @@ class AgentManager(Widget):
             state: ConversationState object to restore
         """
         # Restore message history for agents (includes system prompts)
-        self.message_history = state.agent_messages.copy()
+        non_hint_messages = [
+            msg for msg in state.agent_messages if not isinstance(msg, HintMessage)
+        ]
+        self.message_history = non_hint_messages
 
-        # Filter out system prompts for UI display
-        self.ui_message_history = self._filter_system_prompts(state.agent_messages)
+        # Filter out system prompts for UI display while keeping hints
+        ui_source = state.ui_messages or cast(
+            list[ModelMessage | HintMessage], state.agent_messages
+        )
+        self.ui_message_history = self._filter_system_prompts(ui_source)
 
         # Restore agent type
         self._current_agent_type = AgentType(state.agent_type)
@@ -535,6 +547,10 @@ class AgentManager(Widget):
         # Notify listeners about the restored messages
         self._post_messages_updated()
 
+    def add_hint_message(self, message: HintMessage) -> None:
+        self.ui_message_history.append(message)
+        self._post_messages_updated()
+
 
 # Re-export AgentType for backward compatibility
 __all__ = [

{shotgun_sh-0.1.0.dev25 → shotgun_sh-0.1.0.dev26}/src/shotgun/agents/common.py

@@ -2,6 +2,7 @@
 
 import asyncio
 from collections.abc import Callable
+from pathlib import Path
 from typing import Any
 
 from pydantic_ai import (
@@ -28,7 +29,7 @@ from shotgun.utils.file_system_utils import get_shotgun_base_path
 
 from .history import token_limit_compactor
 from .history.compaction import apply_persistent_compaction
-from .models import AgentDeps, AgentRuntimeOptions
+from .models import AgentDeps, AgentRuntimeOptions, PipelineConfigEntry
 from .tools import (
     append_file,
     ask_user,
@@ -197,33 +198,24 @@ def create_base_agent(
     return agent, deps
 
 
-def extract_markdown_toc(agent_mode: AgentType | None) -> str | None:
-    """Extract table of contents from agent's markdown file.
+def _extract_file_toc_content(
+    file_path: Path, max_depth: int | None = None, max_chars: int = 500
+) -> str | None:
+    """Extract TOC from a single file with depth and character limits.
 
     Args:
-        agent_mode: The agent mode to extract TOC for
+        file_path: Path to the markdown file
+        max_depth: Maximum heading depth (1=#, 2=##, None=all)
+        max_chars: Maximum characters for the TOC
 
     Returns:
-        Formatted TOC string (up to 2000 chars) or None if not applicable
+        Formatted TOC string or None if file doesn't exist
     """
-    # Skip for EXPORT mode or no mode
-    if (
-        not agent_mode
-        or agent_mode == AgentType.EXPORT
-        or agent_mode not in AGENT_DIRECTORIES
-    ):
-        return None
-
-    base_path = get_shotgun_base_path()
-    md_file = AGENT_DIRECTORIES[agent_mode]
-    md_path = base_path / md_file
-
-    # Check if the markdown file exists
-    if not md_path.exists():
+    if not file_path.exists():
         return None
 
     try:
-        content = md_path.read_text(encoding="utf-8")
+        content = file_path.read_text(encoding="utf-8")
         lines = content.split("\n")
 
         # Extract headings
@@ -239,6 +231,10 @@ def extract_markdown_toc(agent_mode: AgentType | None) -> str | None:
                     else:
                         break
 
+                # Skip if exceeds max_depth
+                if max_depth and level > max_depth:
+                    continue
+
                 # Get the heading text (remove the # symbols and clean up)
                 heading_text = stripped[level:].strip()
                 if heading_text:
@@ -246,21 +242,110 @@ def extract_markdown_toc(agent_mode: AgentType | None) -> str | None:
                     indent = "  " * (level - 1)
                     toc_lines.append(f"{indent}{'#' * level} {heading_text}")
 
+                    # Check if we're approaching the character limit
+                    current_length = sum(len(line) + 1 for line in toc_lines)
+                    if current_length > max_chars:
+                        # Remove the last line and add ellipsis
+                        toc_lines.pop()
+                        if toc_lines:
+                            toc_lines.append("  ...")
+                        break
+
         if not toc_lines:
             return None
 
-        # Join and truncate to 2000 characters
-        toc = "\n".join(toc_lines)
-        if len(toc) > 2000:
-            toc = toc[:1997] + "..."
-
-        return toc
+        return "\n".join(toc_lines)
 
     except Exception as e:
-        logger.debug(f"Failed to extract TOC from {md_file}: {e}")
+        logger.debug(f"Failed to extract TOC from {file_path}: {e}")
         return None
 
 
+def extract_markdown_toc(agent_mode: AgentType | None) -> str | None:
+    """Extract TOCs from current and prior agents' files in the pipeline.
+
+    Shows full TOC of agent's own file and high-level summaries of prior agents'
+    files to maintain context awareness while keeping context window tight.
+
+    Args:
+        agent_mode: The agent mode to extract TOC for
+
+    Returns:
+        Formatted multi-file TOC string or None if not applicable
+    """
+    # Skip if no mode
+    if not agent_mode:
+        return None
+
+    # Define pipeline order and dependencies
+    pipeline_config: dict[AgentType, PipelineConfigEntry] = {
+        AgentType.RESEARCH: PipelineConfigEntry(
+            own_file="research.md",
+            prior_files=[],  # First in pipeline
+        ),
+        AgentType.SPECIFY: PipelineConfigEntry(
+            own_file="specification.md",
+            prior_files=["research.md"],
+        ),
+        AgentType.PLAN: PipelineConfigEntry(
+            own_file="plan.md",
+            prior_files=["research.md", "specification.md"],
+        ),
+        AgentType.TASKS: PipelineConfigEntry(
+            own_file="tasks.md",
+            prior_files=["research.md", "specification.md", "plan.md"],
+        ),
+        AgentType.EXPORT: PipelineConfigEntry(
+            own_file=None,  # Export uses directory
+            prior_files=["research.md", "specification.md", "plan.md", "tasks.md"],
+        ),
+    }
+
+    # Get configuration for current agent
+    if agent_mode not in pipeline_config:
+        return None
+
+    config = pipeline_config[agent_mode]
+    base_path = get_shotgun_base_path()
+    toc_sections: list[str] = []
+
+    # Extract TOCs from prior files (high-level only)
+    for prior_file in config.prior_files:
+        file_path = base_path / prior_file
+        # Only show # and ## headings from prior files, max 500 chars each
+        prior_toc = _extract_file_toc_content(file_path, max_depth=2, max_chars=500)
+        if prior_toc:
+            # Add section header
+            file_label = prior_file.replace(".md", "").replace("_", " ").title()
+            toc_sections.append(
+                f"=== Prior Context: {file_label} (summary) ===\n{prior_toc}"
+            )
+
+    # Extract TOC from own file (full detail)
+    if config.own_file:
+        own_path = base_path / config.own_file
+        own_toc = _extract_file_toc_content(own_path, max_depth=None, max_chars=2000)
+        if own_toc:
+            file_label = config.own_file.replace(".md", "").replace("_", " ").title()
+            # Put own file TOC at the beginning
+            toc_sections.insert(
+                0, f"=== Your Current Document: {file_label} ===\n{own_toc}"
+            )
+
+    # Combine all sections
+    if not toc_sections:
+        return None
+
+    combined_toc = "\n\n".join(toc_sections)
+
+    # Final truncation if needed (should rarely happen with our limits)
+    max_total = 3500  # Conservative total limit
+    if len(combined_toc) > max_total:
+        combined_toc = combined_toc[: max_total - 3] + "..."
+
+    return combined_toc
+
+
 def get_agent_existing_files(agent_mode: AgentType | None = None) -> list[str]:
     """Get list of existing files for the given agent mode.
 

shotgun_sh-0.1.0.dev26/src/shotgun/agents/conversation_history.py

@@ -0,0 +1,106 @@
+"""Models and utilities for persisting TUI conversation history."""
+
+from datetime import datetime
+from typing import Any, cast
+
+from pydantic import BaseModel, ConfigDict, Field
+from pydantic_ai.messages import (
+    ModelMessage,
+    ModelMessagesTypeAdapter,
+)
+from pydantic_core import to_jsonable_python
+
+from shotgun.tui.screens.chat_screen.hint_message import HintMessage
+
+SerializedMessage = dict[str, Any]
+
+
+class ConversationState(BaseModel):
+    """Represents the complete state of a conversation in memory."""
+
+    agent_messages: list[ModelMessage]
+    ui_messages: list[ModelMessage | HintMessage] = Field(default_factory=list)
+    agent_type: str  # Will store AgentType.value
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+
+class ConversationHistory(BaseModel):
+    """Persistent conversation history for TUI sessions."""
+
+    version: int = 1
+    agent_history: list[SerializedMessage] = Field(
+        default_factory=list
+    )  # Stores serialized ModelMessage objects
+    ui_history: list[SerializedMessage] = Field(
+        default_factory=list
+    )  # Stores serialized ModelMessage and HintMessage objects
+    last_agent_model: str = "research"
+    updated_at: datetime = Field(default_factory=datetime.now)
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    def set_agent_messages(self, messages: list[ModelMessage]) -> None:
+        """Set agent_history from a list of ModelMessage objects.
+
+        Args:
+            messages: List of ModelMessage objects to serialize and store
+        """
+        # Serialize ModelMessage list to JSON-serializable format
+        self.agent_history = to_jsonable_python(
+            messages, fallback=lambda x: str(x), exclude_none=True
+        )
+
+    def set_ui_messages(self, messages: list[ModelMessage | HintMessage]) -> None:
+        """Set ui_history from a list of UI messages."""
+
+        def _serialize_message(
+            message: ModelMessage | HintMessage,
+        ) -> Any:
+            if isinstance(message, HintMessage):
+                data = message.model_dump()
+                data["message_type"] = "hint"
+                return data
+            payload = to_jsonable_python(
+                message, fallback=lambda x: str(x), exclude_none=True
+            )
+            if isinstance(payload, dict):
+                payload.setdefault("message_type", "model")
+            return payload
+
+        self.ui_history = [_serialize_message(msg) for msg in messages]
+
+    def get_agent_messages(self) -> list[ModelMessage]:
+        """Get agent_history as a list of ModelMessage objects.
+
+        Returns:
+            List of deserialized ModelMessage objects
+        """
+        if not self.agent_history:
+            return []
+
+        # Deserialize from JSON format back to ModelMessage objects
+        return ModelMessagesTypeAdapter.validate_python(self.agent_history)
+
+    def get_ui_messages(self) -> list[ModelMessage | HintMessage]:
+        """Get ui_history as a list of Model or hint messages."""
+
+        if not self.ui_history:
+            # Fallback for older conversation files without UI history
+            return cast(list[ModelMessage | HintMessage], self.get_agent_messages())
+
+        messages: list[ModelMessage | HintMessage] = []
+        for item in self.ui_history:
+            message_type = item.get("message_type") if isinstance(item, dict) else None
+            if message_type == "hint":
+                messages.append(HintMessage.model_validate(item))
+                continue
+
+            # Backwards compatibility: data may not include the type marker
+            payload = item
+            if isinstance(payload, dict):
+                payload = {k: v for k, v in payload.items() if k != "message_type"}
+            deserialized = ModelMessagesTypeAdapter.validate_python([payload])
+            messages.append(deserialized[0])
+
+        return messages

{shotgun_sh-0.1.0.dev25 → shotgun_sh-0.1.0.dev26}/src/shotgun/agents/models.py

@@ -27,6 +27,23 @@ class AgentType(StrEnum):
     EXPORT = "export"
 
 
+class PipelineConfigEntry(BaseModel):
+    """Configuration for each agent in the pipeline.
+
+    This model defines what files an agent can write to and what
+    files from prior agents it should read for context.
+    """
+
+    own_file: str | None = Field(
+        default=None,
+        description="The file this agent writes to (None for export agent)",
+    )
+    prior_files: list[str] = Field(
+        default_factory=list,
+        description="Files from prior agents in pipeline to read for context",
+    )
+
+
 class UserAnswer(BaseModel):
     """A answer from the user."""
 

shotgun_sh-0.1.0.dev26/src/shotgun/prompts/agents/export.j2

@@ -0,0 +1,214 @@
+You are an experienced Export Specialist and Data Transformation Expert.
+
+Your job is to help export project documentation and findings to various formats and destinations in the exports/ folder.
+
+{% include 'agents/partials/common_agent_system_prompt.j2' %}
+
+## MEMORY MANAGEMENT PROTOCOL
+
+- You can ONLY write to the `exports/` directory
+- SHOULD READ all files: `research.md`, `specification.md`, `plan.md`, `tasks.md`
+- Create new export files, don't modify source files
+- Name exports descriptively with timestamps: `exports/AGENTS_[timestamp].md`
+- Each export is a standalone deliverable for AI agents
+
+## AI AGENT PIPELINE AWARENESS
+
+**CRITICAL**: Your exports will be consumed by AI coding agents (Claude Code, Cursor, Windsurf, etc.)
+- The AGENTS.md file is THE primary deliverable for AI agents
+- Consolidate all relevant information into a single, actionable document
+- Include all necessary context without requiring access to source files
+- Structure exports for immediate AI agent consumption
+- Prioritize tasks and implementation steps from tasks.md
+- Include specifications and API details from specification.md
+- Add relevant research findings that affect implementation
+- Format as executable instructions, not educational content
+
+## EXPORT WORKFLOW
+
+For AGENTS.md exports:
+1. **MANDATORY: Read ALL pipeline files**:
+   - `tasks.md` - Extract actionable tasks with inputs/outputs
+   - `specification.md` - Get primary objective and constraints
+   - `plan.md` - Convert stages to success criteria
+   - `research.md` - Extract codebase context and open questions
+2. **Map content to template sections**:
+   - Primary Objective: From specification.md's main goal
+   - Tasks: From tasks.md, formatted as action items
+   - Research Needed: Unresolved questions from research.md
+   - Codebase Context: Technical findings from research.md
+   - Success Criteria: Plan.md stages as measurable outcomes
+   - Important Notes: Critical constraints from all files
+   - References: Documentation links from research.md
+3. **Transform content**: Convert to action-oriented language for AI agents
+4. **Create export**: Save as `exports/AGENTS.md` or `exports/AGENTS_[timestamp].md`
+5. **Validate**: Ensure every section has actionable content
+
+For other export tasks:
+1. **Check existing files**: Read relevant source files
+2. **Understand requirements**: Determine format and scope
+3. **Read source content**: Load all necessary information
+4. **Transform and format**: Convert to requested format
+5. **Create export files**: Save in exports/ folder
+6. **Validate output**: Verify proper formatting
+
+## SUPPORTED EXPORT FORMATS
+
+- **AGENTS.md**: See below
+- **Markdown (.md)**: Nicely formatted Markdown file with everything the user wants to export
+- **Multiple files**: Can create multiple export files in the exports/ folder as needed
+
+### AGENTS.md - Primary Export Format for AI Agents
+
+**CRITICAL**: The AGENTS.md file is THE primary deliverable for AI coding agents. It MUST follow this exact template:
+
+```markdown
+# [Project Name] Implementation Guide for AI Agents
+
+## Primary Objective
+[1-2 sentences describing WHAT needs to be built, not HOW]
+
+## Tasks
+
+### Task 1: [Action-oriented title]
+**Input**: [What files/data this task needs]
+**Output**: [What files/code this task produces]
+**Constraints**: [Security, performance, or architectural requirements]
+
+### Task 2: [Next action]
+[Continue pattern...]
+
+## Research Needed
+- [ ] [Specific technical question to investigate]
+- [ ] [API endpoint to understand]
+- [ ] [Integration pattern to review]
+
+## Codebase Context
+- **Language**: [Primary language and version]
+- **Key Files**: [Critical files to read first]
+- **Patterns**: [Design patterns used in codebase]
+- **Dependencies**: [Important libraries/frameworks]
+
+## Success Criteria
+- [ ] [Measurable outcome 1]
+- [ ] [Measurable outcome 2]
+- [ ] [Tests pass / Coverage meets X%]
+
+## Important Notes
+- [Critical constraint or requirement]
+- [Security consideration]
+- [Performance requirement]
+
+## References
+- [Link to API documentation]
+- [Link to architecture diagrams]
+- [Link to test requirements]
+```
+
+**Export Requirements**:
+- Extract Primary Objective from specification.md
+- Map tasks from tasks.md into action-oriented Task sections
+- Pull research questions from research.md that are still relevant
+- Include codebase context from research findings
+- Convert plan stages into Success Criteria
+- Add implementation constraints from specifications
+- Format ALL content for immediate AI agent execution
+- NO educational content, NO "learn X" instructions
+- Every section must be actionable by Claude Code
+
+**Example of GOOD AGENTS.md Content**:
+```markdown
+# E-commerce API Implementation Guide for AI Agents
+
+## Primary Objective
+Build a REST API for product catalog management with authentication, supporting CRUD operations and search functionality.
+
+## Tasks
+
+### Task 1: Implement Database Models
+**Input**: requirements.md, existing database schema
+**Output**: models/product.py, models/user.py, migrations/
+**Constraints**: Use SQLAlchemy ORM, maintain backward compatibility
+
+### Task 2: Create Authentication Endpoints
+**Input**: models/user.py, auth requirements
+**Output**: api/auth.py, middleware/auth.py
+**Constraints**: JWT tokens, 15-minute expiry, refresh token support
+
+## Research Needed
+- [ ] Check if existing auth middleware supports JWT refresh tokens
+- [ ] Verify PostgreSQL full-text search capabilities for product search
+- [ ] Review rate limiting implementation in current middleware
+
+## Codebase Context
+- **Language**: Python 3.11
+- **Key Files**: src/api/__init__.py, src/models/base.py
+- **Patterns**: Repository pattern, dependency injection
+- **Dependencies**: FastAPI, SQLAlchemy, Pydantic
+
+## Success Criteria
+- [ ] All CRUD endpoints return correct status codes
+- [ ] Authentication enforced on protected routes
+- [ ] Test coverage exceeds 80%
+- [ ] API response times under 200ms
+
+## Important Notes
+- Database migrations must be reversible
+- All endpoints require input validation
+- Search must support pagination
+
+## References
+- FastAPI docs: https://fastapi.tiangolo.com
+- Project API spec: docs/openapi.yaml
+```
+
+
+## EXPORT PRINCIPLES
+
+- Preserve content structure and meaning during transformation
+- Include proper headers, metadata, and formatting for target format
+- Maintain links, references, and cross-references where applicable
+- Create self-contained exports that can be used independently
+- Add appropriate file extensions and format indicators
+- Include export timestamp and source information
+- Validate exported content is properly formatted and complete
+- Handle missing or incomplete source data gracefully
+- Consider target audience and use case for formatting decisions
+- Always save exports in the exports/ folder
+
+{% if interactive_mode %}
+USER INTERACTION - CLARIFY EXPORT REQUIREMENTS:
+
+- ALWAYS ask clarifying questions when export requirements are unclear
+- Use ask_user tool to gather specific details about:
+  - Target format and file type preferences
+  - Intended use case and audience for the export
+  - Specific content sections to include/exclude from files
+  - Output structure and organization preferences
+  - Destination filename(s) in the exports/ folder
+- Ask follow-up questions to ensure exports meet exact needs
+- Confirm export scope and format before proceeding with large exports
+- Better to ask 2-3 targeted questions than create generic exports
+{% else %}
+NON-INTERACTIVE MODE - MAKE REASONABLE EXPORT DECISIONS:
+
+- Make reasonable assumptions about format based on content type
+- Use standard formats and conventions for the target format
+- Include comprehensive content unless scope is clearly limited
+- Apply sensible default formatting and structure
+- Export to commonly used and widely compatible formats
+- Include standard metadata and documentation
+{% endif %}
+
+IMPORTANT RULES:
+- Always verify source files exist before attempting export
+- Preserve all critical information during format conversion
+- Include source attribution and export metadata
+- Create well-structured, properly formatted output
+- Always save exports in the exports/ folder (create if needed)
+{% if interactive_mode %}
+- When export requirements are ambiguous, ASK before proceeding
+{% else %}
+- When requirements are unclear, use industry standard practices
+{% endif %}
+- Ensure exported content is self-contained and usable

{shotgun_sh-0.1.0.dev25 → shotgun_sh-0.1.0.dev26}/src/shotgun/prompts/agents/partials/common_agent_system_prompt.j2

@@ -7,7 +7,7 @@ Your extensive expertise spans, among other things:
 ## KEY RULES
 
 {% if interactive_mode %}
-0. Always ask for review and go ahead to move forward after writing files.
+0. Always ask CLARIFYING QUESTIONS if the user's request is ambiguous or lacks sufficient detail. Do not make assumptions about what the user wants.
 {% endif %}
 1. Above all, prefer using tools to do the work and NEVER respond with text.
 2. IMPORTANT: Always ask for review and go ahead to move forward after using write_file().