shotgun-sh 0.2.11.dev3__py3-none-any.whl → 0.2.11.dev7__py3-none-any.whl

shotgun/agents/agent_manager.py

@@ -58,7 +58,12 @@ from shotgun.agents.context_analyzer import (
     ContextCompositionTelemetry,
     ContextFormatter,
 )
-from shotgun.agents.models import AgentResponse, AgentType, FileOperation
+from shotgun.agents.models import (
+    AgentResponse,
+    AgentType,
+    FileOperation,
+    FileOperationTracker,
+)
 from shotgun.posthog_telemetry import track_event
 from shotgun.tui.screens.chat_screen.hint_message import HintMessage
 from shotgun.utils.source_detection import detect_source
@@ -769,6 +774,12 @@ class AgentManager(Widget):
                     HintMessage(message=agent_response.response)
                 )
 
+            # Add file operation hints before questions (so they appear first in UI)
+            if file_operations:
+                file_hint = self._create_file_operation_hint(file_operations)
+                if file_hint:
+                    self.ui_message_history.append(HintMessage(message=file_hint))
+
             if len(agent_response.clarifying_questions) == 1:
                 # Single question - treat as non-blocking suggestion, DON'T enter Q&A mode
                 self.ui_message_history.append(
@@ -1134,6 +1145,38 @@ class AgentManager(Widget):
             )
         )
 
+    def _create_file_operation_hint(
+        self, file_operations: list[FileOperation]
+    ) -> str | None:
+        """Create a hint message for file operations.
+
+        Args:
+            file_operations: List of file operations to create a hint for
+
+        Returns:
+            Hint message string or None if no operations
+        """
+        if not file_operations:
+            return None
+
+        tracker = FileOperationTracker(operations=file_operations)
+        display_path = tracker.get_display_path()
+
+        if not display_path:
+            return None
+
+        path_obj = Path(display_path)
+
+        if len(file_operations) == 1:
+            return f"📝 Modified: `{display_path}`"
+        else:
+            num_files = len({op.file_path for op in file_operations})
+            if path_obj.is_dir():
+                return f"📁 Modified {num_files} files in: `{display_path}`"
+            else:
+                # Common path is a file, show parent directory
+                return f"📁 Modified {num_files} files in: `{path_obj.parent}`"
+
     def _post_messages_updated(
         self, file_operations: list[FileOperation] | None = None
     ) -> None:

shotgun/agents/config/models.py

@@ -205,6 +205,10 @@ class ShotgunConfig(BaseModel):
         default=False,
         description="Whether the welcome screen has been shown to the user",
     )
+    shown_onboarding_popup: datetime | None = Field(
+        default=None,
+        description="Timestamp when the onboarding popup was shown to the user (ISO8601 format)",
+    )
     marketing: MarketingConfig = Field(
         default_factory=MarketingConfig,
         description="Marketing messages configuration and tracking",

shotgun/agents/conversation_manager.py

@@ -46,9 +46,12 @@ class ConversationManager:
 
             conversation.updated_at = datetime.now()
 
-            # Serialize to JSON using Pydantic's model_dump
-            data = conversation.model_dump(mode="json")
-            json_content = json.dumps(data, indent=2, ensure_ascii=False)
+            # Serialize to JSON in background thread to avoid blocking event loop
+            # This is crucial for large conversations (5k+ tokens)
+            data = await asyncio.to_thread(conversation.model_dump, mode="json")
+            json_content = await asyncio.to_thread(
+                json.dumps, data, indent=2, ensure_ascii=False
+            )
 
             async with aiofiles.open(
                 self.conversation_path, "w", encoding="utf-8"
@@ -76,9 +79,13 @@ class ConversationManager:
         try:
             async with aiofiles.open(self.conversation_path, encoding="utf-8") as f:
                 content = await f.read()
-                data = json.loads(content)
+                # Deserialize JSON in background thread to avoid blocking
+                data = await asyncio.to_thread(json.loads, content)
 
-            conversation = ConversationHistory.model_validate(data)
+            # Validate model in background thread for large conversations
+            conversation = await asyncio.to_thread(
+                ConversationHistory.model_validate, data
+            )
             logger.debug(
                 "Conversation loaded from %s with %d agent messages",
                 self.conversation_path,
@@ -127,10 +134,10 @@ class ConversationManager:
                     "Failed to clear conversation at %s: %s", self.conversation_path, e
                 )
 
-    def exists(self) -> bool:
+    async def exists(self) -> bool:
         """Check if a conversation history file exists.
 
         Returns:
             True if conversation file exists, False otherwise
         """
-        return self.conversation_path.exists()
+        return await aiofiles.os.path.exists(str(self.conversation_path))

shotgun/agents/history/history_processors.py

@@ -1,7 +1,9 @@
 """History processors for managing conversation history in Shotgun agents."""
 
+from collections.abc import Awaitable, Callable
 from typing import TYPE_CHECKING, Any, Protocol
 
+from anthropic import APIStatusError
 from pydantic_ai import ModelSettings
 from pydantic_ai.messages import (
     ModelMessage,
@@ -14,6 +16,7 @@ from pydantic_ai.messages import (
 from shotgun.agents.llm import shotgun_model_request
 from shotgun.agents.messages import AgentSystemPrompt, SystemStatusPrompt
 from shotgun.agents.models import AgentDeps
+from shotgun.exceptions import ContextSizeLimitExceeded
 from shotgun.logging_config import get_logger
 from shotgun.posthog_telemetry import track_event
 from shotgun.prompts import PromptLoader
@@ -51,6 +54,86 @@ logger = get_logger(__name__)
 prompt_loader = PromptLoader()
 
 
+async def _safe_token_estimation(
+    estimation_func: Callable[..., Awaitable[int]],
+    model_name: str,
+    max_tokens: int,
+    *args: Any,
+    **kwargs: Any,
+) -> int:
+    """Safely estimate tokens with proper error handling.
+
+    Wraps token estimation functions to handle failures gracefully.
+    Only RuntimeError (from token counters) is wrapped in ContextSizeLimitExceeded.
+    Other errors (network, auth) are allowed to bubble up.
+
+    Args:
+        estimation_func: Async function that estimates tokens
+        model_name: Name of the model for error messages
+        max_tokens: Maximum tokens for the model
+        *args: Arguments to pass to estimation_func
+        **kwargs: Keyword arguments to pass to estimation_func
+
+    Returns:
+        Token count from estimation_func
+
+    Raises:
+        ContextSizeLimitExceeded: If token counting fails with RuntimeError
+        Exception: Any other exceptions from estimation_func
+    """
+    try:
+        return await estimation_func(*args, **kwargs)
+    except Exception as e:
+        # Log the error with full context
+        logger.warning(
+            f"Token counting failed for {model_name}",
+            extra={
+                "error_type": type(e).__name__,
+                "error_message": str(e),
+                "model": model_name,
+            },
+        )
+
+        # Token counting behavior with oversized context (verified via testing):
+        #
+        # 1. OpenAI/tiktoken:
+        #    - Successfully counts any size (tested with 752K tokens, no error)
+        #    - Library errors: ValueError, KeyError, AttributeError, SSLError (file/cache issues)
+        #    - Wrapped as: RuntimeError by our counter
+        #
+        # 2. Gemini/SentencePiece:
+        #    - Successfully counts any size (tested with 752K tokens, no error)
+        #    - Library errors: RuntimeError, IOError, TypeError (file/model loading issues)
+        #    - Wrapped as: RuntimeError by our counter
+        #
+        # 3. Anthropic API:
+        #    - Successfully counts large token counts (tested with 752K tokens, no error)
+        #    - Only enforces 32 MB request size limit (not token count)
+        #    - Raises: APIStatusError(413) with error type 'request_too_large' for 32MB+ requests
+        #    - Other API errors: APIConnectionError, RateLimitError, APIStatusError (4xx/5xx)
+        #    - Wrapped as: RuntimeError by our counter
+        #
+        # IMPORTANT: No provider raises errors for "too many tokens" during counting.
+        # Token count validation happens separately by comparing count to max_input_tokens.
+        #
+        # We wrap RuntimeError (library-level failures from tiktoken/sentencepiece).
+        # We also wrap Anthropic's 413 error (request exceeds 32 MB) as it indicates
+        # context is effectively too large and needs user action to reduce it.
+        if isinstance(e, RuntimeError):
+            raise ContextSizeLimitExceeded(
+                model_name=model_name, max_tokens=max_tokens
+            ) from e
+
+        # Check for Anthropic's 32 MB request size limit (APIStatusError with status 413)
+        if isinstance(e, APIStatusError) and e.status_code == 413:
+            raise ContextSizeLimitExceeded(
+                model_name=model_name, max_tokens=max_tokens
+            ) from e
+
+        # Re-raise other exceptions (network errors, auth failures, etc.)
+        raise
+
+
 def is_summary_part(part: Any) -> bool:
     """Check if a message part is a compacted summary."""
     return isinstance(part, TextPart) and part.content.startswith(SUMMARY_MARKER)
@@ -157,9 +240,15 @@ async def token_limit_compactor(
 
     if last_summary_index is not None:
         # Check if post-summary conversation exceeds threshold for incremental compaction
-        post_summary_tokens = await estimate_post_summary_tokens(
-            messages, last_summary_index, deps.llm_model
+        post_summary_tokens = await _safe_token_estimation(
+            estimate_post_summary_tokens,
+            deps.llm_model.name,
+            model_max_tokens,
+            messages,
+            last_summary_index,
+            deps.llm_model,
         )
+
         post_summary_percentage = (
             (post_summary_tokens / max_tokens) * 100 if max_tokens > 0 else 0
         )
@@ -366,7 +455,14 @@ async def token_limit_compactor(
 
     else:
         # Check if total conversation exceeds threshold for full compaction
-        total_tokens = await estimate_tokens_from_messages(messages, deps.llm_model)
+        total_tokens = await _safe_token_estimation(
+            estimate_tokens_from_messages,
+            deps.llm_model.name,
+            model_max_tokens,
+            messages,
+            deps.llm_model,
+        )
+
         total_percentage = (total_tokens / max_tokens) * 100 if max_tokens > 0 else 0
 
         logger.debug(

shotgun/agents/history/token_counting/openai.py

@@ -63,7 +63,9 @@ class OpenAITokenCounter(TokenCounter):
 
         try:
             return len(self.encoding.encode(text))
-        except Exception as e:
+        except BaseException as e:
+            # Must catch BaseException to handle PanicException from tiktoken's Rust layer
+            # which can occur with extremely long texts. Regular Exception won't catch it.
             raise RuntimeError(
                 f"Failed to count tokens for OpenAI model {self.model_name}"
             ) from e

shotgun/exceptions.py

@@ -0,0 +1,32 @@
+"""General exceptions for Shotgun application."""
+
+
+class ErrorNotPickedUpBySentry(Exception):  # noqa: N818
+    """Base for user-actionable errors that shouldn't be sent to Sentry.
+
+    These errors represent expected user conditions requiring action
+    rather than bugs that need tracking.
+    """
+
+
+class ContextSizeLimitExceeded(ErrorNotPickedUpBySentry):
+    """Raised when conversation context exceeds the model's limits.
+
+    This is a user-actionable error - they need to either:
+    1. Switch to a larger context model
+    2. Switch to a larger model, compact their conversation, then switch back
+    3. Clear the conversation and start fresh
+    """
+
+    def __init__(self, model_name: str, max_tokens: int):
+        """Initialize the exception.
+
+        Args:
+            model_name: Name of the model whose limit was exceeded
+            max_tokens: Maximum tokens allowed by the model
+        """
+        self.model_name = model_name
+        self.max_tokens = max_tokens
+        super().__init__(
+            f"Context too large for {model_name} (limit: {max_tokens:,} tokens)"
+        )

shotgun/sentry_telemetry.py

@@ -1,5 +1,7 @@
 """Sentry observability setup for Shotgun."""
 
+from typing import Any
+
 from shotgun import __version__
 from shotgun.logging_config import get_early_logger
 from shotgun.settings import settings
@@ -32,12 +34,27 @@ def setup_sentry_observability() -> bool:
         logger.debug("Using Sentry DSN from settings, proceeding with setup")
 
         # Determine environment based on version
-        # Dev versions contain "dev", "rc", "alpha", or "beta"
+        # Dev versions contain "dev", "rc", "alpha", "beta"
         if any(marker in __version__ for marker in ["dev", "rc", "alpha", "beta"]):
             environment = "development"
         else:
             environment = "production"
 
+        def before_send(event: Any, hint: dict[str, Any]) -> Any:
+            """Filter out user-actionable errors from Sentry.
+
+            User-actionable errors (like context size limits) are expected conditions
+            that users need to resolve, not bugs that need tracking.
+            """
+            if "exc_info" in hint:
+                exc_type, exc_value, tb = hint["exc_info"]
+                from shotgun.exceptions import ErrorNotPickedUpBySentry
+
+                if isinstance(exc_value, ErrorNotPickedUpBySentry):
+                    # Don't send to Sentry - this is user-actionable, not a bug
+                    return None
+            return event
+
         # Initialize Sentry
         sentry_sdk.init(
             dsn=dsn,
@@ -46,6 +63,7 @@ def setup_sentry_observability() -> bool:
             send_default_pii=False,  # Privacy-first: never send PII
             traces_sample_rate=0.1 if environment == "production" else 1.0,
             profiles_sample_rate=0.1 if environment == "production" else 1.0,
+            before_send=before_send,
         )
 
         # Set user context with anonymous shotgun instance ID from config

shotgun/tui/app.py

@@ -19,7 +19,7 @@ from shotgun.utils.update_checker import (
 
 from .screens.chat import ChatScreen
 from .screens.directory_setup import DirectorySetupScreen
-from .screens.feedback import FeedbackScreen
+from .screens.github_issue import GitHubIssueScreen
 from .screens.model_picker import ModelPickerScreen
 from .screens.pipx_migration import PipxMigrationScreen
 from .screens.provider_config import ProviderConfigScreen
@@ -35,7 +35,7 @@ class ShotgunApp(App[None]):
         "provider_config": ProviderConfigScreen,
         "model_picker": ModelPickerScreen,
         "directory_setup": DirectorySetupScreen,
-        "feedback": FeedbackScreen,
+        "github_issue": GitHubIssueScreen,
     }
     BINDINGS = [
         Binding("ctrl+c", "quit", "Quit the app"),
@@ -181,20 +181,15 @@ class ShotgunApp(App[None]):
     def get_system_commands(self, screen: Screen[Any]) -> Iterable[SystemCommand]:
         return [
             SystemCommand(
-                "Feedback", "Send us feedback or report a bug", self.action_feedback
+                "New Issue",
+                "Report a bug or request a feature on GitHub",
+                self.action_new_issue,
             )
-        ]  # we don't want any system commands
+        ]
 
-    def action_feedback(self) -> None:
-        """Open feedback screen and submit feedback."""
-        from shotgun.posthog_telemetry import Feedback, submit_feedback_survey
-
-        def handle_feedback(feedback: Feedback | None) -> None:
-            if feedback is not None:
-                submit_feedback_survey(feedback)
-                self.notify("Feedback sent. Thank you!")
-
-        self.push_screen(FeedbackScreen(), callback=handle_feedback)
+    def action_new_issue(self) -> None:
+        """Open GitHub issue screen to guide users to create an issue."""
+        self.push_screen(GitHubIssueScreen())
 
 
 def run(

shotgun/tui/screens/chat/chat_screen.py

@@ -2,6 +2,7 @@
 
 import asyncio
 import logging
+from datetime import datetime, timezone
 from pathlib import Path
 from typing import cast
 
@@ -31,6 +32,7 @@ from shotgun.agents.agent_manager import (
     ModelConfigUpdated,
     PartialResponseMessage,
 )
+from shotgun.agents.config import get_config_manager
 from shotgun.agents.config.models import MODEL_SPECS
 from shotgun.agents.conversation_manager import ConversationManager
 from shotgun.agents.history.compaction import apply_persistent_compaction
@@ -45,6 +47,7 @@ from shotgun.codebase.core.manager import (
     CodebaseGraphManager,
 )
 from shotgun.codebase.models import IndexProgress, ProgressPhase
+from shotgun.exceptions import ContextSizeLimitExceeded
 from shotgun.posthog_telemetry import track_event
 from shotgun.sdk.codebase import CodebaseSDK
 from shotgun.sdk.exceptions import CodebaseNotFoundError, InvalidPathError
@@ -70,6 +73,7 @@ from shotgun.tui.screens.chat_screen.command_providers import (
 from shotgun.tui.screens.chat_screen.hint_message import HintMessage
 from shotgun.tui.screens.chat_screen.history import ChatHistory
 from shotgun.tui.screens.confirmation_dialog import ConfirmationDialog
+from shotgun.tui.screens.onboarding import OnboardingModal
 from shotgun.tui.services.conversation_service import ConversationService
 from shotgun.tui.state.processing_state import ProcessingStateManager
 from shotgun.tui.utils.mode_progress import PlaceholderHints
@@ -166,13 +170,17 @@ class ChatScreen(Screen[None]):
         self.processing_state.bind_spinner(self.query_one("#spinner", Spinner))
 
         # Load conversation history if --continue flag was provided
-        if self.continue_session and self.conversation_manager.exists():
-            self._load_conversation()
+        # Use call_later to handle async exists() check
+        if self.continue_session:
+            self.call_later(self._check_and_load_conversation)
 
         self.call_later(self.check_if_codebase_is_indexed)
         # Initial update of context indicator
         self.update_context_indicator()
 
+        # Show onboarding popup if not shown before
+        self.call_later(self._check_and_show_onboarding)
+
     async def on_key(self, event: events.Key) -> None:
         """Handle key presses for cancellation."""
         # If escape is pressed during Q&A mode, exit Q&A
@@ -305,6 +313,10 @@ class ChatScreen(Screen[None]):
         else:
             self.notify("No context analysis available", severity="error")
 
+    def action_view_onboarding(self) -> None:
+        """Show the onboarding modal."""
+        self.app.push_screen(OnboardingModal())
+
     @work
     async def action_compact_conversation(self) -> None:
         """Compact the conversation history to reduce size."""
@@ -456,7 +468,7 @@ class ChatScreen(Screen[None]):
             self.agent_manager.ui_message_history = []
 
             # Use conversation service to clear conversation
-            self.conversation_service.clear_conversation()
+            await self.conversation_service.clear_conversation()
 
             # Post message history updated event to refresh UI
             self.agent_manager.post_message(
@@ -655,32 +667,42 @@ class ChatScreen(Screen[None]):
         self.update_context_indicator()
 
         # If there are file operations, add a message showing the modified files
+        # Skip if hint was already added by agent_manager (e.g., in QA mode)
         if event.file_operations:
-            chat_history = self.query_one(ChatHistory)
-            if chat_history.vertical_tail:
-                tracker = FileOperationTracker(operations=event.file_operations)
-                display_path = tracker.get_display_path()
-
-                if display_path:
-                    # Create a simple markdown message with the file path
-                    # The terminal emulator will make this clickable automatically
-                    path_obj = Path(display_path)
-
-                    if len(event.file_operations) == 1:
-                        message = f"📝 Modified: `{display_path}`"
-                    else:
-                        num_files = len({op.file_path for op in event.file_operations})
-                        if path_obj.is_dir():
-                            message = (
-                                f"📁 Modified {num_files} files in: `{display_path}`"
-                            )
+            # Check if file operation hint already exists in recent messages
+            file_hint_exists = any(
+                isinstance(msg, HintMessage)
+                and (
+                    msg.message.startswith("📝 Modified:")
+                    or msg.message.startswith("📁 Modified")
+                )
+                for msg in event.messages[-5:]  # Check last 5 messages
+            )
+
+            if not file_hint_exists:
+                chat_history = self.query_one(ChatHistory)
+                if chat_history.vertical_tail:
+                    tracker = FileOperationTracker(operations=event.file_operations)
+                    display_path = tracker.get_display_path()
+
+                    if display_path:
+                        # Create a simple markdown message with the file path
+                        # The terminal emulator will make this clickable automatically
+                        path_obj = Path(display_path)
+
+                        if len(event.file_operations) == 1:
+                            message = f"📝 Modified: `{display_path}`"
                         else:
-                            # Common path is a file, show parent directory
-                            message = (
-                                f"📁 Modified {num_files} files in: `{path_obj.parent}`"
+                            num_files = len(
+                                {op.file_path for op in event.file_operations}
                             )
+                            if path_obj.is_dir():
+                                message = f"📁 Modified {num_files} files in: `{display_path}`"
+                            else:
+                                # Common path is a file, show parent directory
+                                message = f"📁 Modified {num_files} files in: `{path_obj.parent}`"
 
-                    self.mount_hint(message)
+                        self.mount_hint(message)
 
                     # Check and display any marketing messages
                     from shotgun.tui.app import ShotgunApp
@@ -1106,6 +1128,27 @@ class ChatScreen(Screen[None]):
         except asyncio.CancelledError:
             # Handle cancellation gracefully - DO NOT re-raise
             self.mount_hint("⚠️ Operation cancelled by user")
+        except ContextSizeLimitExceeded as e:
+            # User-friendly error with actionable options
+            hint = (
+                f"⚠️ **Context too large for {e.model_name}**\n\n"
+                f"Your conversation history exceeds this model's limit ({e.max_tokens:,} tokens).\n\n"
+                f"**Choose an action:**\n\n"
+                f"1. Switch to a larger model (`Ctrl+P` → Change Model)\n"
+                f"2. Switch to a larger model, compact (`/compact`), then switch back to {e.model_name}\n"
+                f"3. Clear conversation (`/clear`)\n"
+            )
+
+            self.mount_hint(hint)
+
+            # Log for debugging (won't send to Sentry due to ErrorNotPickedUpBySentry)
+            logger.info(
+                "Context size limit exceeded",
+                extra={
+                    "max_tokens": e.max_tokens,
+                    "model_name": e.model_name,
+                },
+            )
         except Exception as e:
             # Log with full stack trace to shotgun.log
             logger.exception(
@@ -1143,11 +1186,17 @@ class ChatScreen(Screen[None]):
     def _save_conversation(self) -> None:
         """Save the current conversation to persistent storage."""
         # Use conversation service for saving (run async in background)
+        # Use exclusive=True to prevent concurrent saves that can cause file contention
         self.run_worker(
             self.conversation_service.save_conversation(self.agent_manager),
-            exclusive=False,
+            exclusive=True,
         )
 
+    async def _check_and_load_conversation(self) -> None:
+        """Check if conversation exists and load it if it does."""
+        if await self.conversation_manager.exists():
+            self._load_conversation()
+
     def _load_conversation(self) -> None:
         """Load conversation from persistent storage."""
 
@@ -1168,3 +1217,18 @@ class ChatScreen(Screen[None]):
                 self.mode = restored_type
 
         self.run_worker(_do_load(), exclusive=False)
+
+    @work
+    async def _check_and_show_onboarding(self) -> None:
+        """Check if onboarding should be shown and display modal if needed."""
+        config_manager = get_config_manager()
+        config = await config_manager.load()
+
+        # Only show onboarding if it hasn't been shown before
+        if config.shown_onboarding_popup is None:
+            # Show the onboarding modal
+            await self.app.push_screen_wait(OnboardingModal())
+
+            # Mark as shown in config with current timestamp
+            config.shown_onboarding_popup = datetime.now(timezone.utc)
+            await config_manager.save(config)

shotgun/tui/screens/chat_screen/command_providers.py

@@ -369,6 +369,11 @@ class UnifiedCommandProvider(Provider):
             self.chat_screen.action_show_usage,
             help="Display usage information for the current session",
         )
+        yield DiscoveryHit(
+            "View Onboarding",
+            self.chat_screen.action_view_onboarding,
+            help="View the onboarding tutorial and helpful resources",
+        )
 
     async def search(self, query: str) -> AsyncGenerator[Hit, None]:
         """Search for commands in alphabetical order."""
@@ -416,6 +421,11 @@ class UnifiedCommandProvider(Provider):
                 self.chat_screen.action_show_usage,
                 "Display usage information for the current session",
             ),
+            (
+                "View Onboarding",
+                self.chat_screen.action_view_onboarding,
+                "View the onboarding tutorial and helpful resources",
+            ),
         ]
 
         for title, callback, help_text in commands: