shotgun-sh 0.3.3.dev1__py3-none-any.whl → 0.4.0.dev1__py3-none-any.whl

shotgun/agents/config/manager.py

@@ -51,7 +51,7 @@ class ConfigMigrationError(Exception):
 ProviderConfig = OpenAIConfig | AnthropicConfig | GoogleConfig | ShotgunAccountConfig
 
 # Current config version
-CURRENT_CONFIG_VERSION = 5
+CURRENT_CONFIG_VERSION = 6
 
 # Backup directory name
 BACKUP_DIR_NAME = "backup"
@@ -183,6 +183,26 @@ def _migrate_v4_to_v5(data: dict[str, Any]) -> dict[str, Any]:
     return data
 
 
+def _migrate_v5_to_v6(data: dict[str, Any]) -> dict[str, Any]:
+    """Migrate config from version 5 to version 6.
+
+    Changes:
+    - Add 'router_mode' field with default 'planning'
+
+    Args:
+        data: Config data dict at version 5
+
+    Returns:
+        Modified config data dict at version 6
+    """
+    if "router_mode" not in data:
+        data["router_mode"] = "planning"
+        logger.info("Migrated config v5->v6: added router_mode field")
+
+    data["config_version"] = 6
+    return data
+
+
 def _apply_migrations(data: dict[str, Any]) -> dict[str, Any]:
     """Apply all necessary migrations to bring config to current version.
 
@@ -203,6 +223,7 @@ def _apply_migrations(data: dict[str, Any]) -> dict[str, Any]:
         2: _migrate_v2_to_v3,
         3: _migrate_v3_to_v4,
         4: _migrate_v4_to_v5,
+        5: _migrate_v5_to_v6,
     }
 
     # Apply migrations sequentially
@@ -772,6 +793,26 @@ class ConfigManager:
         await self.save(config)
         logger.info("Updated Shotgun Account configuration")
 
+    async def get_router_mode(self) -> str:
+        """Get the saved router mode.
+
+        Returns:
+            The router mode string ('planning' or 'drafting')
+        """
+        config = await self.load()
+        return config.router_mode
+
+    async def set_router_mode(self, mode: str) -> None:
+        """Save the router mode.
+
+        Args:
+            mode: Router mode to save ('planning' or 'drafting')
+        """
+        config = await self.load()
+        config.router_mode = mode
+        await self.save(config)
+        logger.debug("Router mode saved: %s", mode)
+
 
 # Global singleton instance
 _config_manager_instance: ConfigManager | None = None

shotgun/agents/config/models.py

@@ -226,6 +226,18 @@ class ShotgunAccountConfig(BaseModel):
         default=None, description="Default workspace ID for shared specs"
     )
 
+    @property
+    def has_valid_account(self) -> bool:
+        """Check if the user has a valid Shotgun Account configured.
+
+        Returns:
+            True if api_key is set and non-empty, False otherwise
+        """
+        if self.api_key is None:
+            return False
+        value = self.api_key.get_secret_value()
+        return bool(value and value.strip())
+
 
 class MarketingMessageRecord(BaseModel):
     """Record of when a marketing message was shown to the user."""
@@ -277,3 +289,7 @@ class ShotgunConfig(BaseModel):
         default=None,
         description="Path to the backup file created when migration failed",
     )
+    router_mode: str = Field(
+        default="planning",
+        description="Router execution mode: 'planning' or 'drafting'",
+    )

shotgun/agents/conversation/history/file_content_deduplication.py

@@ -5,8 +5,6 @@ tool returns before LLM-based compaction. Files are still accessible via
 `retrieve_code` (codebase) or `read_file` (.shotgun/ folder).
 """
 
-import copy
-import re
 from enum import StrEnum
 from typing import Any
 
@@ -43,40 +41,46 @@ SHOTGUN_PLACEHOLDER = (
     "**Content**: [Removed for compaction - file persisted in .shotgun/ folder]"
 )
 
-# Pattern for parsing file_read output (codebase files)
-# Format: **File**: `path`\n**Size**: N bytes\n[optional encoding]\n\n**Content**:\n```lang\ncontent```
-CODEBASE_FILE_PATTERN = re.compile(
-    r"\*\*File\*\*:\s*`([^`]+)`\s*\n"  # File path
-    r"\*\*Size\*\*:\s*(\d+)\s*bytes\s*\n"  # Size in bytes
-    r"(?:\*\*Encoding\*\*:.*?\n)?"  # Optional encoding line
-    r"\n\*\*Content\*\*:\s*\n"  # Blank line + Content header
-    r"```(\w*)\n"  # Language tag
-    r"(.*?)```",  # Actual content
-    re.DOTALL,
-)
+# Simple prefix for detecting file_read output format
+# Instead of using regex, we just check for the expected prefix and extract the file path
+CODEBASE_FILE_PREFIX = "**File**: `"
+
 
+def _extract_file_path(content: str) -> str | None:
+    """Extract file path from file_read tool return content.
 
-def _parse_codebase_file_content(
-    content: str,
-) -> tuple[str, int, str, str] | None:
-    """Parse file_read tool return content.
+    Uses simple string operations instead of regex for maximum performance.
+    The file_read tool output format is: **File**: `path`\\n...
 
     Args:
         content: The tool return content string
 
     Returns:
-        Tuple of (file_path, size_bytes, language, actual_content) or None if not parseable
+        The file path or None if format doesn't match
     """
-    match = CODEBASE_FILE_PATTERN.search(content)
-    if not match:
+    # Fast check: content must start with expected prefix
+    if not content.startswith(CODEBASE_FILE_PREFIX):
+        return None
+
+    # Find the closing backtick after the prefix
+    prefix_len = len(CODEBASE_FILE_PREFIX)
+    backtick_pos = content.find("`", prefix_len)
+
+    if backtick_pos == -1:
         return None
 
-    file_path = match.group(1)
-    size_bytes = int(match.group(2))
-    language = match.group(3) or ""
-    actual_content = match.group(4)
+    return content[prefix_len:backtick_pos]
+
+
+def _get_language_from_path(file_path: str) -> str:
+    """Infer programming language from file extension."""
+    from pathlib import Path
+
+    from shotgun.codebase.core.language_config import get_language_config
 
-    return file_path, size_bytes, language, actual_content
+    ext = Path(file_path).suffix
+    config = get_language_config(ext)
+    return config.name if config else "unknown"
 
 
 def _create_codebase_placeholder(file_path: str, size_bytes: int, language: str) -> str:
@@ -110,6 +114,11 @@ def deduplicate_file_content(
     This is a deterministic pre-compaction pass that reduces tokens without
     requiring an LLM. Files remain accessible via their respective tools.
 
+    This function uses copy-on-write semantics: only messages that need
+    modification are copied, while unmodified messages are reused by reference.
+    This significantly reduces memory allocation and processing time for large
+    conversations where only a subset of messages contain file content.
+
     Args:
         messages: Conversation history
         retention_window: Keep full content in last N messages (for recent context)
@@ -120,15 +129,17 @@ def deduplicate_file_content(
     if not messages:
         return messages, 0
 
-    # Deep copy to avoid modifying original
-    modified_messages = copy.deepcopy(messages)
     total_tokens_saved = 0
     files_deduplicated = 0
 
     # Calculate retention boundary (keep last N messages intact)
-    retention_start = max(0, len(modified_messages) - retention_window)
+    retention_start = max(0, len(messages) - retention_window)
+
+    # Track which message indices need replacement
+    # We use a dict to store index -> new_message mappings
+    replacements: dict[int, ModelMessage] = {}
 
-    for msg_idx, message in enumerate(modified_messages):
+    for msg_idx, message in enumerate(messages):
         # Skip messages in retention window
         if msg_idx >= retention_start:
             continue
@@ -159,18 +170,18 @@ def deduplicate_file_content(
 
             # Handle codebase file reads (file_read)
             if tool_name == FileReadTool.CODEBASE:
-                parsed = _parse_codebase_file_content(content)
-                if parsed:
-                    file_path, size_bytes, language, actual_content = parsed
-                    # Only replace if actual content is substantial
-                    if len(actual_content) >= MIN_CONTENT_LENGTH:
-                        replacement = _create_codebase_placeholder(
-                            file_path, size_bytes, language
-                        )
-                        logger.debug(
-                            f"Deduplicating codebase file: {file_path} "
-                            f"({size_bytes} bytes)"
-                        )
+                file_path = _extract_file_path(content)
+                if file_path:
+                    # Use content length as size estimate (includes formatting overhead
+                    # but close enough for deduplication purposes)
+                    size_bytes = len(content)
+                    language = _get_language_from_path(file_path)
+                    replacement = _create_codebase_placeholder(
+                        file_path, size_bytes, language
+                    )
+                    logger.debug(
+                        f"Deduplicating codebase file: {file_path} ({size_bytes} bytes)"
+                    )
 
             # Handle .shotgun/ file reads (read_file)
             elif tool_name == FileReadTool.SHOTGUN_FOLDER:
@@ -203,9 +214,21 @@ def deduplicate_file_content(
             else:
                 new_parts.append(part)
 
-        # Replace message with new parts if modified
+        # Only create a new message if parts were actually modified
         if message_modified:
-            modified_messages[msg_idx] = ModelRequest(parts=new_parts)
+            replacements[msg_idx] = ModelRequest(parts=new_parts)
+
+    # If no modifications were made, return original list (no allocation needed)
+    if not replacements:
+        return messages, 0
+
+    # Build result list with copy-on-write: reuse unmodified messages
+    modified_messages: list[ModelMessage] = []
+    for idx, msg in enumerate(messages):
+        if idx in replacements:
+            modified_messages.append(replacements[idx])
+        else:
+            modified_messages.append(msg)
 
     if files_deduplicated > 0:
         logger.info(

shotgun/agents/export.py

@@ -2,16 +2,15 @@
 
 from functools import partial
 
-from pydantic_ai import (
-    Agent,
-)
 from pydantic_ai.agent import AgentRunResult
 from pydantic_ai.messages import ModelMessage
 
 from shotgun.agents.config import ProviderType
+from shotgun.agents.models import ShotgunAgent
 from shotgun.logging_config import get_logger
 
 from .common import (
+    EventStreamHandler,
     add_system_status_message,
     build_agent_system_prompt,
     create_base_agent,
@@ -25,7 +24,7 @@ logger = get_logger(__name__)
 
 async def create_export_agent(
     agent_runtime_options: AgentRuntimeOptions, provider: ProviderType | None = None
-) -> tuple[Agent[AgentDeps, AgentResponse], AgentDeps]:
+) -> tuple[ShotgunAgent, AgentDeps]:
     """Create an export agent with file management capabilities.
 
     Args:
@@ -49,39 +48,39 @@ async def create_export_agent(
 
 
 async def run_export_agent(
-    agent: Agent[AgentDeps, AgentResponse],
-    instruction: str,
+    agent: ShotgunAgent,
+    prompt: str,
     deps: AgentDeps,
     message_history: list[ModelMessage] | None = None,
+    event_stream_handler: EventStreamHandler | None = None,
 ) -> AgentRunResult[AgentResponse]:
-    """Export artifacts based on the given instruction.
+    """Export artifacts based on the given prompt.
 
     Args:
         agent: The configured export agent
-        instruction: The export instruction
+        prompt: The export prompt
         deps: Agent dependencies
         message_history: Optional message history for conversation continuity
+        event_stream_handler: Optional callback for streaming events
 
     Returns:
         AgentRunResult containing the export process output
     """
-    logger.debug("📤 Starting export for instruction: %s", instruction)
+    logger.debug("📤 Starting export for prompt: %s", prompt)
 
     message_history = await add_system_status_message(deps, message_history)
 
-    # Let the agent use its tools to read existing artifacts and export them
-    full_prompt = f"Export artifacts or findings based on: {instruction}"
-
     try:
         # Create usage limits for responsible API usage
         usage_limits = create_usage_limits()
 
         result = await run_agent(
             agent=agent,
-            prompt=full_prompt,
+            prompt=prompt,
             deps=deps,
             message_history=message_history,
             usage_limits=usage_limits,
+            event_stream_handler=event_stream_handler,
         )
 
         logger.debug("✅ Export completed successfully")

shotgun/agents/models.py

@@ -6,7 +6,7 @@ from collections.abc import Callable
 from datetime import datetime
 from enum import StrEnum
 from pathlib import Path
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, TypeAlias
 
 from pydantic import BaseModel, ConfigDict, Field
 from pydantic_ai import RunContext
@@ -16,9 +16,57 @@ from shotgun.agents.usage_manager import SessionUsageManager, get_session_usage_
 from .config.models import ModelConfig
 
 if TYPE_CHECKING:
+    from pydantic_ai import Agent
+
+    from shotgun.agents.router.models import RouterDeps
     from shotgun.codebase.service import CodebaseService
 
 
+class SubAgentContext(BaseModel):
+    """
+    Context passed to sub-agents so they know they're being orchestrated.
+
+    When sub-agents receive this context, they should:
+    - Be more concise (router handles user communication)
+    - Focus on their specific task
+    - Return structured results
+    """
+
+    is_router_delegated: bool = Field(
+        default=True, description="Always True when passed to sub-agent"
+    )
+    plan_goal: str = Field(
+        default="", description="High-level goal from execution plan"
+    )
+    current_step_id: str | None = Field(
+        default=None, description="ID of the current execution step"
+    )
+    current_step_title: str | None = Field(
+        default=None, description="Title of the current execution step"
+    )
+
+
+class AgentSystemPromptContext(BaseModel):
+    """Context passed to agent system prompt templates.
+
+    This model standardizes the context variables passed to Jinja2 templates
+    when rendering agent system prompts. Using a model makes it easier to
+    test template context construction and ensures type safety.
+    """
+
+    interactive_mode: bool = Field(
+        description="Whether the agent is running in interactive mode"
+    )
+    mode: str = Field(description="The agent type (research, specify, plan, etc.)")
+    sub_agent_context: SubAgentContext | None = Field(
+        default=None, description="Context when running as a sub-agent of the router"
+    )
+    router_mode: str | None = Field(
+        default=None,
+        description="Router mode value (planning/drafting) if router agent",
+    )
+
+
 class AgentResponse(BaseModel):
     """Structured response from an agent with optional clarifying questions.
 
@@ -51,6 +99,7 @@ class AgentType(StrEnum):
     PLAN = "plan"
     TASKS = "tasks"
     EXPORT = "export"
+    ROUTER = "router"
 
 
 class PipelineConfigEntry(BaseModel):
@@ -319,6 +368,11 @@ class AgentDeps(AgentRuntimeOptions):
         description="Current agent mode for file scoping",
     )
 
+    sub_agent_context: SubAgentContext | None = Field(
+        default=None,
+        description="Context when agent is delegated to by router",
+    )
+
 
 # Rebuild model to resolve forward references after imports are available
 try:
@@ -328,3 +382,14 @@ try:
 except ImportError:
     # Services may not be available in all contexts
     pass
+
+
+# Type alias for the standard agent type used throughout the codebase
+ShotgunAgent: TypeAlias = "Agent[AgentDeps, AgentResponse]"
+
+# Type alias for router agent (uses RouterDeps which extends AgentDeps)
+# Note: Agent is contravariant in deps, so RouterAgent is NOT a subtype of ShotgunAgent
+RouterAgent: TypeAlias = "Agent[RouterDeps, AgentResponse]"
+
+# Union type for any agent type (used in AgentManager)
+AnyAgent: TypeAlias = "ShotgunAgent | RouterAgent"

shotgun/agents/plan.py

@@ -2,16 +2,15 @@
 
 from functools import partial
 
-from pydantic_ai import (
-    Agent,
-)
 from pydantic_ai.agent import AgentRunResult
 from pydantic_ai.messages import ModelMessage
 
 from shotgun.agents.config import ProviderType
+from shotgun.agents.models import ShotgunAgent
 from shotgun.logging_config import get_logger
 
 from .common import (
+    EventStreamHandler,
     add_system_status_message,
     build_agent_system_prompt,
     create_base_agent,
@@ -25,7 +24,7 @@ logger = get_logger(__name__)
 
 async def create_plan_agent(
     agent_runtime_options: AgentRuntimeOptions, provider: ProviderType | None = None
-) -> tuple[Agent[AgentDeps, AgentResponse], AgentDeps]:
+) -> tuple[ShotgunAgent, AgentDeps]:
     """Create a plan agent with artifact management capabilities.
 
     Args:
@@ -51,26 +50,25 @@ async def create_plan_agent(
 
 
 async def run_plan_agent(
-    agent: Agent[AgentDeps, AgentResponse],
-    goal: str,
+    agent: ShotgunAgent,
+    prompt: str,
     deps: AgentDeps,
     message_history: list[ModelMessage] | None = None,
+    event_stream_handler: EventStreamHandler | None = None,
 ) -> AgentRunResult[AgentResponse]:
-    """Create or update a plan based on the given goal using artifacts.
+    """Create or update a plan based on the given prompt using artifacts.
 
     Args:
         agent: The configured plan agent
-        goal: The planning goal or instruction
+        prompt: The planning prompt or instruction
         deps: Agent dependencies
         message_history: Optional message history for conversation continuity
+        event_stream_handler: Optional callback for streaming events
 
     Returns:
         AgentRunResult containing the planning process output
     """
-    logger.debug("📋 Starting planning for goal: %s", goal)
-
-    # Simple prompt - the agent system prompt has all the artifact instructions
-    full_prompt = f"Create a comprehensive plan for: {goal}"
+    logger.debug("📋 Starting planning for prompt: %s", prompt)
 
     try:
         # Create usage limits for responsible API usage
@@ -80,10 +78,11 @@ async def run_plan_agent(
 
         result = await run_agent(
             agent=agent,
-            prompt=full_prompt,
+            prompt=prompt,
             deps=deps,
             message_history=message_history,
             usage_limits=usage_limits,
+            event_stream_handler=event_stream_handler,
         )
 
         logger.debug("✅ Planning completed successfully")

shotgun/agents/research.py

@@ -2,18 +2,17 @@
 
 from functools import partial
 
-from pydantic_ai import (
-    Agent,
-)
 from pydantic_ai.agent import AgentRunResult
 from pydantic_ai.messages import (
     ModelMessage,
 )
 
 from shotgun.agents.config import ProviderType
+from shotgun.agents.models import ShotgunAgent
 from shotgun.logging_config import get_logger
 
 from .common import (
+    EventStreamHandler,
     add_system_status_message,
     build_agent_system_prompt,
     create_base_agent,
@@ -28,7 +27,7 @@ logger = get_logger(__name__)
 
 async def create_research_agent(
     agent_runtime_options: AgentRuntimeOptions, provider: ProviderType | None = None
-) -> tuple[Agent[AgentDeps, AgentResponse], AgentDeps]:
+) -> tuple[ShotgunAgent, AgentDeps]:
     """Create a research agent with web search and artifact management capabilities.
 
     Args:
@@ -65,22 +64,25 @@ async def create_research_agent(
 
 
 async def run_research_agent(
-    agent: Agent[AgentDeps, AgentResponse],
-    query: str,
+    agent: ShotgunAgent,
+    prompt: str,
     deps: AgentDeps,
     message_history: list[ModelMessage] | None = None,
+    event_stream_handler: EventStreamHandler | None = None,
 ) -> AgentRunResult[AgentResponse]:
-    """Perform research on the given query and update research artifacts.
+    """Perform research on the given prompt and update research artifacts.
 
     Args:
         agent: The configured research agent
-        query: The research query to investigate
+        prompt: The research prompt to investigate
         deps: Agent dependencies
+        message_history: Optional message history for conversation continuity
+        event_stream_handler: Optional callback for streaming events
 
     Returns:
         Summary of research findings
     """
-    logger.debug("🔬 Starting research for query: %s", query)
+    logger.debug("🔬 Starting research for prompt: %s", prompt)
 
     message_history = await add_system_status_message(deps, message_history)
 
@@ -90,10 +92,11 @@ async def run_research_agent(
 
         result = await run_agent(
             agent=agent,
-            prompt=query,
+            prompt=prompt,
             deps=deps,
             message_history=message_history,
             usage_limits=usage_limits,
+            event_stream_handler=event_stream_handler,
         )
 
         logger.debug("✅ Research completed successfully")

shotgun/agents/router/__init__.py

@@ -0,0 +1,47 @@
+"""Router Agent - The intelligent orchestrator for shotgun agents."""
+
+from shotgun.agents.router.models import (
+    CascadeScope,
+    CreatePlanInput,
+    DelegationInput,
+    DelegationResult,
+    ExecutionPlan,
+    ExecutionStep,
+    ExecutionStepInput,
+    MarkStepDoneInput,
+    PlanApprovalStatus,
+    RemoveStepInput,
+    RouterDeps,
+    RouterMode,
+    StepCheckpointAction,
+    SubAgentResult,
+    SubAgentResultStatus,
+    ToolResult,
+)
+from shotgun.agents.router.router import create_router_agent, run_router_agent
+
+__all__ = [
+    # Agent factory
+    "create_router_agent",
+    "run_router_agent",
+    # Enums
+    "RouterMode",
+    "PlanApprovalStatus",
+    "StepCheckpointAction",
+    "CascadeScope",
+    "SubAgentResultStatus",
+    # Plan models
+    "ExecutionStep",
+    "ExecutionPlan",
+    # Tool I/O models
+    "ExecutionStepInput",
+    "CreatePlanInput",
+    "MarkStepDoneInput",
+    "RemoveStepInput",
+    "DelegationInput",
+    "ToolResult",
+    "DelegationResult",
+    "SubAgentResult",
+    # Deps
+    "RouterDeps",
+]