shotgun-sh 0.2.6.dev1__py3-none-any.whl → 0.2.17__py3-none-any.whl

shotgun/agents/context_analyzer/constants.py

@@ -0,0 +1,9 @@
+"""Tool category registry for context analysis.
+
+This module re-exports the tool registry functionality for backward compatibility.
+The actual implementation is in shotgun.agents.tools.registry.
+"""
+
+from shotgun.agents.tools.registry import ToolCategory, get_tool_category
+
+__all__ = ["ToolCategory", "get_tool_category"]

shotgun/agents/context_analyzer/formatter.py

@@ -0,0 +1,115 @@
+"""Format context analysis for various output types."""
+
+from typing import Any
+
+from .models import ContextAnalysis
+
+
+class ContextFormatter:
+    """Formats context analysis for various output types."""
+
+    @staticmethod
+    def format_markdown(analysis: ContextAnalysis) -> str:
+        """Format the analysis as markdown for display.
+
+        Args:
+            analysis: Context analysis to format
+
+        Returns:
+            Markdown-formatted string
+        """
+        lines = ["# Conversation Context Analysis", ""]
+
+        # Top-level summary with model and usage info
+        usage_percent = (
+            (analysis.agent_context_tokens / analysis.max_usable_tokens * 100)
+            if analysis.max_usable_tokens > 0
+            else 0
+        )
+        free_percent = (
+            (analysis.free_space_tokens / analysis.max_usable_tokens * 100)
+            if analysis.max_usable_tokens > 0
+            else 0
+        )
+
+        lines.extend(
+            [
+                f"Model: {analysis.model_name}",
+                "",
+                f"Total Context: {analysis.agent_context_tokens:,} / {analysis.max_usable_tokens:,} tokens ({usage_percent:.1f}%)",
+                "",
+                f"Free Space: {analysis.free_space_tokens:,} tokens ({free_percent:.1f}%)",
+                "",
+                "Autocompact Buffer: 500 tokens",
+                "",
+            ]
+        )
+
+        # Create 25-character visual bar showing proportional usage
+        # Each character represents 4% of total context
+        filled_chars = int(usage_percent / 4)
+        empty_chars = 25 - filled_chars
+        visual_bar = "●" * filled_chars + "○" * empty_chars
+
+        lines.extend(
+            [
+                "## Context Composition",
+                visual_bar,
+                "",
+            ]
+        )
+
+        # Add agent context categories only (hints are not part of agent context)
+        agent_categories = [
+            ("🧑 User Messages", analysis.user_messages),
+            ("🤖 Agent Responses", analysis.agent_responses),
+            ("📋 System Prompts", analysis.system_prompts),
+            ("📊 System Status", analysis.system_status),
+            ("🔍 Codebase Understanding", analysis.codebase_understanding),
+            ("📦 Artifact Management", analysis.artifact_management),
+            ("🌐 Web Research", analysis.web_research),
+        ]
+
+        # Only add unknown if it has content
+        if analysis.unknown.count > 0:
+            agent_categories.append(("⚠️  Unknown Tools", analysis.unknown))
+
+        for label, stats in agent_categories:
+            if stats.count > 0:
+                percentage = analysis.get_percentage(stats)
+                # Align labels to 30 characters for clean visual layout
+                lines.append(
+                    f"{label:<30} {percentage:>5.1f}%  ({stats.count} messages, ~{stats.tokens:,} tokens)"
+                )
+                # Add blank line to prevent Textual's Markdown widget from reflowing
+                lines.append("")
+
+        return "\n".join(lines)
+
+    @staticmethod
+    def format_json(analysis: ContextAnalysis) -> dict[str, Any]:
+        """Format the analysis as a JSON-serializable dictionary.
+
+        Args:
+            analysis: Context analysis to format
+
+        Returns:
+            Dictionary with context analysis data
+        """
+        # Use Pydantic's model_dump() to serialize the model
+        data = analysis.model_dump()
+
+        # Add computed summary field
+        data["summary"] = {
+            "total_messages": analysis.total_messages - analysis.hint_messages.count,
+            "agent_context_tokens": analysis.agent_context_tokens,
+            "context_window": analysis.context_window,
+            "usage_percentage": round(
+                (analysis.agent_context_tokens / analysis.context_window * 100)
+                if analysis.context_window > 0
+                else 0,
+                1,
+            ),
+        }
+
+        return data

shotgun/agents/context_analyzer/models.py

@@ -0,0 +1,212 @@
+"""Pydantic models for context analysis."""
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class TokenAllocation(BaseModel):
+    """Token counts allocated from API usage data by message/tool type.
+
+    Used internally by ContextAnalyzer to track token distribution across
+    different message types and tool categories.
+    """
+
+    user: int = Field(ge=0, default=0, description="Tokens from user prompts")
+    agent_responses: int = Field(
+        ge=0, default=0, description="Tokens from agent text responses"
+    )
+    system_prompts: int = Field(
+        ge=0, default=0, description="Tokens from system prompts"
+    )
+    system_status: int = Field(
+        ge=0, default=0, description="Tokens from system status messages"
+    )
+    codebase_understanding: int = Field(
+        ge=0, default=0, description="Tokens from codebase understanding tools"
+    )
+    artifact_management: int = Field(
+        ge=0, default=0, description="Tokens from artifact management tools"
+    )
+    web_research: int = Field(
+        ge=0, default=0, description="Tokens from web research tools"
+    )
+    unknown: int = Field(ge=0, default=0, description="Tokens from uncategorized tools")
+
+
+class MessageTypeStats(BaseModel):
+    """Statistics for a specific message type."""
+
+    count: int = Field(ge=0, description="Number of messages of this type")
+    tokens: int = Field(ge=0, description="Total tokens consumed by this type")
+
+    @property
+    def avg_tokens(self) -> float:
+        """Calculate average tokens per message."""
+        return self.tokens / self.count if self.count > 0 else 0.0
+
+
+class ContextAnalysis(BaseModel):
+    """Complete analysis of conversation context composition."""
+
+    user_messages: MessageTypeStats
+    agent_responses: MessageTypeStats
+    system_prompts: MessageTypeStats
+    system_status: MessageTypeStats
+    codebase_understanding: MessageTypeStats
+    artifact_management: MessageTypeStats
+    web_research: MessageTypeStats
+    unknown: MessageTypeStats
+    hint_messages: MessageTypeStats
+    total_tokens: int = Field(ge=0, description="Total tokens including hints")
+    total_messages: int = Field(ge=0, description="Total message count including hints")
+    context_window: int = Field(ge=0, description="Model's maximum input tokens")
+    agent_context_tokens: int = Field(
+        ge=0,
+        description="Tokens that actually consume agent context (excluding UI-only)",
+    )
+    model_name: str = Field(description="Name of the model being used")
+    max_usable_tokens: int = Field(
+        ge=0, description="80% of max_input_tokens (usable limit)"
+    )
+    free_space_tokens: int = Field(
+        description="Remaining tokens available (negative if over capacity)"
+    )
+
+    def get_percentage(self, stats: MessageTypeStats) -> float:
+        """Calculate percentage of agent context tokens for a message type.
+
+        Args:
+            stats: Message type statistics to calculate percentage for
+
+        Returns:
+            Percentage of total agent context tokens (0-100)
+        """
+        return (
+            (stats.tokens / self.agent_context_tokens * 100)
+            if self.agent_context_tokens > 0
+            else 0.0
+        )
+
+
+class ContextCompositionTelemetry(BaseModel):
+    """Telemetry data for context composition tracking to PostHog."""
+
+    # Context usage
+    total_messages: int = Field(ge=0)
+    agent_context_tokens: int = Field(ge=0)
+    context_window: int = Field(ge=0)
+    max_usable_tokens: int = Field(ge=0)
+    free_space_tokens: int = Field(ge=0)
+    usage_percentage: float = Field(ge=0, le=100)
+
+    # Message type counts
+    user_messages_count: int = Field(ge=0)
+    agent_responses_count: int = Field(ge=0)
+    system_prompts_count: int = Field(ge=0)
+    system_status_count: int = Field(ge=0)
+    codebase_understanding_count: int = Field(ge=0)
+    artifact_management_count: int = Field(ge=0)
+    web_research_count: int = Field(ge=0)
+    unknown_tools_count: int = Field(ge=0)
+
+    # Token distribution percentages
+    user_messages_pct: float = Field(ge=0, le=100)
+    agent_responses_pct: float = Field(ge=0, le=100)
+    system_prompts_pct: float = Field(ge=0, le=100)
+    system_status_pct: float = Field(ge=0, le=100)
+    codebase_understanding_pct: float = Field(ge=0, le=100)
+    artifact_management_pct: float = Field(ge=0, le=100)
+    web_research_pct: float = Field(ge=0, le=100)
+    unknown_tools_pct: float = Field(ge=0, le=100)
+
+    # Compaction info
+    compaction_occurred: bool
+    messages_before_compaction: int | None = None
+    messages_after_compaction: int | None = None
+    compaction_reduction_pct: float | None = None
+
+    @classmethod
+    def from_analysis(
+        cls,
+        analysis: "ContextAnalysis",
+        compaction_occurred: bool = False,
+        messages_before_compaction: int | None = None,
+    ) -> "ContextCompositionTelemetry":
+        """Create telemetry from context analysis.
+
+        Args:
+            analysis: The context analysis to convert
+            compaction_occurred: Whether message compaction occurred
+            messages_before_compaction: Number of messages before compaction
+
+        Returns:
+            ContextCompositionTelemetry instance
+        """
+        total_messages = analysis.total_messages - analysis.hint_messages.count
+        usage_pct = (
+            round((analysis.agent_context_tokens / analysis.max_usable_tokens * 100), 1)
+            if analysis.max_usable_tokens > 0
+            else 0
+        )
+
+        # Calculate compaction metrics
+        messages_after: int | None = None
+        compaction_reduction_pct: float | None = None
+
+        if compaction_occurred and messages_before_compaction is not None:
+            messages_after = total_messages
+            if messages_before_compaction > 0:
+                compaction_reduction_pct = round(
+                    (1 - (total_messages / messages_before_compaction)) * 100, 1
+                )
+
+        return cls(
+            # Context usage
+            total_messages=total_messages,
+            agent_context_tokens=analysis.agent_context_tokens,
+            context_window=analysis.context_window,
+            max_usable_tokens=analysis.max_usable_tokens,
+            free_space_tokens=analysis.free_space_tokens,
+            usage_percentage=usage_pct,
+            # Message type counts
+            user_messages_count=analysis.user_messages.count,
+            agent_responses_count=analysis.agent_responses.count,
+            system_prompts_count=analysis.system_prompts.count,
+            system_status_count=analysis.system_status.count,
+            codebase_understanding_count=analysis.codebase_understanding.count,
+            artifact_management_count=analysis.artifact_management.count,
+            web_research_count=analysis.web_research.count,
+            unknown_tools_count=analysis.unknown.count,
+            # Token distribution percentages
+            user_messages_pct=round(analysis.get_percentage(analysis.user_messages), 1),
+            agent_responses_pct=round(
+                analysis.get_percentage(analysis.agent_responses), 1
+            ),
+            system_prompts_pct=round(
+                analysis.get_percentage(analysis.system_prompts), 1
+            ),
+            system_status_pct=round(analysis.get_percentage(analysis.system_status), 1),
+            codebase_understanding_pct=round(
+                analysis.get_percentage(analysis.codebase_understanding), 1
+            ),
+            artifact_management_pct=round(
+                analysis.get_percentage(analysis.artifact_management), 1
+            ),
+            web_research_pct=round(analysis.get_percentage(analysis.web_research), 1),
+            unknown_tools_pct=round(analysis.get_percentage(analysis.unknown), 1),
+            # Compaction info
+            compaction_occurred=compaction_occurred,
+            messages_before_compaction=messages_before_compaction,
+            messages_after_compaction=messages_after,
+            compaction_reduction_pct=compaction_reduction_pct,
+        )
+
+
+class ContextAnalysisOutput(BaseModel):
+    """Output format for context analysis with multiple representations."""
+
+    markdown: str = Field(description="Markdown-formatted analysis for display")
+    json_data: dict[str, Any] = Field(
+        description="JSON representation of analysis data"
+    )

shotgun/agents/conversation_history.py

@@ -1,5 +1,7 @@
 """Models and utilities for persisting TUI conversation history."""
 
+import json
+import logging
 from datetime import datetime
 from typing import Any, cast
 
@@ -7,14 +9,108 @@ from pydantic import BaseModel, ConfigDict, Field
 from pydantic_ai.messages import (
     ModelMessage,
     ModelMessagesTypeAdapter,
+    ModelResponse,
+    ToolCallPart,
 )
 from pydantic_core import to_jsonable_python
 
 from shotgun.tui.screens.chat_screen.hint_message import HintMessage
 
+__all__ = ["HintMessage", "ConversationHistory"]
+
+logger = logging.getLogger(__name__)
+
 SerializedMessage = dict[str, Any]
 
 
+def is_tool_call_complete(tool_call: ToolCallPart) -> bool:
+    """Check if a tool call has valid, complete JSON arguments.
+
+    Args:
+        tool_call: The tool call part to validate
+
+    Returns:
+        True if the tool call args are valid JSON, False otherwise
+    """
+    if tool_call.args is None:
+        return True  # No args is valid
+
+    if isinstance(tool_call.args, dict):
+        return True  # Already parsed dict is valid
+
+    if not isinstance(tool_call.args, str):
+        return False
+
+    # Try to parse the JSON string
+    try:
+        json.loads(tool_call.args)
+        return True
+    except (json.JSONDecodeError, ValueError) as e:
+        # Log incomplete tool call detection
+        args_preview = (
+            tool_call.args[:100] + "..."
+            if len(tool_call.args) > 100
+            else tool_call.args
+        )
+        logger.info(
+            "Detected incomplete tool call in validation",
+            extra={
+                "tool_name": tool_call.tool_name,
+                "tool_call_id": tool_call.tool_call_id,
+                "args_preview": args_preview,
+                "error": str(e),
+            },
+        )
+        return False
+
+
+def filter_incomplete_messages(messages: list[ModelMessage]) -> list[ModelMessage]:
+    """Filter out messages with incomplete tool calls.
+
+    Args:
+        messages: List of messages to filter
+
+    Returns:
+        List of messages with only complete tool calls
+    """
+    filtered: list[ModelMessage] = []
+    filtered_count = 0
+    filtered_tool_names: list[str] = []
+
+    for message in messages:
+        # Only check ModelResponse messages for tool calls
+        if not isinstance(message, ModelResponse):
+            filtered.append(message)
+            continue
+
+        # Check if any tool calls are incomplete
+        has_incomplete_tool_call = False
+        for part in message.parts:
+            if isinstance(part, ToolCallPart) and not is_tool_call_complete(part):
+                has_incomplete_tool_call = True
+                filtered_tool_names.append(part.tool_name)
+                break
+
+        # Only include messages without incomplete tool calls
+        if not has_incomplete_tool_call:
+            filtered.append(message)
+        else:
+            filtered_count += 1
+
+    # Log if any messages were filtered
+    if filtered_count > 0:
+        logger.info(
+            "Filtered incomplete messages before saving",
+            extra={
+                "filtered_count": filtered_count,
+                "total_messages": len(messages),
+                "filtered_tool_names": filtered_tool_names,
+            },
+        )
+
+    return filtered
+
+
 class ConversationState(BaseModel):
     """Represents the complete state of a conversation in memory."""
 
@@ -46,14 +142,41 @@ class ConversationHistory(BaseModel):
         Args:
             messages: List of ModelMessage objects to serialize and store
         """
+        # Filter out messages with incomplete tool calls to prevent corruption
+        filtered_messages = filter_incomplete_messages(messages)
+
         # Serialize ModelMessage list to JSON-serializable format
         self.agent_history = to_jsonable_python(
-            messages, fallback=lambda x: str(x), exclude_none=True
+            filtered_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."""
 
+        # Filter out ModelMessages with incomplete tool calls (keep all HintMessages)
+        # We need to maintain message order, so we'll check each message individually
+        filtered_messages: list[ModelMessage | HintMessage] = []
+
+        for msg in messages:
+            if isinstance(msg, HintMessage):
+                # Always keep hint messages
+                filtered_messages.append(msg)
+            elif isinstance(msg, ModelResponse):
+                # Check if this ModelResponse has incomplete tool calls
+                has_incomplete = False
+                for part in msg.parts:
+                    if isinstance(part, ToolCallPart) and not is_tool_call_complete(
+                        part
+                    ):
+                        has_incomplete = True
+                        break
+
+                if not has_incomplete:
+                    filtered_messages.append(msg)
+            else:
+                # Keep all other ModelMessage types (ModelRequest, etc.)
+                filtered_messages.append(msg)
+
         def _serialize_message(
             message: ModelMessage | HintMessage,
         ) -> Any:
@@ -68,7 +191,7 @@ class ConversationHistory(BaseModel):
                 payload.setdefault("message_type", "model")
             return payload
 
-        self.ui_history = [_serialize_message(msg) for msg in messages]
+        self.ui_history = [_serialize_message(msg) for msg in filtered_messages]
 
     def get_agent_messages(self) -> list[ModelMessage]:
         """Get agent_history as a list of ModelMessage objects.

shotgun/agents/conversation_manager.py

@@ -1,10 +1,15 @@
 """Manager for handling conversation persistence operations."""
 
+import asyncio
 import json
 from pathlib import Path
 
+import aiofiles
+import aiofiles.os
+
 from shotgun.logging_config import get_logger
 from shotgun.utils import get_shotgun_home
+from shotgun.utils.file_system_utils import async_copy_file
 
 from .conversation_history import ConversationHistory
 
@@ -26,14 +31,14 @@ class ConversationManager:
         else:
             self.conversation_path = conversation_path
 
-    def save(self, conversation: ConversationHistory) -> None:
+    async def save(self, conversation: ConversationHistory) -> None:
         """Save conversation history to file.
 
         Args:
             conversation: ConversationHistory to save
         """
         # Ensure directory exists
-        self.conversation_path.parent.mkdir(parents=True, exist_ok=True)
+        await aiofiles.os.makedirs(self.conversation_path.parent, exist_ok=True)
 
         try:
             # Update timestamp
@@ -41,11 +46,17 @@ class ConversationManager:
 
             conversation.updated_at = datetime.now()
 
-            # Serialize to JSON using Pydantic's model_dump
-            data = conversation.model_dump(mode="json")
+            # 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
+            )
 
-            with open(self.conversation_path, "w", encoding="utf-8") as f:
-                json.dump(data, f, indent=2, ensure_ascii=False)
+            async with aiofiles.open(
+                self.conversation_path, "w", encoding="utf-8"
+            ) as f:
+                await f.write(json_content)
 
             logger.debug("Conversation saved to %s", self.conversation_path)
 
@@ -55,21 +66,26 @@ class ConversationManager:
             )
             # Don't raise - we don't want to interrupt the user's session
 
-    def load(self) -> ConversationHistory | None:
+    async def load(self) -> ConversationHistory | None:
         """Load conversation history from file.
 
         Returns:
             ConversationHistory if file exists and is valid, None otherwise
         """
-        if not self.conversation_path.exists():
+        if not await aiofiles.os.path.exists(self.conversation_path):
             logger.debug("No conversation history found at %s", self.conversation_path)
             return None
 
         try:
-            with open(self.conversation_path, encoding="utf-8") as f:
-                data = json.load(f)
-
-            conversation = ConversationHistory.model_validate(data)
+            async with aiofiles.open(self.conversation_path, encoding="utf-8") as f:
+                content = await f.read()
+                # Deserialize JSON in background thread to avoid blocking
+                data = await asyncio.to_thread(json.loads, content)
+
+            # 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,
@@ -77,17 +93,39 @@ class ConversationManager:
             )
             return conversation
 
-        except Exception as e:
+        except (json.JSONDecodeError, ValueError) as e:
+            # Handle corrupted JSON or validation errors
+            logger.error(
+                "Corrupted conversation file at %s: %s. Creating backup and starting fresh.",
+                self.conversation_path,
+                e,
+            )
+
+            # Create a backup of the corrupted file for debugging
+            backup_path = self.conversation_path.with_suffix(".json.backup")
+            try:
+                await async_copy_file(self.conversation_path, backup_path)
+                logger.info("Backed up corrupted conversation to %s", backup_path)
+            except Exception as backup_error:  # pragma: no cover
+                logger.warning("Failed to backup corrupted file: %s", backup_error)
+
+            return None
+
+        except Exception as e:  # pragma: no cover
+            # Catch-all for unexpected errors
             logger.error(
-                "Failed to load conversation from %s: %s", self.conversation_path, e
+                "Unexpected error loading conversation from %s: %s",
+                self.conversation_path,
+                e,
             )
             return None
 
-    def clear(self) -> None:
+    async def clear(self) -> None:
         """Delete the conversation history file."""
-        if self.conversation_path.exists():
+        if await aiofiles.os.path.exists(self.conversation_path):
             try:
-                self.conversation_path.unlink()
+                # Use asyncio.to_thread for unlink operation
+                await asyncio.to_thread(self.conversation_path.unlink)
                 logger.debug(
                     "Conversation history cleared at %s", self.conversation_path
                 )
@@ -96,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))