shotgun-sh 0.4.0.dev1__py3-none-any.whl → 0.6.2__py3-none-any.whl

shotgun/agents/config/models.py

@@ -26,10 +26,8 @@ class ModelName(StrEnum):
     """Available AI model names."""
 
     GPT_5_1 = "gpt-5.1"
-    GPT_5_1_CODEX = "gpt-5.1-codex"
-    GPT_5_1_CODEX_MINI = "gpt-5.1-codex-mini"
+    GPT_5_2 = "gpt-5.2"
     CLAUDE_OPUS_4_5 = "claude-opus-4-5"
-    CLAUDE_SONNET_4 = "claude-sonnet-4"
     CLAUDE_SONNET_4_5 = "claude-sonnet-4-5"
     CLAUDE_HAIKU_4_5 = "claude-haiku-4-5"
     GEMINI_2_5_PRO = "gemini-2.5-pro"
@@ -110,21 +108,13 @@ MODEL_SPECS: dict[ModelName, ModelSpec] = {
         litellm_proxy_model_name="openai/gpt-5.1",
         short_name="GPT-5.1",
     ),
-    ModelName.GPT_5_1_CODEX: ModelSpec(
-        name=ModelName.GPT_5_1_CODEX,
+    ModelName.GPT_5_2: ModelSpec(
+        name=ModelName.GPT_5_2,
         provider=ProviderType.OPENAI,
         max_input_tokens=272_000,
         max_output_tokens=128_000,
-        litellm_proxy_model_name="openai/gpt-5.1-codex",
-        short_name="GPT-5.1 Codex",
-    ),
-    ModelName.GPT_5_1_CODEX_MINI: ModelSpec(
-        name=ModelName.GPT_5_1_CODEX_MINI,
-        provider=ProviderType.OPENAI,
-        max_input_tokens=272_000,
-        max_output_tokens=128_000,
-        litellm_proxy_model_name="openai/gpt-5.1-codex-mini",
-        short_name="GPT-5.1 Codex Mini",
+        litellm_proxy_model_name="openai/gpt-5.2",
+        short_name="GPT-5.2",
     ),
     ModelName.CLAUDE_SONNET_4_5: ModelSpec(
         name=ModelName.CLAUDE_SONNET_4_5,
@@ -166,14 +156,6 @@ MODEL_SPECS: dict[ModelName, ModelSpec] = {
         litellm_proxy_model_name="anthropic/claude-opus-4-5",
         short_name="Opus 4.5",
     ),
-    ModelName.CLAUDE_SONNET_4: ModelSpec(
-        name=ModelName.CLAUDE_SONNET_4,
-        provider=ProviderType.ANTHROPIC,
-        max_input_tokens=200_000,
-        max_output_tokens=64_000,
-        litellm_proxy_model_name="anthropic/claude-sonnet-4",
-        short_name="Sonnet 4",
-    ),
     ModelName.GEMINI_2_5_FLASH_LITE: ModelSpec(
         name=ModelName.GEMINI_2_5_FLASH_LITE,
         provider=ProviderType.GOOGLE,
@@ -273,10 +255,6 @@ 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/config/provider.py

@@ -4,7 +4,7 @@ from pydantic import SecretStr
 from pydantic_ai.models import Model
 from pydantic_ai.models.anthropic import AnthropicModel, AnthropicModelSettings
 from pydantic_ai.models.google import GoogleModel
-from pydantic_ai.models.openai import OpenAIChatModel
+from pydantic_ai.models.openai import OpenAIResponsesModel
 from pydantic_ai.providers.anthropic import AnthropicProvider
 from pydantic_ai.providers.google import GoogleProvider
 from pydantic_ai.providers.openai import OpenAIProvider
@@ -47,18 +47,18 @@ def get_default_model_for_provider(config: ShotgunConfig) -> ModelName:
     """
     # Priority 1: Shotgun Account
     if _get_api_key(config.shotgun.api_key):
-        return ModelName.GPT_5_1
+        return ModelName.CLAUDE_SONNET_4_5
 
     # Priority 2: Individual provider keys
     if _get_api_key(config.anthropic.api_key):
-        return ModelName.CLAUDE_HAIKU_4_5
+        return ModelName.CLAUDE_SONNET_4_5
     if _get_api_key(config.openai.api_key):
-        return ModelName.GPT_5_1
+        return ModelName.GPT_5_2
     if _get_api_key(config.google.api_key):
-        return ModelName.GEMINI_2_5_PRO
+        return ModelName.GEMINI_3_PRO_PREVIEW
 
     # Fallback: system-wide default
-    return ModelName.CLAUDE_HAIKU_4_5
+    return ModelName.CLAUDE_SONNET_4_5
 
 
 def get_or_create_model(
@@ -130,7 +130,7 @@ def get_or_create_model(
                 # OpenAI and Google: Use LiteLLMProvider (OpenAI-compatible format)
                 # Google's GoogleProvider doesn't support base_url, so use LiteLLM
                 litellm_provider = create_litellm_provider(api_key)
-                _model_cache[cache_key] = OpenAIChatModel(
+                _model_cache[cache_key] = OpenAIResponsesModel(
                     litellm_model_name,
                     provider=litellm_provider,
                     settings=ModelSettings(max_tokens=max_tokens),
@@ -139,7 +139,7 @@ def get_or_create_model(
             # Use native provider implementations with user's API keys
             if provider == ProviderType.OPENAI:
                 openai_provider = OpenAIProvider(api_key=api_key)
-                _model_cache[cache_key] = OpenAIChatModel(
+                _model_cache[cache_key] = OpenAIResponsesModel(
                     model_name,
                     provider=openai_provider,
                     settings=ModelSettings(max_tokens=max_tokens),
@@ -257,23 +257,24 @@ async def get_provider_model(
         requested_model = None  # Will use provider's default model
 
     if provider_enum == ProviderType.OPENAI:
-        api_key = _get_api_key(config.openai.api_key)
+        api_key = _get_api_key(config.openai.api_key, "OPENAI_API_KEY")
         if not api_key:
-            raise ValueError("OpenAI API key not configured. Set via config.")
+            raise ValueError(
+                "OpenAI API key not configured. Set via config or OPENAI_API_KEY env var."
+            )
 
-        # Use requested model or default to gpt-5.1
-        model_name = requested_model if requested_model else ModelName.GPT_5_1
+        # Use requested model or default to gpt-5.2
+        model_name = requested_model if requested_model else ModelName.GPT_5_2
         # Gracefully fall back if model doesn't exist
         if model_name not in MODEL_SPECS:
-            model_name = ModelName.GPT_5_1
+            model_name = ModelName.GPT_5_2
         spec = MODEL_SPECS[model_name]
 
         # Check and test streaming capability for GPT-5 family models
         supports_streaming = True  # Default to True for all models
         if model_name in (
             ModelName.GPT_5_1,
-            ModelName.GPT_5_1_CODEX,
-            ModelName.GPT_5_1_CODEX_MINI,
+            ModelName.GPT_5_2,
         ):
             # Check if streaming capability has been tested
             streaming_capability = config.openai.supports_streaming
@@ -307,15 +308,17 @@ async def get_provider_model(
         )
 
     elif provider_enum == ProviderType.ANTHROPIC:
-        api_key = _get_api_key(config.anthropic.api_key)
+        api_key = _get_api_key(config.anthropic.api_key, "ANTHROPIC_API_KEY")
         if not api_key:
-            raise ValueError("Anthropic API key not configured. Set via config.")
+            raise ValueError(
+                "Anthropic API key not configured. Set via config or ANTHROPIC_API_KEY env var."
+            )
 
-        # Use requested model or default to claude-haiku-4-5
-        model_name = requested_model if requested_model else ModelName.CLAUDE_HAIKU_4_5
+        # Use requested model or default to claude-sonnet-4-5
+        model_name = requested_model if requested_model else ModelName.CLAUDE_SONNET_4_5
         # Gracefully fall back if model doesn't exist
         if model_name not in MODEL_SPECS:
-            model_name = ModelName.CLAUDE_HAIKU_4_5
+            model_name = ModelName.CLAUDE_SONNET_4_5
         spec = MODEL_SPECS[model_name]
 
         # Create fully configured ModelConfig
@@ -329,15 +332,19 @@ async def get_provider_model(
         )
 
     elif provider_enum == ProviderType.GOOGLE:
-        api_key = _get_api_key(config.google.api_key)
+        api_key = _get_api_key(config.google.api_key, "GEMINI_API_KEY")
         if not api_key:
-            raise ValueError("Gemini API key not configured. Set via config.")
+            raise ValueError(
+                "Gemini API key not configured. Set via config or GEMINI_API_KEY env var."
+            )
 
-        # Use requested model or default to gemini-2.5-pro
-        model_name = requested_model if requested_model else ModelName.GEMINI_2_5_PRO
+        # Use requested model or default to gemini-3-pro-preview
+        model_name = (
+            requested_model if requested_model else ModelName.GEMINI_3_PRO_PREVIEW
+        )
         # Gracefully fall back if model doesn't exist
         if model_name not in MODEL_SPECS:
-            model_name = ModelName.GEMINI_2_5_PRO
+            model_name = ModelName.GEMINI_3_PRO_PREVIEW
         spec = MODEL_SPECS[model_name]
 
         # Create fully configured ModelConfig
@@ -373,16 +380,26 @@ def _has_provider_key(config: "ShotgunConfig", provider: ProviderType) -> bool:
     return False
 
 
-def _get_api_key(config_key: SecretStr | None) -> str | None:
-    """Get API key from config.
+def _get_api_key(
+    config_key: SecretStr | None, env_var_name: str | None = None
+) -> str | None:
+    """Get API key from config or environment variable.
 
     Args:
         config_key: API key from configuration
+        env_var_name: Optional environment variable name to check as fallback
 
     Returns:
         API key string or None
     """
+    # First check config
     if config_key is not None:
         return config_key.get_secret_value()
 
+    # Fallback to environment variable
+    if env_var_name:
+        import os
+
+        return os.environ.get(env_var_name)
+
     return None

shotgun/agents/conversation/history/token_counting/base.py

@@ -2,7 +2,7 @@
 
 from abc import ABC, abstractmethod
 
-from pydantic_ai.messages import ModelMessage
+from pydantic_ai.messages import BinaryContent, ModelMessage
 
 
 class TokenCounter(ABC):
@@ -41,33 +41,75 @@ class TokenCounter(ABC):
         """
 
 
+def _extract_text_from_content(content: object) -> str | None:
+    """Extract text from a content object, skipping BinaryContent.
+
+    Args:
+        content: A content object (str, BinaryContent, list, etc.)
+
+    Returns:
+        Extracted text or None if content is binary/empty
+    """
+    if isinstance(content, BinaryContent):
+        return None
+    if isinstance(content, str):
+        return content.strip() if content.strip() else None
+    if isinstance(content, list):
+        # Content can be a list like ['text', BinaryContent(...), 'more text']
+        text_items = []
+        for item in content:
+            extracted = _extract_text_from_content(item)
+            if extracted:
+                text_items.append(extracted)
+        return "\n".join(text_items) if text_items else None
+    # For other types, convert to string but skip if it looks like binary
+    text = str(content)
+    # Skip if it's a BinaryContent repr (contains raw bytes)
+    if "BinaryContent(data=b" in text:
+        return None
+    return text.strip() if text.strip() else None
+
+
 def extract_text_from_messages(messages: list[ModelMessage]) -> str:
     """Extract all text content from messages for token counting.
 
+    Note: BinaryContent (PDFs, images) is skipped because:
+    1. str(BinaryContent) includes raw bytes which tokenize terribly
+    2. Claude uses fixed token costs for images/PDFs based on dimensions/pages,
+       not raw data size
+    3. Including binary data in text token counting causes massive overestimates
+       (e.g., 127KB of PDFs -> 267K tokens instead of ~few thousand)
+
     Args:
         messages: List of PydanticAI messages
 
     Returns:
-        Combined text content from all messages
+        Combined text content from all messages (excluding binary content)
     """
     text_parts = []
 
     for message in messages:
         if hasattr(message, "parts"):
             for part in message.parts:
-                if hasattr(part, "content") and isinstance(part.content, str):
-                    # Only add non-empty content
-                    if part.content.strip():
-                        text_parts.append(part.content)
+                # Skip BinaryContent directly
+                if isinstance(part, BinaryContent):
+                    continue
+
+                # Check if part has content attribute (UserPromptPart, etc.)
+                if hasattr(part, "content"):
+                    extracted = _extract_text_from_content(part.content)
+                    if extracted:
+                        text_parts.append(extracted)
                 else:
-                    # Handle non-text parts (tool calls, etc.)
+                    # Handle other parts (tool calls, etc.) - but check for binary
                     part_str = str(part)
-                    if part_str.strip():
+                    # Skip if it contains BinaryContent repr
+                    if "BinaryContent(data=b" not in part_str and part_str.strip():
                         text_parts.append(part_str)
         else:
             # Handle messages without parts
             msg_str = str(message)
-            if msg_str.strip():
+            if "BinaryContent(data=b" not in msg_str and msg_str.strip():
                 text_parts.append(msg_str)
 
     # If no valid text parts found, return a minimal placeholder

shotgun/agents/file_read.py

@@ -0,0 +1,176 @@
+"""FileRead agent factory - lightweight agent for searching and reading files.
+
+This agent is designed for finding and reading files (including PDFs and images)
+without the overhead of full codebase understanding tools.
+"""
+
+from functools import partial
+
+from pydantic_ai import Agent, RunContext, UsageLimits
+from pydantic_ai.agent import AgentRunResult
+from pydantic_ai.messages import ModelMessage
+
+from shotgun.agents.config import ProviderType, get_provider_model
+from shotgun.agents.models import (
+    AgentDeps,
+    AgentResponse,
+    AgentRuntimeOptions,
+    AgentType,
+    ShotgunAgent,
+)
+from shotgun.logging_config import get_logger
+from shotgun.prompts import PromptLoader
+from shotgun.sdk.services import get_codebase_service
+from shotgun.utils import ensure_shotgun_directory_exists
+
+from .common import (
+    EventStreamHandler,
+    add_system_status_message,
+    run_agent,
+)
+from .conversation.history import token_limit_compactor
+from .tools import directory_lister, file_read, read_file
+from .tools.file_read_tools import multimodal_file_read
+
+logger = get_logger(__name__)
+
+# Prompt loader instance
+prompt_loader = PromptLoader()
+
+
+def _build_file_read_system_prompt(ctx: RunContext[AgentDeps]) -> str:
+    """Build system prompt for FileRead agent."""
+    template = prompt_loader.load_template("agents/file_read.j2")
+    return template.render(
+        interactive_mode=ctx.deps.interactive_mode,
+        mode="file_read",
+    )
+
+
+async def create_file_read_agent(
+    agent_runtime_options: AgentRuntimeOptions,
+    provider: ProviderType | None = None,
+) -> tuple[ShotgunAgent, AgentDeps]:
+    """Create a lightweight file reading agent.
+
+    This agent has minimal tools focused on file discovery and reading:
+    - directory_lister: List directory contents
+    - file_read: Read text files (from codebase tools)
+    - read_file: Read files by path
+    - multimodal_file_read: Read PDFs/images with BinaryContent
+
+    Args:
+        agent_runtime_options: Agent runtime options
+        provider: Optional provider override
+
+    Returns:
+        Tuple of (Configured agent, Agent dependencies)
+    """
+    logger.debug("Initializing FileRead agent")
+    ensure_shotgun_directory_exists()
+
+    # Get configured model
+    model_config = await get_provider_model(provider)
+    logger.debug(
+        "FileRead agent using %s model: %s",
+        model_config.provider.value.upper(),
+        model_config.name,
+    )
+
+    # Create minimal dependencies (no heavy codebase analysis)
+    codebase_service = get_codebase_service()
+
+    deps = AgentDeps(
+        **agent_runtime_options.model_dump(),
+        llm_model=model_config,
+        codebase_service=codebase_service,
+        system_prompt_fn=partial(_build_file_read_system_prompt),
+        agent_mode=AgentType.FILE_READ,
+    )
+
+    # History processor for context management
+    async def history_processor(messages: list[ModelMessage]) -> list[ModelMessage]:
+        class ProcessorContext:
+            def __init__(self, deps: AgentDeps):
+                self.deps = deps
+                self.usage = None
+
+        ctx = ProcessorContext(deps)
+        return await token_limit_compactor(ctx, messages)
+
+    # Create agent with structured output
+    model = model_config.model_instance
+    agent: ShotgunAgent = Agent(
+        model,
+        output_type=AgentResponse,
+        deps_type=AgentDeps,
+        instrument=True,
+        history_processors=[history_processor],
+        retries=3,
+    )
+
+    # Register only file reading tools (no write tools, no codebase query tools)
+    agent.tool(read_file)  # Basic file read
+    agent.tool(file_read)  # Codebase file read with CWD fallback
+    agent.tool(directory_lister)  # List directories
+    agent.tool(multimodal_file_read)  # PDF/image reading with BinaryContent
+
+    logger.debug("FileRead agent created with minimal tools")
+    return agent, deps
+
+
+def create_file_read_usage_limits() -> UsageLimits:
+    """Create conservative usage limits for FileRead agent.
+
+    FileRead should be quick - if it can't find the file in a few turns,
+    it should give up.
+    """
+    return UsageLimits(
+        request_limit=10,  # Max 10 API calls
+        request_tokens_limit=50_000,  # 50k input tokens
+        response_tokens_limit=8_000,  # 8k output tokens
+        total_tokens_limit=60_000,  # 60k total
+    )
+
+
+async def run_file_read_agent(
+    agent: ShotgunAgent,
+    prompt: str,
+    deps: AgentDeps,
+    message_history: list[ModelMessage] | None = None,
+    event_stream_handler: EventStreamHandler | None = None,
+) -> AgentRunResult[AgentResponse]:
+    """Run the FileRead agent to search for and read files.
+
+    Args:
+        agent: The configured FileRead agent
+        prompt: The file search prompt (e.g., "find the user stories PDF")
+        deps: Agent dependencies
+        message_history: Optional message history
+        event_stream_handler: Optional callback for streaming events
+
+    Returns:
+        AgentRunResult with response and files_found
+    """
+    logger.debug("FileRead agent searching: %s", prompt)
+
+    message_history = await add_system_status_message(deps, message_history)
+
+    try:
+        usage_limits = create_file_read_usage_limits()
+
+        result = await run_agent(
+            agent=agent,
+            prompt=prompt,
+            deps=deps,
+            message_history=message_history,
+            usage_limits=usage_limits,
+            event_stream_handler=event_stream_handler,
+        )
+
+        logger.debug("FileRead agent completed successfully")
+        return result
+
+    except Exception as e:
+        logger.error("FileRead agent failed: %s", str(e))
+        raise

shotgun/agents/messages.py

@@ -1,12 +1,13 @@
 """Custom message types for Shotgun agents.
 
-This module defines specialized SystemPromptPart subclasses to distinguish
-between different types of system prompts in the agent pipeline.
+This module defines specialized message part subclasses to distinguish
+between different types of prompts in the agent pipeline.
 """
 
 from dataclasses import dataclass, field
+from typing import Literal
 
-from pydantic_ai.messages import SystemPromptPart
+from pydantic_ai.messages import SystemPromptPart, UserPromptPart
 
 from shotgun.agents.models import AgentType
 
@@ -33,3 +34,14 @@ class SystemStatusPrompt(SystemPromptPart):
     """
 
     prompt_type: str = "status"
+
+
+@dataclass
+class InternalPromptPart(UserPromptPart):
+    """User prompt that is system-generated rather than actual user input.
+
+    Used for internal continuation prompts like file resume messages.
+    These should be hidden from the UI but preserved in agent history for context.
+    """
+
+    part_kind: Literal["internal-prompt"] = "internal-prompt"  # type: ignore[assignment]

shotgun/agents/models.py

@@ -1,7 +1,7 @@
 """Pydantic models for agent dependencies and configuration."""
 
 import os
-from asyncio import Future, Queue
+from asyncio import Event, Future, Queue
 from collections.abc import Callable
 from datetime import datetime
 from enum import StrEnum
@@ -87,6 +87,23 @@ class AgentResponse(BaseModel):
 Optional list of clarifying questions to ask the user.
 - Single question: Shown as a non-blocking suggestion (user can answer or continue with other prompts)
 - Multiple questions (2+): Asked sequentially in Q&A mode (blocks input until all answered or cancelled)
+""",
+    )
+    files_found: list[str] | None = Field(
+        default=None,
+        description="""
+Optional list of absolute file paths found by the agent.
+Used by FileReadAgent to return paths of files it searched and found.
+The delegation tool can then load these files as multimodal content.
+""",
+    )
+    file_requests: list[str] | None = Field(
+        default=None,
+        description="""
+Optional list of file paths the agent wants to read.
+When set, the agent loop exits, files are loaded as BinaryContent,
+and the loop resumes with file content in the next prompt.
+Use this for PDFs, images, or other binary files you need to analyze.
 """,
     )
 
@@ -100,6 +117,7 @@ class AgentType(StrEnum):
     TASKS = "tasks"
     EXPORT = "export"
     ROUTER = "router"
+    FILE_READ = "file_read"
 
 
 class PipelineConfigEntry(BaseModel):
@@ -373,6 +391,11 @@ class AgentDeps(AgentRuntimeOptions):
         description="Context when agent is delegated to by router",
     )
 
+    cancellation_event: Event | None = Field(
+        default=None,
+        description="Event set when the operation should be cancelled",
+    )
+
 
 # Rebuild model to resolve forward references after imports are available
 try:

shotgun/agents/router/models.py

@@ -216,6 +216,10 @@ class DelegationResult(BaseModel):
     files_modified: list[str] = Field(
         default_factory=list, description="Files modified by sub-agent"
     )
+    files_found: list[str] = Field(
+        default_factory=list,
+        description="Files found by sub-agent (used by FileReadAgent)",
+    )
     has_questions: bool = Field(
         default=False, description="Whether sub-agent has clarifying questions"
     )
@@ -358,6 +362,10 @@ class RouterDeps(AgentDeps):
     # Set by create_plan tool when plan.needs_approval() returns True
     # Excluded from serialization as it's transient UI state
     pending_approval: PendingApproval | None = Field(default=None, exclude=True)
+    # Completion state for Drafting mode
+    # Set by mark_step_done when plan completes in drafting mode
+    # Excluded from serialization as it's transient UI state
+    pending_completion: bool = Field(default=False, exclude=True)
     # Event stream handler for forwarding sub-agent streaming events to UI
     # This is set by the AgentManager when running the router with streaming
     # Excluded from serialization as it's a callable