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

shotgun/agents/tools/file_management.py

@@ -23,7 +23,10 @@ logger = get_logger(__name__)
 # - A list of Paths: multiple allowed files/directories (e.g., [Path("specification.md"), Path("contracts")])
 # - "*": any file except protected files (for export agent)
 AGENT_DIRECTORIES: dict[AgentType, str | Path | list[Path]] = {
-    AgentType.RESEARCH: Path("research.md"),
+    AgentType.RESEARCH: [
+        Path("research.md"),
+        Path("research"),
+    ],  # Research can write main file and research folder
     AgentType.SPECIFY: [
         Path("specification.md"),
         Path("contracts"),
@@ -282,3 +285,48 @@ async def append_file(ctx: RunContext[AgentDeps], filename: str, content: str) -
         Success message or error message
     """
     return await write_file(ctx, filename, content, mode="a")
+
+
+@register_tool(
+    category=ToolCategory.ARTIFACT_MANAGEMENT,
+    display_text="Deleting file",
+    key_arg="filename",
+)
+async def delete_file(ctx: RunContext[AgentDeps], filename: str) -> str:
+    """Delete a file from the .shotgun directory.
+
+    Uses the same permission model as write_file - agents can only delete
+    files they have permission to write to.
+
+    Args:
+        filename: Relative path to file within .shotgun directory
+
+    Returns:
+        Success message or error message
+
+    Raises:
+        ValueError: If path is outside .shotgun directory or agent lacks permission
+        FileNotFoundError: If file does not exist
+    """
+    logger.debug("🔧 Deleting file: %s", filename)
+
+    try:
+        # Use agent-scoped validation (same as write_file)
+        file_path = _validate_agent_scoped_path(filename, ctx.deps.agent_mode)
+
+        if not await aiofiles.os.path.exists(file_path):
+            raise FileNotFoundError(f"File not found: {filename}")
+
+        # Delete the file
+        await aiofiles.os.remove(file_path)
+        logger.debug("🗑️ Deleted file: %s", filename)
+
+        # Track the file operation
+        ctx.deps.file_tracker.add_operation(file_path, FileOperationType.DELETED)
+
+        return f"Successfully deleted {filename}"
+
+    except Exception as e:
+        error_msg = f"Error deleting file '{filename}': {str(e)}"
+        logger.error("❌ File delete failed: %s", error_msg)
+        return error_msg

shotgun/agents/tools/registry.py

@@ -30,6 +30,8 @@ class ToolCategory(StrEnum):
     ARTIFACT_MANAGEMENT = "artifact_management"
     WEB_RESEARCH = "web_research"
     AGENT_RESPONSE = "agent_response"
+    PLANNING = "planning"
+    DELEGATION = "delegation"
     UNKNOWN = "unknown"
 
 

shotgun/agents/tools/web_search/__init__.py

@@ -44,9 +44,8 @@ async def get_available_web_search_tools() -> list[WebSearchTool]:
     # Check if using Shotgun Account
     config_manager = get_config_manager()
     config = await config_manager.load()
-    has_shotgun_key = config.shotgun.api_key is not None
 
-    if has_shotgun_key:
+    if config.shotgun.has_valid_account:
         logger.debug("🔑 Shotgun Account - only Gemini web search available")
 
         # Gemini: Only search tool available for Shotgun Account

shotgun/agents/tools/web_search/gemini.py

@@ -1,7 +1,7 @@
 """Gemini web search tool implementation."""
 
 from opentelemetry import trace
-from pydantic_ai.messages import ModelMessage, ModelRequest
+from pydantic_ai.messages import ModelMessage, ModelRequest, TextPart
 from pydantic_ai.settings import ModelSettings
 
 from shotgun.agents.config import get_provider_model
@@ -82,8 +82,6 @@ async def gemini_web_search_tool(query: str) -> str:
         )
 
         # Extract text from response
-        from pydantic_ai.messages import TextPart
-
         result_text = "No content returned from search"
         if response.parts:
             for part in response.parts:

shotgun/agents/tools/web_search/openai.py

@@ -64,7 +64,7 @@ async def openai_web_search_tool(query: str) -> str:
         )
 
         client = AsyncOpenAI(api_key=api_key)
-        response = await client.responses.create(  # type: ignore[call-overload]
+        response = await client.responses.create(
             model="gpt-5-mini",
             input=[
                 {"role": "user", "content": [{"type": "input_text", "text": prompt}]}

shotgun/build_constants.py

@@ -12,8 +12,8 @@ POSTHOG_API_KEY = 'phc_KKnChzZUKeNqZDOTJ6soCBWNQSx3vjiULdwTR9H5Mcr'
 POSTHOG_PROJECT_ID = '191396'
 
 # Logfire configuration embedded at build time (only for dev builds)
-LOGFIRE_ENABLED = ''
-LOGFIRE_TOKEN = ''
+LOGFIRE_ENABLED = 'true'
+LOGFIRE_TOKEN = 'pylf_v1_us_RwZMlJm1tX6j0PL5RWWbmZpzK2hLBNtFWStNKlySfjh8'
 
 # Build metadata
 BUILD_TIME_ENV = "production" if SENTRY_DSN else "development"

shotgun/cli/clear.py

@@ -6,7 +6,7 @@ from pathlib import Path
 import typer
 from rich.console import Console
 
-from shotgun.agents.conversation_manager import ConversationManager
+from shotgun.agents.conversation import ConversationManager
 from shotgun.logging_config import get_logger
 
 app = typer.Typer(

shotgun/cli/compact.py

@@ -10,9 +10,11 @@ from pydantic_ai.usage import RequestUsage
 from rich.console import Console
 
 from shotgun.agents.config import get_provider_model
-from shotgun.agents.conversation_manager import ConversationManager
-from shotgun.agents.history.history_processors import token_limit_compactor
-from shotgun.agents.history.token_estimation import estimate_tokens_from_messages
+from shotgun.agents.conversation import ConversationManager
+from shotgun.agents.conversation.history.history_processors import token_limit_compactor
+from shotgun.agents.conversation.history.token_estimation import (
+    estimate_tokens_from_messages,
+)
 from shotgun.cli.models import OutputFormat
 from shotgun.logging_config import get_logger
 

shotgun/cli/context.py

@@ -5,6 +5,7 @@ import json
 from pathlib import Path
 from typing import Annotated
 
+import httpx
 import typer
 from rich.console import Console
 
@@ -14,8 +15,9 @@ from shotgun.agents.context_analyzer import (
     ContextAnalyzer,
     ContextFormatter,
 )
-from shotgun.agents.conversation_manager import ConversationManager
+from shotgun.agents.conversation import ConversationManager
 from shotgun.cli.models import OutputFormat
+from shotgun.llm_proxy import BudgetInfo, LiteLLMProxyClient
 from shotgun.logging_config import get_logger
 
 app = typer.Typer(
@@ -108,4 +110,45 @@ async def analyze_context() -> ContextAnalysisOutput:
     markdown = ContextFormatter.format_markdown(analysis)
     json_data = ContextFormatter.format_json(analysis)
 
+    # Add budget info for Shotgun Account users
+    if model_config.is_shotgun_account:
+        try:
+            logger.debug("Fetching budget info for Shotgun Account")
+            client = LiteLLMProxyClient(model_config.api_key)
+            budget_info = await client.get_budget_info()
+
+            # Format budget section for markdown
+            budget_markdown = _format_budget_markdown(budget_info)
+            markdown = f"{markdown}\n\n{budget_markdown}"
+
+            # Add budget info to JSON using Pydantic model
+            json_data["budget"] = budget_info.model_dump()
+            logger.debug("Successfully added budget info to context output")
+
+        except httpx.HTTPError as e:
+            logger.warning(f"Failed to fetch budget info: {e}")
+            # Don't fail the entire command if budget fetch fails
+        except Exception as e:
+            logger.warning(f"Unexpected error fetching budget info: {e}")
+            # Don't fail the entire command if budget fetch fails
+
     return ContextAnalysisOutput(markdown=markdown, json_data=json_data)
+
+
+def _format_budget_markdown(budget_info: BudgetInfo) -> str:
+    """Format budget information as markdown.
+
+    Args:
+        budget_info: BudgetInfo instance
+
+    Returns:
+        Formatted markdown string
+    """
+    source_label = "Key" if budget_info.source == "key" else "Team"
+
+    return f"""## Shotgun Account Budget
+
+* Max Budget:     ${budget_info.max_budget:.2f}
+* Current Spend:  ${budget_info.spend:.2f}
+* Remaining:      ${budget_info.remaining:.2f} ({100 - budget_info.percentage_used:.1f}%)
+* Budget Source:  {source_label}-level"""

shotgun/cli/error_handler.py

@@ -0,0 +1,24 @@
+"""CLI-specific error handling utilities.
+
+This module provides utilities for displaying agent errors in the CLI
+by printing formatted messages to the console.
+"""
+
+from rich.console import Console
+
+from shotgun.exceptions import ErrorNotPickedUpBySentry
+
+console = Console(stderr=True)
+
+
+def print_agent_error(exception: ErrorNotPickedUpBySentry) -> None:
+    """Print an agent error to the console in yellow.
+
+    Args:
+        exception: The error exception with formatting methods
+    """
+    # Get plain text version for CLI
+    message = exception.to_plain_text()
+
+    # Print with yellow styling
+    console.print(message, style="yellow")

shotgun/cli/export.py

@@ -11,7 +11,10 @@ from shotgun.agents.export import (
     run_export_agent,
 )
 from shotgun.agents.models import AgentRuntimeOptions
+from shotgun.cli.error_handler import print_agent_error
+from shotgun.exceptions import ErrorNotPickedUpBySentry
 from shotgun.logging_config import get_logger
+from shotgun.posthog_telemetry import track_event
 
 app = typer.Typer(
     name="export", help="Export artifacts to various formats with agentic approach"
@@ -45,37 +48,34 @@ def export(
 
     logger.info("📤 Export Instruction: %s", instruction)
 
-    try:
-        # Track export command usage
-        from shotgun.posthog_telemetry import track_event
-
-        track_event(
-            "export_command",
-            {
-                "non_interactive": non_interactive,
-                "provider": provider.value if provider else "default",
-            },
-        )
-
-        # Create agent dependencies
-        agent_runtime_options = AgentRuntimeOptions(
-            interactive_mode=not non_interactive
-        )
-
-        # Create the export agent with deps and provider
-        agent, deps = asyncio.run(create_export_agent(agent_runtime_options, provider))
-
-        # Start export process
-        logger.info("🎯 Starting export...")
-        result = asyncio.run(run_export_agent(agent, instruction, deps))
-
-        # Display results
-        logger.info("✅ Export Complete!")
-        logger.info("📤 Results:")
-        logger.info("%s", result.output)
-
-    except Exception as e:
-        logger.error("❌ Error during export: %s", str(e))
-        import traceback
-
-        logger.debug("Full traceback:\n%s", traceback.format_exc())
+    # Track export command usage
+    track_event(
+        "export_command",
+        {
+            "non_interactive": non_interactive,
+            "provider": provider.value if provider else "default",
+        },
+    )
+
+    # Create agent dependencies
+    agent_runtime_options = AgentRuntimeOptions(interactive_mode=not non_interactive)
+
+    # Create the export agent with deps and provider
+    agent, deps = asyncio.run(create_export_agent(agent_runtime_options, provider))
+
+    # Start export process with error handling
+    logger.info("🎯 Starting export...")
+
+    async def async_export() -> None:
+        try:
+            result = await run_export_agent(agent, instruction, deps)
+            logger.info("✅ Export Complete!")
+            logger.info("📤 Results:")
+            logger.info("%s", result.output)
+        except ErrorNotPickedUpBySentry as e:
+            print_agent_error(e)
+        except Exception as e:
+            logger.exception("Unexpected error in export command")
+            print(f"⚠️  An unexpected error occurred: {str(e)}")
+
+    asyncio.run(async_export())

shotgun/cli/plan.py

@@ -8,7 +8,10 @@ import typer
 from shotgun.agents.config import ProviderType
 from shotgun.agents.models import AgentRuntimeOptions
 from shotgun.agents.plan import create_plan_agent, run_plan_agent
+from shotgun.cli.error_handler import print_agent_error
+from shotgun.exceptions import ErrorNotPickedUpBySentry
 from shotgun.logging_config import get_logger
+from shotgun.posthog_telemetry import track_event
 
 app = typer.Typer(name="plan", help="Generate structured plans", no_args_is_help=True)
 logger = get_logger(__name__)
@@ -37,37 +40,34 @@ def plan(
 
     logger.info("📋 Planning Goal: %s", goal)
 
-    try:
-        # Track plan command usage
-        from shotgun.posthog_telemetry import track_event
-
-        track_event(
-            "plan_command",
-            {
-                "non_interactive": non_interactive,
-                "provider": provider.value if provider else "default",
-            },
-        )
-
-        # Create agent dependencies
-        agent_runtime_options = AgentRuntimeOptions(
-            interactive_mode=not non_interactive
-        )
-
-        # Create the plan agent with deps and provider
-        agent, deps = asyncio.run(create_plan_agent(agent_runtime_options, provider))
-
-        # Start planning process
-        logger.info("🎯 Starting planning...")
-        result = asyncio.run(run_plan_agent(agent, goal, deps))
-
-        # Display results
-        logger.info("✅ Planning Complete!")
-        logger.info("📋 Results:")
-        logger.info("%s", result.output)
-
-    except Exception as e:
-        logger.error("❌ Error during planning: %s", str(e))
-        import traceback
-
-        logger.debug("Full traceback:\n%s", traceback.format_exc())
+    # Track plan command usage
+    track_event(
+        "plan_command",
+        {
+            "non_interactive": non_interactive,
+            "provider": provider.value if provider else "default",
+        },
+    )
+
+    # Create agent dependencies
+    agent_runtime_options = AgentRuntimeOptions(interactive_mode=not non_interactive)
+
+    # Create the plan agent with deps and provider
+    agent, deps = asyncio.run(create_plan_agent(agent_runtime_options, provider))
+
+    # Start planning process with error handling
+    logger.info("🎯 Starting planning...")
+
+    async def async_plan() -> None:
+        try:
+            result = await run_plan_agent(agent, goal, deps)
+            logger.info("✅ Planning Complete!")
+            logger.info("📋 Results:")
+            logger.info("%s", result.output)
+        except ErrorNotPickedUpBySentry as e:
+            print_agent_error(e)
+        except Exception as e:
+            logger.exception("Unexpected error in plan command")
+            print(f"⚠️  An unexpected error occurred: {str(e)}")
+
+    asyncio.run(async_plan())

shotgun/cli/research.py

@@ -11,7 +11,10 @@ from shotgun.agents.research import (
     create_research_agent,
     run_research_agent,
 )
+from shotgun.cli.error_handler import print_agent_error
+from shotgun.exceptions import ErrorNotPickedUpBySentry
 from shotgun.logging_config import get_logger
+from shotgun.posthog_telemetry import track_event
 
 app = typer.Typer(
     name="research", help="Perform research with agentic loops", no_args_is_help=True
@@ -59,8 +62,6 @@ async def async_research(
 ) -> None:
     """Async wrapper for research process."""
     # Track research command usage
-    from shotgun.posthog_telemetry import track_event
-
     track_event(
         "research_command",
         {
@@ -75,11 +76,18 @@ async def async_research(
     # Create the research agent with deps and provider
     agent, deps = await create_research_agent(agent_runtime_options, provider)
 
-    # Start research process
+    # Start research process with error handling
     logger.info("🔬 Starting research...")
-    result = await run_research_agent(agent, query, deps)
-
-    # Display results
-    print("✅ Research Complete!")
-    print("📋 Findings:")
-    print(result.output)
+    try:
+        result = await run_research_agent(agent, query, deps)
+        # Display results
+        print("✅ Research Complete!")
+        print("📋 Findings:")
+        print(result.output)
+    except ErrorNotPickedUpBySentry as e:
+        # All user-actionable errors - display with plain text
+        print_agent_error(e)
+    except Exception as e:
+        # Unexpected errors that weren't wrapped (shouldn't happen)
+        logger.exception("Unexpected error in research command")
+        print(f"⚠️  An unexpected error occurred: {str(e)}")

shotgun/cli/spec/__init__.py

@@ -0,0 +1,5 @@
+"""Spec CLI module."""
+
+from .commands import app
+
+__all__ = ["app"]

shotgun/cli/spec/backup.py

@@ -0,0 +1,81 @@
+"""Backup utility for .shotgun/ directory before pulling specs."""
+
+import shutil
+import zipfile
+from datetime import datetime, timezone
+from pathlib import Path
+
+from shotgun.logging_config import get_logger
+
+logger = get_logger(__name__)
+
+# Backup directory location
+BACKUP_DIR = Path.home() / ".shotgun-sh" / "backups"
+
+
+async def create_backup(shotgun_dir: Path) -> str | None:
+    """Create a zip backup of the .shotgun/ directory.
+
+    Creates a timestamped backup at ~/.shotgun-sh/backups/{YYYYMMDD_HHMMSS}.zip.
+    Only creates backup if the directory exists and has content.
+
+    Args:
+        shotgun_dir: Path to the .shotgun/ directory to backup
+
+    Returns:
+        Path to the backup file as string, or None if no backup was created
+        (e.g., directory doesn't exist or is empty)
+
+    Raises:
+        Exception: If backup creation fails (caller should handle)
+    """
+    # Check if directory exists and has content
+    if not shotgun_dir.exists():
+        logger.debug("No .shotgun/ directory to backup")
+        return None
+
+    files_to_backup = list(shotgun_dir.rglob("*"))
+    if not any(f.is_file() for f in files_to_backup):
+        logger.debug(".shotgun/ directory is empty, skipping backup")
+        return None
+
+    # Create backup directory if needed
+    BACKUP_DIR.mkdir(parents=True, exist_ok=True)
+
+    # Generate timestamp-based filename
+    timestamp = datetime.now(timezone.utc).strftime("%Y%m%d_%H%M%S")
+    backup_path = BACKUP_DIR / f"{timestamp}.zip"
+
+    logger.info("Creating backup of .shotgun/ at %s", backup_path)
+
+    # Create zip file
+    with zipfile.ZipFile(backup_path, "w", zipfile.ZIP_DEFLATED) as zipf:
+        for file_path in files_to_backup:
+            if file_path.is_file():
+                # Store with path relative to shotgun_dir
+                arcname = file_path.relative_to(shotgun_dir)
+                zipf.write(file_path, arcname)
+                logger.debug("Added to backup: %s", arcname)
+
+    logger.info("Backup created successfully: %s", backup_path)
+    return str(backup_path)
+
+
+def clear_shotgun_dir(shotgun_dir: Path) -> None:
+    """Clear all contents of the .shotgun/ directory.
+
+    Removes all files and subdirectories but keeps the .shotgun/ directory itself.
+
+    Args:
+        shotgun_dir: Path to the .shotgun/ directory to clear
+    """
+    if not shotgun_dir.exists():
+        return
+
+    for item in shotgun_dir.iterdir():
+        if item.is_dir():
+            shutil.rmtree(item)
+        else:
+            item.unlink()
+
+    logger.debug("Cleared contents of %s", shotgun_dir)

shotgun/cli/spec/commands.py

@@ -0,0 +1,132 @@
+"""Spec management commands for shotgun CLI."""
+
+import asyncio
+from typing import Annotated
+
+import typer
+from rich.console import Console
+from rich.progress import BarColumn, Progress, SpinnerColumn, TaskID, TextColumn
+
+from shotgun.logging_config import get_logger
+from shotgun.shotgun_web.exceptions import (
+    ForbiddenError,
+    NotFoundError,
+    UnauthorizedError,
+)
+from shotgun.tui import app as tui_app
+from shotgun.utils.file_system_utils import get_shotgun_base_path
+
+from .models import PullSource
+from .pull_service import CancelledError, PullProgress, SpecPullService
+
+app = typer.Typer(
+    name="spec",
+    help="Manage shared specifications",
+    no_args_is_help=True,
+)
+logger = get_logger(__name__)
+console = Console()
+
+
+@app.command()
+def pull(
+    version_id: Annotated[str, typer.Argument(help="Version ID to pull")],
+    no_tui: Annotated[
+        bool,
+        typer.Option("--no-tui", help="Run in CLI-only mode (requires existing auth)"),
+    ] = False,
+) -> None:
+    """Pull a spec version from the cloud to local .shotgun/ directory.
+
+    Downloads all files for the specified version and writes them to the
+    local .shotgun/ directory. If the directory already has content, it
+    will be backed up to ~/.shotgun-sh/backups/ before being replaced.
+
+    By default, launches the TUI which handles authentication and shows
+    the pull progress. Use --no-tui for scripted/headless use (requires
+    existing authentication).
+
+    Example:
+        shotgun spec pull 2532e1c7-7068-4d23-9379-58ea439c592f
+    """
+    if no_tui:
+        # CLI-only mode: do pull directly (requires existing auth)
+        success = asyncio.run(_async_pull(version_id))
+        if not success:
+            raise typer.Exit(1)
+    else:
+        # TUI mode: launch TUI which handles auth and pull
+        tui_app.run(pull_version_id=version_id)
+
+
+async def _async_pull(version_id: str) -> bool:
+    """Async implementation of spec pull command.
+
+    Returns:
+        True if pull was successful, False otherwise.
+    """
+    shotgun_dir = get_shotgun_base_path()
+    service = SpecPullService()
+
+    # Track current progress state for rich display
+    current_task_id: TaskID | None = None
+    progress_ctx: Progress | None = None
+
+    def on_progress(p: PullProgress) -> None:
+        nonlocal current_task_id, progress_ctx
+        # For CLI, we just update the description - progress bar handled by result
+        if progress_ctx and current_task_id is not None:
+            progress_ctx.update(current_task_id, description=p.phase)
+            if p.total_files and p.file_index is not None:
+                pct = ((p.file_index + 1) / p.total_files) * 100
+                progress_ctx.update(current_task_id, completed=pct)
+
+    try:
+        with Progress(
+            SpinnerColumn(),
+            TextColumn("[progress.description]{task.description}"),
+            BarColumn(),
+            TextColumn("[progress.percentage]{task.percentage:>3.0f}%"),
+        ) as progress:
+            progress_ctx = progress
+            current_task_id = progress.add_task("Starting...", total=100)
+
+            result = await service.pull_version(
+                version_id=version_id,
+                shotgun_dir=shotgun_dir,
+                on_progress=on_progress,
+                source=PullSource.CLI,
+            )
+
+        if result.success:
+            console.print()
+            console.print(f"[green]Successfully pulled '{result.spec_name}'[/green]")
+            console.print(f"  [dim]Files downloaded:[/dim] {result.file_count}")
+            if result.backup_path:
+                console.print(f"  [dim]Previous backup:[/dim] {result.backup_path}")
+            if result.web_url:
+                console.print(f"  [blue]View in browser:[/blue] {result.web_url}")
+            return True
+        else:
+            console.print(f"[red]Error: {result.error}[/red]")
+            return False
+
+    except UnauthorizedError:
+        console.print(
+            "[red]Not authenticated. Please re-run the command to login.[/red]"
+        )
+        raise typer.Exit(1) from None
+    except NotFoundError:
+        console.print(f"[red]Version not found: {version_id}[/red]")
+        console.print("[dim]Check the version ID and try again.[/dim]")
+        raise typer.Exit(1) from None
+    except ForbiddenError:
+        console.print("[red]You don't have access to this spec.[/red]")
+        raise typer.Exit(1) from None
+    except CancelledError:
+        console.print("[yellow]Pull cancelled.[/yellow]")
+        raise typer.Exit(1) from None
+    except Exception as e:
+        logger.exception("Unexpected error in spec pull")
+        console.print(f"[red]Unexpected error: {e}[/red]")
+        raise typer.Exit(1) from None