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

htmlgraph/db/schema.py

@@ -24,7 +24,7 @@ Tables:
 import json
 import logging
 import sqlite3
-from datetime import datetime, timezone
+from datetime import datetime, timedelta, timezone
 from pathlib import Path
 from typing import Any
 
@@ -103,6 +103,7 @@ class HtmlGraphDB:
             ("status", "TEXT DEFAULT 'recorded'"),
             ("created_at", "DATETIME DEFAULT CURRENT_TIMESTAMP"),
             ("updated_at", "DATETIME DEFAULT CURRENT_TIMESTAMP"),
+            ("model", "TEXT"),
         ]
 
         for col_name, col_type in migrations:
@@ -158,6 +159,8 @@ class HtmlGraphDB:
             ("features_worked_on", "TEXT"),
             ("metadata", "TEXT"),
             ("completed_at", "DATETIME"),
+            ("last_user_query_at", "DATETIME"),
+            ("last_user_query", "TEXT"),
         ]
 
         # Refresh columns after potential rename
@@ -220,6 +223,7 @@ class HtmlGraphDB:
                 cost_tokens INTEGER DEFAULT 0,
                 execution_duration_seconds REAL DEFAULT 0.0,
                 status TEXT DEFAULT 'recorded',
+                model TEXT,
                 created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
                 updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
                 FOREIGN KEY (session_id) REFERENCES sessions(session_id) ON DELETE CASCADE ON UPDATE CASCADE,
@@ -280,6 +284,8 @@ class HtmlGraphDB:
                 is_subagent BOOLEAN DEFAULT FALSE,
                 features_worked_on JSON,
                 metadata JSON,
+                last_user_query_at DATETIME,
+                last_user_query 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
             )
@@ -358,7 +364,22 @@ class HtmlGraphDB:
             )
         """)
 
-        # 8. TOOL_TRACES TABLE - Detailed tool execution tracing
+        # 8. LIVE_EVENTS TABLE - Real-time event streaming buffer
+        # Events are inserted here for WebSocket broadcasting, then auto-cleaned after broadcast
+        cursor.execute("""
+            CREATE TABLE IF NOT EXISTS live_events (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                event_type TEXT NOT NULL,
+                event_data TEXT NOT NULL,
+                parent_event_id TEXT,
+                session_id TEXT,
+                spawner_type TEXT,
+                created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+                broadcast_at TIMESTAMP
+            )
+        """)
+
+        # 9. TOOL_TRACES TABLE - Detailed tool execution tracing
         cursor.execute("""
             CREATE TABLE IF NOT EXISTS tool_traces (
                 tool_use_id TEXT PRIMARY KEY,
@@ -465,6 +486,9 @@ class HtmlGraphDB:
             "CREATE INDEX IF NOT EXISTS idx_tool_traces_tool_name ON tool_traces(tool_name, status)",
             "CREATE INDEX IF NOT EXISTS idx_tool_traces_status ON tool_traces(status, start_time DESC)",
             "CREATE INDEX IF NOT EXISTS idx_tool_traces_start_time ON tool_traces(start_time DESC)",
+            # 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)",
         ]
 
         for index_sql in indexes:
@@ -488,6 +512,7 @@ class HtmlGraphDB:
         cost_tokens: int = 0,
         execution_duration_seconds: float = 0.0,
         subagent_type: str | None = None,
+        model: str | None = None,
     ) -> bool:
         """
         Insert an agent event into the database.
@@ -511,6 +536,7 @@ class HtmlGraphDB:
             cost_tokens: Token usage estimate (optional)
             execution_duration_seconds: Execution time in seconds (optional)
             subagent_type: Subagent type for Task delegations (optional)
+            model: Claude model name (e.g., claude-haiku, claude-opus, claude-sonnet) (optional)
 
         Returns:
             True if insert successful, False otherwise
@@ -521,16 +547,16 @@ class HtmlGraphDB:
         try:
             cursor = self.connection.cursor()  # type: ignore[union-attr]
             # Temporarily disable foreign key constraints to allow inserting
-            # parent_event_id references that may not exist yet (will be created later)
-            if parent_event_id:
-                cursor.execute("PRAGMA foreign_keys=OFF")
+            # events even if parent_event_id or session_id don't exist yet
+            # (useful for cross-process event tracking where sessions are created asynchronously)
+            cursor.execute("PRAGMA foreign_keys=OFF")
             cursor.execute(
                 """
                 INSERT INTO agent_events
                 (event_id, agent_id, event_type, session_id, tool_name,
                  input_summary, output_summary, context, parent_agent_id,
-                 parent_event_id, cost_tokens, execution_duration_seconds, subagent_type)
-                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                 parent_event_id, cost_tokens, execution_duration_seconds, subagent_type, model)
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
             """,
                 (
                     event_id,
@@ -546,11 +572,11 @@ class HtmlGraphDB:
                     cost_tokens,
                     execution_duration_seconds,
                     subagent_type,
+                    model,
                 ),
             )
             # Re-enable foreign key constraints
-            if parent_event_id:
-                cursor.execute("PRAGMA foreign_keys=ON")
+            cursor.execute("PRAGMA foreign_keys=ON")
             self.connection.commit()  # type: ignore[union-attr]
             return True
         except sqlite3.IntegrityError as e:
@@ -1329,6 +1355,229 @@ class HtmlGraphDB:
             logger.error(f"Error querying tool traces: {e}")
             return []
 
+    def update_session_activity(self, session_id: str, user_query: str) -> None:
+        """
+        Update session with latest user query activity.
+
+        Args:
+            session_id: Session ID to update
+            user_query: The user query text (will be truncated to 200 chars)
+        """
+        if not self.connection:
+            self.connect()
+
+        try:
+            cursor = self.connection.cursor()  # type: ignore[union-attr]
+            cursor.execute(
+                """
+                UPDATE sessions
+                SET last_user_query_at = ?, last_user_query = ?
+                WHERE session_id = ?
+            """,
+                (
+                    datetime.now(timezone.utc).isoformat(),
+                    user_query[:200] if user_query else None,
+                    session_id,
+                ),
+            )
+            self.connection.commit()  # type: ignore[union-attr]
+        except sqlite3.Error as e:
+            logger.error(f"Error updating session activity: {e}")
+
+    def get_concurrent_sessions(
+        self, current_session_id: str, minutes: int = 30
+    ) -> list[dict[str, Any]]:
+        """
+        Get other sessions active in the last N minutes.
+
+        Args:
+            current_session_id: Current session ID to exclude from results
+            minutes: Time window in minutes (default: 30)
+
+        Returns:
+            List of concurrent session dictionaries
+        """
+        if not self.connection:
+            self.connect()
+
+        try:
+            cursor = self.connection.cursor()  # type: ignore[union-attr]
+            cutoff = (
+                datetime.now(timezone.utc) - timedelta(minutes=minutes)
+            ).isoformat()
+            cursor.execute(
+                """
+                SELECT session_id, agent_assigned, created_at, last_user_query_at,
+                       last_user_query, status
+                FROM sessions
+                WHERE session_id != ?
+                  AND status = 'active'
+                  AND (last_user_query_at > ? OR created_at > ?)
+                ORDER BY last_user_query_at DESC
+            """,
+                (current_session_id, cutoff, cutoff),
+            )
+
+            rows = cursor.fetchall()
+            return [dict(row) for row in rows]
+        except sqlite3.Error as e:
+            logger.error(f"Error querying concurrent sessions: {e}")
+            return []
+
+    def insert_live_event(
+        self,
+        event_type: str,
+        event_data: dict[str, Any],
+        parent_event_id: str | None = None,
+        session_id: str | None = None,
+        spawner_type: str | None = None,
+    ) -> int | None:
+        """
+        Insert a live event for real-time WebSocket streaming.
+
+        These events are temporary and should be cleaned up after broadcast.
+
+        Args:
+            event_type: Type of live event (spawner_start, spawner_phase, spawner_complete, etc.)
+            event_data: Event payload as dictionary (will be JSON serialized)
+            parent_event_id: Parent event ID for hierarchical linking (optional)
+            session_id: Session this event belongs to (optional)
+            spawner_type: Spawner type (gemini, codex, copilot) if applicable (optional)
+
+        Returns:
+            Live event ID if successful, None otherwise
+        """
+        if not self.connection:
+            self.connect()
+
+        try:
+            cursor = self.connection.cursor()  # type: ignore[union-attr]
+            cursor.execute(
+                """
+                INSERT INTO live_events
+                (event_type, event_data, parent_event_id, session_id, spawner_type)
+                VALUES (?, ?, ?, ?, ?)
+            """,
+                (
+                    event_type,
+                    json.dumps(event_data),
+                    parent_event_id,
+                    session_id,
+                    spawner_type,
+                ),
+            )
+            self.connection.commit()  # type: ignore[union-attr]
+            return cursor.lastrowid
+        except sqlite3.Error as e:
+            logger.error(f"Error inserting live event: {e}")
+            return None
+
+    def get_pending_live_events(self, limit: int = 100) -> list[dict[str, Any]]:
+        """
+        Get live events that haven't been broadcast yet.
+
+        Args:
+            limit: Maximum number of events to return
+
+        Returns:
+            List of pending live event dictionaries
+        """
+        if not self.connection:
+            self.connect()
+
+        try:
+            cursor = self.connection.cursor()  # type: ignore[union-attr]
+            cursor.execute(
+                """
+                SELECT id, event_type, event_data, parent_event_id, session_id,
+                       spawner_type, created_at
+                FROM live_events
+                WHERE broadcast_at IS NULL
+                ORDER BY created_at ASC
+                LIMIT ?
+            """,
+                (limit,),
+            )
+
+            rows = cursor.fetchall()
+            events = []
+            for row in rows:
+                event = dict(row)
+                # Parse JSON event_data
+                if event.get("event_data"):
+                    try:
+                        event["event_data"] = json.loads(event["event_data"])
+                    except json.JSONDecodeError:
+                        pass
+                events.append(event)
+            return events
+        except sqlite3.Error as e:
+            logger.error(f"Error fetching pending live events: {e}")
+            return []
+
+    def mark_live_events_broadcast(self, event_ids: list[int]) -> bool:
+        """
+        Mark live events as broadcast (sets broadcast_at timestamp).
+
+        Args:
+            event_ids: List of live event IDs to mark as broadcast
+
+        Returns:
+            True if successful, False otherwise
+        """
+        if not self.connection or not event_ids:
+            return False
+
+        try:
+            cursor = self.connection.cursor()  # type: ignore[union-attr]
+            placeholders = ",".join("?" for _ in event_ids)
+            cursor.execute(
+                f"""
+                UPDATE live_events
+                SET broadcast_at = CURRENT_TIMESTAMP
+                WHERE id IN ({placeholders})
+            """,
+                event_ids,
+            )
+            self.connection.commit()  # type: ignore[union-attr]
+            return True
+        except sqlite3.Error as e:
+            logger.error(f"Error marking live events as broadcast: {e}")
+            return False
+
+    def cleanup_old_live_events(self, max_age_minutes: int = 5) -> int:
+        """
+        Delete live events that have been broadcast and are older than max_age_minutes.
+
+        Args:
+            max_age_minutes: Maximum age in minutes for broadcast events
+
+        Returns:
+            Number of deleted events
+        """
+        if not self.connection:
+            self.connect()
+
+        try:
+            cursor = self.connection.cursor()  # type: ignore[union-attr]
+            cutoff = (
+                datetime.now(timezone.utc) - timedelta(minutes=max_age_minutes)
+            ).isoformat()
+            cursor.execute(
+                """
+                DELETE FROM live_events
+                WHERE broadcast_at IS NOT NULL
+                  AND created_at < ?
+            """,
+                (cutoff,),
+            )
+            deleted_count = cursor.rowcount
+            self.connection.commit()  # type: ignore[union-attr]
+            return deleted_count
+        except sqlite3.Error as e:
+            logger.error(f"Error cleaning up old live events: {e}")
+            return 0
+
     def close(self) -> None:
         """Clean up database connection."""
         self.disconnect()

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

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

htmlgraph/hooks/.htmlgraph/agents.json

@@ -0,0 +1,72 @@
+{
+  "version": "1.0",
+  "updated": "2026-01-10T08:55:56.503507",
+  "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/hooks/cigs_pretool_enforcer.py

@@ -87,7 +87,7 @@ class CIGSPreToolEnforcer:
 
         return graph_dir
 
-    def enforce(self, tool: str, params: dict) -> dict[str, Any]:
+    def enforce(self, tool: str, params: dict[str, Any]) -> dict[str, Any]:
         """
         Enforce CIGS delegation rules with escalating guidance.
 
@@ -223,7 +223,7 @@ class CIGSPreToolEnforcer:
             }
         }
 
-    def _is_sdk_operation(self, tool: str, params: dict) -> bool:
+    def _is_sdk_operation(self, tool: str, params: dict[str, Any]) -> bool:
         """Check if operation is an SDK operation (always allowed)."""
         if tool != "Bash":
             return False

htmlgraph/hooks/concurrent_sessions.py

@@ -0,0 +1,208 @@
+"""
+Concurrent Session Detection and Formatting.
+
+Provides utilities to detect other active sessions and format them
+for injection into the orchestrator's context at session start.
+"""
+
+from datetime import datetime, timedelta, timezone
+from typing import Any
+
+from htmlgraph.db.schema import HtmlGraphDB
+
+
+def get_concurrent_sessions(
+    db: HtmlGraphDB,
+    current_session_id: str,
+    minutes: int = 30,
+) -> list[dict[str, Any]]:
+    """
+    Get other sessions that are currently active.
+
+    Args:
+        db: Database connection
+        current_session_id: Current session to exclude
+        minutes: Look back window for activity
+
+    Returns:
+        List of concurrent session dicts with id, agent_id, last_user_query, etc.
+    """
+    if not db.connection:
+        db.connect()
+
+    try:
+        cursor = db.connection.cursor()  # type: ignore[union-attr]
+        # Use datetime format that matches database (without timezone)
+        cutoff = (datetime.now(timezone.utc) - timedelta(minutes=minutes)).strftime(
+            "%Y-%m-%d %H:%M:%S"
+        )
+
+        cursor.execute(
+            """
+            SELECT
+                session_id as id,
+                agent_assigned as agent_id,
+                created_at,
+                status,
+                (SELECT input_summary FROM agent_events
+                 WHERE session_id = sessions.session_id
+                 ORDER BY timestamp DESC LIMIT 1) as last_user_query,
+                (SELECT timestamp FROM agent_events
+                 WHERE session_id = sessions.session_id
+                 ORDER BY timestamp DESC LIMIT 1) as last_user_query_at
+            FROM sessions
+            WHERE status = 'active'
+              AND session_id != ?
+              AND created_at > ?
+            ORDER BY created_at DESC
+            """,
+            (current_session_id, cutoff),
+        )
+
+        rows = cursor.fetchall()
+        return [dict(row) for row in rows]
+    except Exception:  # pragma: no cover
+        # Gracefully handle database errors
+        return []
+
+
+def format_concurrent_sessions_markdown(sessions: list[dict[str, Any]]) -> str:
+    """
+    Format concurrent sessions as markdown for context injection.
+
+    Args:
+        sessions: List of session dicts from get_concurrent_sessions
+
+    Returns:
+        Markdown formatted string for system prompt injection
+    """
+    if not sessions:
+        return ""
+
+    lines = ["## Concurrent Sessions (Active Now)", ""]
+
+    for session in sessions:
+        session_id = session.get("id", "unknown")
+        session_id = session_id[:12] if len(session_id) > 12 else session_id
+        agent = session.get("agent_id", "unknown")
+        query = session.get("last_user_query", "No recent query")
+        last_active = session.get("last_user_query_at")
+
+        # Calculate time ago
+        time_ago = "unknown"
+        if last_active:
+            try:
+                last_dt = datetime.fromisoformat(
+                    last_active.replace("Z", "+00:00")
+                    if isinstance(last_active, str)
+                    else last_active
+                )
+                delta = datetime.now(timezone.utc) - last_dt
+                if delta.total_seconds() < 60:
+                    time_ago = "just now"
+                elif delta.total_seconds() < 3600:
+                    time_ago = f"{int(delta.total_seconds() // 60)} min ago"
+                else:
+                    time_ago = f"{int(delta.total_seconds() // 3600)} hours ago"
+            except (ValueError, TypeError, AttributeError):
+                time_ago = "unknown"
+
+        # Truncate query for display
+        query_display = (
+            query[:50] + "..." if query and len(query) > 50 else (query or "Unknown")
+        )
+
+        lines.append(f'- **{session_id}** ({agent}): "{query_display}" - {time_ago}')
+
+    lines.append("")
+    lines.append("*Coordinate with concurrent sessions to avoid duplicate work.*")
+    lines.append("")
+
+    return "\n".join(lines)
+
+
+def get_recent_completed_sessions(
+    db: HtmlGraphDB,
+    hours: int = 24,
+    limit: int = 5,
+) -> list[dict[str, Any]]:
+    """
+    Get recently completed sessions for handoff context.
+
+    Args:
+        db: Database connection
+        hours: Look back window
+        limit: Maximum sessions to return
+
+    Returns:
+        List of recently completed session dicts
+    """
+    if not db.connection:
+        db.connect()
+
+    try:
+        cursor = db.connection.cursor()  # type: ignore[union-attr]
+        # Use datetime format that matches database (without timezone)
+        cutoff = (datetime.now(timezone.utc) - timedelta(hours=hours)).strftime(
+            "%Y-%m-%d %H:%M:%S"
+        )
+        cursor.execute(
+            """
+            SELECT session_id as id, agent_assigned as agent_id, created_at as started_at,
+                   completed_at, total_events,
+                   (SELECT input_summary FROM agent_events
+                    WHERE session_id = sessions.session_id
+                    ORDER BY timestamp DESC LIMIT 1) as last_user_query
+            FROM sessions
+            WHERE status = 'completed'
+              AND completed_at > ?
+            ORDER BY completed_at DESC
+            LIMIT ?
+            """,
+            (cutoff, limit),
+        )
+        rows = cursor.fetchall()
+        return [dict(row) for row in rows]
+    except Exception:  # pragma: no cover
+        # Gracefully handle database errors
+        return []
+
+
+def format_recent_work_markdown(sessions: list[dict[str, Any]]) -> str:
+    """
+    Format recently completed sessions as markdown.
+
+    Args:
+        sessions: List of completed session dicts
+
+    Returns:
+        Markdown formatted string
+    """
+    if not sessions:
+        return ""
+
+    lines = ["## Recent Work (Last 24 Hours)", ""]
+
+    for session in sessions:
+        session_id = session.get("id", "unknown")
+        session_id = session_id[:12] if len(session_id) > 12 else session_id
+        query = session.get("last_user_query", "No query recorded")
+        total_events = session.get("total_events") or 0
+
+        query_display = (
+            query[:60] + "..." if query and len(query) > 60 else (query or "Unknown")
+        )
+
+        lines.append(f"- `{session_id}`: {query_display} ({total_events} events)")
+
+    lines.append("")
+
+    return "\n".join(lines)
+
+
+__all__ = [
+    "get_concurrent_sessions",
+    "format_concurrent_sessions_markdown",
+    "get_recent_completed_sessions",
+    "format_recent_work_markdown",
+]