htmlgraph 0.24.2__py3-none-any.whl → 0.25.0__py3-none-any.whl

htmlgraph/sdk.py

@@ -54,16 +54,20 @@ from htmlgraph.collections import (
     FeatureCollection,
     PhaseCollection,
     SpikeCollection,
+    TaskDelegationCollection,
     TodoCollection,
 )
 from htmlgraph.collections.insight import InsightCollection
 from htmlgraph.collections.metric import MetricCollection
 from htmlgraph.collections.pattern import PatternCollection
+from htmlgraph.collections.session import SessionCollection
 from htmlgraph.context_analytics import ContextAnalytics
+from htmlgraph.db.schema import HtmlGraphDB
 from htmlgraph.graph import HtmlGraph
 from htmlgraph.models import Node, Step
 from htmlgraph.session_manager import SessionManager
 from htmlgraph.session_warning import check_and_show_warning
+from htmlgraph.system_prompts import SystemPromptManager
 from htmlgraph.track_builder import TrackCollection
 from htmlgraph.types import (
     ActiveWorkItem,
@@ -93,6 +97,16 @@ class SDK:
         - insights: Session health insights
         - metrics: Aggregated time-series metrics
 
+    System Prompt Management:
+        sdk.system_prompts - Manage system prompts
+            .get_active() - Get active prompt (project override OR plugin default)
+            .get_default() - Get plugin default system prompt
+            .get_project() - Get project-level override if exists
+            .create(template) - Create project-level override
+            .validate() - Validate prompt token count
+            .delete() - Delete project override (fall back to default)
+            .get_stats() - Get prompt statistics
+
     Analytics & Decision Support:
         sdk.dep_analytics - Dependency analysis
             .find_bottlenecks(top_n=5) - Find blocking tasks
@@ -207,25 +221,56 @@ class SDK:
         directory: Path | str | None = None,
         agent: str | None = None,
         parent_session: str | None = None,
+        db_path: str | None = None,
     ):
         """
         Initialize SDK.
 
         Args:
             directory: Path to .htmlgraph directory (auto-discovered if not provided)
-            agent: Agent identifier for operations
+            agent: REQUIRED - Agent identifier for operations.
+                Used to attribute work items (features, spikes, bugs, etc) to the agent.
+                Examples: agent='explorer', agent='coder', agent='tester'
+                Critical for: Work attribution, result retrieval, orchestrator tracking
+                Falls back to: CLAUDE_AGENT_NAME env var, then detect_agent_name()
+                Raises ValueError if not provided and cannot be detected
             parent_session: Parent session ID to log activities to (for nested contexts)
+            db_path: Path to SQLite database file (optional, defaults to ~/.htmlgraph/htmlgraph.db)
         """
         if directory is None:
             directory = self._discover_htmlgraph()
 
         if agent is None:
-            agent = detect_agent_name()
+            # Try environment variable fallback
+            agent = os.getenv("CLAUDE_AGENT_NAME")
+
+        if agent is None:
+            # Try automatic detection
+            detected = detect_agent_name()
+            if detected and detected != "cli":
+                # Only accept detected if it's not the default fallback
+                agent = detected
+            else:
+                # No valid agent found - fail fast with helpful error message
+                raise ValueError(
+                    "Agent identifier is required for work attribution. "
+                    "Pass agent='name' to SDK() initialization. "
+                    "Examples: SDK(agent='explorer'), SDK(agent='coder'), SDK(agent='tester')\n"
+                    "Alternatively, set CLAUDE_AGENT_NAME environment variable.\n"
+                    "Critical for: Work attribution, result retrieval, orchestrator tracking"
+                )
 
         self._directory = Path(directory)
         self._agent_id = agent
         self._parent_session = parent_session or os.getenv("HTMLGRAPH_PARENT_SESSION")
 
+        # Initialize SQLite database (Phase 2)
+        self._db = HtmlGraphDB(
+            db_path or str(Path.home() / ".htmlgraph" / "htmlgraph.db")
+        )
+        self._db.connect()
+        self._db.create_tables()
+
         # Initialize underlying HtmlGraphs first (for backward compatibility and sharing)
         # These are shared with SessionManager to avoid double-loading features
         self._graph = HtmlGraph(self._directory / "features")
@@ -252,7 +297,7 @@ class SDK:
         self.phases = PhaseCollection(self)
 
         # Non-work collections
-        self.sessions: BaseCollection = BaseCollection(self, "sessions", "session")
+        self.sessions: SessionCollection = SessionCollection(self)
         self.tracks: TrackCollection = TrackCollection(
             self
         )  # Use specialized collection with builder support
@@ -266,11 +311,15 @@ class SDK:
         # Todo collection (persistent task tracking)
         self.todos = TodoCollection(self)
 
+        # Task delegation collection (observability for spawned agents)
+        self.task_delegations = TaskDelegationCollection(self)
+
         # Create learning directories if needed
         (self._directory / "patterns").mkdir(exist_ok=True)
         (self._directory / "insights").mkdir(exist_ok=True)
         (self._directory / "metrics").mkdir(exist_ok=True)
         (self._directory / "todos").mkdir(exist_ok=True)
+        (self._directory / "task-delegations").mkdir(exist_ok=True)
 
         # Analytics interface (Phase 2: Work Type Analytics)
         self.analytics = Analytics(self)
@@ -285,7 +334,10 @@ class SDK:
         self.context = ContextAnalytics(self)
 
         # Lazy-loaded orchestrator for subagent management
-        self._orchestrator = None
+        self._orchestrator: Any = None
+
+        # System prompt manager (lazy-loaded)
+        self._system_prompts: SystemPromptManager | None = None
 
         # Session warning system (workaround for Claude Code hook bug #10373)
         # Shows orchestrator instructions on first SDK usage per session
@@ -321,6 +373,43 @@ class SDK:
         """Get current agent ID."""
         return self._agent_id
 
+    @property
+    def system_prompts(self) -> SystemPromptManager:
+        """
+        Access system prompt management.
+
+        Provides methods to:
+        - Get active prompt (project override OR plugin default)
+        - Create/delete project-level overrides
+        - Validate token counts
+        - Get prompt statistics
+
+        Lazy-loaded on first access.
+
+        Returns:
+            SystemPromptManager instance
+
+        Example:
+            >>> sdk = SDK(agent="claude")
+
+            # Get active prompt
+            >>> prompt = sdk.system_prompts.get_active()
+
+            # Create project override
+            >>> sdk.system_prompts.create("## Custom prompt\\n...")
+
+            # Validate token count
+            >>> result = sdk.system_prompts.validate()
+            >>> print(result['message'])
+
+            # Get statistics
+            >>> stats = sdk.system_prompts.get_stats()
+            >>> print(f"Source: {stats['source']}")
+        """
+        if self._system_prompts is None:
+            self._system_prompts = SystemPromptManager(self._directory)
+        return self._system_prompts
+
     def dismiss_session_warning(self) -> bool:
         """
         Dismiss the session warning after reading it.
@@ -359,6 +448,251 @@ class SDK:
             return self._session_warning.get_status()
         return {"dismissed": True, "show_count": 0}
 
+    # =========================================================================
+    # SQLite Database Integration (Phase 2)
+    # =========================================================================
+
+    def db(self) -> HtmlGraphDB:
+        """
+        Get the SQLite database instance.
+
+        Returns:
+            HtmlGraphDB instance for executing queries
+
+        Example:
+            >>> sdk = SDK(agent="claude")
+            >>> db = sdk.db()
+            >>> events = db.get_session_events("sess-123")
+            >>> features = db.get_features_by_status("todo")
+        """
+        return self._db
+
+    def query(self, sql: str, params: tuple = ()) -> list[dict[str, Any]]:
+        """
+        Execute a raw SQL query on the SQLite database.
+
+        Args:
+            sql: SQL query string
+            params: Query parameters (for safe parameterized queries)
+
+        Returns:
+            List of result dictionaries
+
+        Example:
+            >>> sdk = SDK(agent="claude")
+            >>> results = sdk.query(
+            ...     "SELECT * FROM features WHERE status = ? AND priority = ?",
+            ...     ("todo", "high")
+            ... )
+            >>> for row in results:
+            ...     print(row["title"])
+        """
+        if not self._db.connection:
+            self._db.connect()
+
+        cursor = self._db.connection.cursor()  # type: ignore[union-attr]
+        cursor.execute(sql, params)
+        rows = cursor.fetchall()
+        return [dict(row) for row in rows]
+
+    def execute_query_builder(
+        self, sql: str, params: tuple = ()
+    ) -> list[dict[str, Any]]:
+        """
+        Execute a query using the Queries builder.
+
+        Args:
+            sql: SQL query from Queries builder
+            params: Parameters from Queries builder
+
+        Returns:
+            List of result dictionaries
+
+        Example:
+            >>> sdk = SDK(agent="claude")
+            >>> sql, params = Queries.get_features_by_status("todo", limit=5)
+            >>> results = sdk.execute_query_builder(sql, params)
+        """
+        return self.query(sql, params)
+
+    def export_to_html(
+        self,
+        output_dir: str | None = None,
+        include_features: bool = True,
+        include_sessions: bool = True,
+        include_events: bool = False,
+    ) -> dict[str, int]:
+        """
+        Export SQLite data to HTML files for backward compatibility.
+
+        Args:
+            output_dir: Directory to export to (defaults to .htmlgraph)
+            include_features: Export features
+            include_sessions: Export sessions
+            include_events: Export events (detailed, use with care)
+
+        Returns:
+            Dict with export counts: {"features": int, "sessions": int, "events": int}
+
+        Example:
+            >>> sdk = SDK(agent="claude")
+            >>> result = sdk.export_to_html()
+            >>> print(f"Exported {result['features']} features")
+        """
+        if output_dir is None:
+            output_dir = str(self._directory)
+
+        output_path = Path(output_dir)
+        counts = {"features": 0, "sessions": 0, "events": 0}
+
+        if include_features:
+            # Export all features from SQLite to HTML
+            features_dir = output_path / "features"
+            features_dir.mkdir(parents=True, exist_ok=True)
+
+            try:
+                cursor = self._db.connection.cursor()  # type: ignore[union-attr]
+                cursor.execute("SELECT * FROM features")
+                rows = cursor.fetchall()
+
+                for row in rows:
+                    feature_dict = dict(row)
+                    feature_id = feature_dict["id"]
+                    # Write HTML file (simplified export)
+                    html_file = features_dir / f"{feature_id}.html"
+                    html_file.write_text(
+                        f"<h1>{feature_dict['title']}</h1>"
+                        f"<p>Status: {feature_dict['status']}</p>"
+                        f"<p>Type: {feature_dict['type']}</p>"
+                    )
+                    counts["features"] += 1
+            except Exception as e:
+                import logging
+
+                logging.error(f"Error exporting features: {e}")
+
+        if include_sessions:
+            # Export all sessions from SQLite to HTML
+            sessions_dir = output_path / "sessions"
+            sessions_dir.mkdir(parents=True, exist_ok=True)
+
+            try:
+                cursor = self._db.connection.cursor()  # type: ignore[union-attr]
+                cursor.execute("SELECT * FROM sessions")
+                rows = cursor.fetchall()
+
+                for row in rows:
+                    session_dict = dict(row)
+                    session_id = session_dict["session_id"]
+                    # Write HTML file (simplified export)
+                    html_file = sessions_dir / f"{session_id}.html"
+                    html_file.write_text(
+                        f"<h1>Session {session_id}</h1>"
+                        f"<p>Agent: {session_dict['agent_assigned']}</p>"
+                        f"<p>Status: {session_dict['status']}</p>"
+                    )
+                    counts["sessions"] += 1
+            except Exception as e:
+                import logging
+
+                logging.error(f"Error exporting sessions: {e}")
+
+        return counts
+
+    def _log_event(
+        self,
+        event_type: str,
+        tool_name: str | None = None,
+        input_summary: str | None = None,
+        output_summary: str | None = None,
+        context: dict[str, Any] | None = None,
+        cost_tokens: int = 0,
+    ) -> bool:
+        """
+        Log an event to the SQLite database with parent-child linking.
+
+        Internal method used by collections to track operations.
+        Automatically creates a session if one doesn't exist.
+        Reads parent event ID from HTMLGRAPH_PARENT_ACTIVITY env var for hierarchical tracking.
+
+        Args:
+            event_type: Type of event (tool_call, completion, error, etc.)
+            tool_name: Tool that was called
+            input_summary: Summary of input
+            output_summary: Summary of output
+            context: Additional context metadata
+            cost_tokens: Token cost estimate
+
+        Returns:
+            True if logged successfully, False otherwise
+
+        Example (internal use):
+            >>> sdk._log_event(
+            ...     event_type="tool_call",
+            ...     tool_name="Edit",
+            ...     input_summary="Edit file.py",
+            ...     cost_tokens=100
+            ... )
+        """
+        from uuid import uuid4
+
+        event_id = f"evt-{uuid4().hex[:12]}"
+        session_id = self._parent_session or "cli-session"
+
+        # Read parent event ID from environment variable for hierarchical linking
+        parent_event_id = os.getenv("HTMLGRAPH_PARENT_ACTIVITY")
+
+        # Ensure session exists before logging event
+        try:
+            self._ensure_session_exists(session_id, parent_event_id=parent_event_id)
+        except Exception as e:
+            import logging
+
+            logging.debug(f"Failed to ensure session exists: {e}")
+            # Continue anyway - session creation failure shouldn't block event logging
+
+        return self._db.insert_event(
+            event_id=event_id,
+            agent_id=self._agent_id,
+            event_type=event_type,
+            session_id=session_id,
+            tool_name=tool_name,
+            input_summary=input_summary,
+            output_summary=output_summary,
+            context=context,
+            parent_event_id=parent_event_id,
+            cost_tokens=cost_tokens,
+        )
+
+    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:
+            self._db.connect()
+
+        cursor = self._db.connection.cursor()  # type: ignore[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(
+                session_id=session_id,
+                agent_assigned=self._agent_id,
+                is_subagent=self._parent_session is not None,
+                parent_session_id=self._parent_session,
+                parent_event_id=parent_event_id,
+            )
+
     def reload(self) -> None:
         """Reload all data from disk."""
         self._graph.reload()
@@ -460,7 +794,10 @@ class SDK:
             New Session instance
         """
         return self.session_manager.start_session(
-            session_id=session_id, agent=agent or self._agent_id or "cli", title=title
+            session_id=session_id,
+            agent=agent or self._agent_id or "cli",
+            title=title,
+            parent_session_id=self._parent_session,
         )
 
     def end_session(
@@ -566,19 +903,20 @@ class SDK:
             ... )
             >>> print(f"Tracked: [{entry.tool}] {entry.summary}")
         """
-        # Determine target session: explicit > parent > active
+        # Determine target session: explicit parameter > parent_session > active > none
         if not session_id:
-            # Use parent session if available (for nested contexts)
+            # Priority 1: Parent session (explicitly provided or from env var)
             if self._parent_session:
                 session_id = self._parent_session
             else:
-                # Fall back to active session
+                # Priority 2: Active session for this agent
                 active = self.session_manager.get_active_session(agent=self._agent_id)
-                if not active:
+                if active:
+                    session_id = active.id
+                else:
                     raise ValueError(
                         "No active session. Start one with sdk.start_session()"
                     )
-                session_id = active.id
 
         # Get parent activity ID from environment if not provided
         if not parent_activity_id:

htmlgraph/server.py

@@ -49,6 +49,7 @@ class HtmlGraphAPIHandler(SimpleHTTPRequestHandler):
         "sessions",
         "agents",
         "tracks",
+        "task-delegations",
     ]
 
     def __init__(self, *args: Any, **kwargs: Any) -> None:
@@ -235,6 +236,9 @@ 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}"
+        )
 
         # Not an API request - serve static files
         if api != "api":
@@ -260,6 +264,15 @@ class HtmlGraphAPIHandler(SimpleHTTPRequestHandler):
         if collection == "analytics":
             return self._handle_analytics(node_id, params)
 
+        # GET /api/orchestration - Get delegation chains and agent coordination
+        if collection == "orchestration":
+            print(f"DEBUG: Handling orchestration request, params={params}")
+            return self._handle_orchestration_view(params)
+
+        # GET /api/task-delegations/stats - Get aggregated delegation statistics
+        if collection == "task-delegations" and params.get("stats") == "true":
+            return self._handle_task_delegations_stats()
+
         # GET /api/tracks/{track_id}/features - Get features for a track
         if collection == "tracks" and node_id and params.get("features") == "true":
             return self._handle_track_features(node_id)
@@ -1043,6 +1056,187 @@ class HtmlGraphAPIHandler(SimpleHTTPRequestHandler):
         except Exception as e:
             self._send_error_json(f"Failed to generate features: {str(e)}", 500)
 
+    def _handle_orchestration_view(self, params: dict) -> None:
+        """
+        Get delegation chains and agent coordination information.
+
+        Queries the SQLite database for delegation events and builds
+        a view of agent coordination and handoff patterns.
+
+        Returns:
+            {
+                "delegation_count": int,
+                "unique_agents": int,
+                "agents": [str],
+                "delegation_chains": {
+                    "from_agent": [
+                        {
+                            "to_agent": str,
+                            "event_type": str,
+                            "timestamp": str,
+                            "task": str,
+                            "status": str
+                        }
+                    ]
+                }
+            }
+        """
+        try:
+            from htmlgraph.db.schema import HtmlGraphDB
+
+            # Use unified index.sqlite database
+            db_path = str(self.graph_dir / "index.sqlite")
+            db = HtmlGraphDB(db_path=db_path)
+            db.connect()
+
+            # Get all delegation events
+            delegations = db.get_delegations(limit=1000)
+            db.close()
+
+            # Build delegation chains grouped by from_agent
+            delegation_chains: dict[str, list[dict]] = {}
+            agents = set()
+            delegation_count = 0
+
+            for delegation in delegations:
+                from_agent = delegation.get("from_agent", "unknown")
+                to_agent = delegation.get("to_agent", "unknown")
+                timestamp = delegation.get("timestamp", "")
+                reason = delegation.get("reason", "")
+                status = delegation.get("status", "pending")
+
+                agents.add(from_agent)
+                agents.add(to_agent)
+                delegation_count += 1
+
+                if from_agent not in delegation_chains:
+                    delegation_chains[from_agent] = []
+
+                delegation_chains[from_agent].append(
+                    {
+                        "to_agent": to_agent,
+                        "event_type": "delegation",
+                        "timestamp": timestamp,
+                        "task": reason or "Unnamed task",
+                        "status": status,
+                    }
+                )
+
+            self._send_json(
+                {
+                    "delegation_count": delegation_count,
+                    "unique_agents": len(agents),
+                    "agents": sorted(list(agents)),
+                    "delegation_chains": delegation_chains,
+                }
+            )
+
+        except Exception as e:
+            self._send_error_json(f"Failed to get orchestration view: {str(e)}", 500)
+
+    def _handle_task_delegations_stats(self) -> None:
+        """Get aggregated statistics about task delegations."""
+        try:
+            delegations_graph = self._get_graph("task-delegations")
+
+            # Get all delegations
+            all_delegations = list(delegations_graph)
+
+            if not all_delegations:
+                self._send_json(
+                    {
+                        "total_delegations": 0,
+                        "by_agent_type": {},
+                        "by_status": {},
+                        "total_tokens": 0,
+                        "total_cost": 0.0,
+                        "average_duration": 0.0,
+                        "agent_stats": [],
+                    }
+                )
+                return
+
+            # Aggregate by agent type
+            agent_stats: dict = {}
+            by_status: dict[str, int] = {}
+            total_tokens = 0
+            total_cost = 0.0
+            durations = []
+
+            for delegation in all_delegations:
+                agent_type = str(getattr(delegation, "agent_type", "unknown"))
+                status = str(getattr(delegation, "status", "unknown"))
+                tokens_val = getattr(delegation, "tokens_used", 0)
+                tokens = int(tokens_val) if tokens_val else 0
+                cost_val = getattr(delegation, "cost_usd", 0)
+                cost = float(cost_val) if cost_val else 0.0
+                duration_val = getattr(delegation, "duration_seconds", 0)
+                duration = int(duration_val) if duration_val else 0
+
+                # Track by agent
+                if agent_type not in agent_stats:
+                    agent_stats[agent_type] = {
+                        "agent_type": agent_type,
+                        "tasks_completed": 0,
+                        "total_duration": 0,
+                        "total_tokens": 0,
+                        "total_cost": 0.0,
+                        "success_count": 0,
+                        "failure_count": 0,
+                    }
+
+                agent_stats[agent_type]["tasks_completed"] += 1
+                agent_stats[agent_type]["total_duration"] += duration
+                agent_stats[agent_type]["total_tokens"] += tokens
+                agent_stats[agent_type]["total_cost"] += cost
+
+                if status == "success":
+                    agent_stats[agent_type]["success_count"] += 1
+                else:
+                    agent_stats[agent_type]["failure_count"] += 1
+
+                # Track by status
+                by_status[status] = by_status.get(status, 0) + 1
+
+                # Aggregate totals
+                total_tokens += tokens
+                total_cost += cost
+                if duration:
+                    durations.append(duration)
+
+            # Calculate success rate for each agent
+            for agent_stats_item in agent_stats.values():
+                total = agent_stats_item["tasks_completed"]
+                if total > 0:
+                    agent_stats_item["success_rate"] = (
+                        agent_stats_item["success_count"] / total
+                    )
+                else:
+                    agent_stats_item["success_rate"] = 0.0
+
+            average_duration = sum(durations) / len(durations) if durations else 0.0
+
+            self._send_json(
+                {
+                    "total_delegations": len(all_delegations),
+                    "by_agent_type": {
+                        agent: stats["tasks_completed"]
+                        for agent, stats in agent_stats.items()
+                    },
+                    "by_status": by_status,
+                    "total_tokens": total_tokens,
+                    "total_cost": round(total_cost, 4),
+                    "average_duration": round(average_duration, 2),
+                    "agent_stats": sorted(
+                        agent_stats.values(),
+                        key=lambda x: x["total_cost"],
+                        reverse=True,
+                    ),
+                }
+            )
+        except Exception as e:
+            self._send_error_json(f"Failed to get delegation stats: {str(e)}", 500)
+
     def _handle_sync_track(self, track_id: str) -> None:
         """Sync task and spec completion based on features."""
         from htmlgraph.track_manager import TrackManager