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

htmlgraph/sdk/session/info.py

@@ -0,0 +1,309 @@
+"""
+Session info mixin for SDK - session start info and active work tracking.
+
+Provides optimized methods for session context gathering.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from htmlgraph.session_manager import SessionManager
+    from htmlgraph.types import ActiveWorkItem, SessionStartInfo
+
+
+class SessionInfoMixin:
+    """
+    Mixin providing session info and active work methods to SDK.
+
+    Provides optimized methods for gathering session context in single calls.
+    Requires SDK instance with _directory, _agent_id, session_manager attributes.
+    """
+
+    _directory: Path
+    _agent_id: str | None
+    session_manager: SessionManager
+
+    def get_session_start_info(
+        self,
+        include_git_log: bool = True,
+        git_log_count: int = 5,
+        analytics_top_n: int = 3,
+        analytics_max_agents: int = 3,
+    ) -> SessionStartInfo:
+        """
+        Get comprehensive session start information in a single call.
+
+        Consolidates all information needed for session start into one method,
+        reducing context usage from 6+ tool calls to 1.
+
+        Args:
+            include_git_log: Include recent git commits (default: True)
+            git_log_count: Number of recent commits to include (default: 5)
+            analytics_top_n: Number of bottlenecks/recommendations (default: 3)
+            analytics_max_agents: Max agents for parallel work analysis (default: 3)
+
+        Returns:
+            Dict with comprehensive session start context:
+                - status: Project status (nodes, collections, WIP)
+                - active_work: Current active work item (if any)
+                - features: List of features with status
+                - sessions: Recent sessions
+                - git_log: Recent commits (if include_git_log=True)
+                - analytics: Strategic insights (bottlenecks, recommendations, parallel)
+
+        Note:
+            Returns empty dict {} if session context unavailable.
+            Always check for expected keys before accessing.
+
+        Example:
+            >>> sdk = SDK(agent="claude")
+            >>> info = sdk.get_session_start_info()
+            >>> logger.info(f"Project: {info['status']['total_nodes']} nodes")
+            >>> logger.info(f"WIP: {info['status']['in_progress_count']}")
+            >>> if info.get('active_work'):
+            ...     logger.info(f"Active: {info['active_work']['title']}")
+            >>> for bn in info['analytics']['bottlenecks']:
+            ...     logger.info(f"Bottleneck: {bn['title']}")
+        """
+        result: dict[str, Any] = {}
+
+        # 1. Project status
+        result["status"] = self.get_status()  # type: ignore[attr-defined]
+
+        # 2. Active work item (validation status) - always include, even if None
+        result["active_work"] = self.get_active_work_item()
+
+        # 3. Features list (simplified)
+        features_list: list[dict[str, object]] = []
+        for feature in self.features.all():  # type: ignore[attr-defined]
+            features_list.append(
+                {
+                    "id": feature.id,
+                    "title": feature.title,
+                    "status": feature.status,
+                    "priority": feature.priority,
+                    "steps_total": len(feature.steps),
+                    "steps_completed": sum(1 for s in feature.steps if s.completed),
+                }
+            )
+        result["features"] = features_list
+
+        # 4. Sessions list (recent 20)
+        sessions_list: list[dict[str, Any]] = []
+        for session in self.sessions.all()[:20]:  # type: ignore[attr-defined]
+            sessions_list.append(
+                {
+                    "id": session.id,
+                    "status": session.status,
+                    "agent": session.properties.get("agent", "unknown"),
+                    "event_count": session.properties.get("event_count", 0),
+                    "started": session.created.isoformat()
+                    if hasattr(session, "created")
+                    else None,
+                }
+            )
+        result["sessions"] = sessions_list
+
+        # 5. Git log (if requested)
+        if include_git_log:
+            try:
+                git_result = subprocess.run(
+                    ["git", "log", "--oneline", f"-{git_log_count}"],
+                    capture_output=True,
+                    text=True,
+                    check=True,
+                    cwd=self._directory.parent,
+                )
+                git_lines: list[str] = git_result.stdout.strip().split("\n")
+                result["git_log"] = git_lines
+            except (subprocess.CalledProcessError, FileNotFoundError):
+                empty_list: list[str] = []
+                result["git_log"] = empty_list
+
+        # 6. Strategic analytics
+        result["analytics"] = {
+            "bottlenecks": self.find_bottlenecks(top_n=analytics_top_n),  # type: ignore[attr-defined]
+            "recommendations": self.recommend_next_work(agent_count=analytics_top_n),  # type: ignore[attr-defined]
+            "parallel": self.get_parallel_work(max_agents=analytics_max_agents),  # type: ignore[attr-defined]
+        }
+
+        return result  # type: ignore[return-value]
+
+    def get_active_work_item(
+        self,
+        agent: str | None = None,
+        filter_by_agent: bool = False,
+        work_types: list[str] | None = None,
+    ) -> ActiveWorkItem | None:
+        """
+        Get the currently active work item (in-progress status).
+
+        This is used by the PreToolUse validation hook to check if code changes
+        have an active work item for attribution.
+
+        Args:
+            agent: Agent ID for filtering (optional)
+            filter_by_agent: If True, filter by agent. If False (default), return any active work item
+            work_types: Work item types to check (defaults to all: features, bugs, spikes, chores, epics)
+
+        Returns:
+            Dict with work item details or None if no active work item found:
+                - id: Work item ID
+                - title: Work item title
+                - type: Work item type (feature, bug, spike, chore, epic)
+                - status: Should be "in-progress"
+                - agent: Assigned agent
+                - steps_total: Total steps
+                - steps_completed: Completed steps
+                - auto_generated: (spikes only) True if auto-generated spike
+                - spike_subtype: (spikes only) "session-init" or "transition"
+
+        Example:
+            >>> sdk = SDK(agent="claude")
+            >>> # Get any active work item
+            >>> active = sdk.get_active_work_item()
+            >>> if active:
+            ...     logger.info(f"Working on: {active['title']}")
+            ...
+            >>> # Get only this agent's active work item
+            >>> active = sdk.get_active_work_item(filter_by_agent=True)
+        """
+        # Default to all work item types
+        if work_types is None:
+            work_types = ["features", "bugs", "spikes", "chores", "epics"]
+
+        # Search across all work item types
+        # Separate real work items from auto-generated spikes
+        real_work_items: list[dict[str, Any]] = []
+        auto_spikes: list[dict[str, Any]] = []
+
+        for work_type in work_types:
+            collection = getattr(self, work_type, None)
+            if collection is None:
+                continue
+
+            # Query for in-progress items
+            in_progress = collection.where(status="in-progress")
+
+            for item in in_progress:
+                # Filter by agent if requested
+                if filter_by_agent:
+                    agent_id = agent or self._agent_id
+                    if agent_id and hasattr(item, "agent_assigned"):
+                        if item.agent_assigned != agent_id:
+                            continue
+
+                item_dict: dict[str, Any] = {
+                    "id": item.id,
+                    "title": item.title,
+                    "type": item.type,
+                    "status": item.status,
+                    "agent": getattr(item, "agent_assigned", None),
+                    "steps_total": len(item.steps) if hasattr(item, "steps") else 0,
+                    "steps_completed": sum(1 for s in item.steps if s.completed)
+                    if hasattr(item, "steps")
+                    else 0,
+                }
+
+                # Add spike-specific fields for auto-spike detection
+                if item.type == "spike":
+                    item_dict["auto_generated"] = getattr(item, "auto_generated", False)
+                    item_dict["spike_subtype"] = getattr(item, "spike_subtype", None)
+
+                    # Separate auto-spikes from real work
+                    # Auto-spikes are temporary tracking items (session-init, transition, conversation-init)
+                    is_auto_spike = item_dict["auto_generated"] and item_dict[
+                        "spike_subtype"
+                    ] in ("session-init", "transition", "conversation-init")
+
+                    if is_auto_spike:
+                        auto_spikes.append(item_dict)
+                    else:
+                        # Real user-created spike
+                        real_work_items.append(item_dict)
+                else:
+                    # Features, bugs, chores, epics are always real work
+                    real_work_items.append(item_dict)
+
+        # Prioritize real work items over auto-spikes
+        # Auto-spikes should only show if there's NO other active work item
+        if real_work_items:
+            return real_work_items[0]  # type: ignore[return-value]
+
+        if auto_spikes:
+            return auto_spikes[0]  # type: ignore[return-value]
+
+        return None
+
+    def track_activity(
+        self,
+        tool: str,
+        summary: str,
+        file_paths: list[str] | None = None,
+        success: bool = True,
+        feature_id: str | None = None,
+        session_id: str | None = None,
+        parent_activity_id: str | None = None,
+        payload: dict[str, Any] | None = None,
+    ) -> Any:
+        """
+        Track an activity in the current or specified session.
+
+        Args:
+            tool: Tool name (Edit, Bash, Read, etc.)
+            summary: Human-readable summary of the activity
+            file_paths: Files involved in this activity
+            success: Whether the tool call succeeded
+            feature_id: Explicit feature ID (skips attribution if provided)
+            session_id: Session ID (defaults to parent session if available, then active session)
+            parent_activity_id: ID of parent activity (e.g., Skill/Task invocation)
+            payload: Optional rich payload data
+
+        Returns:
+            Created ActivityEntry with attribution
+
+        Example:
+            >>> sdk = SDK(agent="claude")
+            >>> entry = sdk.track_activity(
+            ...     tool="CustomTool",
+            ...     summary="Performed custom analysis",
+            ...     file_paths=["src/main.py"],
+            ...     success=True
+            ... )
+            >>> logger.info(f"Tracked: [{entry.tool}] {entry.summary}")
+        """
+        # Determine target session: explicit parameter > parent_session > active > none
+        if not session_id:
+            # Priority 1: Parent session (explicitly provided or from env var)
+            if hasattr(self, "_parent_session") and self._parent_session:  # type: ignore[attr-defined]
+                session_id = self._parent_session  # type: ignore[attr-defined]
+            else:
+                # Priority 2: Active session for this agent
+                active = self.session_manager.get_active_session(agent=self._agent_id)
+                if active:
+                    session_id = active.id
+                else:
+                    raise ValueError(
+                        "No active session. Start one with sdk.start_session()"
+                    )
+
+        # Get parent activity ID from environment if not provided
+        if not parent_activity_id:
+            parent_activity_id = os.getenv("HTMLGRAPH_PARENT_ACTIVITY")
+
+        return self.session_manager.track_activity(
+            session_id=session_id,
+            tool=tool,
+            summary=summary,
+            file_paths=file_paths,
+            success=success,
+            feature_id=feature_id,
+            parent_activity_id=parent_activity_id,
+            payload=payload,
+        )

htmlgraph/sdk/session/manager.py

@@ -0,0 +1,103 @@
+"""
+SessionManager accessor and session creation/validation for SDK.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from htmlgraph.session_manager import SessionManager
+
+
+class SessionManagerMixin:
+    """
+    Provides SessionManager accessor and session lifecycle operations.
+
+    Attributes accessed by mixins:
+        session_manager: SessionManager instance
+        _db: HtmlGraphDB instance
+        _agent_id: Agent identifier
+        _parent_session: Parent session ID (if nested)
+    """
+
+    session_manager: SessionManager
+
+    def _ensure_session_exists(
+        self, session_id: str, parent_event_id: str | None = None
+    ) -> None:
+        """
+        Create a session record if it doesn't exist.
+
+        Args:
+            session_id: Session ID to ensure exists
+            parent_event_id: Event that spawned this session (optional)
+        """
+        if not self._db.connection:  # type: ignore[attr-defined]
+            self._db.connect()  # type: ignore[attr-defined]
+
+        cursor = self._db.connection.cursor()  # type: ignore[attr-defined,union-attr]
+        cursor.execute(
+            "SELECT COUNT(*) FROM sessions WHERE session_id = ?", (session_id,)
+        )
+        exists = cursor.fetchone()[0] > 0
+
+        if not exists:
+            # Create session record
+            self._db.insert_session(  # type: ignore[attr-defined]
+                session_id=session_id,
+                agent_assigned=self._agent_id,  # type: ignore[attr-defined]
+                is_subagent=self._parent_session is not None,  # type: ignore[attr-defined]
+                parent_session_id=self._parent_session,  # type: ignore[attr-defined]
+                parent_event_id=parent_event_id,
+            )
+
+    def start_session(
+        self,
+        session_id: str | None = None,
+        title: str | None = None,
+        agent: str | None = None,
+    ) -> Any:
+        """
+        Start a new session.
+
+        Args:
+            session_id: Optional session ID
+            title: Optional session title
+            agent: Optional agent override (defaults to SDK agent)
+
+        Returns:
+            New Session instance
+        """
+        return self.session_manager.start_session(
+            session_id=session_id,
+            agent=agent or self._agent_id or "cli",  # type: ignore[attr-defined]
+            title=title,
+            parent_session_id=self._parent_session,  # type: ignore[attr-defined]
+        )
+
+    def end_session(
+        self,
+        session_id: str,
+        handoff_notes: str | None = None,
+        recommended_next: str | None = None,
+        blockers: list[str] | None = None,
+    ) -> Any:
+        """
+        End a session.
+
+        Args:
+            session_id: Session ID to end
+            handoff_notes: Optional handoff notes
+            recommended_next: Optional recommendations
+            blockers: Optional blockers
+
+        Returns:
+            Ended Session instance
+        """
+        return self.session_manager.end_session(
+            session_id=session_id,
+            handoff_notes=handoff_notes,
+            recommended_next=recommended_next,
+            blockers=blockers,
+        )

htmlgraph/server.py

@@ -1,3 +1,7 @@
+import logging
+
+logger = logging.getLogger(__name__)
+
 """
 HtmlGraph REST API Server.
 
@@ -243,8 +247,8 @@ class HtmlGraphAPIHandler(SimpleHTTPRequestHandler):
     def do_GET(self) -> None:
         """Handle GET requests."""
         api, collection, node_id, params = self._parse_path()
-        print(
-            f"DEBUG do_GET: api={api}, collection={collection}, node_id={node_id}, params={params}"
+        logger.debug(
+            f"do_GET: api={api}, collection={collection}, node_id={node_id}, params={params}"
         )
 
         # Not an API request - serve static files
@@ -273,7 +277,7 @@ class HtmlGraphAPIHandler(SimpleHTTPRequestHandler):
 
         # GET /api/orchestration - Get delegation chains and agent coordination
         if collection == "orchestration":
-            print(f"DEBUG: Handling orchestration request, params={params}")
+            logger.info(f"DEBUG: Handling orchestration request, params={params}")
             return self._handle_orchestration_view(params)
 
         # GET /api/task-delegations/stats - Get aggregated delegation statistics
@@ -1275,7 +1279,7 @@ class HtmlGraphAPIHandler(SimpleHTTPRequestHandler):
 
     def log_message(self, format: str, *args: str) -> None:
         """Custom log format."""
-        print(f"[{datetime.now().strftime('%H:%M:%S')}] {args[0]}")
+        logger.info(f"[{datetime.now().strftime('%H:%M:%S')}] {args[0]}")
 
 
 def find_available_port(start_port: int = 8080, max_attempts: int = 10) -> int:
@@ -1434,7 +1438,7 @@ def serve(
         # Print warnings if any
         for warning in result.warnings:
             if not quiet:
-                print(f"⚠️  {warning}")
+                logger.info(f"⚠️  {warning}")
 
         # Print server info
         if not quiet:
@@ -1473,31 +1477,31 @@ Press Ctrl+C to stop.
         asyncio.run(run_fastapi_server(result.handle))
 
     except PortInUseError:
-        print(f"\n❌ Port {port} is already in use\n")
-        print("Solutions:")
-        print("  1. Use a different port:")
-        print(f"     htmlgraph serve --port {port + 1}\n")
-        print("  2. Let htmlgraph automatically find an available port:")
-        print("     htmlgraph serve --auto-port\n")
-        print(f"  3. Find and kill the process using port {port}:")
-        print(f"     lsof -ti:{port} | xargs kill -9\n")
+        logger.info(f"\n❌ Port {port} is already in use\n")
+        logger.info("Solutions:")
+        logger.info("  1. Use a different port:")
+        logger.info(f"     htmlgraph serve --port {port + 1}\n")
+        logger.info("  2. Let htmlgraph automatically find an available port:")
+        logger.info("     htmlgraph serve --auto-port\n")
+        logger.info(f"  3. Find and kill the process using port {port}:")
+        logger.info(f"     lsof -ti:{port} | xargs kill -9\n")
 
         # Try to find and suggest an available port
         try:
             alt_port = find_available_port(port + 1)
-            print(f"💡 Found available port: {alt_port}")
-            print(f"   Run: htmlgraph serve --port {alt_port}\n")
+            logger.info(f"💡 Found available port: {alt_port}")
+            logger.info(f"   Run: htmlgraph serve --port {alt_port}\n")
         except OSError:
             pass
 
         sys.exit(1)
 
     except FastAPIServerError as e:
-        print(f"\n❌ Server error: {e}\n")
+        logger.info(f"\n❌ Server error: {e}\n")
         sys.exit(1)
 
     except KeyboardInterrupt:
-        print("\nShutting down...")
+        logger.info("\nShutting down...")
 
 
 if __name__ == "__main__":

htmlgraph/session_manager.py

@@ -929,13 +929,7 @@ class SessionManager:
         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"
-            ]
+        session.recommended_context = handoff_data["recommended_context"]
 
         # Persist handoff data to database before ending session
         self.session_converter.save(session)

htmlgraph/session_warning.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """
 Session Warning System for AI Agents.
 
@@ -20,7 +22,6 @@ Usage:
     sdk.dismiss_session_warning()
 """
 
-from __future__ import annotations
 
 import json
 import sys

htmlgraph/sessions/handoff.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """
 Session Handoff and Continuity - Phase 2 Feature 3
 
@@ -19,11 +21,10 @@ Usage:
     # Resume next session
     resumed = sdk.sessions.continue_from_last()
     if resumed:
-        print(resumed.summary)
-        print(resumed.recommended_files)
+        logger.info("%s", resumed.summary)
+        logger.info("%s", resumed.recommended_files)
 """
 
-from __future__ import annotations
 
 import json
 import logging
@@ -613,6 +614,9 @@ class HandoffTracker:
         handoff_id = generate_id("hand")
 
         if self.db and self.db.connection:
+            # Ensure session exists in database (handles FK constraint)
+            self.db._ensure_session_exists(from_session_id)
+
             cursor = self.db.connection.cursor()
             cursor.execute(
                 """
@@ -649,6 +653,9 @@ class HandoffTracker:
             return False
 
         try:
+            # Ensure to_session exists in database (handles FK constraint)
+            self.db._ensure_session_exists(to_session_id)
+
             cursor = self.db.connection.cursor()
             cursor.execute(
                 """

htmlgraph/system_prompts.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """System prompt management for HtmlGraph projects.
 
 Provides a two-tier system:
@@ -10,7 +12,6 @@ Architecture:
 - SDK provides methods for creation, validation, and management
 """
 
-from __future__ import annotations
 
 import logging
 from pathlib import Path

htmlgraph/track_builder.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """
 Track Builder and Collection for agent-friendly track creation.
 
@@ -5,7 +7,6 @@ Note: TrackBuilder has been moved to builders/track.py for better organization.
 This module now provides TrackCollection and re-exports TrackBuilder for backward compatibility.
 """
 
-from __future__ import annotations
 
 from collections.abc import Iterator
 from contextlib import contextmanager
@@ -31,6 +32,18 @@ class TrackCollection:
         self.collection_name = "tracks"  # For backward compatibility
         self.id_prefix = "track"
         self._graph: HtmlGraph | None = None  # Lazy-loaded
+        self._ref_manager: Any = None  # Set by SDK during initialization
+
+    def set_ref_manager(self, ref_manager: Any) -> None:
+        """
+        Set the ref manager for this collection.
+
+        Called by SDK during initialization to enable short ref support.
+
+        Args:
+            ref_manager: RefManager instance from SDK
+        """
+        self._ref_manager = ref_manager
 
     def _ensure_graph(self) -> HtmlGraph:
         """Lazy-load the graph for tracks with multi-pattern support."""

htmlgraph/transcript.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """
 Claude Code Transcript Integration.
 
@@ -21,7 +23,6 @@ References:
     - https://github.com/simonw/claude-code-transcripts
 """
 
-from __future__ import annotations
 
 import json
 from collections.abc import Iterator

htmlgraph/watch.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """
 File-change watcher for HtmlGraph.
 
@@ -7,7 +9,6 @@ native "PostToolUse" hooks (e.g. editors/agents that write files directly).
 It batches filesystem changes and records them as activity events.
 """
 
-from __future__ import annotations
 
 import os
 import time

htmlgraph/work_type_utils.py

@@ -1,10 +1,11 @@
+from __future__ import annotations
+
 """
 Utility functions for work type inference and classification.
 
 Provides automatic work type detection based on active work items.
 """
 
-from __future__ import annotations
 
 from typing import TYPE_CHECKING