htmlgraph 0.20.1__py3-none-any.whl → 0.27.5__py3-none-any.whl

htmlgraph/templates/orchestration-view.html

@@ -0,0 +1,350 @@
+<!-- Orchestration View Component
+     Displays agent delegation chains and coordination topology.
+     Fetches from /api/orchestration endpoint.
+-->
+
+<div id="orchestration-view" class="orchestration-container">
+    <div class="orchestration-header">
+        <h2>Agent Orchestration</h2>
+        <p class="subtitle">Delegation chains and agent coordination</p>
+    </div>
+
+    <div class="orchestration-metrics">
+        <div class="metric-card">
+            <div class="metric-label">Total Delegations</div>
+            <div class="metric-value" id="delegation-count">0</div>
+        </div>
+        <div class="metric-card">
+            <div class="metric-label">Unique Agents</div>
+            <div class="metric-value" id="unique-agents">0</div>
+        </div>
+        <div class="metric-card">
+            <div class="metric-label">Active Agents</div>
+            <div class="metric-value" id="agent-list">—</div>
+        </div>
+    </div>
+
+    <div class="orchestration-chains" id="delegation-chains">
+        <div class="empty-state">
+            <p>No delegation events recorded yet.</p>
+            <p class="hint">Delegation events will appear here when Task() calls are made.</p>
+        </div>
+    </div>
+
+    <div class="orchestration-legend">
+        <div class="legend-item">
+            <span class="status-badge pending"></span>
+            <span>Pending</span>
+        </div>
+        <div class="legend-item">
+            <span class="status-badge accepted"></span>
+            <span>Accepted</span>
+        </div>
+        <div class="legend-item">
+            <span class="status-badge completed"></span>
+            <span>Completed</span>
+        </div>
+        <div class="legend-item">
+            <span class="status-badge failed"></span>
+            <span>Failed</span>
+        </div>
+    </div>
+</div>
+
+<style>
+    .orchestration-container {
+        padding: 2rem;
+        background: var(--bg-secondary);
+        border: 1px solid var(--border);
+        border-radius: 4px;
+    }
+
+    .orchestration-header {
+        margin-bottom: 2rem;
+        border-bottom: 2px solid var(--border);
+        padding-bottom: 1rem;
+    }
+
+    .orchestration-header h2 {
+        font-size: 1.5rem;
+        color: var(--text-primary);
+        margin-bottom: 0.5rem;
+        font-weight: 600;
+    }
+
+    .orchestration-header .subtitle {
+        color: var(--text-secondary);
+        font-size: 0.9rem;
+    }
+
+    .orchestration-metrics {
+        display: grid;
+        grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
+        gap: 1rem;
+        margin-bottom: 2rem;
+    }
+
+    .metric-card {
+        background: var(--bg-tertiary);
+        border: 1px solid var(--border);
+        border-radius: 4px;
+        padding: 1.5rem;
+        text-align: center;
+    }
+
+    .metric-label {
+        color: var(--text-secondary);
+        font-size: 0.9rem;
+        margin-bottom: 0.5rem;
+        text-transform: uppercase;
+        letter-spacing: 0.05em;
+    }
+
+    .metric-value {
+        font-size: 2rem;
+        font-weight: 700;
+        color: var(--accent);
+        font-family: 'JetBrains Mono', monospace;
+    }
+
+    .orchestration-chains {
+        margin-bottom: 2rem;
+    }
+
+    .empty-state {
+        text-align: center;
+        padding: 3rem 1rem;
+        color: var(--text-secondary);
+    }
+
+    .empty-state p {
+        margin-bottom: 0.5rem;
+    }
+
+    .empty-state .hint {
+        font-size: 0.85rem;
+        color: var(--text-muted);
+        font-style: italic;
+    }
+
+    .delegation-chain {
+        margin-bottom: 1.5rem;
+        border-left: 3px solid var(--status-active);
+        padding-left: 1rem;
+    }
+
+    .chain-from-agent {
+        font-weight: 600;
+        color: var(--text-primary);
+        font-size: 1rem;
+        margin-bottom: 0.5rem;
+        padding: 0.75rem;
+        background: rgba(41, 121, 255, 0.1);
+        border-radius: 4px;
+        border-left: 3px solid var(--status-active);
+    }
+
+    .chain-delegations {
+        margin-top: 0.5rem;
+    }
+
+    .delegation-item {
+        display: flex;
+        align-items: flex-start;
+        gap: 1rem;
+        padding: 0.75rem;
+        margin-bottom: 0.5rem;
+        background: var(--bg-tertiary);
+        border-radius: 3px;
+        border-left: 3px solid var(--status-active);
+    }
+
+    .delegation-arrow {
+        color: var(--text-secondary);
+        font-weight: bold;
+        min-width: 1rem;
+        text-align: center;
+    }
+
+    .delegation-details {
+        flex: 1;
+    }
+
+    .delegation-to-agent {
+        font-weight: 600;
+        color: var(--text-primary);
+        font-size: 0.95rem;
+    }
+
+    .delegation-task {
+        color: var(--text-secondary);
+        font-size: 0.85rem;
+        margin: 0.25rem 0;
+        font-family: 'JetBrains Mono', monospace;
+    }
+
+    .delegation-timestamp {
+        color: var(--text-muted);
+        font-size: 0.8rem;
+        margin-top: 0.25rem;
+    }
+
+    .status-badge {
+        display: inline-block;
+        width: 0.75rem;
+        height: 0.75rem;
+        border-radius: 50%;
+        margin-right: 0.5rem;
+    }
+
+    .status-badge.pending {
+        background: var(--status-todo);
+    }
+
+    .status-badge.accepted {
+        background: var(--status-active);
+    }
+
+    .status-badge.completed {
+        background: var(--status-done);
+    }
+
+    .status-badge.failed {
+        background: var(--status-blocked);
+    }
+
+    .delegation-status {
+        display: inline-flex;
+        align-items: center;
+        gap: 0.5rem;
+        font-size: 0.8rem;
+        padding: 0.25rem 0.5rem;
+        background: var(--bg-primary);
+        border-radius: 3px;
+        margin-left: auto;
+        text-transform: uppercase;
+    }
+
+    .orchestration-legend {
+        display: flex;
+        gap: 1.5rem;
+        padding: 1rem;
+        background: var(--bg-tertiary);
+        border-radius: 4px;
+        flex-wrap: wrap;
+    }
+
+    .legend-item {
+        display: flex;
+        align-items: center;
+        gap: 0.5rem;
+        font-size: 0.85rem;
+        color: var(--text-secondary);
+    }
+</style>
+
+<script>
+    function renderOrchestrationView(data) {
+        document.getElementById('delegation-count').textContent = data.delegation_count;
+        document.getElementById('unique-agents').textContent = data.unique_agents;
+        document.getElementById('agent-list').textContent = data.agents.join(', ') || '—';
+
+        const chainsContainer = document.getElementById('delegation-chains');
+
+        if (data.delegation_count === 0) {
+            chainsContainer.textContent = '';
+            const emptyDiv = document.createElement('div');
+            emptyDiv.className = 'empty-state';
+            emptyDiv.innerHTML = '<p>No delegation events recorded yet.</p><p class="hint">Delegation events will appear here when Task() calls are made.</p>';
+            chainsContainer.appendChild(emptyDiv);
+            return;
+        }
+
+        chainsContainer.textContent = '';
+
+        for (const fromAgent in data.delegation_chains) {
+            const delegations = data.delegation_chains[fromAgent];
+            const chainDiv = document.createElement('div');
+            chainDiv.className = 'delegation-chain';
+
+            const fromAgentDiv = document.createElement('div');
+            fromAgentDiv.className = 'chain-from-agent';
+            fromAgentDiv.textContent = fromAgent;
+            chainDiv.appendChild(fromAgentDiv);
+
+            const delegationsDiv = document.createElement('div');
+            delegationsDiv.className = 'chain-delegations';
+
+            for (const delegation of delegations) {
+                const itemDiv = document.createElement('div');
+                itemDiv.className = 'delegation-item';
+
+                const arrowDiv = document.createElement('div');
+                arrowDiv.className = 'delegation-arrow';
+                arrowDiv.textContent = '↓';
+                itemDiv.appendChild(arrowDiv);
+
+                const detailsDiv = document.createElement('div');
+                detailsDiv.className = 'delegation-details';
+
+                const toAgentDiv = document.createElement('div');
+                toAgentDiv.className = 'delegation-to-agent';
+                toAgentDiv.textContent = delegation.to_agent;
+                detailsDiv.appendChild(toAgentDiv);
+
+                const taskDiv = document.createElement('div');
+                taskDiv.className = 'delegation-task';
+                taskDiv.textContent = 'Task: ' + delegation.task;
+                detailsDiv.appendChild(taskDiv);
+
+                const timeDiv = document.createElement('div');
+                timeDiv.className = 'delegation-timestamp';
+                try {
+                    const date = new Date(delegation.timestamp);
+                    timeDiv.textContent = date.toLocaleString();
+                } catch {
+                    timeDiv.textContent = delegation.timestamp || 'N/A';
+                }
+                detailsDiv.appendChild(timeDiv);
+
+                itemDiv.appendChild(detailsDiv);
+
+                const statusDiv = document.createElement('div');
+                statusDiv.className = 'delegation-status';
+                const badgeSpan = document.createElement('span');
+                badgeSpan.className = 'status-badge ' + (delegation.status || 'pending');
+                statusDiv.appendChild(badgeSpan);
+                const statusText = document.createTextNode((delegation.status || 'pending').charAt(0).toUpperCase() + (delegation.status || 'pending').slice(1));
+                statusDiv.appendChild(statusText);
+                itemDiv.appendChild(statusDiv);
+
+                delegationsDiv.appendChild(itemDiv);
+            }
+
+            chainDiv.appendChild(delegationsDiv);
+            chainsContainer.appendChild(chainDiv);
+        }
+    }
+
+    async function loadOrchestrationView() {
+        try {
+            const response = await fetch('/api/orchestration');
+            if (!response.ok) {
+                console.warn('Orchestration view not available');
+                return;
+            }
+            const data = await response.json();
+            renderOrchestrationView(data);
+        } catch (error) {
+            console.error('Failed to load orchestration view:', error);
+        }
+    }
+
+    if (document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', loadOrchestrationView);
+    } else {
+        loadOrchestrationView();
+    }
+
+    setInterval(loadOrchestrationView, 10000);
+</script>

htmlgraph/track_builder.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """
 Track Builder and Collection for agent-friendly track creation.
 
@@ -5,7 +7,6 @@ Note: TrackBuilder has been moved to builders/track.py for better organization.
 This module now provides TrackCollection and re-exports TrackBuilder for backward compatibility.
 """
 
-from __future__ import annotations
 
 from collections.abc import Iterator
 from contextlib import contextmanager
@@ -31,6 +32,18 @@ class TrackCollection:
         self.collection_name = "tracks"  # For backward compatibility
         self.id_prefix = "track"
         self._graph: HtmlGraph | None = None  # Lazy-loaded
+        self._ref_manager: Any = None  # Set by SDK during initialization
+
+    def set_ref_manager(self, ref_manager: Any) -> None:
+        """
+        Set the ref manager for this collection.
+
+        Called by SDK during initialization to enable short ref support.
+
+        Args:
+            ref_manager: RefManager instance from SDK
+        """
+        self._ref_manager = ref_manager
 
     def _ensure_graph(self) -> HtmlGraph:
         """Lazy-load the graph for tracks with multi-pattern support."""
@@ -113,6 +126,25 @@ class TrackCollection:
         # Auto-save on exit
         graph.update(node)
 
+    def create(self, title: str) -> TrackBuilder:
+        """
+        Create a new track with fluent interface.
+
+        Args:
+            title: Track title
+
+        Returns:
+            TrackBuilder for method chaining
+
+        Example:
+            track = sdk.tracks.create("Multi-Agent Collaboration") \\
+                .set_priority("high") \\
+                .save()
+        """
+        builder = TrackBuilder(self._sdk)
+        builder._title = title
+        return builder
+
     def builder(self) -> TrackBuilder:
         """
         Create a new track builder with fluent interface.

htmlgraph/track_manager.py

@@ -338,6 +338,44 @@ class TrackManager:
             track_id=track_id,
         )
 
+    def load_track(self, track_id: str) -> Track | None:
+        """
+        Load a track from disk.
+
+        Supports both consolidated (single .html file) and directory-based tracks.
+
+        Args:
+            track_id: Track ID
+
+        Returns:
+            Track instance or None if not found
+        """
+        track_path = self.get_track_path(track_id)
+        if track_path is None:
+            return None
+
+        # For now, return a basic Track instance
+        # TODO: Parse HTML back to Track using justhtml
+        if track_path.is_file():
+            # Consolidated format - single file
+            return Track(
+                id=track_id,
+                title=f"Track {track_id}",
+                description="Loaded from consolidated format",
+            )
+        else:
+            # Directory format - check for spec and plan
+            spec_exists = (track_path / "spec.html").exists()
+            plan_exists = (track_path / "plan.html").exists()
+
+            return Track(
+                id=track_id,
+                title=f"Track {track_id}",
+                description="Loaded from directory format",
+                has_spec=spec_exists,
+                has_plan=plan_exists,
+            )
+
     def list_tracks(self) -> list[str]:
         """
         List all track IDs.

htmlgraph/transcript.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """
 Claude Code Transcript Integration.
 
@@ -21,7 +23,6 @@ References:
     - https://github.com/simonw/claude-code-transcripts
 """
 
-from __future__ import annotations
 
 import json
 from collections.abc import Iterator
@@ -588,14 +589,26 @@ class TranscriptReader:
         Returns:
             List of TranscriptSession objects, newest first
         """
+        from datetime import timezone
+
+        def normalize_dt(dt: datetime | None) -> datetime:
+            """Normalize datetime to UTC for comparison."""
+            if dt is None:
+                return datetime.min.replace(tzinfo=timezone.utc)
+            if dt.tzinfo is None:
+                # Assume naive datetimes are UTC
+                return dt.replace(tzinfo=timezone.utc)
+            return dt.astimezone(timezone.utc)
+
         sessions: list[TranscriptSession] = []
 
         for path in self.list_transcript_files(project_path):
             session = self.read_transcript(path)
 
             # Filter by time
-            if since and session.started_at and session.started_at < since:
-                continue
+            if since and session.started_at:
+                if normalize_dt(session.started_at) < normalize_dt(since):
+                    continue
 
             sessions.append(session)
 
@@ -604,8 +617,8 @@ class TranscriptReader:
         if deduplicate and sessions:
             sessions = self._deduplicate_context_snapshots(sessions)
 
-        # Sort by start time, newest first
-        sessions.sort(key=lambda s: s.started_at or datetime.min, reverse=True)
+        # Sort by start time, newest first (normalize for comparison)
+        sessions.sort(key=lambda s: normalize_dt(s.started_at), reverse=True)
 
         if limit:
             sessions = sessions[:limit]

htmlgraph/validation.py

@@ -0,0 +1,115 @@
+"""
+Rich CLI validation error formatting and utilities.
+
+Provides beautiful error display for Pydantic validation failures.
+"""
+
+from collections.abc import Callable
+from typing import TypeVar
+
+from pydantic import ValidationError
+from rich.console import Console
+
+console = Console()
+
+T = TypeVar("T")
+
+
+def display_validation_error(error: ValidationError) -> None:
+    """
+    Display a Pydantic validation error in Rich format.
+
+    Args:
+        error: ValidationError from Pydantic model validation
+
+    Example:
+        try:
+            input_data = FeatureCreateInput(title="", priority="invalid")
+        except ValidationError as e:
+            display_validation_error(e)
+    """
+    console.print("[red]✗ Validation Error[/red]")
+    console.print()
+
+    for err in error.errors():
+        field = ".".join(str(loc) for loc in err["loc"])
+        msg = err["msg"]
+        error_type = err["type"]
+
+        # Color code by error type for better UX
+        if "at least" in msg.lower() or "at most" in msg.lower():
+            # Length/range constraint violation
+            console.print(f"  [yellow]{field}:[/yellow] {msg}")
+        elif "must be" in msg.lower() or "is not valid" in msg.lower():
+            # Type/value constraint violation
+            console.print(f"  [cyan]{field}:[/cyan] {msg}")
+        elif error_type == "string_pattern":
+            # Pattern validation failed
+            console.print(f"  [magenta]{field}:[/magenta] {msg}")
+        else:
+            # Generic validation error
+            console.print(f"  [red]{field}:[/red] {msg}")
+
+    console.print()
+
+
+def validate_input(
+    validator_class: type[T],
+    **kwargs: object,
+) -> T | None:
+    """
+    Validate input and display rich error messages on failure.
+
+    Args:
+        validator_class: Pydantic model class to validate against
+        **kwargs: Input data to validate
+
+    Returns:
+        Validated model instance, or None if validation failed
+
+    Example:
+        input_data = validate_input(FeatureCreateInput, title="My Feature", priority="high")
+        if input_data is None:
+            sys.exit(1)
+        # Use input_data.title, input_data.priority, etc.
+    """
+    try:
+        return validator_class(**kwargs)
+    except ValidationError as e:
+        display_validation_error(e)
+        return None
+
+
+def wrap_command_validation(func: Callable[..., None]) -> Callable[..., None]:
+    """
+    Decorator to wrap CLI command functions with validation error handling.
+
+    This decorator catches ValidationError and displays it in Rich format,
+    then exits gracefully.
+
+    Args:
+        func: CLI command function
+
+    Returns:
+        Wrapped function with validation error handling
+
+    Example:
+        @wrap_command_validation
+        def cmd_feature_create(args: argparse.Namespace) -> None:
+            input_data = FeatureCreateInput(
+                title=args.title,
+                priority=args.priority
+            )
+            # Rest of command logic
+    """
+
+    def wrapper(*args: object, **kwargs: object) -> None:
+        import sys
+
+        try:
+            return func(*args, **kwargs)
+        except ValidationError as e:
+            display_validation_error(e)
+            sys.exit(1)
+
+    return wrapper

htmlgraph/watch.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """
 File-change watcher for HtmlGraph.
 
@@ -7,7 +9,6 @@ native "PostToolUse" hooks (e.g. editors/agents that write files directly).
 It batches filesystem changes and records them as activity events.
 """
 
-from __future__ import annotations
 
 import os
 import time

htmlgraph/work_type_utils.py

@@ -1,10 +1,11 @@
+from __future__ import annotations
+
 """
 Utility functions for work type inference and classification.
 
 Provides automatic work type detection based on active work items.
 """
 
-from __future__ import annotations
 
 from typing import TYPE_CHECKING