htmlgraph 0.26.1__py3-none-any.whl → 0.26.3__py3-none-any.whl

htmlgraph/.htmlgraph/.session-warning-state.json

@@ -0,0 +1,6 @@
+{
+  "dismissed_at": null,
+  "dismissed_by": null,
+  "session_id": null,
+  "show_count": 30
+}

htmlgraph/.htmlgraph/agents.json

@@ -0,0 +1,72 @@
+{
+  "version": "1.0",
+  "updated": "2026-01-11T04:13:54.354401",
+  "agents": {
+    "claude": {
+      "id": "claude",
+      "name": "Claude",
+      "capabilities": [
+        "python",
+        "javascript",
+        "typescript",
+        "html",
+        "css",
+        "code-review",
+        "testing",
+        "documentation",
+        "debugging",
+        "refactoring",
+        "architecture",
+        "api-design"
+      ],
+      "max_parallel_tasks": 3,
+      "preferred_complexity": [
+        "low",
+        "medium",
+        "high",
+        "very-high"
+      ],
+      "active": true,
+      "metadata": {}
+    },
+    "gemini": {
+      "id": "gemini",
+      "name": "Gemini",
+      "capabilities": [
+        "python",
+        "data-analysis",
+        "documentation",
+        "testing",
+        "code-review",
+        "javascript"
+      ],
+      "max_parallel_tasks": 2,
+      "preferred_complexity": [
+        "low",
+        "medium",
+        "high"
+      ],
+      "active": true,
+      "metadata": {}
+    },
+    "codex": {
+      "id": "codex",
+      "name": "Codex",
+      "capabilities": [
+        "python",
+        "javascript",
+        "debugging",
+        "testing",
+        "code-generation",
+        "documentation"
+      ],
+      "max_parallel_tasks": 2,
+      "preferred_complexity": [
+        "low",
+        "medium"
+      ],
+      "active": true,
+      "metadata": {}
+    }
+  }
+}

htmlgraph/__init__.py

@@ -95,7 +95,7 @@ from htmlgraph.types import (
 )
 from htmlgraph.work_type_utils import infer_work_type, infer_work_type_from_id
 
-__version__ = "0.26.1"
+__version__ = "0.26.3"
 __all__ = [
     # Exceptions
     "HtmlGraphError",

htmlgraph/api/main.py

@@ -394,7 +394,7 @@ def get_app(db_path: str) -> FastAPI:
                 query = """
                     SELECT e.event_id, e.agent_id, e.event_type, e.timestamp, e.tool_name,
                            e.input_summary, e.output_summary, e.session_id,
-                           e.status, e.model
+                           e.parent_event_id, e.status, e.model
                     FROM agent_events e
                     WHERE 1=1
                 """
@@ -428,9 +428,9 @@ def get_app(db_path: str) -> FastAPI:
                         input_summary=row[5],
                         output_summary=row[6],
                         session_id=row[7],
-                        parent_event_id=None,  # Not available in all schema versions
-                        status=row[8],
-                        model=row[9],
+                        parent_event_id=row[8],
+                        status=row[9],
+                        model=row[10],
                     )
                     for row in rows
                 ]
@@ -768,7 +768,8 @@ def get_app(db_path: str) -> FastAPI:
                     output_summary,
                     session_id,
                     status,
-                    model
+                    model,
+                    parent_event_id
                 FROM agent_events
                 WHERE event_type IN ({event_type_placeholders})
             """
@@ -799,6 +800,7 @@ def get_app(db_path: str) -> FastAPI:
                         "session_id": row[8],
                         "status": row[9],
                         "model": row[10],
+                        "parent_event_id": row[11],
                     }
                 )
 
@@ -1017,8 +1019,10 @@ def get_app(db_path: str) -> FastAPI:
                         input_summary,
                         execution_duration_seconds,
                         status,
-                        COALESCE(subagent_type, agent_id) as agent_id,
-                        model
+                        agent_id,
+                        model,
+                        context,
+                        subagent_type
                     FROM agent_events
                     WHERE parent_event_id = ?
                     ORDER BY timestamp ASC
@@ -1048,7 +1052,34 @@ def get_app(db_path: str) -> FastAPI:
                         duration = row[4] or 0.0
                         status = row[5]
                         agent = row[6] or "unknown"
-                        model = row[7]  # Add model field
+                        model = row[7]
+                        context_json = row[8]
+                        subagent_type = row[9]
+
+                        # Parse context to extract spawner metadata
+                        context = {}
+                        spawner_type = None
+                        spawned_agent = None
+                        if context_json:
+                            try:
+                                context = json.loads(context_json)
+                                spawner_type = context.get("spawner_type")
+                                spawned_agent = context.get("spawned_agent")
+                            except (json.JSONDecodeError, TypeError):
+                                pass
+
+                        # If no spawner_type but subagent_type is set, treat it as a spawner delegation
+                        # This handles both HeadlessSpawner (spawner_type in context) and
+                        # Claude Code plugin agents (subagent_type field)
+                        if not spawner_type and subagent_type:
+                            # Extract spawner name from subagent_type (e.g., ".claude-plugin:gemini" -> "gemini")
+                            if ":" in subagent_type:
+                                spawner_type = subagent_type.split(":")[-1]
+                            else:
+                                spawner_type = subagent_type
+                            spawned_agent = (
+                                agent  # Use the agent_id as the spawned agent
+                            )
 
                         # Build summary (input_text already contains formatted summary)
                         summary = input_text[:80] + (
@@ -1071,9 +1102,17 @@ def get_app(db_path: str) -> FastAPI:
                             "duration_seconds": round(duration, 2),
                             "agent": agent,
                             "depth": depth,
-                            "model": model,  # Include model in child dict
+                            "model": model,
                         }
 
+                        # Include spawner metadata if present
+                        if spawner_type:
+                            child_dict["spawner_type"] = spawner_type
+                        if spawned_agent:
+                            child_dict["spawned_agent"] = spawned_agent
+                        if subagent_type:
+                            child_dict["subagent_type"] = subagent_type
+
                         # Only add children key if there are nested children
                         if nested_children:
                             child_dict["children"] = nested_children
@@ -1107,6 +1146,22 @@ def get_app(db_path: str) -> FastAPI:
                     0 if uq_status == "recorded" or uq_status == "success" else 1
                 ) + children_error
 
+                # Check if any child has spawner metadata
+                def has_spawner_in_children(
+                    children_list: list[dict[str, Any]],
+                ) -> bool:
+                    """Recursively check if any child has spawner metadata."""
+                    for child in children_list:
+                        if child.get("spawner_type") or child.get("spawned_agent"):
+                            return True
+                        if child.get("children") and has_spawner_in_children(
+                            child["children"]
+                        ):
+                            return True
+                    return False
+
+                has_spawner = has_spawner_in_children(children)
+
                 # Step 4: Build conversation turn object
                 conversation_turn = {
                     "userQuery": {
@@ -1114,8 +1169,10 @@ def get_app(db_path: str) -> FastAPI:
                         "timestamp": uq_timestamp,
                         "prompt": prompt_text[:200],  # Truncate for display
                         "duration_seconds": round(uq_duration, 2),
+                        "agent_id": uq_row[5],  # Include agent_id from UserQuery
                     },
                     "children": children,
+                    "has_spawner": has_spawner,
                     "stats": {
                         "tool_count": len(children),
                         "total_duration": round(total_duration, 2),

htmlgraph/api/templates/partials/activity-feed.html

@@ -804,6 +804,65 @@ function collapseAllConversationTurns() {
     });
 }
 
+/**
+ * Filter conversation turns by agent type
+ * @param {string} filterValue - Filter type: 'all', 'direct', 'spawner', or specific spawner type ('gemini', 'codex', 'copilot')
+ */
+function filterByAgentType(filterValue) {
+    const conversationTurns = document.querySelectorAll('.conversation-turn');
+
+    conversationTurns.forEach(turn => {
+        const spawnType = turn.getAttribute('data-spawner-type');
+        let shouldShow = false;
+
+        switch (filterValue) {
+            case 'all':
+                // Show all conversation turns
+                shouldShow = true;
+                break;
+
+            case 'direct':
+                // Show only direct (non-spawner) turns
+                shouldShow = spawnType === 'direct';
+                break;
+
+            case 'spawner':
+                // Show only spawner delegation turns
+                shouldShow = spawnType === 'spawner';
+                break;
+
+            case 'gemini':
+            case 'codex':
+            case 'copilot':
+                // Show only turns that contain child events with matching spawner type
+                shouldShow = hasChildWithSpawnerType(turn, filterValue);
+                break;
+
+            default:
+                shouldShow = true;
+        }
+
+        // Apply visibility
+        if (shouldShow) {
+            turn.style.display = '';
+        } else {
+            turn.style.display = 'none';
+        }
+    });
+}
+
+/**
+ * Check if a conversation turn has any child events with the specified spawner type
+ * @param {HTMLElement} turn - The conversation turn element
+ * @param {string} spawnerType - The spawner type to search for ('gemini', 'codex', 'copilot')
+ * @returns {boolean} True if the turn contains at least one child with the spawner type
+ */
+function hasChildWithSpawnerType(turn, spawnerType) {
+    // Look for spawner badges that match the spawner type
+    const spawnerBadges = turn.querySelectorAll(`.spawner-badge.spawner-${spawnerType}`);
+    return spawnerBadges.length > 0;
+}
+
 // ============================================
 // Live Spawner Event Handling via WebSocket
 // ============================================

htmlgraph/cli.py

@@ -150,7 +150,7 @@ def cmd_serve(args: argparse.Namespace) -> None:
         # Default to database in graph dir if not specified
         db_path = getattr(args, "db", None)
         if not db_path:
-            db_path = str(Path(args.graph_dir) / "index.sqlite")
+            db_path = str(Path(args.graph_dir) / "htmlgraph.db")
 
         result = start_fastapi_server(
             port=args.port,

htmlgraph/config.py

@@ -3,111 +3,188 @@ HtmlGraph Configuration Management.
 
 This module provides centralized configuration management using Pydantic Settings,
 allowing configuration from environment variables, .env files, and CLI arguments.
+
+IMPORTANT: Database path functions (get_database_path, get_analytics_cache_path)
+are lightweight and have NO dependencies. They can be imported anywhere.
 """
 
+import os
 from pathlib import Path
 from typing import Any
 
-from pydantic_settings import BaseSettings
+# =============================================================================
+# LIGHTWEIGHT DATABASE PATH FUNCTIONS (NO DEPENDENCIES)
+# These MUST come before any heavy imports so spawners can use them
+# =============================================================================
 
+# Database filenames (SINGLE SOURCE OF TRUTH)
+DATABASE_FILENAME = "htmlgraph.db"  # Unified event database
+ANALYTICS_CACHE_FILENAME = "index.sqlite"  # Analytics cache (rebuildable)
 
-class HtmlGraphConfig(BaseSettings):
-    """Global HtmlGraph configuration using Pydantic Settings.
 
-    Configuration can be provided via:
-    1. Environment variables (prefix: HTMLGRAPH_)
-    2. .env file
-    3. Direct instantiation with parameters
-    4. CLI argument overrides
+def get_database_path(project_root: Path | str | None = None) -> Path:
     """
+    Get the unified database path for event tracking.
+
+    This is the SINGLE source of truth for database location.
+    All hooks, agents, and spawners MUST use this function.
+
+    Args:
+        project_root: Optional project root path. If None, uses HTMLGRAPH_PROJECT_ROOT
+                     env var or current working directory.
+
+    Returns:
+        Path to htmlgraph.db (the unified event database)
+    """
+    if project_root is None:
+        project_root = Path(os.environ.get("HTMLGRAPH_PROJECT_ROOT", os.getcwd()))
+    else:
+        project_root = Path(project_root)
+
+    return project_root / ".htmlgraph" / DATABASE_FILENAME
 
-    # Core paths
-    graph_dir: Path = Path.home() / ".htmlgraph"
-
-    # Feature tracking
-    features_dir: Path | None = None
-    sessions_dir: Path | None = None
-    spikes_dir: Path | None = None
-    tracks_dir: Path | None = None
-    archives_dir: Path | None = None
-
-    # CLI behavior
-    debug: bool = False
-    verbose: bool = False
-    auto_sync: bool = True
-    color_output: bool = True
-
-    # Session management
-    max_sessions: int = 100
-    session_retention_days: int = 30
-    auto_archive_sessions: bool = True
-
-    # Performance
-    max_query_results: int = 1000
-    cache_enabled: bool = True
-    cache_ttl_seconds: int = 3600
-
-    # Logging
-    log_level: str = "INFO"
-    log_file: Path | None = None
-
-    model_config = {
-        "env_prefix": "HTMLGRAPH_",
-        "env_file": ".env",
-        "case_sensitive": False,
-    }
-
-    def __init__(self, **data: Any) -> None:
-        """Initialize config and compute derived paths."""
-        super().__init__(**data)
-        # Compute derived paths if not explicitly set
-        if self.features_dir is None:
-            self.features_dir = self.graph_dir / "features"
-        if self.sessions_dir is None:
-            self.sessions_dir = self.graph_dir / "sessions"
-        if self.spikes_dir is None:
-            self.spikes_dir = self.graph_dir / "spikes"
-        if self.tracks_dir is None:
-            self.tracks_dir = self.graph_dir / "tracks"
-        if self.archives_dir is None:
-            self.archives_dir = self.graph_dir / "archives"
-
-    def ensure_directories(self) -> None:
-        """Create all configured directories if they don't exist."""
-        for directory in [
-            self.graph_dir,
-            self.features_dir,
-            self.sessions_dir,
-            self.spikes_dir,
-            self.tracks_dir,
-            self.archives_dir,
-        ]:
-            if directory:
-                directory.mkdir(parents=True, exist_ok=True)
-
-    def get_config_dict(self) -> dict[str, Any]:
-        """Get configuration as dictionary."""
-        return {
-            "graph_dir": str(self.graph_dir),
-            "features_dir": str(self.features_dir),
-            "sessions_dir": str(self.sessions_dir),
-            "spikes_dir": str(self.spikes_dir),
-            "tracks_dir": str(self.tracks_dir),
-            "archives_dir": str(self.archives_dir),
-            "debug": self.debug,
-            "verbose": self.verbose,
-            "auto_sync": self.auto_sync,
-            "color_output": self.color_output,
-            "max_sessions": self.max_sessions,
-            "session_retention_days": self.session_retention_days,
-            "auto_archive_sessions": self.auto_archive_sessions,
-            "max_query_results": self.max_query_results,
-            "cache_enabled": self.cache_enabled,
-            "cache_ttl_seconds": self.cache_ttl_seconds,
-            "log_level": self.log_level,
-            "log_file": str(self.log_file) if self.log_file else None,
-        }
 
+def get_analytics_cache_path(project_root: Path | str | None = None) -> Path:
+    """
+    Get the analytics cache database path.
+
+    This is for read-only analytics queries (rebuildable from events).
+    NOT for event tracking - use get_database_path() for that.
+
+    Args:
+        project_root: Optional project root path. If None, uses HTMLGRAPH_PROJECT_ROOT
+                     env var or current working directory.
+
+    Returns:
+        Path to index.sqlite (analytics cache, gitignored)
+    """
+    if project_root is None:
+        project_root = Path(os.environ.get("HTMLGRAPH_PROJECT_ROOT", os.getcwd()))
+    else:
+        project_root = Path(project_root)
+
+    return project_root / ".htmlgraph" / ANALYTICS_CACHE_FILENAME
+
+
+# =============================================================================
+# PYDANTIC CONFIGURATION (Heavy imports below - spawners don't need this)
+# =============================================================================
+
+try:
+    from pydantic_settings import BaseSettings
+
+    _PYDANTIC_AVAILABLE = True
+except ImportError:
+    _PYDANTIC_AVAILABLE = False
+    BaseSettings = object  # type: ignore
+
+
+if _PYDANTIC_AVAILABLE:
+
+    class HtmlGraphConfig(BaseSettings):
+        """Global HtmlGraph configuration using Pydantic Settings.
+
+        Configuration can be provided via:
+        1. Environment variables (prefix: HTMLGRAPH_)
+        2. .env file
+        3. Direct instantiation with parameters
+        4. CLI argument overrides
+        """
+
+        # Core paths
+        graph_dir: Path = Path.home() / ".htmlgraph"
+
+        # Database paths (SINGLE SOURCE OF TRUTH)
+        # All hooks, agents, and spawners MUST use these via get_database_path()
+        database_filename: str = "htmlgraph.db"  # Unified event database
+        analytics_cache_filename: str = "index.sqlite"  # Analytics cache (rebuildable)
+
+        # Feature tracking
+        features_dir: Path | None = None
+        sessions_dir: Path | None = None
+        spikes_dir: Path | None = None
+        tracks_dir: Path | None = None
+        archives_dir: Path | None = None
+
+        # CLI behavior
+        debug: bool = False
+        verbose: bool = False
+        auto_sync: bool = True
+        color_output: bool = True
+
+        # Session management
+        max_sessions: int = 100
+        session_retention_days: int = 30
+        auto_archive_sessions: bool = True
+
+        # Performance
+        max_query_results: int = 1000
+        cache_enabled: bool = True
+        cache_ttl_seconds: int = 3600
+
+        # Logging
+        log_level: str = "INFO"
+        log_file: Path | None = None
+
+        model_config = {
+            "env_prefix": "HTMLGRAPH_",
+            "env_file": ".env",
+            "case_sensitive": False,
+        }
 
-# Global configuration instance
-config: HtmlGraphConfig = HtmlGraphConfig()
+        def __init__(self, **data: Any) -> None:
+            """Initialize config and compute derived paths."""
+            super().__init__(**data)
+            # Compute derived paths if not explicitly set
+            if self.features_dir is None:
+                self.features_dir = self.graph_dir / "features"
+            if self.sessions_dir is None:
+                self.sessions_dir = self.graph_dir / "sessions"
+            if self.spikes_dir is None:
+                self.spikes_dir = self.graph_dir / "spikes"
+            if self.tracks_dir is None:
+                self.tracks_dir = self.graph_dir / "tracks"
+            if self.archives_dir is None:
+                self.archives_dir = self.graph_dir / "archives"
+
+        def ensure_directories(self) -> None:
+            """Create all configured directories if they don't exist."""
+            for directory in [
+                self.graph_dir,
+                self.features_dir,
+                self.sessions_dir,
+                self.spikes_dir,
+                self.tracks_dir,
+                self.archives_dir,
+            ]:
+                if directory:
+                    directory.mkdir(parents=True, exist_ok=True)
+
+        def get_config_dict(self) -> dict[str, Any]:
+            """Get configuration as dictionary."""
+            return {
+                "graph_dir": str(self.graph_dir),
+                "features_dir": str(self.features_dir),
+                "sessions_dir": str(self.sessions_dir),
+                "spikes_dir": str(self.spikes_dir),
+                "tracks_dir": str(self.tracks_dir),
+                "archives_dir": str(self.archives_dir),
+                "debug": self.debug,
+                "verbose": self.verbose,
+                "auto_sync": self.auto_sync,
+                "color_output": self.color_output,
+                "max_sessions": self.max_sessions,
+                "session_retention_days": self.session_retention_days,
+                "auto_archive_sessions": self.auto_archive_sessions,
+                "max_query_results": self.max_query_results,
+                "cache_enabled": self.cache_enabled,
+                "cache_ttl_seconds": self.cache_ttl_seconds,
+                "log_level": self.log_level,
+                "log_file": str(self.log_file) if self.log_file else None,
+            }
+
+    # Global configuration instance
+    config: HtmlGraphConfig = HtmlGraphConfig()
+else:
+    # Pydantic not available - config object won't work but database functions will
+    config = None  # type: ignore