gateforge-sdk 0.2.4__tar.gz → 0.2.5__tar.gz

{gateforge_sdk-0.2.4 → gateforge_sdk-0.2.5}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: gateforge-sdk
-Version: 0.2.4
-Summary: Privacy-first LLMOps SDK — Auto-init, tool/agent decorators, session tracing, nested conversation support
+Version: 0.2.5
+Summary: Privacy-first LLMOps SDK — Auto-init, tool/agent decorators, session management, nested conversation support
 Project-URL: Homepage, https://gateforge.dev
 Project-URL: Documentation, https://gateforge.dev/docs
 Project-URL: Repository, https://github.com/gateforge/gateforge-sdk

{gateforge_sdk-0.2.4 → gateforge_sdk-0.2.5}/gateforge/__init__.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-__version__ = "0.2.3"
+__version__ = "0.2.5"
 
 # Auto-install spaCy model if missing (required for PII detection)
 def _ensure_spacy_model():
@@ -26,6 +26,15 @@ from gateforge.response import GatforgeResponse
 from gateforge.tracing import configure_otel
 from gateforge.ab.engine import VariantAssignment
 from gateforge.guardrails.engine import GuardrailViolation, GuardrailBlocked
+from gateforge.session_manager import (
+    SessionManager,
+    SessionState,
+    get_session_manager,
+    create_session,
+    get_session,
+    get_current_conversation_id,
+    get_current_trace_info,
+)
 
 _client: GatforgeClient | None = None
 
@@ -426,6 +435,14 @@ __all__ = [
     "agent",
     "record_tool_call",
     "record_tool_result",
+    # Session management (Phase 2)
+    "SessionManager",
+    "SessionState",
+    "get_session_manager",
+    "create_session",
+    "get_session",
+    "get_current_conversation_id",
+    "get_current_trace_info",
     # OTel configuration
     "configure_otel",
     # Standalone PII helpers

gateforge_sdk-0.2.5/gateforge/session_manager.py

@@ -0,0 +1,344 @@
+"""
+Phase 2: Session Management & Enhanced Trace Context
+
+Provides:
+- SessionManager for persistent session state
+- Enhanced metadata support (user_id, tags, custom fields)
+- Session persistence (save/load from dict)
+- Conversation helpers
+"""
+
+from __future__ import annotations
+
+import uuid
+import time
+from dataclasses import dataclass, field
+from typing import Optional, Dict, Any, List
+from datetime import datetime
+
+
+@dataclass
+class SessionState:
+    """
+    Represents the state of a conversation session.
+    
+    Attributes:
+        conversation_id: Unique identifier for the conversation
+        user_id: Optional user identifier
+        created_at: Unix timestamp when session was created
+        updated_at: Unix timestamp of last activity
+        message_count: Number of messages/turns in this conversation
+        tags: Optional tags for categorization
+        metadata: Custom metadata dictionary
+    """
+    conversation_id: str
+    user_id: Optional[str] = None
+    created_at: float = field(default_factory=time.time)
+    updated_at: float = field(default_factory=time.time)
+    message_count: int = 0
+    tags: List[str] = field(default_factory=list)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Serialize session state to dictionary."""
+        return {
+            "conversation_id": self.conversation_id,
+            "user_id": self.user_id,
+            "created_at": self.created_at,
+            "updated_at": self.updated_at,
+            "message_count": self.message_count,
+            "tags": self.tags,
+            "metadata": self.metadata,
+        }
+    
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> SessionState:
+        """Deserialize session state from dictionary."""
+        return cls(
+            conversation_id=data["conversation_id"],
+            user_id=data.get("user_id"),
+            created_at=data.get("created_at", time.time()),
+            updated_at=data.get("updated_at", time.time()),
+            message_count=data.get("message_count", 0),
+            tags=data.get("tags", []),
+            metadata=data.get("metadata", {}),
+        )
+    
+    def touch(self) -> None:
+        """Update the updated_at timestamp and increment message count."""
+        self.updated_at = time.time()
+        self.message_count += 1
+    
+    def add_tag(self, tag: str) -> None:
+        """Add a tag to the session."""
+        if tag not in self.tags:
+            self.tags.append(tag)
+    
+    def set_metadata(self, key: str, value: Any) -> None:
+        """Set a metadata field."""
+        self.metadata[key] = value
+
+
+class SessionManager:
+    """
+    Manages conversation sessions with persistence support.
+    
+    Usage::
+        # Create manager
+        manager = SessionManager()
+        
+        # Create new session
+        session = manager.create_session(user_id="user-123")
+        print(session.conversation_id)
+        
+        # Get existing session
+        session = manager.get_session("conv-123")
+        
+        # Update session activity
+        manager.touch("conv-123")
+        
+        # Serialize all sessions
+        data = manager.to_dict()
+        
+        # Load from serialized data
+        manager2 = SessionManager.from_dict(data)
+    """
+    
+    def __init__(self):
+        self._sessions: Dict[str, SessionState] = {}
+    
+    def create_session(
+        self,
+        user_id: Optional[str] = None,
+        conversation_id: Optional[str] = None,
+        tags: Optional[List[str]] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> SessionState:
+        """
+        Create a new session.
+        
+        Args:
+            user_id: Optional user identifier
+            conversation_id: Optional explicit conversation_id (auto-generated if not provided)
+            tags: Optional list of tags
+            metadata: Optional custom metadata
+        
+        Returns:
+            New SessionState object
+        """
+        cid = conversation_id or str(uuid.uuid4())
+        
+        session = SessionState(
+            conversation_id=cid,
+            user_id=user_id,
+            tags=tags or [],
+            metadata=metadata or {},
+        )
+        
+        self._sessions[cid] = session
+        return session
+    
+    def get_session(self, conversation_id: str) -> Optional[SessionState]:
+        """
+        Get an existing session by ID.
+        
+        Args:
+            conversation_id: The conversation ID to look up
+        
+        Returns:
+            SessionState if found, None otherwise
+        """
+        return self._sessions.get(conversation_id)
+    
+    def get_or_create_session(
+        self,
+        conversation_id: str,
+        user_id: Optional[str] = None,
+    ) -> SessionState:
+        """
+        Get existing session or create new one if not exists.
+        
+        Args:
+            conversation_id: The conversation ID
+            user_id: Optional user_id for new session
+        
+        Returns:
+            Existing or new SessionState
+        """
+        if conversation_id in self._sessions:
+            return self._sessions[conversation_id]
+        
+        return self.create_session(
+            conversation_id=conversation_id,
+            user_id=user_id,
+        )
+    
+    def touch(self, conversation_id: str) -> None:
+        """
+        Update session activity timestamp and message count.
+        
+        Args:
+            conversation_id: The conversation ID to touch
+        """
+        session = self._sessions.get(conversation_id)
+        if session:
+            session.touch()
+    
+    def delete_session(self, conversation_id: str) -> bool:
+        """
+        Delete a session.
+        
+        Args:
+            conversation_id: The conversation ID to delete
+        
+        Returns:
+            True if deleted, False if not found
+        """
+        if conversation_id in self._sessions:
+            del self._sessions[conversation_id]
+            return True
+        return False
+    
+    def list_sessions(
+        self,
+        user_id: Optional[str] = None,
+        tags: Optional[List[str]] = None,
+        limit: Optional[int] = None,
+    ) -> List[SessionState]:
+        """
+        List sessions with optional filters.
+        
+        Args:
+            user_id: Filter by user_id
+            tags: Filter by tags (must have all specified tags)
+            limit: Maximum number of sessions to return
+        
+        Returns:
+            List of matching SessionState objects
+        """
+        sessions = list(self._sessions.values())
+        
+        if user_id:
+            sessions = [s for s in sessions if s.user_id == user_id]
+        
+        if tags:
+            sessions = [s for s in sessions if all(tag in s.tags for tag in tags)]
+        
+        # Sort by updated_at (most recent first)
+        sessions.sort(key=lambda s: s.updated_at, reverse=True)
+        
+        if limit:
+            sessions = sessions[:limit]
+        
+        return sessions
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Serialize all sessions to dictionary."""
+        return {
+            "sessions": {
+                cid: session.to_dict()
+                for cid, session in self._sessions.items()
+            }
+        }
+    
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> SessionManager:
+        """Deserialize SessionManager from dictionary."""
+        manager = cls()
+        
+        sessions_data = data.get("sessions", {})
+        for cid, session_data in sessions_data.items():
+            manager._sessions[cid] = SessionState.from_dict(session_data)
+        
+        return manager
+    
+    def __len__(self) -> int:
+        """Return number of active sessions."""
+        return len(self._sessions)
+    
+    def __contains__(self, conversation_id: str) -> bool:
+        """Check if conversation_id exists."""
+        return conversation_id in self._sessions
+
+
+# ---------------------------------------------------------------------------
+# Global session manager (optional convenience)
+# ---------------------------------------------------------------------------
+
+_default_manager: Optional[SessionManager] = None
+
+
+def get_session_manager() -> SessionManager:
+    """Get or create the default session manager."""
+    global _default_manager
+    if _default_manager is None:
+        _default_manager = SessionManager()
+    return _default_manager
+
+
+def create_session(
+    user_id: Optional[str] = None,
+    conversation_id: Optional[str] = None,
+    tags: Optional[List[str]] = None,
+) -> SessionState:
+    """
+    Create a new session using the default manager.
+    
+    Usage::
+        session = gateforge.create_session(user_id="user-123")
+        print(session.conversation_id)
+    """
+    return get_session_manager().create_session(
+        user_id=user_id,
+        conversation_id=conversation_id,
+        tags=tags,
+    )
+
+
+def get_session(conversation_id: str) -> Optional[SessionState]:
+    """
+    Get an existing session using the default manager.
+    
+    Usage::
+        session = gateforge.get_session("conv-123")
+        if session:
+            print(f"Messages: {session.message_count}")
+    """
+    return get_session_manager().get_session(conversation_id)
+
+
+def get_current_conversation_id() -> Optional[str]:
+    """
+    Get the conversation_id from the active trace context.
+    
+    Usage::
+        cid = gateforge.get_current_conversation_id()
+        if cid:
+            print(f"Current conversation: {cid}")
+    """
+    from gateforge.context import get_active_trace
+    trace = get_active_trace()
+    return trace.conversation_id if trace else None
+
+
+def get_current_trace_info() -> Optional[Dict[str, Any]]:
+    """
+    Get information about the current trace context.
+    
+    Returns:
+        Dictionary with conversation_id, trace_id, step, or None if no active trace
+    
+    Usage::
+        info = gateforge.get_current_trace_info()
+        if info:
+            print(f"Conversation: {info['conversation_id']}, Step: {info['step']}")
+    """
+    from gateforge.context import get_active_trace
+    trace = get_active_trace()
+    if trace:
+        return {
+            "conversation_id": trace.conversation_id,
+            "trace_id": trace.trace_id,
+            "step": trace.step,
+        }
+    return None

{gateforge_sdk-0.2.4 → gateforge_sdk-0.2.5}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
 
 [project]
 name = "gateforge-sdk"
-version = "0.2.4"
-description = "Privacy-first LLMOps SDK — Auto-init, tool/agent decorators, session tracing, nested conversation support"
+version = "0.2.5"
+description = "Privacy-first LLMOps SDK — Auto-init, tool/agent decorators, session management, nested conversation support"
 readme = "README.md"
 license = { text = "MIT" }
 requires-python = ">=3.10"

gateforge_sdk-0.2.5/tests/test_phase2.py

@@ -0,0 +1,528 @@
+"""
+Tests for Phase 2 features:
+- SessionManager
+- SessionState
+- Enhanced trace context helpers
+"""
+
+import os
+import sys
+import pytest
+import time
+
+# Add gateforge to path
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..'))
+
+
+class TestSessionState:
+    """Tests for SessionState dataclass."""
+    
+    def test_create_session_state(self):
+        """Should create SessionState with required fields."""
+        from gateforge.session_manager import SessionState
+        
+        session = SessionState(conversation_id="conv-123")
+        
+        assert session.conversation_id == "conv-123"
+        assert session.user_id is None
+        assert session.message_count == 0
+        assert session.tags == []
+        assert session.metadata == {}
+    
+    def test_create_session_state_with_user(self):
+        """Should create SessionState with user_id."""
+        from gateforge.session_manager import SessionState
+        
+        session = SessionState(
+            conversation_id="conv-123",
+            user_id="user-456",
+            tags=["test", "phase2"],
+        )
+        
+        assert session.user_id == "user-456"
+        assert session.tags == ["test", "phase2"]
+    
+    def test_session_to_dict(self):
+        """Should serialize SessionState to dictionary."""
+        from gateforge.session_manager import SessionState
+        
+        session = SessionState(
+            conversation_id="conv-123",
+            user_id="user-456",
+            message_count=5,
+            tags=["tag1"],
+            metadata={"key": "value"},
+        )
+        
+        data = session.to_dict()
+        
+        assert data["conversation_id"] == "conv-123"
+        assert data["user_id"] == "user-456"
+        assert data["message_count"] == 5
+        assert data["tags"] == ["tag1"]
+        assert data["metadata"]["key"] == "value"
+    
+    def test_session_from_dict(self):
+        """Should deserialize SessionState from dictionary."""
+        from gateforge.session_manager import SessionState
+        
+        data = {
+            "conversation_id": "conv-789",
+            "user_id": "user-999",
+            "message_count": 10,
+            "tags": ["a", "b"],
+            "metadata": {"x": 1},
+        }
+        
+        session = SessionState.from_dict(data)
+        
+        assert session.conversation_id == "conv-789"
+        assert session.user_id == "user-999"
+        assert session.message_count == 10
+        assert session.tags == ["a", "b"]
+    
+    def test_session_touch(self):
+        """Should update timestamp and increment message count."""
+        from gateforge.session_manager import SessionState
+        
+        session = SessionState(conversation_id="conv-123", message_count=0)
+        old_updated = session.updated_at
+        
+        time.sleep(0.01)  # Small delay to ensure timestamp changes
+        session.touch()
+        
+        assert session.message_count == 1
+        assert session.updated_at > old_updated
+    
+    def test_session_add_tag(self):
+        """Should add tag to session."""
+        from gateforge.session_manager import SessionState
+        
+        session = SessionState(conversation_id="conv-123")
+        session.add_tag("weather")
+        session.add_tag("agent")
+        
+        assert "weather" in session.tags
+        assert "agent" in session.tags
+        assert len(session.tags) == 2
+    
+    def test_session_add_duplicate_tag(self):
+        """Should not add duplicate tags."""
+        from gateforge.session_manager import SessionState
+        
+        session = SessionState(conversation_id="conv-123")
+        session.add_tag("test")
+        session.add_tag("test")  # Duplicate
+        
+        assert session.tags == ["test"]
+        assert len(session.tags) == 1
+    
+    def test_session_set_metadata(self):
+        """Should set metadata field."""
+        from gateforge.session_manager import SessionState
+        
+        session = SessionState(conversation_id="conv-123")
+        session.set_metadata("model", "gemini-2.5-flash")
+        session.set_metadata("temperature", 0.7)
+        
+        assert session.metadata["model"] == "gemini-2.5-flash"
+        assert session.metadata["temperature"] == 0.7
+
+
+class TestSessionManager:
+    """Tests for SessionManager."""
+    
+    def test_create_session(self):
+        """Should create new session."""
+        from gateforge.session_manager import SessionManager
+        
+        manager = SessionManager()
+        session = manager.create_session(user_id="user-123")
+        
+        assert session.conversation_id is not None
+        assert session.user_id == "user-123"
+        assert len(manager) == 1
+    
+    def test_create_session_with_explicit_id(self):
+        """Should create session with explicit conversation_id."""
+        from gateforge.session_manager import SessionManager
+        
+        manager = SessionManager()
+        session = manager.create_session(
+            conversation_id="my-conv-123",
+            user_id="user-456",
+        )
+        
+        assert session.conversation_id == "my-conv-123"
+        assert session.user_id == "user-456"
+    
+    def test_get_session(self):
+        """Should retrieve existing session."""
+        from gateforge.session_manager import SessionManager
+        
+        manager = SessionManager()
+        session = manager.create_session(user_id="user-789")
+        
+        retrieved = manager.get_session(session.conversation_id)
+        
+        assert retrieved is not None
+        assert retrieved.user_id == "user-789"
+    
+    def test_get_session_not_found(self):
+        """Should return None for non-existent session."""
+        from gateforge.session_manager import SessionManager
+        
+        manager = SessionManager()
+        retrieved = manager.get_session("non-existent")
+        
+        assert retrieved is None
+    
+    def test_get_or_create_session_existing(self):
+        """Should return existing session."""
+        from gateforge.session_manager import SessionManager
+        
+        manager = SessionManager()
+        session1 = manager.create_session(
+            conversation_id="conv-123",
+            user_id="user-original",
+        )
+        
+        session2 = manager.get_or_create_session(
+            conversation_id="conv-123",
+            user_id="user-new",  # Should be ignored
+        )
+        
+        assert session2.user_id == "user-original"
+        assert session1 is session2
+    
+    def test_get_or_create_session_new(self):
+        """Should create new session if not exists."""
+        from gateforge.session_manager import SessionManager
+        
+        manager = SessionManager()
+        
+        session = manager.get_or_create_session(
+            conversation_id="new-conv",
+            user_id="user-new",
+        )
+        
+        assert session.conversation_id == "new-conv"
+        assert session.user_id == "user-new"
+    
+    def test_touch_session(self):
+        """Should update session activity."""
+        from gateforge.session_manager import SessionManager
+        
+        manager = SessionManager()
+        session = manager.create_session(conversation_id="conv-123")
+        
+        manager.touch("conv-123")
+        
+        assert session.message_count == 1
+    
+    def test_delete_session(self):
+        """Should delete session."""
+        from gateforge.session_manager import SessionManager
+        
+        manager = SessionManager()
+        session = manager.create_session(conversation_id="conv-123")
+        
+        result = manager.delete_session("conv-123")
+        
+        assert result is True
+        assert len(manager) == 0
+        assert manager.get_session("conv-123") is None
+    
+    def test_delete_nonexistent_session(self):
+        """Should return False for non-existent session."""
+        from gateforge.session_manager import SessionManager
+        
+        manager = SessionManager()
+        result = manager.delete_session("non-existent")
+        
+        assert result is False
+    
+    def test_list_sessions_all(self):
+        """Should list all sessions."""
+        from gateforge.session_manager import SessionManager
+        
+        manager = SessionManager()
+        manager.create_session(conversation_id="conv-1")
+        manager.create_session(conversation_id="conv-2")
+        manager.create_session(conversation_id="conv-3")
+        
+        sessions = manager.list_sessions()
+        
+        assert len(sessions) == 3
+    
+    def test_list_sessions_by_user(self):
+        """Should filter sessions by user_id."""
+        from gateforge.session_manager import SessionManager
+        
+        manager = SessionManager()
+        manager.create_session(conversation_id="conv-1", user_id="user-a")
+        manager.create_session(conversation_id="conv-2", user_id="user-b")
+        manager.create_session(conversation_id="conv-3", user_id="user-a")
+        
+        sessions = manager.list_sessions(user_id="user-a")
+        
+        assert len(sessions) == 2
+        assert all(s.user_id == "user-a" for s in sessions)
+    
+    def test_list_sessions_by_tags(self):
+        """Should filter sessions by tags."""
+        from gateforge.session_manager import SessionManager
+        
+        manager = SessionManager()
+        manager.create_session(conversation_id="conv-1", tags=["weather"])
+        manager.create_session(conversation_id="conv-2", tags=["search"])
+        manager.create_session(conversation_id="conv-3", tags=["weather", "agent"])
+        
+        sessions = manager.list_sessions(tags=["weather"])
+        
+        assert len(sessions) == 2
+    
+    def test_list_sessions_limit(self):
+        """Should limit number of sessions returned."""
+        from gateforge.session_manager import SessionManager
+        
+        manager = SessionManager()
+        for i in range(10):
+            manager.create_session(conversation_id=f"conv-{i}")
+        
+        sessions = manager.list_sessions(limit=3)
+        
+        assert len(sessions) == 3
+    
+    def test_list_sessions_sorted_by_updated(self):
+        """Should return sessions sorted by updated_at (most recent first)."""
+        from gateforge.session_manager import SessionManager
+        import time
+        
+        manager = SessionManager()
+        manager.create_session(conversation_id="conv-1")
+        time.sleep(0.01)
+        manager.create_session(conversation_id="conv-2")
+        time.sleep(0.01)
+        manager.create_session(conversation_id="conv-3")
+        
+        sessions = manager.list_sessions()
+        
+        assert sessions[0].conversation_id == "conv-3"
+        assert sessions[1].conversation_id == "conv-2"
+        assert sessions[2].conversation_id == "conv-1"
+    
+    def test_serialize_to_dict(self):
+        """Should serialize all sessions to dictionary."""
+        from gateforge.session_manager import SessionManager
+        
+        manager = SessionManager()
+        manager.create_session(
+            conversation_id="conv-123",
+            user_id="user-456",
+            tags=["test"],
+        )
+        
+        data = manager.to_dict()
+        
+        assert "sessions" in data
+        assert "conv-123" in data["sessions"]
+        assert data["sessions"]["conv-123"]["user_id"] == "user-456"
+    
+    def test_deserialize_from_dict(self):
+        """Should deserialize SessionManager from dictionary."""
+        from gateforge.session_manager import SessionManager
+        
+        data = {
+            "sessions": {
+                "conv-123": {
+                    "conversation_id": "conv-123",
+                    "user_id": "user-456",
+                    "message_count": 5,
+                    "tags": ["a", "b"],
+                    "metadata": {},
+                }
+            }
+        }
+        
+        manager = SessionManager.from_dict(data)
+        
+        assert len(manager) == 1
+        session = manager.get_session("conv-123")
+        assert session.user_id == "user-456"
+        assert session.message_count == 5
+    
+    def test_contains(self):
+        """Should support 'in' operator."""
+        from gateforge.session_manager import SessionManager
+        
+        manager = SessionManager()
+        manager.create_session(conversation_id="conv-123")
+        
+        assert "conv-123" in manager
+        assert "conv-456" not in manager
+    
+    def test_len(self):
+        """Should support len()."""
+        from gateforge.session_manager import SessionManager
+        
+        manager = SessionManager()
+        manager.create_session(conversation_id="conv-1")
+        manager.create_session(conversation_id="conv-2")
+        
+        assert len(manager) == 2
+
+
+class TestGlobalHelpers:
+    """Tests for global helper functions."""
+    
+    def test_create_session_global(self):
+        """Should create session using default manager."""
+        from gateforge.session_manager import create_session, get_session_manager
+        
+        # Clear default manager
+        import gateforge.session_manager as sm
+        sm._default_manager = None
+        
+        session = create_session(user_id="test-user")
+        
+        assert session.user_id == "test-user"
+        assert len(get_session_manager()) == 1
+    
+    def test_get_session_global(self):
+        """Should get session using default manager."""
+        from gateforge.session_manager import create_session, get_session
+        
+        # Clear default manager
+        import gateforge.session_manager as sm
+        sm._default_manager = None
+        
+        session = create_session(conversation_id="test-conv")
+        retrieved = get_session("test-conv")
+        
+        assert retrieved is session
+    
+    def test_get_current_conversation_id_with_trace(self):
+        """Should return conversation_id from active trace."""
+        from gateforge.session_manager import get_current_conversation_id
+        from gateforge.context import trace
+        
+        with trace(conversation_id="test-conv-123"):
+            cid = get_current_conversation_id()
+            assert cid == "test-conv-123"
+    
+    def test_get_current_conversation_id_no_trace(self):
+        """Should return None when no active trace."""
+        from gateforge.session_manager import get_current_conversation_id
+        
+        cid = get_current_conversation_id()
+        assert cid is None
+    
+    def test_get_current_trace_info(self):
+        """Should return trace info dictionary."""
+        from gateforge.session_manager import get_current_trace_info
+        from gateforge.context import trace
+        
+        with trace(conversation_id="test-conv") as t:
+            # Advance step
+            t.next_step()
+            
+            info = get_current_trace_info()
+            
+            assert info is not None
+            assert info["conversation_id"] == "test-conv"
+            assert info["trace_id"] is not None
+            assert info["step"] == 1
+    
+    def test_get_current_trace_info_no_trace(self):
+        """Should return None when no active trace."""
+        from gateforge.session_manager import get_current_trace_info
+        
+        info = get_current_trace_info()
+        assert info is None
+
+
+class TestIntegration:
+    """Integration tests for Phase 2 features."""
+    
+    def test_session_manager_with_trace(self):
+        """Should work with trace context manager."""
+        from gateforge.session_manager import SessionManager
+        from gateforge.context import trace
+        
+        manager = SessionManager()
+        session = manager.create_session(conversation_id="conv-123")
+        
+        with trace(conversation_id=session.conversation_id) as t:
+            # Simulate tool call
+            t.next_step()
+            t.next_step()
+        
+        manager.touch(session.conversation_id)
+        
+        assert session.message_count == 1
+        assert t.step == 2
+    
+    def test_multiple_concurrent_sessions(self):
+        """Should handle multiple concurrent sessions."""
+        from gateforge.session_manager import SessionManager
+        from gateforge.context import trace, get_active_trace
+        
+        manager = SessionManager()
+        
+        # Create two sessions
+        session1 = manager.create_session(conversation_id="conv-a")
+        session2 = manager.create_session(conversation_id="conv-b")
+        
+        # Use first session
+        with trace(conversation_id=session1.conversation_id):
+            assert get_active_trace().conversation_id == "conv-a"
+        
+        # Use second session
+        with trace(conversation_id=session2.conversation_id):
+            assert get_active_trace().conversation_id == "conv-b"
+        
+        # Outside trace, no active session
+        assert get_active_trace() is None
+    
+    def test_session_persistence_roundtrip(self):
+        """Should serialize and deserialize correctly."""
+        from gateforge.session_manager import SessionManager
+        
+        # Create manager with sessions
+        manager1 = SessionManager()
+        manager1.create_session(
+            conversation_id="conv-1",
+            user_id="user-a",
+            tags=["test"],
+            metadata={"key": "value1"},
+        )
+        manager1.create_session(
+            conversation_id="conv-2",
+            user_id="user-b",
+            tags=["prod"],
+            metadata={"key": "value2"},
+        )
+        
+        # Serialize
+        data = manager1.to_dict()
+        
+        # Deserialize
+        manager2 = SessionManager.from_dict(data)
+        
+        # Verify
+        assert len(manager2) == 2
+        
+        s1 = manager2.get_session("conv-1")
+        assert s1.user_id == "user-a"
+        assert s1.tags == ["test"]
+        assert s1.metadata["key"] == "value1"
+        
+        s2 = manager2.get_session("conv-2")
+        assert s2.user_id == "user-b"
+        assert s2.tags == ["prod"]
+        assert s2.metadata["key"] == "value2"
+
+
+if __name__ == '__main__':
+    pytest.main([__file__, '-v'])