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

htmlgraph/__init__.py

@@ -8,6 +8,14 @@ hyperlinks as edges, and CSS selectors as the query language.
 from htmlgraph.agent_detection import detect_agent_name, get_agent_display_name
 from htmlgraph.agents import AgentInterface
 from htmlgraph.analytics import Analytics, DependencyAnalytics
+from htmlgraph.atomic_ops import (
+    AtomicFileWriter,
+    DirectoryLocker,
+    atomic_rename,
+    cleanup_orphaned_temp_files,
+    safe_temp_file,
+    validate_atomic_write,
+)
 from htmlgraph.builders import BaseBuilder, FeatureBuilder, SpikeBuilder
 from htmlgraph.collections import BaseCollection, FeatureCollection, SpikeCollection
 from htmlgraph.context_analytics import ContextAnalytics, ContextUsage
@@ -56,9 +64,11 @@ from htmlgraph.orchestrator_mode import OrchestratorMode, OrchestratorModeManage
 from htmlgraph.parallel import AggregateResult, ParallelAnalysis, ParallelWorkflow
 from htmlgraph.query_builder import Condition, Operator, QueryBuilder
 from htmlgraph.reflection import ComputationalReflection, get_reflection_context
+from htmlgraph.repo_hash import RepoHash
 from htmlgraph.sdk import SDK
 from htmlgraph.server import serve
 from htmlgraph.session_manager import SessionManager
+from htmlgraph.session_registry import SessionRegistry
 from htmlgraph.types import (
     ActiveWorkItem,
     AggregateResultsDict,
@@ -85,7 +95,7 @@ from htmlgraph.types import (
 )
 from htmlgraph.work_type_utils import infer_work_type, infer_work_type_from_id
 
-__version__ = "0.24.1"
+__version__ = "0.25.0"
 __all__ = [
     # Exceptions
     "HtmlGraphError",
@@ -123,6 +133,8 @@ __all__ = [
     "find_all",
     "AgentInterface",
     "SessionManager",
+    "SessionRegistry",
+    "RepoHash",
     "SDK",
     "Analytics",  # Phase 2: Work Type Analytics
     "DependencyAnalytics",  # Advanced dependency-aware analytics
@@ -190,4 +202,11 @@ __all__ = [
     "get_results_by_task_id",
     "parallel_delegate",
     "generate_task_id",
+    # Atomic file operations (Phase 1.3: Session File Tracking)
+    "AtomicFileWriter",
+    "DirectoryLocker",
+    "atomic_rename",
+    "cleanup_orphaned_temp_files",
+    "safe_temp_file",
+    "validate_atomic_write",
 ]

htmlgraph/agent_detection.py

@@ -14,34 +14,48 @@ def detect_agent_name() -> str:
     Detect the current agent/interface name based on environment.
 
     Returns:
-        Agent name (e.g., "claude", "gemini", "cli")
+        Agent name (e.g., "claude-code", "gemini", "cli")
 
     Detection order:
         1. HTMLGRAPH_AGENT environment variable (explicit override)
-        2. Claude Code detection (CLAUDE_CODE_VERSION, parent process)
-        3. Gemini detection (GEMINI environment markers)
-        4. Fall back to "cli"
+        2. HTMLGRAPH_PARENT_AGENT (set by hooks for session context)
+        3. Gemini detection (GEMINI environment markers) - checked before Claude to allow override
+        4. Claude Code detection (CLAUDECODE env var, parent process)
+        5. Fall back to "cli" only if no AI agent detected
     """
     # 1. Explicit override
     explicit = os.environ.get("HTMLGRAPH_AGENT")
     if explicit:
         return explicit.strip()
 
-    # 2. Claude Code detection
-    if _is_claude_code():
-        return "claude"
+    # 2. Parent agent context (set by HtmlGraph hooks)
+    parent_agent = os.environ.get("HTMLGRAPH_PARENT_AGENT")
+    if parent_agent:
+        return parent_agent.strip()
 
-    # 3. Gemini detection
+    # 3. Gemini detection (checked before Claude to allow explicit override)
     if _is_gemini():
         return "gemini"
 
-    # 4. Default to CLI
+    # 4. Claude Code detection
+    if _is_claude_code():
+        return "claude-code"
+
+    # 5. Default to CLI only if no AI agent detected
     return "cli"
 
 
 def _is_claude_code() -> bool:
     """Check if running in Claude Code environment."""
     # Check for Claude Code environment variables
+    # CLAUDECODE=1 is set by Claude Code CLI
+    if os.environ.get("CLAUDECODE"):
+        return True
+
+    # CLAUDE_CODE_ENTRYPOINT indicates the entry point (cli, api, etc.)
+    if os.environ.get("CLAUDE_CODE_ENTRYPOINT"):
+        return True
+
     if os.environ.get("CLAUDE_CODE_VERSION"):
         return True
 
@@ -100,12 +114,14 @@ def get_agent_display_name(agent: str) -> str:
     """
     display_names = {
         "claude": "Claude",
-        "claude-code": "Claude",
+        "claude-code": "Claude Code",
         "gemini": "Gemini",
         "cli": "CLI",
         "haiku": "Haiku",
         "opus": "Opus",
         "sonnet": "Sonnet",
+        "claude-opus-4-5-20251101": "Claude Opus 4.5",
+        "claude-sonnet-4-20250514": "Claude Sonnet 4",
     }
 
     return display_names.get(agent.lower(), agent.title())

htmlgraph/analytics/cross_session.py

@@ -51,6 +51,7 @@ if TYPE_CHECKING:
     from htmlgraph import SDK
 
 from htmlgraph.event_log import JsonlEventLog
+from htmlgraph.models import utc_now
 
 
 @dataclass
@@ -598,7 +599,7 @@ class CrossSessionAnalytics:
     def _parse_timestamp(self, timestamp: str | datetime | None) -> datetime:
         """Parse timestamp from various formats."""
         if timestamp is None:
-            return datetime.now()
+            return utc_now()
 
         if isinstance(timestamp, datetime):
             return timestamp
@@ -607,6 +608,6 @@ class CrossSessionAnalytics:
             try:
                 return datetime.fromisoformat(timestamp.replace("Z", "+00:00"))
             except (ValueError, AttributeError):
-                return datetime.now()
+                return utc_now()
 
-        return datetime.now()
+        return utc_now()

htmlgraph/analytics/work_type.py

@@ -27,17 +27,35 @@ Example:
 
 from __future__ import annotations
 
-from datetime import datetime
+from datetime import datetime, timezone
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
     from htmlgraph import SDK
 
 from htmlgraph.converter import html_to_session
-from htmlgraph.models import Session, WorkType
+from htmlgraph.models import Session, WorkType, utc_now
 from htmlgraph.session_manager import SessionManager
 
 
+def normalize_datetime(dt: datetime | None) -> datetime | None:
+    """
+    Normalize datetime to UTC-aware format for safe comparisons.
+
+    Handles three cases:
+    - None: returns None
+    - Naive (no timezone): assumes UTC and adds timezone
+    - Aware (has timezone): converts to UTC
+    """
+    if dt is None:
+        return None
+    if dt.tzinfo is None:
+        # Naive datetime - assume UTC
+        return dt.replace(tzinfo=timezone.utc)
+    # Already aware - convert to UTC
+    return dt.astimezone(timezone.utc)
+
+
 class Analytics:
     """
     Analytics interface for work type analysis.
@@ -270,9 +288,11 @@ class Analytics:
                 continue
 
             # Check date range
-            if start_date and session.started_at < start_date:
+            start_normalized = normalize_datetime(start_date)
+            end_normalized = normalize_datetime(end_date)
+            if start_normalized and session.started_at < start_normalized:
                 continue
-            if end_date and session.started_at > end_date:
+            if end_normalized and session.started_at > end_normalized:
                 continue
 
             # Check primary work type
@@ -413,18 +433,26 @@ class Analytics:
         # Calculate time for each spike
         for spike in all_spikes:
             # Apply date filters
-            if start_date and spike.created < start_date:
+            start_normalized = normalize_datetime(start_date)
+            end_normalized = normalize_datetime(end_date)
+            if start_normalized and spike.created < start_normalized:
                 continue
-            if end_date and spike.created > end_date:
+            if end_normalized and spike.created > end_normalized:
                 continue
 
-            # Calculate duration
-            start_time = spike.created
+            # Calculate duration (normalize datetimes for safe comparison)
+            start_time = normalize_datetime(spike.created)
+            if not start_time:
+                continue  # Skip if spike creation date is missing
             if spike.status == "done" and spike.updated:
-                end_time = spike.updated
+                end_time = normalize_datetime(spike.updated)
             else:
                 # If still in progress, use last updated time
-                end_time = spike.updated if spike.updated else datetime.now()
+                end_time = normalize_datetime(
+                    spike.updated if spike.updated else utc_now()
+                )
+            if not end_time:
+                end_time = start_time  # Fallback to start time if end time missing
 
             duration = (
                 end_time - start_time
@@ -460,17 +488,25 @@ class Analytics:
 
             for node in nodes:
                 # Apply date filters
-                if start_date and node.created < start_date:
+                start_normalized = normalize_datetime(start_date)
+                end_normalized = normalize_datetime(end_date)
+                if start_normalized and node.created < start_normalized:
                     continue
-                if end_date and node.created > end_date:
+                if end_normalized and node.created > end_normalized:
                     continue
 
-                # Calculate duration
-                start_time = node.created
+                # Calculate duration (normalize datetimes for safe comparison)
+                start_time = normalize_datetime(node.created)
+                if not start_time:
+                    continue  # Skip if node creation date is missing
                 if node.status == "done" and node.updated:
-                    end_time = node.updated
+                    end_time = normalize_datetime(node.updated)
                 else:
-                    end_time = node.updated if node.updated else datetime.now()
+                    end_time = normalize_datetime(
+                        node.updated if node.updated else utc_now()
+                    )
+                if not end_time:
+                    end_time = start_time  # Fallback to start time if end time missing
 
                 duration = (end_time - start_time).total_seconds() / 60
                 feature_minutes += duration

htmlgraph/analytics_index.py

@@ -14,7 +14,7 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Any
 
-SCHEMA_VERSION = 2
+SCHEMA_VERSION = 4  # Bumped: renamed 'agent' column to 'agent_assigned'
 
 
 @dataclass(frozen=True)
@@ -82,12 +82,14 @@ class AnalyticsIndex:
                 """
                 CREATE TABLE IF NOT EXISTS sessions (
                     session_id TEXT PRIMARY KEY,
-                    agent TEXT,
+                    agent_assigned TEXT,
                     start_commit TEXT,
                     continued_from TEXT,
                     status TEXT,
                     started_at TEXT,
-                    ended_at TEXT
+                    ended_at TEXT,
+                    parent_session_id TEXT,
+                    parent_event_id TEXT
                 )
                 """
             )
@@ -103,6 +105,9 @@ class AnalyticsIndex:
                     feature_id TEXT,
                     drift_score REAL,
                     payload_json TEXT,
+                    parent_event_id TEXT,
+                    cost_tokens INTEGER,
+                    execution_duration_seconds REAL,
                     FOREIGN KEY(session_id) REFERENCES sessions(session_id)
                 )
                 """
@@ -157,6 +162,9 @@ class AnalyticsIndex:
             )
 
             # Indexes for typical dashboard queries
+            conn.execute(
+                "CREATE INDEX IF NOT EXISTS idx_sessions_parent ON sessions(parent_session_id)"
+            )
             conn.execute("CREATE INDEX IF NOT EXISTS idx_events_ts ON events(ts)")
             conn.execute(
                 "CREATE INDEX IF NOT EXISTS idx_events_session_ts ON events(session_id, ts)"
@@ -190,15 +198,17 @@ class AnalyticsIndex:
         with self.connect() as conn:
             conn.execute(
                 """
-                INSERT INTO sessions(session_id, agent, start_commit, continued_from, status, started_at, ended_at)
-                VALUES(?,?,?,?,?,?,?)
+                INSERT INTO sessions(session_id, agent_assigned, start_commit, continued_from, status, started_at, ended_at, parent_session_id, parent_event_id)
+                VALUES(?,?,?,?,?,?,?,?,?)
                 ON CONFLICT(session_id) DO UPDATE SET
-                    agent=excluded.agent,
+                    agent_assigned=excluded.agent_assigned,
                     start_commit=excluded.start_commit,
                     continued_from=excluded.continued_from,
                     status=excluded.status,
                     started_at=excluded.started_at,
-                    ended_at=excluded.ended_at
+                    ended_at=excluded.ended_at,
+                    parent_session_id=excluded.parent_session_id,
+                    parent_event_id=excluded.parent_event_id
                 """,
                 (
                     session.get("session_id"),
@@ -208,6 +218,8 @@ class AnalyticsIndex:
                     session.get("status"),
                     session.get("started_at"),
                     session.get("ended_at"),
+                    session.get("parent_session_id"),
+                    session.get("parent_event_id"),
                 ),
             )
 
@@ -238,8 +250,8 @@ class AnalyticsIndex:
         with self.connect() as conn:
             conn.execute(
                 """
-                INSERT OR IGNORE INTO events(event_id, session_id, ts, tool, summary, success, feature_id, drift_score, payload_json)
-                VALUES(?,?,?,?,?,?,?,?,?)
+                INSERT OR IGNORE INTO events(event_id, session_id, ts, tool, summary, success, feature_id, drift_score, payload_json, parent_event_id, cost_tokens, execution_duration_seconds)
+                VALUES(?,?,?,?,?,?,?,?,?,?,?,?)
                 """,
                 (
                     event_id,
@@ -251,6 +263,9 @@ class AnalyticsIndex:
                     event.get("feature_id"),
                     event.get("drift_score"),
                     payload_json,
+                    event.get("parent_event_id"),
+                    event.get("cost_tokens"),
+                    event.get("execution_duration_seconds"),
                 ),
             )
             # Insert file path rows, idempotent by (event_id, path)
@@ -367,6 +382,8 @@ class AnalyticsIndex:
                         "status": event.get("session_status"),
                         "started_at": None,
                         "ended_at": None,
+                        "parent_session_id": event.get("parent_session_id"),
+                        "parent_event_id": event.get("parent_event_id"),
                     },
                 )
                 if meta.get("agent") is None and event.get("agent"):
@@ -377,6 +394,12 @@ class AnalyticsIndex:
                     meta["continued_from"] = event.get("continued_from")
                 if meta.get("status") is None and event.get("session_status"):
                     meta["status"] = event.get("session_status")
+                if meta.get("parent_session_id") is None and event.get(
+                    "parent_session_id"
+                ):
+                    meta["parent_session_id"] = event.get("parent_session_id")
+                if meta.get("parent_event_id") is None and event.get("parent_event_id"):
+                    meta["parent_event_id"] = event.get("parent_event_id")
 
                 # Track time range (treat earliest event as started_at, latest as ended_at if session is ended)
                 if meta["started_at"] is None or ts < meta["started_at"]:
@@ -393,8 +416,8 @@ class AnalyticsIndex:
 
                 conn.execute(
                     """
-                    INSERT OR IGNORE INTO events(event_id, session_id, ts, tool, summary, success, feature_id, drift_score, payload_json)
-                    VALUES(?,?,?,?,?,?,?,?,?)
+                    INSERT OR IGNORE INTO events(event_id, session_id, ts, tool, summary, success, feature_id, drift_score, payload_json, parent_event_id, cost_tokens, execution_duration_seconds)
+                    VALUES(?,?,?,?,?,?,?,?,?,?,?,?)
                     """,
                     (
                         event_id,
@@ -406,6 +429,9 @@ class AnalyticsIndex:
                         event.get("feature_id"),
                         event.get("drift_score"),
                         payload_json,
+                        event.get("parent_event_id"),
+                        event.get("cost_tokens"),
+                        event.get("execution_duration_seconds"),
                     ),
                 )
 
@@ -483,17 +509,19 @@ class AnalyticsIndex:
             for meta in session_meta.values():
                 conn.execute(
                     """
-                    INSERT INTO sessions(session_id, agent, start_commit, continued_from, status, started_at, ended_at)
-                    VALUES(?,?,?,?,?,?,?)
+                    INSERT INTO sessions(session_id, agent_assigned, start_commit, continued_from, status, started_at, ended_at, parent_session_id, parent_event_id)
+                    VALUES(?,?,?,?,?,?,?,?,?)
                     """,
                     (
                         meta.get("session_id"),
-                        meta.get("agent"),
+                        meta.get("agent"),  # Source data still uses 'agent' key
                         meta.get("start_commit"),
                         meta.get("continued_from"),
                         meta.get("status"),
                         meta.get("started_at"),
                         meta.get("ended_at"),
+                        meta.get("parent_session_id"),
+                        meta.get("parent_event_id"),
                     ),
                 )
 
@@ -676,13 +704,17 @@ class AnalyticsIndex:
         with self.connect() as conn:
             rows = conn.execute(
                 """
-                SELECT event_id, session_id, ts, tool, summary, success, feature_id, drift_score
-                FROM events
-                WHERE session_id=?
-                ORDER BY ts DESC
+                SELECT e.event_id, e.session_id, e.ts, e.tool, e.summary, e.success, e.feature_id, e.drift_score,
+                       COALESCE(e.parent_event_id, s.parent_event_id) as parent_event_id,
+                       e.cost_tokens, e.execution_duration_seconds
+                FROM events e
+                JOIN sessions s ON e.session_id = s.session_id
+                WHERE e.session_id = ?
+                   OR s.parent_session_id = ?
+                ORDER BY e.ts DESC
                 LIMIT ?
                 """,
-                (session_id, int(limit)),
+                (session_id, session_id, int(limit)),
             ).fetchall()
         return [dict(r) for r in rows]
 

htmlgraph/api/__init__.py

@@ -0,0 +1,3 @@
+"""HtmlGraph FastAPI Backend - Real-time Agent Observability Dashboard."""
+
+__all__ = ["app", "get_app"]