gobby 0.2.7__py3-none-any.whl → 0.2.9__py3-none-any.whl

gobby/mcp_proxy/tools/artifacts.py

@@ -19,23 +19,35 @@ from gobby.mcp_proxy.tools.internal import InternalToolRegistry
 
 if TYPE_CHECKING:
     from gobby.storage.artifacts import LocalArtifactManager
-    from gobby.storage.database import LocalDatabase
+    from gobby.storage.database import DatabaseProtocol
 
 
 def create_artifacts_registry(
-    db: LocalDatabase | None = None,
+    db: DatabaseProtocol | None = None,
     artifact_manager: LocalArtifactManager | None = None,
+    session_manager: Any | None = None,
 ) -> InternalToolRegistry:
     """
     Create an artifacts tool registry with all artifact-related tools.
 
     Args:
-        db: LocalDatabase instance (used to create artifact_manager if not provided)
+        db: DatabaseProtocol instance (used to create artifact_manager if not provided)
         artifact_manager: LocalArtifactManager instance
+        session_manager: Session manager for resolving session references
 
     Returns:
         InternalToolRegistry with artifact tools registered
     """
+    from gobby.utils.project_context import get_project_context
+
+    def _resolve_session_id(ref: str) -> str:
+        """Resolve session reference (#N, N, UUID, or prefix) to UUID."""
+        if session_manager is None:
+            return ref  # No resolution available, return as-is
+        ctx = get_project_context()
+        project_id = ctx.get("id") if ctx else None
+        return str(session_manager.resolve_session_reference(ref, project_id))
+
     # Create artifact manager if not provided
     if artifact_manager is None:
         if db is None:
@@ -55,7 +67,7 @@ def create_artifacts_registry(
 
     @registry.tool(
         name="search_artifacts",
-        description="Search artifacts by content using full-text search.",
+        description="Search artifacts by content using full-text search. Accepts #N, N, UUID, or prefix for session_id.",
     )
     def search_artifacts(
         query: str,
@@ -68,7 +80,7 @@ def create_artifacts_registry(
 
         Args:
             query: Search query text
-            session_id: Optional session ID to filter by
+            session_id: Optional session reference (accepts #N, N, UUID, or prefix) to filter by
             artifact_type: Optional artifact type to filter by (code, diff, error, etc.)
             limit: Maximum number of results (default: 50)
 
@@ -78,10 +90,18 @@ def create_artifacts_registry(
         if not query or not query.strip():
             return {"success": True, "artifacts": [], "count": 0}
 
+        # Resolve session_id to UUID (accepts #N, N, UUID, or prefix)
+        resolved_session_id = session_id
+        if session_id:
+            try:
+                resolved_session_id = _resolve_session_id(session_id)
+            except ValueError as e:
+                return {"success": False, "error": str(e), "artifacts": []}
+
         try:
             artifacts = _artifact_manager.search_artifacts(
                 query_text=query,
-                session_id=session_id,
+                session_id=resolved_session_id,
                 artifact_type=artifact_type,
                 limit=limit,
             )
@@ -95,7 +115,7 @@ def create_artifacts_registry(
 
     @registry.tool(
         name="list_artifacts",
-        description="List artifacts with optional filters.",
+        description="List artifacts with optional filters. Accepts #N, N, UUID, or prefix for session_id.",
     )
     def list_artifacts(
         session_id: str | None = None,
@@ -107,7 +127,7 @@ def create_artifacts_registry(
         List artifacts with optional filters.
 
         Args:
-            session_id: Optional session ID to filter by
+            session_id: Optional session reference (accepts #N, N, UUID, or prefix) to filter by
             artifact_type: Optional artifact type to filter by
             limit: Maximum number of results (default: 100)
             offset: Offset for pagination (default: 0)
@@ -115,9 +135,17 @@ def create_artifacts_registry(
         Returns:
             Dict with success status and list of artifacts
         """
+        # Resolve session_id to UUID (accepts #N, N, UUID, or prefix)
+        resolved_session_id = session_id
+        if session_id:
+            try:
+                resolved_session_id = _resolve_session_id(session_id)
+            except ValueError as e:
+                return {"success": False, "error": str(e), "artifacts": []}
+
         try:
             artifacts = _artifact_manager.list_artifacts(
-                session_id=session_id,
+                session_id=resolved_session_id,
                 artifact_type=artifact_type,
                 limit=limit,
                 offset=offset,
@@ -161,7 +189,7 @@ def create_artifacts_registry(
 
     @registry.tool(
         name="get_timeline",
-        description="Get artifacts for a session in chronological order.",
+        description="Get artifacts for a session in chronological order. Accepts #N, N, UUID, or prefix for session_id.",
     )
     def get_timeline(
         session_id: str | None = None,
@@ -172,7 +200,7 @@ def create_artifacts_registry(
         Get artifacts for a session in chronological order (oldest first).
 
         Args:
-            session_id: Required session ID to get timeline for
+            session_id: Required session reference (accepts #N, N, UUID, or prefix) to get timeline for
             artifact_type: Optional artifact type to filter by
             limit: Maximum number of results (default: 100)
 
@@ -186,10 +214,16 @@ def create_artifacts_registry(
                 "artifacts": [],
             }
 
+        # Resolve session_id to UUID (accepts #N, N, UUID, or prefix)
+        try:
+            resolved_session_id = _resolve_session_id(session_id)
+        except ValueError as e:
+            return {"success": False, "error": str(e), "artifacts": []}
+
         try:
             # Get artifacts (list_artifacts returns newest first by default)
             artifacts = _artifact_manager.list_artifacts(
-                session_id=session_id,
+                session_id=resolved_session_id,
                 artifact_type=artifact_type,
                 limit=limit,
                 offset=0,

gobby/mcp_proxy/tools/sessions/_commits.py

@@ -27,9 +27,18 @@ def register_commits_tools(
         session_manager: LocalSessionManager instance for session operations
     """
 
+    def _resolve_session_id(ref: str) -> str:
+        """Resolve session reference (#N, N, UUID, or prefix) to UUID."""
+        from gobby.utils.project_context import get_project_context
+
+        project_ctx = get_project_context()
+        project_id = project_ctx.get("id") if project_ctx else None
+
+        return session_manager.resolve_session_reference(ref, project_id)
+
     @registry.tool(
         name="get_session_commits",
-        description="Get git commits made during a session timeframe.",
+        description="Get git commits made during a session timeframe. Accepts #N, N, UUID, or prefix for session_id.",
     )
     def get_session_commits(
         session_id: str,
@@ -42,7 +51,7 @@ def register_commits_tools(
         git log within that timeframe.
 
         Args:
-            session_id: Session ID
+            session_id: Session reference - supports #N, N (seq_num), UUID, or prefix
             max_commits: Maximum commits to return (default 20)
 
         Returns:
@@ -55,21 +64,15 @@ def register_commits_tools(
         if session_manager is None:
             return {"error": "Session manager not available"}
 
-        # Get session
-        session = session_manager.get(session_id)
+        # Resolve session reference (#N, N, UUID, or prefix)
+        try:
+            resolved_id = _resolve_session_id(session_id)
+            session = session_manager.get(resolved_id)
+        except ValueError as e:
+            return {"error": str(e)}
+
         if not session:
-            # Try prefix match
-            sessions = session_manager.list(limit=100)
-            matches = [s for s in sessions if s.id.startswith(session_id)]
-            if len(matches) == 1:
-                session = matches[0]
-            elif len(matches) > 1:
-                return {
-                    "error": f"Ambiguous session ID prefix '{session_id}'",
-                    "matches": [s.id for s in matches[:5]],
-                }
-            else:
-                return {"error": f"Session {session_id} not found"}
+            return {"error": f"Session {session_id} not found"}
 
         # Get working directory from transcript path or project
         cwd = None
@@ -163,12 +166,12 @@ def register_commits_tools(
 
     @registry.tool(
         name="mark_loop_complete",
-        description="""Mark the autonomous loop as complete, preventing session chaining.
+        description="""Mark the autonomous loop as complete, preventing session chaining. Accepts #N, N, UUID, or prefix for session_id.
 
 Args:
-    session_id: (REQUIRED) Your session ID. Get it from:
-        1. Your injected context (look for 'session_id: xxx')
-        2. Or call get_current(external_id, source) first""",
+    session_id: (REQUIRED) Your session ID. Accepts #N, N, UUID, or prefix. Get it from:
+        1. Your injected context (look for 'Session Ref: #N' or 'session_id: xxx')
+        2. Or call get_current_session(external_id, source) first""",
     )
     def mark_loop_complete(session_id: str) -> dict[str, Any]:
         """
@@ -184,16 +187,20 @@ Args:
         - The user has explicitly asked to stop
 
         Args:
-            session_id: Session ID (REQUIRED)
+            session_id: Session reference - supports #N, N (seq_num), UUID, or prefix (REQUIRED)
 
         Returns:
             Success status and session details
         """
         if not session_manager:
-            raise RuntimeError("Session manager not available")
+            return {"error": "Session manager not available"}
 
-        # Find session - session_id is now required
-        session = session_manager.get(session_id)
+        # Resolve session reference (#N, N, UUID, or prefix)
+        try:
+            resolved_id = _resolve_session_id(session_id)
+            session = session_manager.get(resolved_id)
+        except ValueError as e:
+            return {"error": str(e), "session_id": session_id}
 
         if not session:
             return {"error": f"Session {session_id} not found", "session_id": session_id}

gobby/mcp_proxy/tools/sessions/_crud.py

@@ -2,7 +2,7 @@
 
 This module contains MCP tools for:
 - Getting session details (get_session)
-- Getting current session (get_current)
+- Getting current session (get_current_session)
 - Listing sessions (list_sessions)
 - Session statistics (session_stats)
 """
@@ -71,7 +71,7 @@ def register_crud_tools(
         }
 
     @registry.tool(
-        name="get_current",
+        name="get_current_session",
         description="""Get YOUR current session ID - the CORRECT way to look up your session.
 
 Use this when session_id wasn't in your injected context. Pass your external_id
@@ -79,7 +79,7 @@ Use this when session_id wasn't in your injected context. Pass your external_id
 
 DO NOT use list_sessions to find your session - it won't work with multiple active sessions.""",
     )
-    def get_current(
+    def get_current_session(
         external_id: str,
         source: str,
     ) -> dict[str, Any]:
@@ -148,7 +148,7 @@ DO NOT use list_sessions to find your session - it won't work with multiple acti
 WARNING: Do NOT use this to find your own session_id!
 - `list_sessions(status="active", limit=1)` will NOT reliably return YOUR session
 - Multiple sessions can be active simultaneously (parallel agents, multiple terminals)
-- Use `get_current(external_id, source)` instead - it uses your unique session key
+- Use `get_current_session(external_id, source)` instead - it uses your unique session key
 
 This tool is for browsing/listing sessions, not for self-identification.""",
     )
@@ -192,7 +192,7 @@ This tool is for browsing/listing sessions, not for self-identification.""",
                 "warning": (
                     "list_sessions(status='active', limit=1) will NOT reliably get YOUR session_id! "
                     "Multiple sessions can be active simultaneously. "
-                    "Use get_current(external_id='<your-external-id>', source='claude') instead."
+                    "Use get_current_session(external_id='<your-external-id>', source='claude') instead."
                 ),
                 "hint": "Your external_id is in your transcript path: /path/to/<external_id>.jsonl",
                 "sessions": [s.to_dict() for s in sessions],

gobby/mcp_proxy/tools/sessions/_handoff.py

@@ -123,23 +123,29 @@ def register_handoff_tools(
         registry: The InternalToolRegistry to register tools with
         session_manager: LocalSessionManager instance for session operations
     """
+    from gobby.utils.project_context import get_project_context
+
+    def _resolve_session_id(ref: str) -> str:
+        """Resolve session reference (#N, N, UUID, or prefix) to UUID."""
+        project_ctx = get_project_context()
+        project_id = project_ctx.get("id") if project_ctx else None
+
+        return session_manager.resolve_session_reference(ref, project_id)
 
     @registry.tool(
         name="get_handoff_context",
-        description="Get the handoff context (compact_markdown) for a session. Accepts #N, UUID, or prefix.",
+        description="Get the handoff context (compact_markdown) for a session. Accepts #N, N, UUID, or prefix.",
     )
     def get_handoff_context(session_id: str) -> dict[str, Any]:
         """
         Retrieve stored handoff context.
 
         Args:
-            session_id: Session reference - supports #N (project-scoped), UUID, or prefix
+            session_id: Session reference - supports #N, N (seq_num), UUID, or prefix
 
         Returns:
             Session ID, compact_markdown, and whether context exists
         """
-        from gobby.utils.project_context import get_project_context
-
         if not session_manager:
             raise RuntimeError("Session manager not available")
 
@@ -165,12 +171,12 @@ def register_handoff_tools(
 
     @registry.tool(
         name="create_handoff",
-        description="""Create handoff context by extracting structured data from the session transcript.
+        description="""Create handoff context by extracting structured data from the session transcript. Accepts #N, N, UUID, or prefix for session_id.
 
 Args:
-    session_id: (REQUIRED) Your session ID. Get it from:
-        1. Your injected context (look for 'session_id: xxx')
-        2. Or call get_current(external_id, source) first""",
+    session_id: (REQUIRED) Your session ID. Accepts #N, N, UUID, or prefix. Get it from:
+        1. Your injected context (look for 'Session Ref: #N' or 'session_id: xxx')
+        2. Or call get_current_session(external_id, source) first""",
     )
     async def create_handoff(
         session_id: str,
@@ -187,7 +193,7 @@ Args:
         Always saves to database. Optionally writes to file.
 
         Args:
-            session_id: Session ID (REQUIRED)
+            session_id: Session reference - supports #N, N (seq_num), UUID, or prefix (REQUIRED)
             notes: Additional notes to include in handoff
             compact: Generate compact summary only (default: False, neither = both)
             full: Generate full LLM summary only (default: False, neither = both)
@@ -207,19 +213,12 @@ Args:
         if session_manager is None:
             return {"success": False, "error": "Session manager not available"}
 
-        # Find session - session_id is now required
-        session = session_manager.get(session_id)
-        if not session:
-            # Try prefix match
-            sessions = session_manager.list(limit=100)
-            matches = [s for s in sessions if s.id.startswith(session_id)]
-            if len(matches) == 1:
-                session = matches[0]
-            elif len(matches) > 1:
-                return {
-                    "error": f"Ambiguous session ID prefix '{session_id}'",
-                    "matches": [s.id for s in matches[:5]],
-                }
+        # Resolve session reference (#N, N, UUID, or prefix)
+        try:
+            resolved_id = _resolve_session_id(session_id)
+            session = session_manager.get(resolved_id)
+        except ValueError as e:
+            return {"success": False, "error": str(e), "session_id": session_id}
 
         if not session:
             return {"success": False, "error": "No session found", "session_id": session_id}
@@ -397,7 +396,7 @@ Args:
 
     @registry.tool(
         name="pickup",
-        description="Restore context from a previous session's handoff. For CLIs/IDEs without hooks.",
+        description="Restore context from a previous session's handoff. For CLIs/IDEs without hooks. Accepts #N, N, UUID, or prefix for session_id.",
     )
     def pickup(
         session_id: str | None = None,
@@ -413,10 +412,10 @@ Args:
         for injection into a new session.
 
         Args:
-            session_id: Specific session ID to pickup from (optional)
+            session_id: Session reference - supports #N, N (seq_num), UUID, or prefix (optional)
             project_id: Project ID to find parent session in (optional)
             source: Filter by CLI source - claude_code, gemini, codex (optional)
-            link_child_session_id: If provided, links this session as a child
+            link_child_session_id: Session to link as child - supports #N, N, UUID, or prefix (optional)
 
         Returns:
             Handoff context markdown and session metadata
@@ -428,20 +427,13 @@ Args:
 
         parent_session = None
 
-        # Option 1: Direct session_id lookup
+        # Option 1: Direct session_id lookup with resolution
         if session_id:
-            parent_session = session_manager.get(session_id)
-            if not parent_session:
-                # Try prefix match
-                sessions = session_manager.list(limit=100)
-                matches = [s for s in sessions if s.id.startswith(session_id)]
-                if len(matches) == 1:
-                    parent_session = matches[0]
-                elif len(matches) > 1:
-                    return {
-                        "error": f"Ambiguous session ID prefix '{session_id}'",
-                        "matches": [s.id for s in matches[:5]],
-                    }
+            try:
+                resolved_id = _resolve_session_id(session_id)
+                parent_session = session_manager.get(resolved_id)
+            except ValueError as e:
+                return {"error": str(e)}
 
         # Option 2: Find parent by project_id and source
         if not parent_session and project_id:
@@ -481,9 +473,21 @@ Args:
                 "message": "Session found but has no handoff context",
             }
 
-        # Optionally link child session
+        # Optionally link child session (resolve if using #N format)
+        resolved_child_id = None
         if link_child_session_id:
-            session_manager.update_parent_session_id(link_child_session_id, parent_session.id)
+            try:
+                resolved_child_id = _resolve_session_id(link_child_session_id)
+                session_manager.update_parent_session_id(resolved_child_id, parent_session.id)
+            except ValueError as e:
+                # Do not fallback to raw reference - propagate the error
+                return {
+                    "found": True,
+                    "session_id": parent_session.id,
+                    "has_context": True,
+                    "error": f"Failed to resolve child session '{link_child_session_id}': {e}",
+                    "context": context,
+                }
 
         return {
             "found": True,
@@ -495,5 +499,5 @@ Args:
             ),
             "parent_title": parent_session.title,
             "parent_status": parent_session.status,
-            "linked_child": link_child_session_id,
+            "linked_child": resolved_child_id or link_child_session_id,
         }

gobby/mcp_proxy/tools/sessions/_messages.py

@@ -12,11 +12,13 @@ from typing import TYPE_CHECKING, Any
 if TYPE_CHECKING:
     from gobby.mcp_proxy.tools.internal import InternalToolRegistry
     from gobby.storage.session_messages import LocalSessionMessageManager
+    from gobby.storage.sessions import LocalSessionManager
 
 
 def register_message_tools(
     registry: InternalToolRegistry,
     message_manager: LocalSessionMessageManager,
+    session_manager: LocalSessionManager | None = None,
 ) -> None:
     """
     Register message retrieval and search tools with a registry.
@@ -24,11 +26,31 @@ def register_message_tools(
     Args:
         registry: The InternalToolRegistry to register tools with
         message_manager: LocalSessionMessageManager instance for message operations
+        session_manager: LocalSessionManager for resolving session references
     """
 
+    def _resolve_session_id(session_id: str) -> str:
+        """Resolve session reference (#N, N, UUID, or prefix) to UUID.
+
+        Returns:
+            str: Resolved UUID on success
+
+        Raises:
+            ValueError: If session reference cannot be resolved (when session_manager exists)
+        """
+        if not session_manager:
+            return session_id  # Fall back to raw value if no manager (backward compat)
+
+        from gobby.utils.project_context import get_project_context
+
+        project_ctx = get_project_context()
+        project_id = project_ctx.get("id") if project_ctx else None
+
+        return session_manager.resolve_session_reference(session_id, project_id)
+
     @registry.tool(
         name="get_session_messages",
-        description="Get messages for a session.",
+        description="Get messages for a session. Accepts #N, N, UUID, or prefix for session_id.",
     )
     async def get_session_messages(
         session_id: str,
@@ -40,7 +62,7 @@ def register_message_tools(
         Get messages for a session.
 
         Args:
-            session_id: The session ID
+            session_id: Session reference - supports #N, N (seq_num), UUID, or prefix
             limit: Max messages to return
             offset: Offset for pagination
             full_content: If True, returns full content. If False (default), truncates large content.
@@ -48,8 +70,10 @@ def register_message_tools(
         try:
             if not message_manager:
                 raise RuntimeError("Message manager not available")
+
+            resolved_id = _resolve_session_id(session_id)
             messages = await message_manager.get_messages(
-                session_id=session_id,
+                session_id=resolved_id,
                 limit=limit,
                 offset=offset,
             )
@@ -79,7 +103,7 @@ def register_message_tools(
                         ):
                             tr["content"] = tr["content"][:200] + "... (truncated)"
 
-            session_total = await message_manager.count_messages(session_id)
+            session_total = await message_manager.count_messages(resolved_id)
 
             return {
                 "success": True,
@@ -95,7 +119,7 @@ def register_message_tools(
 
     @registry.tool(
         name="search_messages",
-        description="Search messages using Full Text Search (FTS).",
+        description="Search messages using Full Text Search (FTS). Accepts #N, N, UUID, or prefix for session_id.",
     )
     async def search_messages(
         query: str,
@@ -108,16 +132,20 @@ def register_message_tools(
 
         Args:
             query: Search query
-            session_id: Optional session filter
+            session_id: Optional session filter - supports #N, N (seq_num), UUID, or prefix
             limit: Max results
             full_content: If True, returns full content. If False (default), truncates large content.
         """
         try:
             if not message_manager:
                 raise RuntimeError("Message manager not available")
+
+            resolved_session_id = None
+            if session_id:
+                resolved_session_id = _resolve_session_id(session_id)
             results = await message_manager.search_messages(
                 query_text=query,
-                session_id=session_id,
+                session_id=resolved_session_id,
                 limit=limit,
             )