shotgun-sh 0.2.7.dev1__py3-none-any.whl → 0.2.8.dev1__py3-none-any.whl

shotgun/agents/agent_manager.py

@@ -4,9 +4,17 @@ import json
 import logging
 from collections.abc import AsyncIterable, Sequence
 from dataclasses import dataclass, field, is_dataclass, replace
+from pathlib import Path
 from typing import TYPE_CHECKING, Any, cast
 
 import logfire
+from tenacity import (
+    before_sleep_log,
+    retry,
+    retry_if_exception,
+    stop_after_attempt,
+    wait_exponential,
+)
 
 if TYPE_CHECKING:
     from shotgun.agents.conversation_history import ConversationState
@@ -55,6 +63,35 @@ from .tasks import create_tasks_agent
 logger = logging.getLogger(__name__)
 
 
+def _is_retryable_error(exception: BaseException) -> bool:
+    """Check if exception should trigger a retry.
+
+    Args:
+        exception: The exception to check.
+
+    Returns:
+        True if the exception is a transient error that should be retried.
+    """
+    # ValueError for truncated/incomplete JSON
+    if isinstance(exception, ValueError):
+        error_str = str(exception)
+        return "EOF while parsing" in error_str or (
+            "JSON" in error_str and "parsing" in error_str
+        )
+
+    # API errors (overload, rate limits)
+    exception_name = type(exception).__name__
+    if "APIStatusError" in exception_name:
+        error_str = str(exception)
+        return "overload" in error_str.lower() or "rate" in error_str.lower()
+
+    # Network errors
+    if "ConnectionError" in exception_name or "TimeoutError" in exception_name:
+        return True
+
+    return False
+
+
 class MessageHistoryUpdated(Message):
     """Event posted when the message history is updated."""
 
@@ -268,6 +305,49 @@ class AgentManager(Widget):
                 f"Invalid agent type: {agent_type}. Must be one of: {', '.join(e.value for e in AgentType)}"
             ) from None
 
+    @retry(
+        stop=stop_after_attempt(3),
+        wait=wait_exponential(multiplier=1, min=1, max=8),
+        retry=retry_if_exception(_is_retryable_error),
+        before_sleep=before_sleep_log(logger, logging.WARNING),
+        reraise=True,
+    )
+    async def _run_agent_with_retry(
+        self,
+        agent: Agent[AgentDeps, AgentResponse],
+        prompt: str | None,
+        deps: AgentDeps,
+        usage_limits: UsageLimits | None,
+        message_history: list[ModelMessage],
+        event_stream_handler: Any,
+        **kwargs: Any,
+    ) -> AgentRunResult[AgentResponse]:
+        """Run agent with automatic retry on transient errors.
+
+        Args:
+            agent: The agent to run.
+            prompt: Optional prompt to send to the agent.
+            deps: Agent dependencies.
+            usage_limits: Optional usage limits.
+            message_history: Message history to provide to agent.
+            event_stream_handler: Event handler for streaming.
+            **kwargs: Additional keyword arguments.
+
+        Returns:
+            The agent run result.
+
+        Raises:
+            Various exceptions if all retries fail.
+        """
+        return await agent.run(
+            prompt,
+            deps=deps,
+            usage_limits=usage_limits,
+            message_history=message_history,
+            event_stream_handler=event_stream_handler,
+            **kwargs,
+        )
+
     async def run(
         self,
         prompt: str | None = None,
@@ -394,8 +474,9 @@ class AgentManager(Widget):
         )
 
         try:
-            result: AgentRunResult[AgentResponse] = await self.current_agent.run(
-                prompt,
+            result: AgentRunResult[AgentResponse] = await self._run_agent_with_retry(
+                agent=self.current_agent,
+                prompt=prompt,
                 deps=deps,
                 usage_limits=usage_limits,
                 message_history=message_history,
@@ -404,6 +485,36 @@ class AgentManager(Widget):
                 else None,
                 **kwargs,
             )
+        except ValueError as e:
+            # Handle truncated/incomplete JSON in tool calls specifically
+            error_str = str(e)
+            if "EOF while parsing" in error_str or (
+                "JSON" in error_str and "parsing" in error_str
+            ):
+                logger.error(
+                    "Tool call with truncated/incomplete JSON arguments detected",
+                    extra={
+                        "agent_mode": self._current_agent_type.value,
+                        "model_name": model_name,
+                        "error": error_str,
+                    },
+                )
+                logfire.error(
+                    "Tool call with truncated JSON arguments",
+                    agent_mode=self._current_agent_type.value,
+                    model_name=model_name,
+                    error=error_str,
+                )
+                # Add helpful hint message for the user
+                self.ui_message_history.append(
+                    HintMessage(
+                        message="⚠️ The agent attempted an operation with arguments that were too large (truncated JSON). "
+                        "Try breaking your request into smaller steps or more focused contracts."
+                    )
+                )
+                self._post_messages_updated()
+            # Re-raise to maintain error visibility
+            raise
         except Exception as e:
             # Log the error with full stack trace to shotgun.log and Logfire
             logger.exception(
@@ -427,13 +538,40 @@ class AgentManager(Widget):
 
         # Agent ALWAYS returns AgentResponse with structured output
         agent_response = result.output
-        logger.debug("Agent returned structured AgentResponse")
+        logger.debug(
+            "Agent returned structured AgentResponse",
+            extra={
+                "has_response": agent_response.response is not None,
+                "response_length": len(agent_response.response)
+                if agent_response.response
+                else 0,
+                "response_preview": agent_response.response[:100] + "..."
+                if agent_response.response and len(agent_response.response) > 100
+                else agent_response.response or "(empty)",
+                "has_clarifying_questions": bool(agent_response.clarifying_questions),
+                "num_clarifying_questions": len(agent_response.clarifying_questions)
+                if agent_response.clarifying_questions
+                else 0,
+            },
+        )
 
         # Always add the agent's response messages to maintain conversation history
         self.ui_message_history = original_messages + cast(
             list[ModelRequest | ModelResponse | HintMessage], result.new_messages()
         )
 
+        # Get file operations early so we can use them for contextual messages
+        file_operations = deps.file_tracker.operations.copy()
+        self.recently_change_files = file_operations
+
+        logger.debug(
+            "File operations tracked",
+            extra={
+                "num_file_operations": len(file_operations),
+                "operation_files": [Path(op.file_path).name for op in file_operations],
+            },
+        )
+
         # Check if there are clarifying questions
         if agent_response.clarifying_questions:
             logger.info(
@@ -480,12 +618,50 @@ class AgentManager(Widget):
                         response_text=agent_response.response,
                     )
                 )
+
+            # Post UI update with hint messages and file operations
+            logger.debug(
+                "Posting UI update for Q&A mode with hint messages and file operations"
+            )
+            self._post_messages_updated(file_operations)
         else:
-            # No clarifying questions - just show the response if present
+            # No clarifying questions - show the response or a default success message
             if agent_response.response and agent_response.response.strip():
+                logger.debug(
+                    "Adding agent response as hint",
+                    extra={
+                        "response_preview": agent_response.response[:100] + "..."
+                        if len(agent_response.response) > 100
+                        else agent_response.response,
+                        "has_file_operations": len(file_operations) > 0,
+                    },
+                )
                 self.ui_message_history.append(
                     HintMessage(message=agent_response.response)
                 )
+            else:
+                # Fallback: response is empty or whitespace
+                logger.debug(
+                    "Agent response was empty, using fallback completion message",
+                    extra={"has_file_operations": len(file_operations) > 0},
+                )
+                # Show contextual message based on whether files were modified
+                if file_operations:
+                    self.ui_message_history.append(
+                        HintMessage(
+                            message="✅ Task completed - files have been modified"
+                        )
+                    )
+                else:
+                    self.ui_message_history.append(
+                        HintMessage(message="✅ Task completed")
+                    )
+
+            # Post UI update immediately so user sees the response without delay
+            logger.debug(
+                "Posting immediate UI update with hint message and file operations"
+            )
+            self._post_messages_updated(file_operations)
 
         # Apply compaction to persistent message history to prevent cascading growth
         all_messages = result.all_messages()
@@ -517,16 +693,18 @@ class AgentManager(Widget):
             self.message_history = all_messages
 
         usage = result.usage()
-        deps.usage_manager.add_usage(
-            usage, model_name=deps.llm_model.name, provider=deps.llm_model.provider
-        )
-
-        # Log file operations summary if any files were modified
-        file_operations = deps.file_tracker.operations.copy()
-        self.recently_change_files = file_operations
+        if hasattr(deps, "llm_model") and deps.llm_model is not None:
+            deps.usage_manager.add_usage(
+                usage, model_name=deps.llm_model.name, provider=deps.llm_model.provider
+            )
+        else:
+            logger.warning(
+                "llm_model is None, skipping usage tracking",
+                extra={"agent_mode": self._current_agent_type.value},
+            )
 
-        # Post message history update (hints are now added synchronously above)
-        self._post_messages_updated(file_operations)
+        # UI updates are now posted immediately in each branch (Q&A or non-Q&A)
+        # before compaction, so no duplicate posting needed here
 
         return result
 

shotgun/agents/common.py

@@ -384,23 +384,48 @@ def get_agent_existing_files(agent_mode: AgentType | None = None) -> list[str]:
                     relative_path = file_path.relative_to(base_path)
                     existing_files.append(str(relative_path))
     else:
-        # For other agents, check both .md file and directory with same name
-        allowed_file = AGENT_DIRECTORIES[agent_mode]
-
-        # Check for the .md file
-        md_file_path = base_path / allowed_file
-        if md_file_path.exists():
-            existing_files.append(allowed_file)
-
-        # Check for directory with same base name (e.g., research/ for research.md)
-        base_name = allowed_file.replace(".md", "")
-        dir_path = base_path / base_name
-        if dir_path.exists() and dir_path.is_dir():
-            # List all files in the directory
-            for file_path in dir_path.rglob("*"):
-                if file_path.is_file():
-                    relative_path = file_path.relative_to(base_path)
-                    existing_files.append(str(relative_path))
+        # For other agents, check files/directories they have access to
+        allowed_paths_raw = AGENT_DIRECTORIES[agent_mode]
+
+        # Convert single Path/string to list of Paths for uniform handling
+        if isinstance(allowed_paths_raw, str):
+            # Special case: "*" means export agent (shouldn't reach here but handle it)
+            allowed_paths = (
+                [Path(allowed_paths_raw)] if allowed_paths_raw != "*" else []
+            )
+        elif isinstance(allowed_paths_raw, Path):
+            allowed_paths = [allowed_paths_raw]
+        else:
+            # Already a list
+            allowed_paths = allowed_paths_raw
+
+        # Check each allowed path
+        for allowed_path in allowed_paths:
+            allowed_str = str(allowed_path)
+
+            # Check if it's a directory (no .md suffix)
+            if not allowed_path.suffix or not allowed_str.endswith(".md"):
+                # It's a directory - list all files within it
+                dir_path = base_path / allowed_str
+                if dir_path.exists() and dir_path.is_dir():
+                    for file_path in dir_path.rglob("*"):
+                        if file_path.is_file():
+                            relative_path = file_path.relative_to(base_path)
+                            existing_files.append(str(relative_path))
+            else:
+                # It's a file - check if it exists
+                file_path = base_path / allowed_str
+                if file_path.exists():
+                    existing_files.append(allowed_str)
+
+                # Also check for associated directory (e.g., research/ for research.md)
+                base_name = allowed_str.replace(".md", "")
+                dir_path = base_path / base_name
+                if dir_path.exists() and dir_path.is_dir():
+                    for file_path in dir_path.rglob("*"):
+                        if file_path.is_file():
+                            relative_path = file_path.relative_to(base_path)
+                            existing_files.append(str(relative_path))
 
     return existing_files
 

shotgun/agents/tools/file_management.py

@@ -15,11 +15,18 @@ from shotgun.utils.file_system_utils import get_shotgun_base_path
 logger = get_logger(__name__)
 
 # Map agent modes to their allowed directories/files (in workflow order)
-AGENT_DIRECTORIES = {
-    AgentType.RESEARCH: "research.md",
-    AgentType.SPECIFY: "specification.md",
-    AgentType.PLAN: "plan.md",
-    AgentType.TASKS: "tasks.md",
+# Values can be:
+# - A Path: exact file (e.g., Path("research.md"))
+# - 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.SPECIFY: [
+        Path("specification.md"),
+        Path("contracts"),
+    ],  # Specify can write specs and contract files
+    AgentType.PLAN: Path("plan.md"),
+    AgentType.TASKS: Path("tasks.md"),
     AgentType.EXPORT: "*",  # Export agent can write anywhere except protected files
 }
 
@@ -60,13 +67,52 @@ def _validate_agent_scoped_path(filename: str, agent_mode: AgentType | None) ->
             # Allow writing anywhere else in .shotgun directory
             full_path = (base_path / filename).resolve()
         else:
-            # For other agents, only allow writing to their specific file
-            allowed_file = AGENT_DIRECTORIES[agent_mode]
-            if filename != allowed_file:
+            # For other agents, check if they have access to the requested file
+            allowed_paths_raw = AGENT_DIRECTORIES[agent_mode]
+
+            # Convert single Path/string to list of Paths for uniform handling
+            if isinstance(allowed_paths_raw, str):
+                # Special case: "*" means export agent
+                allowed_paths = (
+                    [Path(allowed_paths_raw)] if allowed_paths_raw != "*" else []
+                )
+            elif isinstance(allowed_paths_raw, Path):
+                allowed_paths = [allowed_paths_raw]
+            else:
+                # Already a list
+                allowed_paths = allowed_paths_raw
+
+            # Check if filename matches any allowed path
+            is_allowed = False
+            for allowed_path in allowed_paths:
+                allowed_str = str(allowed_path)
+
+                # Check if it's a directory (no .md extension or suffix)
+                # Directories: Path("contracts") has no suffix, files: Path("spec.md") has .md suffix
+                if not allowed_path.suffix or (
+                    allowed_path.suffix and not allowed_str.endswith(".md")
+                ):
+                    # Directory - allow any file within this directory
+                    # Check both "contracts/file.py" and "contracts" prefix
+                    if (
+                        filename.startswith(allowed_str + "/")
+                        or filename == allowed_str
+                    ):
+                        is_allowed = True
+                        break
+                else:
+                    # Exact file match
+                    if filename == allowed_str:
+                        is_allowed = True
+                        break
+
+            if not is_allowed:
+                allowed_display = ", ".join(f"'{p}'" for p in allowed_paths)
                 raise ValueError(
-                    f"{agent_mode.value.capitalize()} agent can only write to '{allowed_file}'. "
+                    f"{agent_mode.value.capitalize()} agent can only write to {allowed_display}. "
                     f"Attempted to write to '{filename}'"
                 )
+
             full_path = (base_path / filename).resolve()
     else:
         # No agent mode specified, fall back to old validation

shotgun/main.py

@@ -125,6 +125,34 @@ def main(
             help="Continue previous TUI conversation",
         ),
     ] = False,
+    web: Annotated[
+        bool,
+        typer.Option(
+            "--web",
+            help="Serve TUI as web application",
+        ),
+    ] = False,
+    port: Annotated[
+        int,
+        typer.Option(
+            "--port",
+            help="Port for web server (only used with --web)",
+        ),
+    ] = 8000,
+    host: Annotated[
+        str,
+        typer.Option(
+            "--host",
+            help="Host address for web server (only used with --web)",
+        ),
+    ] = "localhost",
+    public_url: Annotated[
+        str | None,
+        typer.Option(
+            "--public-url",
+            help="Public URL if behind proxy (only used with --web)",
+        ),
+    ] = None,
 ) -> None:
     """Shotgun - AI-powered CLI tool."""
     logger.debug("Starting shotgun CLI application")
@@ -134,16 +162,32 @@ def main(
         perform_auto_update_async(no_update_check=no_update_check)
 
     if ctx.invoked_subcommand is None and not ctx.resilient_parsing:
-        logger.debug("Launching shotgun TUI application")
-        try:
-            tui_app.run(
-                no_update_check=no_update_check, continue_session=continue_session
-            )
-        finally:
-            # Ensure PostHog is shut down cleanly even if TUI exits unexpectedly
-            from shotgun.posthog_telemetry import shutdown
-
-            shutdown()
+        if web:
+            logger.debug("Launching shotgun TUI as web application")
+            try:
+                tui_app.serve(
+                    host=host,
+                    port=port,
+                    public_url=public_url,
+                    no_update_check=no_update_check,
+                    continue_session=continue_session,
+                )
+            finally:
+                # Ensure PostHog is shut down cleanly even if server exits unexpectedly
+                from shotgun.posthog_telemetry import shutdown
+
+                shutdown()
+        else:
+            logger.debug("Launching shotgun TUI application")
+            try:
+                tui_app.run(
+                    no_update_check=no_update_check, continue_session=continue_session
+                )
+            finally:
+                # Ensure PostHog is shut down cleanly even if TUI exits unexpectedly
+                from shotgun.posthog_telemetry import shutdown
+
+                shutdown()
         raise typer.Exit()
 
     # For CLI commands, register PostHog shutdown handler

shotgun/prompts/agents/specify.j2

@@ -8,14 +8,281 @@ Transform requirements into detailed, actionable specifications that development
 
 ## MEMORY MANAGEMENT PROTOCOL
 
-- You have exclusive write access to: `specification.md`
+- You have exclusive write access to: `specification.md` and `.shotgun/contracts/*`
 - SHOULD READ `research.md` for context but CANNOT write to it
-- This is your persistent memory store - ALWAYS load it first
+- **specification.md is for PROSE ONLY** - no code, no implementation details, no type definitions
+- **All code goes in .shotgun/contracts/** - types, interfaces, schemas
+- specification.md describes WHAT and WHY, contracts/ show HOW with actual code
+- This is your persistent memory store - ALWAYS load specification.md first
 - Compress content regularly to stay within context limits
-- Keep your file updated as you work - it's your memory across sessions
+- Keep your files updated as you work - they're your memory across sessions
 - When adding new specifications, review and consolidate overlapping requirements
 - Structure specifications for easy reference by the next agents
 
+## WHAT GOES IN SPECIFICATION.MD
+
+specification.md is your prose documentation file. It should contain:
+
+**INCLUDE in specification.md:**
+- Requirements and business context (what needs to be built and why)
+- Architecture overview and system design decisions
+- Component descriptions and how they interact
+- User workflows and use cases
+- Directory structure as succinct prose (e.g., "src/ contains main code, tests/ contains test files")
+- Dependencies listed in prose (e.g., "Requires TypeScript 5.0+, React 18, and PostgreSQL")
+- Configuration requirements described (e.g., "App needs database URL and API key in environment")
+- Testing strategies and acceptance criteria
+- References to contract files (e.g., "See contracts/user_models.py for User type definition")
+
+**DO NOT INCLUDE in specification.md:**
+- Code blocks, type definitions, or function signatures (those go in contracts/)
+- Implementation details or algorithms (describe behavior instead)
+- Actual configuration files or build manifests (describe what's needed instead)
+- Directory trees or file listings (keep structure descriptions succinct)
+
+**When you need to show structure:** Reference contract files instead of inline code.
+Example: "User authentication uses OAuth2. See contracts/auth_types.ts for AuthUser and AuthToken types."
+
+## CONTRACT FILES
+
+Contract files define the **interfaces and types** that form contracts between components.
+They contain actual code that shows structure, not prose descriptions.
+
+**ONLY put these in `.shotgun/contracts/` (language-agnostic):**
+- **Type definitions ONLY** - Shape and structure, NO behavior or logic:
+  - Python: Pydantic models, dataclasses, `typing.Protocol` classes (interface definitions)
+  - TypeScript: interfaces, type aliases
+  - Rust: struct definitions
+  - Java: interfaces, POJOs
+  - C++: header files with class/struct declarations
+  - Go: interface types, struct definitions
+- **Schema definitions**: API contracts and data schemas
+  - OpenAPI/Swagger specs (openapi.json, openapi.yaml)
+  - JSON Schema definitions
+  - GraphQL schemas
+  - Protobuf definitions
+- **Protocol/Interface classes**: Pure interface definitions with method signatures only
+  - Python: `class Storage(Protocol): def save(self, data: str) -> None: ...`
+  - Use `...` (Ellipsis) for protocol methods, NOT `pass`
+
+**NEVER put these in `.shotgun/contracts/` - NO EXECUTABLE CODE:**
+- ❌ **Functions or methods with implementations** (even with `pass` or empty bodies)
+- ❌ **Helper functions** with any logic whatsoever
+- ❌ **Classes with method implementations** (use Protocol classes instead)
+- ❌ **Standalone functions** like `def main(): pass` or `def validate_input(x): ...`
+- ❌ **Code with behavior**: loops, conditionals, data manipulation, computations
+- ❌ **Data constants**: dictionaries, lists, or any runtime values
+- ❌ **`if __name__ == "__main__":` blocks** or any executable code
+- Build/dependency configs (pyproject.toml, package.json, Cargo.toml, requirements.txt)
+- Directory structure files (directory_structure.txt)
+- Configuration templates (.env, config.yaml, example configs)
+- Documentation or markdown files
+- SQL migration files or database dumps
+
+**These belong in specification.md instead:**
+- Directory structure (as succinct prose: "src/ contains modules, tests/ has unit tests")
+- Dependencies (as prose: "Requires Rust 1.70+, tokio, serde")
+- Configuration needs (describe: "App needs DB_URL and API_KEY environment variables")
+
+**Guidelines for contract files:**
+- Keep each file focused on a single domain (e.g., user_types.ts, payment_models.py)
+- Reference from specification.md: "See contracts/user_types.ts for User and Profile types"
+- Use descriptive filenames: `auth_models.py`, `api_spec.json`, `database_types.rs`
+- Keep files under 500 lines to avoid truncation
+- When contracts grow large, split into focused files
+
+**Example workflow:**
+1. In specification.md: "Authentication system with JWT tokens. See contracts/auth_types.ts for types."
+2. Create contract file: `write_file("contracts/auth_types.ts", content)` with actual TypeScript interfaces
+3. Create contract file: `write_file("contracts/auth_api.json", content)` with actual OpenAPI spec
+4. Coding agents can directly use these contracts to implement features
+
+## HOW TO WRITE CONTRACT FILES
+
+**CRITICAL - Always use correct file paths with write_file():**
+
+Your working directory is `.shotgun/`, so paths should be relative to that directory.
+
+<GOOD_EXAMPLES>
+✅ `write_file("contracts/user_models.py", content)` - Correct path for Python models
+✅ `write_file("contracts/auth_types.ts", content)` - Correct path for TypeScript types
+✅ `write_file("contracts/api_spec.json", content)` - Correct path for OpenAPI spec
+✅ `write_file("contracts/payment_service.rs", content)` - Correct path for Rust code
+</GOOD_EXAMPLES>
+
+<BAD_EXAMPLES>
+❌ `write_file(".shotgun/contracts/user_models.py", content)` - WRONG! Don't include .shotgun/ prefix
+❌ `write_file("contracts/directory_structure.txt", content)` - WRONG! No documentation files
+❌ `write_file("contracts/pyproject.toml", content)` - WRONG! No build configs in contracts/
+❌ `write_file("contracts/requirements.txt", content)` - WRONG! No dependency lists in contracts/
+❌ `write_file("contracts/config.yaml", content)` - WRONG! No config templates in contracts/
+</BAD_EXAMPLES>
+
+**Path format rule:** Always use `contracts/filename.ext`, never `.shotgun/contracts/filename.ext`
+
+**Language-specific examples:**
+
+<PYTHON_EXAMPLE>
+# Python Pydantic model contract
+from pydantic import BaseModel, Field
+from typing import Optional
+
+class User(BaseModel):
+    """User model contract."""
+    id: int
+    email: str = Field(..., description="User email address")
+    username: str
+    is_active: bool = True
+    role: Optional[str] = None
+
+# Save as: write_file("contracts/user_models.py", content)
+</PYTHON_EXAMPLE>
+
+<TYPESCRIPT_EXAMPLE>
+// TypeScript interface contract
+interface User {
+  id: number;
+  email: string;
+  username: string;
+  isActive: boolean;
+  role?: string;
+}
+
+interface AuthToken {
+  token: string;
+  expiresAt: Date;
+  userId: number;
+}
+
+// Save as: write_file("contracts/auth_types.ts", content)
+</TYPESCRIPT_EXAMPLE>
+
+<RUST_EXAMPLE>
+// Rust struct contract
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Serialize, Deserialize)]
+pub struct User {
+    pub id: u64,
+    pub email: String,
+    pub username: String,
+    pub is_active: bool,
+    pub role: Option<String>,
+}
+
+// Save as: write_file("contracts/user_types.rs", content)
+</RUST_EXAMPLE>
+
+<OPENAPI_EXAMPLE>
+{
+  "openapi": "3.0.0",
+  "info": {
+    "title": "User API",
+    "version": "1.0.0"
+  },
+  "paths": {
+    "/users": {
+      "get": {
+        "summary": "List users",
+        "responses": {
+          "200": {
+            "description": "Successful response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "array",
+                  "items": { "$ref": "#/components/schemas/User" }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "User": {
+        "type": "object",
+        "properties": {
+          "id": { "type": "integer" },
+          "email": { "type": "string" },
+          "username": { "type": "string" }
+        }
+      }
+    }
+  }
+}
+
+// Save as: write_file("contracts/user_api.json", content)
+</OPENAPI_EXAMPLE>
+
+## WHAT IS ALLOWED vs WHAT IS FORBIDDEN
+
+**✅ ALLOWED - Type Definitions (Shape and Structure):**
+
+```python
+# ✅ GOOD: Pydantic model (type definition)
+from pydantic import BaseModel
+
+class User(BaseModel):
+    id: int
+    email: str
+    username: str
+
+# ✅ GOOD: Protocol class (interface definition)
+from typing import Protocol
+
+class Storage(Protocol):
+    def save(self, data: str) -> None: ...
+    def load(self) -> str: ...
+
+# ✅ GOOD: Type aliases and enums
+from typing import Literal
+from enum import Enum
+
+UserRole = Literal["admin", "user", "guest"]
+
+class Status(Enum):
+    ACTIVE = "active"
+    INACTIVE = "inactive"
+```
+
+**❌ FORBIDDEN - Executable Code (Behavior and Logic):**
+
+```python
+# ❌ BAD: Function with pass (executable code)
+def main() -> int:
+    pass
+
+# ❌ BAD: Function with implementation
+def validate_input(x: str) -> str:
+    return x.strip()
+
+# ❌ BAD: Class with method implementations
+class HistoryManager:
+    def __init__(self):
+        pass
+
+    def add_message(self, msg: str):
+        pass
+
+# ❌ BAD: Data constants (runtime values)
+SUPPORTED_PROVIDERS = [
+    {"name": "openai", "key": "OPENAI_API_KEY"}
+]
+
+# ❌ BAD: Helper functions
+def get_default_config() -> dict:
+    return {"model": "gpt-4"}
+
+# ❌ BAD: Executable code blocks
+if __name__ == "__main__":
+    main()
+```
+
+**Remember**: Contracts define **SHAPES** (types, interfaces, schemas), NOT **BEHAVIOR** (functions, logic, implementations).
+
 ## AI AGENT PIPELINE AWARENESS
 
 **CRITICAL**: Your output will be consumed by AI coding agents (Claude Code, Cursor, Windsurf, etc.)

shotgun/tui/app.py

@@ -152,5 +152,121 @@ def run(no_update_check: bool = False, continue_session: bool = False) -> None:
     app.run(inline_no_clear=True)
 
 
+def serve(
+    host: str = "localhost",
+    port: int = 8000,
+    public_url: str | None = None,
+    no_update_check: bool = False,
+    continue_session: bool = False,
+) -> None:
+    """Serve the TUI application as a web application.
+
+    Args:
+        host: Host address for the web server.
+        port: Port number for the web server.
+        public_url: Public URL if behind a proxy.
+        no_update_check: If True, disable automatic update checks.
+        continue_session: If True, continue from previous conversation.
+    """
+    # Clean up any corrupted databases BEFORE starting the TUI
+    # This prevents crashes from corrupted databases during initialization
+    import asyncio
+
+    from textual_serve.server import Server
+
+    from shotgun.codebase.core.manager import CodebaseGraphManager
+    from shotgun.utils import get_shotgun_home
+
+    storage_dir = get_shotgun_home() / "codebases"
+    manager = CodebaseGraphManager(storage_dir)
+
+    try:
+        removed = asyncio.run(manager.cleanup_corrupted_databases())
+        if removed:
+            logger.info(
+                f"Cleaned up {len(removed)} corrupted database(s) before TUI startup"
+            )
+    except Exception as e:
+        logger.error(f"Failed to cleanup corrupted databases: {e}")
+        # Continue anyway - the TUI can still function
+
+    # Create a new event loop after asyncio.run() closes the previous one
+    # This is needed for the Server.serve() method
+    loop = asyncio.new_event_loop()
+    asyncio.set_event_loop(loop)
+
+    # Build the command string based on flags
+    command = "shotgun"
+    if no_update_check:
+        command += " --no-update-check"
+    if continue_session:
+        command += " --continue"
+
+    # Create and start the server with hardcoded title and debug=False
+    server = Server(
+        command=command,
+        host=host,
+        port=port,
+        title="The Shotgun",
+        public_url=public_url,
+    )
+
+    # Set up graceful shutdown on SIGTERM/SIGINT
+    import signal
+    import sys
+
+    def signal_handler(_signum: int, _frame: Any) -> None:
+        """Handle shutdown signals gracefully."""
+        from shotgun.posthog_telemetry import shutdown
+
+        logger.info("Received shutdown signal, cleaning up...")
+        # Restore stdout/stderr before shutting down
+        sys.stdout = original_stdout
+        sys.stderr = original_stderr
+        shutdown()
+        sys.exit(0)
+
+    signal.signal(signal.SIGTERM, signal_handler)
+    signal.signal(signal.SIGINT, signal_handler)
+
+    # Suppress the textual-serve banner by redirecting stdout/stderr
+    import io
+
+    # Capture and suppress the banner, but show the actual serving URL
+    original_stdout = sys.stdout
+    original_stderr = sys.stderr
+
+    captured_output = io.StringIO()
+    sys.stdout = captured_output
+    sys.stderr = captured_output
+
+    try:
+        # This will print the banner to our captured output
+        import logging
+
+        # Temporarily set logging to ERROR level to suppress INFO messages
+        textual_serve_logger = logging.getLogger("textual_serve")
+        original_level = textual_serve_logger.level
+        textual_serve_logger.setLevel(logging.ERROR)
+
+        # Print our own message to the original stdout
+        sys.stdout = original_stdout
+        sys.stderr = original_stderr
+        print(f"Serving Shotgun TUI at http://{host}:{port}")
+        print("Press Ctrl+C to quit")
+
+        # Now suppress output again for the serve call
+        sys.stdout = captured_output
+        sys.stderr = captured_output
+
+        server.serve(debug=False)
+    finally:
+        # Restore original stdout/stderr
+        sys.stdout = original_stdout
+        sys.stderr = original_stderr
+        if "textual_serve_logger" in locals():
+            textual_serve_logger.setLevel(original_level)
+
+
 if __name__ == "__main__":
     run()

{shotgun_sh-0.2.7.dev1.dist-info → shotgun_sh-0.2.8.dev1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shotgun-sh
-Version: 0.2.7.dev1
+Version: 0.2.8.dev1
 Summary: AI-powered research, planning, and task management CLI tool
 Project-URL: Homepage, https://shotgun.sh/
 Project-URL: Repository, https://github.com/shotgun-sh/shotgun
@@ -34,7 +34,9 @@ Requires-Dist: pydantic-ai>=0.0.14
 Requires-Dist: rich>=13.0.0
 Requires-Dist: sentencepiece>=0.2.0
 Requires-Dist: sentry-sdk[pure-eval]>=2.0.0
+Requires-Dist: tenacity>=8.0.0
 Requires-Dist: textual-dev>=1.7.0
+Requires-Dist: textual-serve>=0.1.0
 Requires-Dist: textual>=6.1.0
 Requires-Dist: tiktoken>=0.7.0
 Requires-Dist: tree-sitter-go>=0.23.0

{shotgun_sh-0.2.7.dev1.dist-info → shotgun_sh-0.2.8.dev1.dist-info}/RECORD

@@ -2,14 +2,14 @@ shotgun/__init__.py,sha256=P40K0fnIsb7SKcQrFnXZ4aREjpWchVDhvM1HxI4cyIQ,104
 shotgun/api_endpoints.py,sha256=TvxuJyMrZLy6KZTrR6lrdkG8OBtb3TJ48qaw3pWitO0,526
 shotgun/build_constants.py,sha256=RXNxMz46HaB5jucgMVpw8a2yCJqjbhTOh0PddyEVMN8,713
 shotgun/logging_config.py,sha256=UKenihvgH8OA3W0b8ZFcItYaFJVe9MlsMYlcevyW1HY,7440
-shotgun/main.py,sha256=RA3q1xPfqxCu43UmgI2ryZpA-IxPhJb_MJrbLqp9c_g,5140
+shotgun/main.py,sha256=8t-jw4KZAlvUVvoqMlp0rTVCXtJx4herSheI2N8i-8Y,6445
 shotgun/posthog_telemetry.py,sha256=TOiyBtLg21SttHGWKc4-e-PQgpbq6Uz_4OzlvlxMcZ0,6099
 shotgun/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 shotgun/sentry_telemetry.py,sha256=VD8es-tREfgtRKhDsEVvqpo0_kM_ab6iVm2lkOEmTlI,2950
 shotgun/telemetry.py,sha256=C8dM7Feo1OxJMwDvgAMaA2RyRDO2rYPvC_8kLBuRUS8,3683
 shotgun/agents/__init__.py,sha256=8Jzv1YsDuLyNPFJyckSr_qI4ehTVeDyIMDW4omsfPGc,25
-shotgun/agents/agent_manager.py,sha256=Fjm_7fDqmaqWgjAgGiiIdMNnK0ahanLLZ4bxJIbrMlE,32611
-shotgun/agents/common.py,sha256=g8QW782XZfZHjAJPC6k2uXqoX4UZufvbGaejzWgya8E,17768
+shotgun/agents/agent_manager.py,sha256=CgG_Cj1P_ZB7wzwvqqqJ5gxOUVKTGy_o0VS4eaB7NqI,39522
+shotgun/agents/common.py,sha256=0F_dwEc72APvbY1b-lqM9VgPYuY1GpfhjSWv5-1pCB0,19032
 shotgun/agents/conversation_history.py,sha256=c-1PBaG9FXPfSmekWtrD6s6YVT0sd98DdDhzS4a1Hyo,7859
 shotgun/agents/conversation_manager.py,sha256=X3DWZZIqrv0hS1SUasyoxexnLPBUrZMBg4ZmRAipkBE,4429
 shotgun/agents/export.py,sha256=7ZNw7781WJ4peLSeoUc7zxKeaZVxFpow2y4nU4dCfbo,2919
@@ -42,7 +42,7 @@ shotgun/agents/history/token_counting/sentencepiece_counter.py,sha256=qj1bT7J5nC
 shotgun/agents/history/token_counting/tokenizer_cache.py,sha256=Y0V6KMtEwn42M5-zJGAc7YudM8X6m5-j2ekA6YGL5Xk,2868
 shotgun/agents/history/token_counting/utils.py,sha256=d124IDjtd0IYBYrr3gDJGWxSbdP10Vrc7ZistbUosMg,5002
 shotgun/agents/tools/__init__.py,sha256=kYppd4f4MoJcfTEPzkY2rqtxL1suXRGa9IRUm1G82GY,717
-shotgun/agents/tools/file_management.py,sha256=HYNe_QA4T3_bPzSWBYcFZcnWdj8eb4aQ3GB735-G8Nw,7138
+shotgun/agents/tools/file_management.py,sha256=7qj2yxzOC_40_swuBIcRcFv6MSZM78mNfsV3SCL_sH4,9205
 shotgun/agents/tools/codebase/__init__.py,sha256=ceAGkK006NeOYaIJBLQsw7Q46sAyCRK9PYDs8feMQVw,661
 shotgun/agents/tools/codebase/codebase_shell.py,sha256=9b7ZStAVFprdGqp1O23ZgwkToMytlUdp_R4MhvmENhc,8584
 shotgun/agents/tools/codebase/directory_lister.py,sha256=eX5GKDSmbKggKDvjPpYMa2WPSGPYQAtUEZ4eN01T0t8,4703
@@ -90,7 +90,7 @@ shotgun/prompts/agents/__init__.py,sha256=YRIJMbzpArojNX1BP5gfxxois334z_GQga8T-x
 shotgun/prompts/agents/export.j2,sha256=DGqVijH1PkpkY0rDauU52u_fMv15frEvOdXAPFZNMM4,17057
 shotgun/prompts/agents/plan.j2,sha256=mbt505NdqmzmPxXzQYJS_gH5vkiVa2a3Dgz2K-15JZk,6093
 shotgun/prompts/agents/research.j2,sha256=QFoSSiF_5v7c78RHaiucZEb9mOC_wF54BVKnJEH_DnI,3964
-shotgun/prompts/agents/specify.j2,sha256=AP7XrA3KE7GZsCvW4guASxZHBM2mnrMw3irdZ3RUOBs,2808
+shotgun/prompts/agents/specify.j2,sha256=XdB2WehbVmszw9crl6PEHLyLgwvU08MV--ClV3hI4mA,12014
 shotgun/prompts/agents/tasks.j2,sha256=SMvTQPzRR6eHlW3fcj-7Bl-Lh9HWaiF3uAKv77nMdZw,5956
 shotgun/prompts/agents/partials/codebase_understanding.j2,sha256=7WH-PVd-TRBFQUdOdKkwwn9hAUaJznFZMAGHhO7IGGU,5633
 shotgun/prompts/agents/partials/common_agent_system_prompt.j2,sha256=wfjsQGcMTWWGBk9l0pKDnPehG8NrwTHm5FFEqba__LI,2161
@@ -119,7 +119,7 @@ shotgun/shotgun_web/client.py,sha256=n5DDuVfSa6VPZjhSsfSxQlSFOnhgDHyidRnB8Hv9XF4
 shotgun/shotgun_web/constants.py,sha256=eNvtjlu81bAVQaCwZXOVjSpDopUm9pf34XuZEvuMiko,661
 shotgun/shotgun_web/models.py,sha256=Ie9VfqKZM2tIJhIjentU9qLoNaMZvnUJaIu-xg9kQsA,1391
 shotgun/tui/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-shotgun/tui/app.py,sha256=B2tKbXeGhWBIVec1jJHGAuBcP1SMbO_6xol2OaBpw2Y,5374
+shotgun/tui/app.py,sha256=dBoniec5iscVozM7BTDiKAwMWLUvzw2CioLiTqtmoqo,9184
 shotgun/tui/filtered_codebase_service.py,sha256=lJ8gTMhIveTatmvmGLP299msWWTkVYKwvY_2FhuL2s4,1687
 shotgun/tui/styles.tcss,sha256=ETyyw1bpMBOqTi5RLcAJUScdPWTvAWEqE9YcT0kVs_E,121
 shotgun/tui/commands/__init__.py,sha256=8D5lvtpqMW5-fF7Bg3oJtUzU75cKOv6aUaHYYszydU8,2518
@@ -148,8 +148,8 @@ shotgun/utils/env_utils.py,sha256=ulM3BRi9ZhS7uC-zorGeDQm4SHvsyFuuU9BtVPqdrHY,14
 shotgun/utils/file_system_utils.py,sha256=l-0p1bEHF34OU19MahnRFdClHufThfGAjQ431teAIp0,1004
 shotgun/utils/source_detection.py,sha256=Co6Q03R3fT771TF3RzB-70stfjNP2S4F_ArZKibwzm8,454
 shotgun/utils/update_checker.py,sha256=IgzPHRhS1ETH7PnJR_dIx6lxgr1qHpCkMTgzUxvGjhI,7586
-shotgun_sh-0.2.7.dev1.dist-info/METADATA,sha256=MEaQlu9HJSSTi9_WuCgVgC8nX5J34O8PzyP8b8mCj_4,4268
-shotgun_sh-0.2.7.dev1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-shotgun_sh-0.2.7.dev1.dist-info/entry_points.txt,sha256=asZxLU4QILneq0MWW10saVCZc4VWhZfb0wFZvERnzfA,45
-shotgun_sh-0.2.7.dev1.dist-info/licenses/LICENSE,sha256=YebsZl590zCHrF_acCU5pmNt0pnAfD2DmAnevJPB1tY,1065
-shotgun_sh-0.2.7.dev1.dist-info/RECORD,,
+shotgun_sh-0.2.8.dev1.dist-info/METADATA,sha256=razgwSFigJNH56uBlRPZ8yxyQjjvThAbMZpHlPI4_JY,4335
+shotgun_sh-0.2.8.dev1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+shotgun_sh-0.2.8.dev1.dist-info/entry_points.txt,sha256=asZxLU4QILneq0MWW10saVCZc4VWhZfb0wFZvERnzfA,45
+shotgun_sh-0.2.8.dev1.dist-info/licenses/LICENSE,sha256=YebsZl590zCHrF_acCU5pmNt0pnAfD2DmAnevJPB1tY,1065
+shotgun_sh-0.2.8.dev1.dist-info/RECORD,,