htmlgraph 0.26.23__py3-none-any.whl → 0.26.24__py3-none-any.whl

htmlgraph/db/schema.py

@@ -163,6 +163,12 @@ class HtmlGraphDB:
             ("completed_at", "DATETIME"),
             ("last_user_query_at", "DATETIME"),
             ("last_user_query", "TEXT"),
+            # Phase 2 Feature 3: Cross-Session Continuity handoff fields
+            ("handoff_notes", "TEXT"),
+            ("recommended_next", "TEXT"),
+            ("blockers", "TEXT"),  # JSON array of blocker strings
+            ("recommended_context", "TEXT"),  # JSON array of file paths
+            ("continued_from", "TEXT"),  # Previous session ID
         ]
 
         # Refresh columns after potential rename
@@ -291,8 +297,14 @@ class HtmlGraphDB:
                 metadata JSON,
                 last_user_query_at DATETIME,
                 last_user_query TEXT,
+                handoff_notes TEXT,
+                recommended_next TEXT,
+                blockers JSON,
+                recommended_context JSON,
+                continued_from TEXT,
                 FOREIGN KEY (parent_session_id) REFERENCES sessions(session_id) ON DELETE SET NULL ON UPDATE CASCADE,
-                FOREIGN KEY (parent_event_id) REFERENCES agent_events(event_id) ON DELETE SET NULL ON UPDATE CASCADE
+                FOREIGN KEY (parent_event_id) REFERENCES agent_events(event_id) ON DELETE SET NULL ON UPDATE CASCADE,
+                FOREIGN KEY (continued_from) REFERENCES sessions(session_id) ON DELETE SET NULL ON UPDATE CASCADE
             )
         """)
 
@@ -407,6 +419,23 @@ class HtmlGraphDB:
             )
         """)
 
+        # 10. HANDOFF_TRACKING TABLE - Phase 2 Feature 3: Track handoff effectiveness
+        cursor.execute("""
+            CREATE TABLE IF NOT EXISTS handoff_tracking (
+                handoff_id TEXT PRIMARY KEY,
+                from_session_id TEXT NOT NULL,
+                to_session_id TEXT,
+                items_in_context INTEGER DEFAULT 0,
+                items_accessed INTEGER DEFAULT 0,
+                time_to_resume_seconds INTEGER DEFAULT 0,
+                user_rating INTEGER CHECK(user_rating BETWEEN 1 AND 5),
+                created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+                resumed_at DATETIME,
+                FOREIGN KEY (from_session_id) REFERENCES sessions(session_id) ON DELETE CASCADE,
+                FOREIGN KEY (to_session_id) REFERENCES sessions(session_id) ON DELETE SET NULL
+            )
+        """)
+
         # 9. Create indexes for performance
         self._create_indexes(cursor)
 
@@ -496,6 +525,10 @@ class HtmlGraphDB:
             # live_events indexes - optimized for real-time WebSocket streaming
             "CREATE INDEX IF NOT EXISTS idx_live_events_pending ON live_events(broadcast_at) WHERE broadcast_at IS NULL",
             "CREATE INDEX IF NOT EXISTS idx_live_events_created ON live_events(created_at DESC)",
+            # handoff_tracking indexes - optimized for handoff effectiveness queries
+            "CREATE INDEX IF NOT EXISTS idx_handoff_from_session ON handoff_tracking(from_session_id, created_at DESC)",
+            "CREATE INDEX IF NOT EXISTS idx_handoff_to_session ON handoff_tracking(to_session_id, resumed_at DESC)",
+            "CREATE INDEX IF NOT EXISTS idx_handoff_rating ON handoff_tracking(user_rating, created_at DESC)",
         ]
 
         for index_sql in indexes:

htmlgraph/models.py

@@ -975,10 +975,13 @@ class Session(BaseModel):
     parent_activity: str | None = None  # Parent activity ID
     nesting_depth: int = 0  # Depth of nesting (0 = top-level)
 
-    # Handoff context
+    # Handoff context (Phase 2 Feature 3: Cross-Session Continuity)
     handoff_notes: str | None = None
     recommended_next: str | None = None
     blockers: list[str] = Field(default_factory=list)
+    recommended_context: list[str] = Field(
+        default_factory=list
+    )  # File paths to keep context for
 
     # High-frequency activity log
     activity_log: list[ActivityEntry] = Field(default_factory=list)

htmlgraph/sdk.py

@@ -333,6 +333,11 @@ class SDK:
         # Context analytics interface (Context usage tracking)
         self.context = ContextAnalytics(self)
 
+        # Pattern learning interface (Phase 2: Behavior Pattern Learning)
+        from htmlgraph.analytics.pattern_learning import PatternLearner
+
+        self.pattern_learning = PatternLearner(self._directory)
+
         # Lazy-loaded orchestrator for subagent management
         self._orchestrator: Any = None
 
@@ -776,6 +781,92 @@ class SDK:
             blockers=blockers,
         )
 
+    def continue_from_last(
+        self,
+        agent: str | None = None,
+        auto_create_session: bool = True,
+    ) -> tuple[Any, Any]:
+        """
+        Continue work from the last completed session.
+
+        Loads context from previous session including handoff notes,
+        recommended files, blockers, and recent commits.
+
+        Args:
+            agent: Filter by agent (None = current SDK agent)
+            auto_create_session: Create new session if True
+
+        Returns:
+            Tuple of (new_session, resume_info) or (None, None)
+
+        Example:
+            >>> sdk = SDK(agent="claude")
+            >>> session, resume = sdk.continue_from_last()
+            >>> if resume:
+            ...     print(resume.summary)
+            ...     print(resume.next_focus)
+            ...     for file in resume.recommended_files:
+            ...         print(f"  - {file}")
+        """
+        if not agent:
+            agent = self._agent_id
+
+        return self.session_manager.continue_from_last(
+            agent=agent,
+            auto_create_session=auto_create_session,
+        )
+
+    def end_session_with_handoff(
+        self,
+        session_id: str | None = None,
+        summary: str | None = None,
+        next_focus: str | None = None,
+        blockers: list[str] | None = None,
+        keep_context: list[str] | None = None,
+        auto_recommend_context: bool = True,
+    ) -> Any:
+        """
+        End session with handoff information for next session.
+
+        Args:
+            session_id: Session to end (None = active session)
+            summary: What was accomplished
+            next_focus: What should be done next
+            blockers: List of blockers
+            keep_context: List of files to keep context for
+            auto_recommend_context: Auto-recommend files from git
+
+        Returns:
+            Updated Session or None
+
+        Example:
+            >>> sdk.end_session_with_handoff(
+            ...     summary="Completed OAuth integration",
+            ...     next_focus="Implement JWT token refresh",
+            ...     blockers=["Waiting for security review"],
+            ...     keep_context=["src/auth/oauth.py"]
+            ... )
+        """
+        if not session_id:
+            if self._agent_id:
+                active = self.session_manager.get_active_session_for_agent(
+                    self._agent_id
+                )
+            else:
+                active = self.session_manager.get_active_session()
+            if not active:
+                return None
+            session_id = active.id
+
+        return self.session_manager.end_session_with_handoff(
+            session_id=session_id,
+            summary=summary,
+            next_focus=next_focus,
+            blockers=blockers,
+            keep_context=keep_context,
+            auto_recommend_context=auto_recommend_context,
+        )
+
     def start_session(
         self,
         session_id: str | None = None,

htmlgraph/session_manager.py

@@ -186,7 +186,7 @@ class SessionManager:
         """Mark a session as stale (kept for history but not considered active)."""
         if session.status != "active":
             return
-        now = datetime.now()
+        now = datetime.now(timezone.utc)
         session.status = "stale"
         session.ended_at = now
         session.last_activity = now
@@ -742,7 +742,7 @@ class SessionManager:
             ActivityEntry(
                 tool="SessionEnd",
                 summary="Session ended",
-                timestamp=datetime.now(),
+                timestamp=datetime.now(timezone.utc),
             )
         )
 
@@ -792,6 +792,164 @@ class SessionManager:
 
         return session
 
+    def continue_from_last(
+        self,
+        agent: str | None = None,
+        auto_create_session: bool = True,
+    ) -> tuple[Session | None, Any]:  # Returns (new_session, resume_info)
+        """
+        Continue work from the last completed session.
+
+        Loads context from the previous session including:
+        - Handoff notes and next focus
+        - Blockers
+        - Recommended context files
+        - Recent commits
+        - Features worked on
+
+        Args:
+            agent: Filter by agent (None = current agent)
+            auto_create_session: Create new session if True
+
+        Returns:
+            Tuple of (new_session, resume_info) or (None, None) if no previous session
+
+        Example:
+            >>> manager = SessionManager(".htmlgraph")
+            >>> new_session, resume = manager.continue_from_last(agent="claude")
+            >>> if resume:
+            ...     print(resume.summary)
+            ...     print(resume.recommended_files)
+        """
+        # Import handoff module
+        from typing import Any
+
+        from htmlgraph.sessions.handoff import SessionResume
+
+        # Create a minimal SDK-like object with just the directory
+        # to avoid circular dependency and database initialization issues
+        class MinimalSDK:
+            def __init__(self, directory: Path) -> None:
+                self._directory = directory
+
+        sdk: Any = MinimalSDK(self.graph_dir)
+        resume = SessionResume(sdk)
+
+        # Get last session
+        last_session = resume.get_last_session(agent=agent)
+        if not last_session:
+            return None, None
+
+        # Build resume info
+        resume_info = resume.build_resume_info(last_session)
+
+        # Create new session if requested
+        new_session = None
+        if auto_create_session:
+            from htmlgraph.ids import generate_id
+
+            session_id = generate_id("sess")
+            new_session = self.start_session(
+                session_id=session_id,
+                agent=agent or last_session.agent,
+                title=f"Continuing from {last_session.id}",
+            )
+
+            # Link to previous session
+            new_session.continued_from = last_session.id
+            self.session_converter.save(new_session)
+
+        return new_session, resume_info
+
+    def end_session_with_handoff(
+        self,
+        session_id: str,
+        summary: str | None = None,
+        next_focus: str | None = None,
+        blockers: list[str] | None = None,
+        keep_context: list[str] | None = None,
+        auto_recommend_context: bool = True,
+    ) -> Session | None:
+        """
+        End session with handoff information for next session.
+
+        Args:
+            session_id: Session to end
+            summary: What was accomplished (handoff notes)
+            next_focus: What should be done next
+            blockers: List of blockers preventing progress
+            keep_context: List of files to keep context for
+            auto_recommend_context: Auto-recommend files from git history
+
+        Returns:
+            Updated session or None
+
+        Example:
+            >>> manager.end_session_with_handoff(
+            ...     session_id="sess-123",
+            ...     summary="Completed OAuth integration",
+            ...     next_focus="Implement JWT token refresh",
+            ...     blockers=["Waiting for security review"],
+            ...     keep_context=["src/auth/oauth.py"]
+            ... )
+        """
+        from htmlgraph.sessions.handoff import (
+            ContextRecommender,
+            HandoffBuilder,
+        )
+
+        # Get session
+        session = self.get_session(session_id)
+        if not session:
+            return None
+
+        # Build handoff using HandoffBuilder
+        builder = HandoffBuilder(session)
+
+        if summary:
+            builder.add_summary(summary)
+
+        if next_focus:
+            builder.add_next_focus(next_focus)
+
+        if blockers:
+            builder.add_blockers(blockers)
+
+        if keep_context:
+            builder.add_context_files(keep_context)
+
+        # Auto-recommend context files
+        if auto_recommend_context:
+            recommender = ContextRecommender()
+            builder.auto_recommend_context(recommender, max_files=10)
+
+        handoff_data = builder.build()
+
+        # Update session with handoff data
+        session.handoff_notes = handoff_data["handoff_notes"]
+        session.recommended_next = handoff_data["recommended_next"]
+        session.blockers = handoff_data["blockers"]
+
+        # Store recommended_context as JSON-serializable list
+        # (Session model expects list[str], converter will handle serialization)
+        if hasattr(session, "__dict__"):
+            session.__dict__["recommended_context"] = handoff_data[
+                "recommended_context"
+            ]
+
+        # Persist handoff data to database before ending session
+        self.session_converter.save(session)
+
+        # End the session
+        self.end_session(session_id)
+
+        # Track handoff effectiveness (optional - only if database available)
+        # Note: SessionManager doesn't have direct database access,
+        # handoff tracking is primarily done through SDK
+        # Users should use SDK.end_session_with_handoff() for full tracking
+
+        return session
+
     def release_session_features(self, session_id: str) -> list[str]:
         """
         Release all features claimed by a specific session.

htmlgraph/sessions/__init__.py

@@ -0,0 +1,23 @@
+"""
+Session management and continuity.
+
+Provides session lifecycle, handoff, and resumption features.
+"""
+
+from htmlgraph.sessions.handoff import (
+    ContextRecommender,
+    HandoffBuilder,
+    HandoffMetrics,
+    HandoffTracker,
+    SessionResume,
+    SessionResumeInfo,
+)
+
+__all__ = [
+    "HandoffBuilder",
+    "SessionResume",
+    "SessionResumeInfo",
+    "HandoffTracker",
+    "HandoffMetrics",
+    "ContextRecommender",
+]