htmlgraph 0.27.7__py3-none-any.whl → 0.28.1__py3-none-any.whl

htmlgraph/db/schema.py

@@ -484,6 +484,81 @@ class HtmlGraphDB:
             )
         """)
 
+        # 12. AGENT_PRESENCE TABLE - Phase 1: Cross-Agent Presence Tracking
+        cursor.execute("""
+            CREATE TABLE IF NOT EXISTS agent_presence (
+                agent_id TEXT PRIMARY KEY,
+                status TEXT NOT NULL DEFAULT 'offline' CHECK(
+                    status IN ('active', 'idle', 'offline')
+                ),
+                current_feature_id TEXT,
+                last_tool_name TEXT,
+                last_activity DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+                total_tools_executed INTEGER DEFAULT 0,
+                total_cost_tokens INTEGER DEFAULT 0,
+                session_id TEXT,
+                updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+                FOREIGN KEY (current_feature_id) REFERENCES features(id) ON DELETE SET NULL,
+                FOREIGN KEY (session_id) REFERENCES sessions(session_id) ON DELETE SET NULL
+            )
+        """)
+
+        # 13. OFFLINE_EVENTS TABLE - Phase 4: Offline-First Merge
+        cursor.execute("""
+            CREATE TABLE IF NOT EXISTS offline_events (
+                event_id TEXT PRIMARY KEY,
+                agent_id TEXT NOT NULL,
+                resource_id TEXT NOT NULL,
+                resource_type TEXT NOT NULL,
+                operation TEXT NOT NULL CHECK(
+                    operation IN ('create', 'update', 'delete')
+                ),
+                timestamp TEXT NOT NULL,
+                payload TEXT NOT NULL,
+                status TEXT DEFAULT 'local_only' CHECK(
+                    status IN ('local_only', 'synced', 'conflict', 'resolved')
+                ),
+                created_at TEXT DEFAULT CURRENT_TIMESTAMP
+            )
+        """)
+
+        # 14. CONFLICT_LOG TABLE - Phase 4: Conflict tracking and resolution
+        cursor.execute("""
+            CREATE TABLE IF NOT EXISTS conflict_log (
+                conflict_id TEXT PRIMARY KEY,
+                local_event_id TEXT NOT NULL,
+                remote_event_id TEXT,
+                resource_id TEXT NOT NULL,
+                conflict_type TEXT NOT NULL,
+                local_timestamp TEXT NOT NULL,
+                remote_timestamp TEXT NOT NULL,
+                resolution_strategy TEXT NOT NULL,
+                resolution TEXT,
+                status TEXT DEFAULT 'pending_review' CHECK(
+                    status IN ('pending_review', 'resolved')
+                ),
+                created_at TEXT DEFAULT CURRENT_TIMESTAMP,
+                FOREIGN KEY (local_event_id) REFERENCES offline_events(event_id) ON DELETE CASCADE
+            )
+        """)
+
+        # 15. SYNC_OPERATIONS TABLE - Phase 5: Git sync tracking
+        cursor.execute("""
+            CREATE TABLE IF NOT EXISTS sync_operations (
+                sync_id TEXT PRIMARY KEY,
+                operation TEXT NOT NULL CHECK(operation IN ('push', 'pull')),
+                status TEXT NOT NULL CHECK(
+                    status IN ('idle', 'pushing', 'pulling', 'success', 'error', 'conflict')
+                ),
+                timestamp DATETIME NOT NULL,
+                files_changed INTEGER DEFAULT 0,
+                conflicts TEXT,
+                message TEXT,
+                hostname TEXT,
+                created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+            )
+        """)
+
         # 9. Create indexes for performance
         self._create_indexes(cursor)
 
@@ -590,6 +665,34 @@ class HtmlGraphDB:
             "CREATE INDEX IF NOT EXISTS idx_cost_events_severity ON cost_events(severity, timestamp DESC)",
             # Pattern: Timestamp range queries for predictions
             "CREATE INDEX IF NOT EXISTS idx_cost_events_timestamp ON cost_events(timestamp DESC)",
+            # agent_presence indexes - optimized for presence queries
+            # Pattern: WHERE status (filter by status)
+            "CREATE INDEX IF NOT EXISTS idx_agent_presence_status ON agent_presence(status, last_activity DESC)",
+            # Pattern: WHERE current_feature_id (agents working on feature)
+            "CREATE INDEX IF NOT EXISTS idx_agent_presence_feature ON agent_presence(current_feature_id, last_activity DESC)",
+            # Pattern: ORDER BY last_activity (recent activity)
+            "CREATE INDEX IF NOT EXISTS idx_agent_presence_activity ON agent_presence(last_activity DESC)",
+            # offline_events indexes - optimized for sync and conflict detection
+            # Pattern: WHERE status = 'local_only' (unsynced events)
+            "CREATE INDEX IF NOT EXISTS idx_offline_events_status ON offline_events(status, timestamp DESC)",
+            # Pattern: WHERE resource_id (detect conflicts)
+            "CREATE INDEX IF NOT EXISTS idx_offline_events_resource ON offline_events(resource_id, resource_type)",
+            # Pattern: WHERE agent_id (agent's offline work)
+            "CREATE INDEX IF NOT EXISTS idx_offline_events_agent ON offline_events(agent_id, timestamp DESC)",
+            # conflict_log indexes - optimized for conflict management
+            # Pattern: WHERE status = 'pending_review' (unresolved conflicts)
+            "CREATE INDEX IF NOT EXISTS idx_conflict_log_status ON conflict_log(status, created_at DESC)",
+            # Pattern: WHERE resource_id (conflicts for resource)
+            "CREATE INDEX IF NOT EXISTS idx_conflict_log_resource ON conflict_log(resource_id, created_at DESC)",
+            # Pattern: WHERE local_event_id (lookup by event)
+            "CREATE INDEX IF NOT EXISTS idx_conflict_log_local_event ON conflict_log(local_event_id)",
+            # sync_operations indexes - optimized for sync history queries
+            # Pattern: WHERE status ORDER BY timestamp DESC (recent sync status)
+            "CREATE INDEX IF NOT EXISTS idx_sync_operations_status ON sync_operations(status, timestamp DESC)",
+            # Pattern: WHERE operation ORDER BY timestamp DESC (push/pull history)
+            "CREATE INDEX IF NOT EXISTS idx_sync_operations_operation ON sync_operations(operation, timestamp DESC)",
+            # Pattern: ORDER BY timestamp DESC (recent activity)
+            "CREATE INDEX IF NOT EXISTS idx_sync_operations_timestamp ON sync_operations(timestamp DESC)",
         ]
 
         for index_sql in indexes:
@@ -683,6 +786,18 @@ class HtmlGraphDB:
             )
             # Re-enable foreign key constraints
             cursor.execute("PRAGMA foreign_keys=ON")
+
+            # Update session metadata counters
+            cursor.execute(
+                """
+                UPDATE sessions
+                SET total_events = total_events + 1,
+                    total_tokens_used = total_tokens_used + ?
+                WHERE session_id = ?
+            """,
+                (cost_tokens, session_id),
+            )
+
             self.connection.commit()  # type: ignore[union-attr]
             return True
         except sqlite3.IntegrityError as e:
@@ -1783,6 +1898,117 @@ class HtmlGraphDB:
             logger.error(f"Error querying subagent work: {e}")
             return {}
 
+    def insert_sync_operation(
+        self,
+        sync_id: str,
+        operation: str,
+        status: str,
+        timestamp: str,
+        files_changed: int = 0,
+        conflicts: list[str] | None = None,
+        message: str | None = None,
+        hostname: str | None = None,
+    ) -> bool:
+        """
+        Record a sync operation in the database.
+
+        Args:
+            sync_id: Unique sync operation ID
+            operation: Operation type (push, pull)
+            status: Sync status (idle, pushing, pulling, success, error, conflict)
+            timestamp: Operation timestamp
+            files_changed: Number of files changed
+            conflicts: List of conflicted files (optional)
+            message: Status message (optional)
+            hostname: Hostname that performed the sync (optional)
+
+        Returns:
+            True if insert successful, False otherwise
+        """
+        if not self.connection:
+            self.connect()
+
+        try:
+            cursor = self.connection.cursor()  # type: ignore[union-attr]
+            cursor.execute(
+                """
+                INSERT INTO sync_operations
+                (sync_id, operation, status, timestamp, files_changed, conflicts,
+                 message, hostname)
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+            """,
+                (
+                    sync_id,
+                    operation,
+                    status,
+                    timestamp,
+                    files_changed,
+                    json.dumps(conflicts) if conflicts else None,
+                    message,
+                    hostname,
+                ),
+            )
+            self.connection.commit()  # type: ignore[union-attr]
+            return True
+        except sqlite3.Error as e:
+            logger.error(f"Error inserting sync operation: {e}")
+            return False
+
+    def get_sync_operations(
+        self, limit: int = 100, operation: str | None = None
+    ) -> list[dict[str, Any]]:
+        """
+        Get recent sync operations.
+
+        Args:
+            limit: Maximum number of results
+            operation: Filter by operation type (optional)
+
+        Returns:
+            List of sync operation dictionaries
+        """
+        if not self.connection:
+            self.connect()
+
+        try:
+            cursor = self.connection.cursor()  # type: ignore[union-attr]
+
+            if operation:
+                cursor.execute(
+                    """
+                    SELECT * FROM sync_operations
+                    WHERE operation = ?
+                    ORDER BY timestamp DESC
+                    LIMIT ?
+                """,
+                    (operation, limit),
+                )
+            else:
+                cursor.execute(
+                    """
+                    SELECT * FROM sync_operations
+                    ORDER BY timestamp DESC
+                    LIMIT ?
+                """,
+                    (limit,),
+                )
+
+            rows = cursor.fetchall()
+            results = []
+            for row in rows:
+                row_dict = dict(row)
+                # Parse JSON conflicts
+                if row_dict.get("conflicts"):
+                    try:
+                        row_dict["conflicts"] = json.loads(row_dict["conflicts"])
+                    except json.JSONDecodeError:
+                        pass
+                results.append(row_dict)
+            return results
+        except sqlite3.Error as e:
+            logger.error(f"Error querying sync operations: {e}")
+            return []
+
     def close(self) -> None:
         """Clean up database connection."""
         self.disconnect()

htmlgraph/hooks/event_tracker.py

@@ -34,6 +34,25 @@ from htmlgraph.db.schema import HtmlGraphDB
 from htmlgraph.ids import generate_id
 from htmlgraph.session_manager import SessionManager
 
+# Global presence manager instance (initialized on first use)
+_presence_manager = None
+
+
+def get_presence_manager() -> Any:
+    """Get or create global PresenceManager instance."""
+    global _presence_manager
+    if _presence_manager is None:
+        try:
+            from htmlgraph.api.presence import PresenceManager
+            from htmlgraph.config import get_database_path
+
+            _presence_manager = PresenceManager(db_path=str(get_database_path()))
+        except Exception as e:
+            logger.warning(f"Could not initialize PresenceManager: {e}")
+            _presence_manager = None
+    return _presence_manager
+
+
 # Drift classification queue (stored in session directory)
 DRIFT_QUEUE_FILE = "drift-queue.json"
 
@@ -1011,6 +1030,11 @@ def track_event(hook_type: str, hook_input: dict[str, Any]) -> dict[str, Any]:
                     model=detected_model,
                     feature_id=result.feature_id if result else None,
                 )
+
+            # Update presence - mark as offline
+            presence_mgr = get_presence_manager()
+            if presence_mgr:
+                presence_mgr.mark_offline(detected_agent)
         except Exception as e:
             logger.warning(f"Warning: Could not track stop: {e}")
         return {"continue": True}
@@ -1031,7 +1055,7 @@ def track_event(hook_type: str, hook_input: dict[str, Any]) -> dict[str, Any]:
             # UserQuery event is stored in database - no file-based state needed
             # Subsequent tool calls query database for parent via get_parent_user_query()
             if db:
-                record_event_to_sqlite(
+                event_id = record_event_to_sqlite(
                     db=db,
                     session_id=active_session_id,
                     tool_name="UserQuery",
@@ -1043,6 +1067,19 @@ def track_event(hook_type: str, hook_input: dict[str, Any]) -> dict[str, Any]:
                     feature_id=result.feature_id if result else None,
                 )
 
+                # Update presence
+                presence_mgr = get_presence_manager()
+                if presence_mgr and event_id:
+                    presence_mgr.update_presence(
+                        agent_id=detected_agent,
+                        event={
+                            "tool_name": "UserQuery",
+                            "session_id": active_session_id,
+                            "feature_id": result.feature_id if result else None,
+                            "event_id": event_id,
+                        },
+                    )
+
         except Exception as e:
             logger.warning(f"Warning: Could not track query: {e}")
         return {"continue": True}
@@ -1176,7 +1213,7 @@ def track_event(hook_type: str, hook_input: dict[str, Any]) -> dict[str, Any]:
                         "subagent_type", "general-purpose"
                     )
 
-                record_event_to_sqlite(
+                event_id = record_event_to_sqlite(
                     db=db,
                     session_id=active_session_id,
                     tool_name=tool_name,
@@ -1191,6 +1228,20 @@ def track_event(hook_type: str, hook_input: dict[str, Any]) -> dict[str, Any]:
                     feature_id=result.feature_id if result else None,
                 )
 
+                # Update presence
+                presence_mgr = get_presence_manager()
+                if presence_mgr and event_id:
+                    presence_mgr.update_presence(
+                        agent_id=detected_agent,
+                        event={
+                            "tool_name": tool_name,
+                            "session_id": active_session_id,
+                            "feature_id": result.feature_id if result else None,
+                            "cost_tokens": 0,  # TODO: Extract from tool_response
+                            "event_id": event_id,
+                        },
+                    )
+
             # If this was a Task() delegation, also record to agent_collaboration
             if tool_name == "Task" and db:
                 subagent = tool_input_data.get("subagent_type", "general-purpose")

htmlgraph/models.py

@@ -964,6 +964,7 @@ class Session(BaseModel):
     last_activity: datetime = Field(default_factory=datetime.now)
 
     start_commit: str | None = None  # Git commit hash at session start
+    end_commit: str | None = None  # Git commit hash at session end
     event_count: int = 0
 
     # Relationships

htmlgraph/reactive_integration.py

@@ -0,0 +1,148 @@
+"""
+Reactive Query Integration - Connect to Event Pipeline
+
+Integrates reactive queries with the broadcast system to automatically
+invalidate queries when resources (features, events, sessions) are updated.
+
+This module provides the glue between:
+- Broadcast events (resource updates)
+- Reactive query manager (query invalidation)
+- Event tracker (tool call tracking)
+
+When a resource is updated:
+1. Broadcast event is fired
+2. This module catches it
+3. Reactive query manager invalidates dependent queries
+4. Query subscribers receive new results via WebSocket
+"""
+
+import logging
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+# Global reactive query manager instance
+_reactive_query_manager: Any = None
+
+
+def set_reactive_query_manager(manager: Any) -> None:
+    """
+    Set global reactive query manager instance.
+
+    Args:
+        manager: ReactiveQueryManager instance
+    """
+    global _reactive_query_manager
+    _reactive_query_manager = manager
+    logger.info("Reactive query manager registered for event integration")
+
+
+def get_reactive_query_manager() -> Any | None:
+    """
+    Get global reactive query manager instance.
+
+    Returns:
+        ReactiveQueryManager instance or None if not initialized
+    """
+    return _reactive_query_manager
+
+
+async def on_broadcast_event(event: dict[str, Any]) -> None:
+    """
+    Called when a broadcast event occurs.
+
+    Invalidates queries that depend on the updated resource.
+
+    Args:
+        event: Broadcast event data
+    """
+    if not _reactive_query_manager:
+        return
+
+    resource_id = event.get("resource_id")
+    resource_type = event.get("resource_type")
+
+    if resource_id and resource_type:
+        try:
+            await _reactive_query_manager.on_resource_updated(
+                resource_id, resource_type
+            )
+            logger.debug(
+                f"Reactive queries invalidated for {resource_type}:{resource_id}"
+            )
+        except Exception as e:
+            logger.error(f"Error invalidating queries for {resource_id}: {e}")
+
+
+async def on_tool_call_complete(
+    session_id: str,
+    tool_name: str,
+    feature_id: str | None = None,
+) -> None:
+    """
+    Called when a tool call completes.
+
+    Invalidates queries that depend on the affected resources.
+
+    Args:
+        session_id: Session ID
+        tool_name: Tool that was called
+        feature_id: Feature ID if applicable
+    """
+    if not _reactive_query_manager:
+        return
+
+    try:
+        # Tool calls affect events
+        await _reactive_query_manager.on_resource_updated(session_id, "event")
+
+        # If feature involved, invalidate feature queries
+        if feature_id:
+            await _reactive_query_manager.on_resource_updated(feature_id, "feature")
+
+        logger.debug(
+            f"Reactive queries invalidated for tool call: {tool_name} "
+            f"(session={session_id}, feature={feature_id})"
+        )
+
+    except Exception as e:
+        logger.error(f"Error invalidating queries for tool call: {e}")
+
+
+async def on_session_start(session_id: str, agent_id: str) -> None:
+    """
+    Called when a session starts.
+
+    Invalidates queries that depend on sessions.
+
+    Args:
+        session_id: Session ID
+        agent_id: Agent ID
+    """
+    if not _reactive_query_manager:
+        return
+
+    try:
+        await _reactive_query_manager.on_resource_updated(session_id, "session")
+        logger.debug(f"Reactive queries invalidated for session start: {session_id}")
+    except Exception as e:
+        logger.error(f"Error invalidating queries for session start: {e}")
+
+
+async def on_session_end(session_id: str) -> None:
+    """
+    Called when a session ends.
+
+    Invalidates queries that depend on sessions.
+
+    Args:
+        session_id: Session ID
+    """
+    if not _reactive_query_manager:
+        return
+
+    try:
+        await _reactive_query_manager.on_resource_updated(session_id, "session")
+        logger.debug(f"Reactive queries invalidated for session end: {session_id}")
+    except Exception as e:
+        logger.error(f"Error invalidating queries for session end: {e}")

htmlgraph/session_manager.py

@@ -713,6 +713,7 @@ class SessionManager:
         handoff_notes: str | None = None,
         recommended_next: str | None = None,
         blockers: list[str] | None = None,
+        end_commit: str | None = None,
     ) -> Session | None:
         """
         End a session.
@@ -722,6 +723,7 @@ class SessionManager:
             handoff_notes: Optional handoff notes for next session
             recommended_next: Optional recommended next steps
             blockers: Optional list of blockers
+            end_commit: Optional git commit hash at session end
 
         Returns:
             Updated Session or None if not found
@@ -736,6 +738,11 @@ class SessionManager:
             session.recommended_next = recommended_next
         if blockers is not None:
             session.blockers = blockers
+        if end_commit is not None:
+            session.end_commit = end_commit
+        elif not session.end_commit:
+            # Auto-detect current commit if not provided
+            session.end_commit = self._get_current_commit()
 
         session.end()
         session.add_activity(

htmlgraph/sync/__init__.py

@@ -0,0 +1,21 @@
+"""
+Git-based synchronization for multi-device continuity.
+
+Enables automatic sync of .htmlgraph/ directory across devices via Git.
+"""
+
+from .git_sync import (
+    GitSyncManager,
+    SyncConfig,
+    SyncResult,
+    SyncStatus,
+    SyncStrategy,
+)
+
+__all__ = [
+    "GitSyncManager",
+    "SyncConfig",
+    "SyncStrategy",
+    "SyncStatus",
+    "SyncResult",
+]