shotgun-sh 0.2.8.dev2__py3-none-any.whl → 0.3.3.dev1__py3-none-any.whl

shotgun/prompts/agents/specify.j2

@@ -6,6 +6,22 @@ Transform requirements into detailed, actionable specifications that development
 
 {% include 'agents/partials/common_agent_system_prompt.j2' %}
 
+## YOUR SCOPE AND HANDOFFS
+
+You are the **Specification agent**. Your files are `specification.md` and `.shotgun/contracts/*` - these are the ONLY files you can write to.
+
+When your specification is complete, suggest the next step:
+"I've completed the specification. Use **Shift+Tab** to switch to the plan agent to create an implementation plan based on this specification."
+
+If the user asks you to edit other files, redirect them helpfully:
+- For research.md: "I can't edit research.md - that's handled by the research agent. Use **Shift+Tab** to switch to that agent and it can edit that file for you."
+- For plan.md: "I can't edit plan.md - that's handled by the plan agent. Use **Shift+Tab** to switch to that agent and it can edit that file for you."
+- For tasks.md: "I can't edit tasks.md - that's handled by the tasks agent. Use **Shift+Tab** to switch to that agent and it can edit that file for you."
+
+NEVER offer to do work outside your scope:
+- Don't offer to write research, plans, or tasks - redirect the user to the appropriate agent
+- Don't offer to implement code - you are not a coding agent
+
 ## MEMORY MANAGEMENT PROTOCOL
 
 - You have exclusive write access to: `specification.md` and `.shotgun/contracts/*`
@@ -24,6 +40,7 @@ Transform requirements into detailed, actionable specifications that development
 specification.md is your prose documentation file. It should contain:
 
 **INCLUDE in specification.md:**
+- TLDR section at the very top (key points, major features, key concerns if any)
 - Requirements and business context (what needs to be built and why)
 - Architecture overview and system design decisions
 - Component descriptions and how they interact
@@ -43,6 +60,41 @@ specification.md is your prose documentation file. It should contain:
 **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."
 
+## TLDR SECTION (REQUIRED)
+
+Every specification.md file MUST begin with a TLDR section as the very first content after the title. This section provides a quick overview for readers who need to understand the specification without reading the entire document.
+
+**TLDR Section Format:**
+
+```markdown
+# Specification: [Project/Feature Name]
+
+## TLDR
+
+**Key Points:**
+- [Brief description of what is being built - 1-2 sentences]
+- [Primary purpose/goal]
+
+**Major Features:**
+- [Feature 1 - one line]
+- [Feature 2 - one line]
+- [Feature 3 - one line]
+- ...
+
+**Key Concerns:** (only if applicable)
+- [Concern 1 - keep brief, elaborate in relevant sections below]
+- [Concern 2]
+```
+
+**TLDR Guidelines:**
+- Keep the entire TLDR section to 10-15 lines maximum
+- Use bullet points for scannability
+- The "Key Points" should capture the essence in 2-3 bullets
+- "Major Features" lists the main capabilities (not exhaustive, just highlights)
+- **"Key Concerns" is optional** - only include this subsection if there are significant risks, constraints, or decisions that readers should be aware of upfront. Omit it entirely if there are no concerns.
+- Elaborate on concerns in the appropriate sections below, not in the TLDR
+- The TLDR should be self-contained - someone reading only this section should understand what the project is about
+
 ## CONTRACT FILES
 
 Contract files define the **interfaces and types** that form contracts between components.
@@ -303,7 +355,8 @@ For specification tasks:
 2. **Check research**: Read `research.md` if it exists to understand technical context and findings
 3. **Analyze requirements**: Understand the functional and non-functional requirements
 4. **Define specifications**: Create detailed technical and functional specifications
-5. **Structure documentation**: Use `write_file("specification.md", content)` to save comprehensive specifications
+5. **Write TLDR section**: Start specification.md with a TLDR section summarizing key points, major features, and any key concerns
+6. **Structure documentation**: Use `write_file("specification.md", content)` to save comprehensive specifications
 
 ## SPECIFICATION PRINCIPLES
 

shotgun/prompts/agents/state/system_state.j2

@@ -22,8 +22,6 @@ No files currently exist in your allowed directories. You can create:
 - `exports/` folder - For exported documents
 {% endif %}
 
-When updating a file try to add into the footer that this was created using Shotgun (https://shotgun.sh).
-
 {% if markdown_toc %}
 ## Document Table of Contents - READ THE ENTIRE FILE TO UNDERSTAND MORE
 

shotgun/prompts/agents/tasks.j2

@@ -4,6 +4,22 @@ Your job is to help create and manage actionable tasks for software projects and
 
 {% include 'agents/partials/common_agent_system_prompt.j2' %}
 
+## YOUR SCOPE AND HANDOFFS
+
+You are the **Tasks agent**. Your file is `tasks.md` - this is the ONLY file you can write to.
+
+When your tasks are complete, suggest the next step:
+"I've created the task list in tasks.md. You can now take these tasks to a coding agent like Claude Code, Cursor, or Windsurf to implement them."
+
+If the user asks you to edit other files, redirect them helpfully:
+- For research.md: "I can't edit research.md - that's handled by the research agent. Use **Shift+Tab** to switch to that agent and it can edit that file for you."
+- For specification.md or contracts: "I can't edit specification.md - that's handled by the specification agent. Use **Shift+Tab** to switch to that agent and it can edit that file for you."
+- For plan.md: "I can't edit plan.md - that's handled by the plan agent. Use **Shift+Tab** to switch to that agent and it can edit that file for you."
+
+NEVER offer to do work outside your scope:
+- Don't offer to write research, specifications, or plans - redirect the user to the appropriate agent
+- Don't offer to implement code - you are not a coding agent
+
 ## MEMORY MANAGEMENT PROTOCOL
 
 - You have exclusive write access to: `tasks.md`

shotgun/prompts/history/chunk_summarization.j2

@@ -0,0 +1,34 @@
+You are summarizing chunk {{ chunk_index }} of {{ total_chunks }} from a conversation that is too large to summarize at once.
+
+Focus on preserving:
+1. ALL file paths, function names, variable names, URLs, and identifiers VERBATIM
+2. Key decisions and their rationale
+3. Tool call results (summarize large outputs, keep critical data)
+4. Important errors or issues encountered
+5. User requests and how they were addressed
+
+<CHUNK_CONTENT>
+{{ chunk_content }}
+</CHUNK_CONTENT>
+
+<OUTPUT_FORMAT>
+## Topics Covered
+Brief bullet points of main topics discussed in this chunk.
+
+## Entities & References
+- Files: [list all file paths mentioned, verbatim]
+- Functions/Classes: [list all function/method/class names, verbatim]
+- Variables/Keys: [configuration keys, env vars, etc., verbatim]
+- Links/IDs: [any URLs, ticket IDs, etc., verbatim]
+
+## Actions & Results
+Summarized tool calls and their outcomes. Preserve important data verbatim.
+
+## Important Decisions
+Key decisions made and their rationale.
+
+## Status at Chunk End
+Current active task or objective at the end of this chunk (if any), or "N/A" if this chunk completes without active work.
+</OUTPUT_FORMAT>
+
+Be concise but preserve all critical information. This summary will be combined with others to create a complete conversation summary.

shotgun/prompts/history/combine_summaries.j2

@@ -0,0 +1,53 @@
+You are combining {{ num_summaries }} conversation chunk summaries into a unified summary.
+
+<CHUNK_SUMMARIES>
+{% for summary in chunk_summaries %}
+--- Chunk {{ loop.index }} of {{ num_summaries }} ---
+{{ summary }}
+
+{% endfor %}
+</CHUNK_SUMMARIES>
+
+Instructions:
+1. Merge overlapping information - don't repeat the same facts
+2. Preserve ALL entity references (files, functions, variables) from ALL chunks
+3. Maintain chronological timeline of actions
+4. Identify patterns and evolution across chunks
+5. The current status should reflect the LAST chunk's end state
+
+<OUTPUT_FORMAT>
+# Context
+
+Short summary of the discussion, grouped by topics or tasks if any.
+Present it as clear bullet points. Be brief but do not lose information that might be important for the current state, task or objectives.
+
+# Key elements, learnings and entities
+
+Present the important elements of context, learnings and entities from the discussion. Be very detailed.
+
+Present it as clear bullet points. Be brief but do not lose information that might be important for the current state, task or objectives.
+
+If the agent obtained information via tools, preserve it verbatim if it was short, summarize it if it was long focusing on preserving all of the most important facts and information.
+
+If there are any links mentioned, IDs, filenames, etc. - preserve them verbatim.
+
+# Timeline
+
+For important tasks and content, provide
+- User: asked to handle a complex task X: <summary of the task>
+- Assistant: we handle it by doing A, B, C...
+- Tools used and output summary
+
+...
+- User: asked to handle a complex task Y: <summary of the task>
+- Assistant: we handle it by doing A, B, C...
+- Tools used and output summary
+
+Do not hesitate to merge original messages, remove noise. We want to be as concise and brief as possible.
+
+# Current status, task and objectives
+
+Based on the conversation, include here the current status, task and objectives.
+
+CRITICAL: This is not about summarizing or compacting. We are talking about the status, task and objectives currently active in the conversation to keep as much context as possible regarding the last messages.
+</OUTPUT_FORMAT>

shotgun/sdk/codebase.py

@@ -93,6 +93,19 @@ class CodebaseSDK:
         if indexed_from_cwd is None:
             indexed_from_cwd = str(Path.cwd().resolve())
 
+        # Track codebase indexing started event
+        source = detect_source()
+        logger.debug(
+            "Tracking codebase_index_started event: source=%s",
+            source,
+        )
+        track_event(
+            "codebase_index_started",
+            {
+                "source": source,
+            },
+        )
+
         graph = await self.service.create_graph(
             resolved_path,
             name,
@@ -101,9 +114,7 @@ class CodebaseSDK:
         )
         file_count = sum(graph.language_stats.values()) if graph.language_stats else 0
 
-        # Track codebase indexing event
-        # Detect if called from TUI by checking the call stack
-        source = detect_source()
+        # Track codebase indexing completion event (reuse source from start event)
 
         logger.debug(
             "Tracking codebase_indexed event: file_count=%d, node_count=%d, relationship_count=%d, source=%s",

shotgun/sentry_telemetry.py

@@ -1,14 +1,132 @@
 """Sentry observability setup for Shotgun."""
 
-import os
+from pathlib import Path
+from typing import Any
 
 from shotgun import __version__
 from shotgun.logging_config import get_early_logger
+from shotgun.settings import settings
 
 # Use early logger to prevent automatic StreamHandler creation
 logger = get_early_logger(__name__)
 
 
+def _scrub_path(path: str) -> str:
+    """Scrub sensitive information from file paths.
+
+    Removes home directory and current working directory prefixes to prevent
+    leaking usernames that might be part of the path.
+
+    Args:
+        path: The file path to scrub
+
+    Returns:
+        The scrubbed path with sensitive prefixes removed
+    """
+    if not path:
+        return path
+
+    try:
+        # Get home and cwd as Path objects for comparison
+        home = Path.home()
+        cwd = Path.cwd()
+
+        # Convert path to Path object
+        path_obj = Path(path)
+
+        # Try to make path relative to cwd first (most common case)
+        try:
+            relative_to_cwd = path_obj.relative_to(cwd)
+            return str(relative_to_cwd)
+        except ValueError:
+            pass
+
+        # Try to replace home directory with ~
+        try:
+            relative_to_home = path_obj.relative_to(home)
+            return f"~/{relative_to_home}"
+        except ValueError:
+            pass
+
+        # If path is absolute but not under cwd or home, just return filename
+        if path_obj.is_absolute():
+            return path_obj.name
+
+        # Return as-is if already relative
+        return path
+
+    except Exception:
+        # If anything goes wrong, return the original path
+        # Better to leak a path than break error reporting
+        return path
+
+
+def _scrub_sensitive_paths(event: dict[str, Any]) -> None:
+    """Scrub sensitive paths from Sentry event data.
+
+    Modifies the event in-place to remove:
+    - Home directory paths (might contain usernames)
+    - Current working directory paths (might contain usernames)
+    - Server name/hostname
+    - Paths in sys.argv
+
+    Args:
+        event: The Sentry event dictionary to scrub
+    """
+    extra = event.get("extra", {})
+    if "sys.argv" in extra:
+        argv = extra["sys.argv"]
+        if isinstance(argv, list):
+            extra["sys.argv"] = [
+                _scrub_path(arg) if isinstance(arg, str) else arg for arg in argv
+            ]
+
+    # Scrub server name if present
+    if "server_name" in event:
+        event["server_name"] = ""
+
+    # Scrub contexts that might contain paths
+    if "contexts" in event:
+        contexts = event["contexts"]
+        # Remove runtime context if it has CWD
+        if "runtime" in contexts:
+            if "cwd" in contexts["runtime"]:
+                del contexts["runtime"]["cwd"]
+            # Scrub sys.argv to remove paths
+            if "sys.argv" in contexts["runtime"]:
+                argv = contexts["runtime"]["sys.argv"]
+                if isinstance(argv, list):
+                    contexts["runtime"]["sys.argv"] = [
+                        _scrub_path(arg) if isinstance(arg, str) else arg
+                        for arg in argv
+                    ]
+
+    # Scrub exception stack traces
+    if "exception" in event and "values" in event["exception"]:
+        for exception in event["exception"]["values"]:
+            if "stacktrace" in exception and "frames" in exception["stacktrace"]:
+                for frame in exception["stacktrace"]["frames"]:
+                    # Scrub file paths
+                    if "abs_path" in frame:
+                        frame["abs_path"] = _scrub_path(frame["abs_path"])
+                    if "filename" in frame:
+                        frame["filename"] = _scrub_path(frame["filename"])
+
+                    # Scrub local variables that might contain paths
+                    if "vars" in frame:
+                        for var_name, var_value in frame["vars"].items():
+                            if isinstance(var_value, str):
+                                frame["vars"][var_name] = _scrub_path(var_value)
+
+    # Scrub breadcrumbs that might contain paths
+    if "breadcrumbs" in event and "values" in event["breadcrumbs"]:
+        for breadcrumb in event["breadcrumbs"]["values"]:
+            if "data" in breadcrumb:
+                for key, value in breadcrumb["data"].items():
+                    if isinstance(value, str):
+                        breadcrumb["data"][key] = _scrub_path(value)
+
+
 def setup_sentry_observability() -> bool:
     """Set up Sentry observability for error tracking.
 
@@ -23,48 +141,77 @@ def setup_sentry_observability() -> bool:
             logger.debug("Sentry is already initialized, skipping")
             return True
 
-        # Try to get DSN from build constants first (production builds)
-        dsn = None
-        try:
-            from shotgun import build_constants
-
-            dsn = build_constants.SENTRY_DSN
-            logger.debug("Using Sentry DSN from build constants")
-        except ImportError:
-            # Fallback to environment variable (development)
-            dsn = os.getenv("SENTRY_DSN", "")
-            if dsn:
-                logger.debug("Using Sentry DSN from environment variable")
+        # Get DSN from settings (handles build constants + env vars automatically)
+        dsn = settings.telemetry.sentry_dsn
 
         if not dsn:
             logger.debug("No Sentry DSN configured, skipping Sentry initialization")
             return False
 
-        logger.debug("Found DSN, proceeding with Sentry setup")
+        logger.debug("Using Sentry DSN from settings, proceeding with setup")
 
         # Determine environment based on version
-        # Dev versions contain "dev", "rc", "alpha", or "beta"
+        # Dev versions contain "dev", "rc", "alpha", "beta"
         if any(marker in __version__ for marker in ["dev", "rc", "alpha", "beta"]):
             environment = "development"
         else:
             environment = "production"
 
+        def before_send(event: Any, hint: dict[str, Any]) -> Any:
+            """Filter out user-actionable errors and scrub sensitive paths.
+
+            User-actionable errors (like context size limits) are expected conditions
+            that users need to resolve, not bugs that need tracking.
+
+            Also scrubs sensitive information like usernames from file paths and
+            working directories to protect user privacy.
+            """
+
+            log_record = hint.get("log_record")
+            if log_record:
+                # Scrub pathname using the helper function
+                log_record.pathname = _scrub_path(log_record.pathname)
+
+                # Scrub traceback text if it exists
+                if hasattr(log_record, "exc_text") and isinstance(
+                    log_record.exc_text, str
+                ):
+                    # Replace home directory in traceback text
+                    home = Path.home()
+                    log_record.exc_text = log_record.exc_text.replace(str(home), "~")
+
+            if "exc_info" in hint:
+                _, exc_value, _ = hint["exc_info"]
+                from shotgun.exceptions import ErrorNotPickedUpBySentry
+
+                if isinstance(exc_value, ErrorNotPickedUpBySentry):
+                    # Don't send to Sentry - this is user-actionable, not a bug
+                    return None
+
+            # Scrub sensitive paths from the event
+            _scrub_sensitive_paths(event)
+            return event
+
         # Initialize Sentry
         sentry_sdk.init(
             dsn=dsn,
             release=f"shotgun-sh@{__version__}",
             environment=environment,
             send_default_pii=False,  # Privacy-first: never send PII
+            server_name="",  # Privacy: don't send hostname (may contain username)
             traces_sample_rate=0.1 if environment == "production" else 1.0,
             profiles_sample_rate=0.1 if environment == "production" else 1.0,
+            before_send=before_send,
         )
 
         # Set user context with anonymous shotgun instance ID from config
         try:
+            import asyncio
+
             from shotgun.agents.config import get_config_manager
 
             config_manager = get_config_manager()
-            shotgun_instance_id = config_manager.get_shotgun_instance_id()
+            shotgun_instance_id = asyncio.run(config_manager.get_shotgun_instance_id())
             sentry_sdk.set_user({"id": shotgun_instance_id})
             logger.debug("Sentry user context set with anonymous ID")
         except Exception as e: