shotgun-sh 0.2.6.dev5__py3-none-any.whl → 0.2.7.dev2__py3-none-any.whl

shotgun/agents/history/context_extraction.py

@@ -1,5 +1,9 @@
 """Context extraction utilities for history processing."""
 
+import json
+import logging
+import traceback
+
 from pydantic_ai.messages import (
     BuiltinToolCallPart,
     BuiltinToolReturnPart,
@@ -16,6 +20,46 @@ from pydantic_ai.messages import (
     UserPromptPart,
 )
 
+logger = logging.getLogger(__name__)
+
+
+def _safely_parse_tool_args(args: dict[str, object] | str | None) -> dict[str, object]:
+    """Safely parse tool call arguments, handling incomplete/invalid JSON.
+
+    Args:
+        args: Tool call arguments (dict, JSON string, or None)
+
+    Returns:
+        Parsed args dict, or empty dict if parsing fails
+    """
+    if args is None:
+        return {}
+
+    if isinstance(args, dict):
+        return args
+
+    if not isinstance(args, str):
+        return {}
+
+    try:
+        parsed = json.loads(args)
+        return parsed if isinstance(parsed, dict) else {}
+    except (json.JSONDecodeError, ValueError) as e:
+        # Only log warning if it looks like JSON (starts with { or [) - incomplete JSON
+        # Plain strings are valid args and shouldn't trigger warnings
+        stripped_args = args.strip()
+        if stripped_args.startswith(("{", "[")):
+            args_preview = args[:100] + "..." if len(args) > 100 else args
+            logger.warning(
+                "Detected incomplete/invalid JSON in tool call args during parsing",
+                extra={
+                    "args_preview": args_preview,
+                    "error": str(e),
+                    "args_length": len(args),
+                },
+            )
+        return {}
+
 
 def extract_context_from_messages(messages: list[ModelMessage]) -> str:
     """Extract context from a list of messages for summarization."""
@@ -87,12 +131,55 @@ def extract_context_from_part(
         return f"<ASSISTANT_TEXT>\n{message_part.content}\n</ASSISTANT_TEXT>"
 
     elif isinstance(message_part, ToolCallPart):
-        if isinstance(message_part.args, dict):
-            args_str = ", ".join(f"{k}={repr(v)}" for k, v in message_part.args.items())
-            tool_call_str = f"{message_part.tool_name}({args_str})"
-        else:
-            tool_call_str = f"{message_part.tool_name}({message_part.args})"
-        return f"<TOOL_CALL>\n{tool_call_str}\n</TOOL_CALL>"
+        # Safely parse args to avoid crashes from incomplete JSON during streaming
+        try:
+            parsed_args = _safely_parse_tool_args(message_part.args)
+            if parsed_args:
+                # Successfully parsed as dict - format nicely
+                args_str = ", ".join(f"{k}={repr(v)}" for k, v in parsed_args.items())
+                tool_call_str = f"{message_part.tool_name}({args_str})"
+            elif isinstance(message_part.args, str) and message_part.args:
+                # Non-empty string that didn't parse as JSON
+                # Check if it looks like JSON (starts with { or [) - if so, it's incomplete
+                stripped_args = message_part.args.strip()
+                if stripped_args.startswith(("{", "[")):
+                    # Looks like incomplete JSON - log warning and show empty parens
+                    args_preview = (
+                        stripped_args[:100] + "..."
+                        if len(stripped_args) > 100
+                        else stripped_args
+                    )
+                    stack_trace = "".join(traceback.format_stack())
+                    logger.warning(
+                        "ToolCallPart with unparseable args encountered during context extraction",
+                        extra={
+                            "tool_name": message_part.tool_name,
+                            "tool_call_id": message_part.tool_call_id,
+                            "args_preview": args_preview,
+                            "args_type": type(message_part.args).__name__,
+                            "stack_trace": stack_trace,
+                        },
+                    )
+                    tool_call_str = f"{message_part.tool_name}()"
+                else:
+                    # Plain string arg - display as-is
+                    tool_call_str = f"{message_part.tool_name}({message_part.args})"
+            else:
+                # No args
+                tool_call_str = f"{message_part.tool_name}()"
+            return f"<TOOL_CALL>\n{tool_call_str}\n</TOOL_CALL>"
+        except Exception as e:  # pragma: no cover - defensive catch-all
+            # If anything goes wrong, log full exception with stack trace
+            logger.error(
+                "Unexpected error processing ToolCallPart",
+                exc_info=True,
+                extra={
+                    "tool_name": message_part.tool_name,
+                    "tool_call_id": message_part.tool_call_id,
+                    "error": str(e),
+                },
+            )
+            return f"<TOOL_CALL>\n{message_part.tool_name}()\n</TOOL_CALL>"
 
     elif isinstance(message_part, BuiltinToolCallPart):
         return f"<BUILTIN_TOOL_CALL>\n{message_part.tool_name}\n</BUILTIN_TOOL_CALL>"

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/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/screens/chat.py

@@ -881,6 +881,30 @@ class ChatScreen(Screen[None]):
         except asyncio.CancelledError:
             # Handle cancellation gracefully - DO NOT re-raise
             self.mount_hint("⚠️ Operation cancelled by user")
+        except Exception as e:
+            # Log with full stack trace to shotgun.log
+            logger.exception(
+                "Agent run failed",
+                extra={
+                    "agent_mode": self.mode.value,
+                    "error_type": type(e).__name__,
+                },
+            )
+
+            # Determine user-friendly message based on error type
+            error_name = type(e).__name__
+            error_message = str(e)
+
+            if "APIStatusError" in error_name and "overload" in error_message.lower():
+                hint = "⚠️ The AI service is temporarily overloaded. Please wait a moment and try again."
+            elif "APIStatusError" in error_name and "rate" in error_message.lower():
+                hint = "⚠️ Rate limit reached. Please wait before trying again."
+            elif "APIStatusError" in error_name:
+                hint = f"⚠️ AI service error: {error_message}"
+            else:
+                hint = f"⚠️ An error occurred: {error_message}\n\nCheck logs at ~/.shotgun-sh/logs/shotgun.log"
+
+            self.mount_hint(hint)
         finally:
             self.working = False
             self._current_worker = None
@@ -910,24 +934,41 @@ class ChatScreen(Screen[None]):
         """Load conversation from persistent storage."""
         conversation = self.conversation_manager.load()
         if conversation is None:
+            # Check if file existed but was corrupted (backup was created)
+            backup_path = self.conversation_manager.conversation_path.with_suffix(
+                ".json.backup"
+            )
+            if backup_path.exists():
+                # File was corrupted - show friendly notification
+                self.mount_hint(
+                    "⚠️ Previous session was corrupted and has been backed up. Starting fresh conversation."
+                )
             return
 
-        # Restore agent state
-        agent_messages = conversation.get_agent_messages()
-        ui_messages = conversation.get_ui_messages()
+        try:
+            # Restore agent state
+            agent_messages = conversation.get_agent_messages()
+            ui_messages = conversation.get_ui_messages()
+
+            # Create ConversationState for restoration
+            state = ConversationState(
+                agent_messages=agent_messages,
+                ui_messages=ui_messages,
+                agent_type=conversation.last_agent_model,
+            )
 
-        # Create ConversationState for restoration
-        state = ConversationState(
-            agent_messages=agent_messages,
-            ui_messages=ui_messages,
-            agent_type=conversation.last_agent_model,
-        )
+            self.agent_manager.restore_conversation_state(state)
 
-        self.agent_manager.restore_conversation_state(state)
+            # Update the current mode
+            self.mode = AgentType(conversation.last_agent_model)
+            self.deps.usage_manager.restore_usage_state()
 
-        # Update the current mode
-        self.mode = AgentType(conversation.last_agent_model)
-        self.deps.usage_manager.restore_usage_state()
+        except Exception as e:  # pragma: no cover
+            # If anything goes wrong during restoration, log it and continue
+            logger.error("Failed to restore conversation state: %s", e)
+            self.mount_hint(
+                "⚠️ Could not restore previous session. Starting fresh conversation."
+            )
 
 
 def help_text_with_codebase(already_indexed: bool = False) -> str: