claude-team-mcp 0.8.0__py3-none-any.whl → 0.9.0__py3-none-any.whl

claude_team_mcp/tools/list_workers.py

@@ -4,6 +4,7 @@ List workers tool.
 Provides list_workers for viewing all managed Claude Code sessions.
 """
 
+import logging
 from pathlib import Path
 from typing import TYPE_CHECKING
 
@@ -16,6 +17,8 @@ if TYPE_CHECKING:
 from ..registry import SessionStatus
 from ..utils import error_response
 
+logger = logging.getLogger("claude-team-mcp")
+
 
 def register_tools(mcp: FastMCP) -> None:
     """Register list_workers tool on the MCP server."""
@@ -44,6 +47,22 @@ def register_tools(mcp: FastMCP) -> None:
         app_ctx = ctx.request_context.lifespan_context
         registry = app_ctx.registry
 
+        # Lazy fallback: if registry is empty and recovery hasn't been attempted,
+        # try to recover from the event log. This handles edge cases where startup
+        # recovery may have failed or wasn't triggered.
+        from ..server import is_recovery_attempted, recover_registry
+
+        if not is_recovery_attempted() and len(registry.list_all()) == 0:
+            logger.info("Registry empty on first list_workers call, attempting lazy recovery...")
+            report = recover_registry(registry)
+            if report is not None:
+                logger.info(
+                    "Lazy recovery complete: added=%d, skipped=%d, closed=%d",
+                    report.added,
+                    report.skipped,
+                    report.closed,
+                )
+
         # Get sessions, optionally filtered by status
         if status_filter:
             try:
@@ -84,17 +103,26 @@ def register_tools(mcp: FastMCP) -> None:
                         filtered_sessions.append(session)
                 sessions = filtered_sessions
 
-        # Sort by created_at
-        sessions = sorted(sessions, key=lambda s: s.created_at)
+        # Sort by created_at (normalize to UTC-aware for mixed live/recovered)
+        from datetime import timezone as _tz
+
+        def _sort_key(s):
+            dt = s.created_at
+            if dt.tzinfo is None:
+                dt = dt.replace(tzinfo=_tz.utc)
+            return dt
+
+        sessions = sorted(sessions, key=_sort_key)
 
         # Convert to dicts and add message count + idle status
         workers = []
         for session in sessions:
             info = session.to_dict()
-            # Try to get conversation stats
-            state = session.get_conversation_state()
-            if state:
-                info["message_count"] = state.message_count
+            # Try to get conversation stats (only available on live ManagedSessions)
+            if hasattr(session, "get_conversation_state"):
+                state = session.get_conversation_state()
+                if state:
+                    info["message_count"] = state.message_count
             # Check idle using stop hook detection
             info["is_idle"] = session.is_idle()
             workers.append(info)

claude_team_mcp/tools/poll_worker_changes.py

@@ -18,6 +18,7 @@ from claude_team.events import WorkerEvent
 if TYPE_CHECKING:
     from ..server import AppContext
 
+from ..config import load_config
 from ..utils import error_response
 
 
@@ -120,7 +121,7 @@ def register_tools(mcp: FastMCP) -> None:
     async def poll_worker_changes(
         ctx: Context[ServerSession, "AppContext"],
         since: str | None = None,
-        stale_threshold_minutes: int = 20,
+        stale_threshold_minutes: int | None = None,
         include_snapshots: bool = False,
     ) -> dict:
         """
@@ -132,6 +133,7 @@ def register_tools(mcp: FastMCP) -> None:
         Args:
             since: ISO timestamp to filter events from (inclusive), or None for latest.
             stale_threshold_minutes: Minutes without activity before a worker is marked stuck.
+                Defaults to the value in ~/.claude-team/config.json (events.stale_threshold_minutes).
             include_snapshots: Whether to include snapshot events in the response.
 
         Returns:
@@ -145,6 +147,11 @@ def register_tools(mcp: FastMCP) -> None:
         app_ctx = ctx.request_context.lifespan_context
         registry = app_ctx.registry
 
+        # Resolve stale threshold: tool param overrides config default.
+        if stale_threshold_minutes is None:
+            config = load_config()
+            stale_threshold_minutes = config.events.stale_threshold_minutes
+
         # Validate inputs before reading the log.
         if stale_threshold_minutes <= 0:
             return error_response(

claude_team_mcp/tools/worker_events.py

@@ -0,0 +1,273 @@
+"""
+Worker events tool.
+
+Provides worker_events for querying the event log with optional summary and snapshot.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING
+
+from mcp.server.fastmcp import Context, FastMCP
+from mcp.server.session import ServerSession
+
+from claude_team import events as events_module
+from claude_team.events import WorkerEvent
+
+if TYPE_CHECKING:
+    from ..server import AppContext
+
+
+def _parse_iso_timestamp(value: str) -> datetime | None:
+    """Parse ISO timestamps for query filtering."""
+    value = value.strip()
+    if not value:
+        return None
+    # Normalize Zulu timestamps for fromisoformat.
+    if value.endswith("Z"):
+        value = value[:-1] + "+00:00"
+    try:
+        parsed = datetime.fromisoformat(value)
+    except ValueError:
+        return None
+    # Default to UTC when no timezone is provided.
+    if parsed.tzinfo is None:
+        return parsed.replace(tzinfo=timezone.utc)
+    return parsed.astimezone(timezone.utc)
+
+
+def _serialize_event(event: WorkerEvent) -> dict:
+    """Convert a WorkerEvent into a JSON-serializable payload."""
+    return {
+        "ts": event.ts,
+        "type": event.type,
+        "worker_id": event.worker_id,
+        "data": event.data,
+    }
+
+
+def _event_project(event: WorkerEvent) -> str | None:
+    """Extract a project identifier from event data."""
+    data = event.data or {}
+    for key in ("project", "project_path"):
+        value = data.get(key)
+        if value:
+            return str(value)
+    return None
+
+
+def _filter_by_project(events: list[WorkerEvent], project_filter: str) -> list[WorkerEvent]:
+    """Filter events to only those matching the project filter."""
+    filtered = []
+    for event in events:
+        project = _event_project(event)
+        # Include events with no project (e.g. snapshots) or matching project.
+        if project is None or project_filter in project:
+            filtered.append(event)
+    return filtered
+
+
+def _build_summary(
+    events: list[WorkerEvent],
+    stale_threshold_minutes: int,
+) -> dict:
+    """
+    Build summary from the event window.
+
+    Returns:
+        Dict with started, closed, idle, active, stuck lists and last_event_ts.
+    """
+    # Track worker states from events.
+    started: list[str] = []
+    closed: list[str] = []
+    idle: list[str] = []
+    active: list[str] = []
+
+    # Track last known state and activity time per worker.
+    last_state: dict[str, str] = {}
+    last_activity: dict[str, datetime] = {}
+
+    last_event_ts: str | None = None
+
+    for event in events:
+        # Track latest event timestamp.
+        last_event_ts = event.ts
+
+        worker_id = event.worker_id
+        if not worker_id:
+            # Handle snapshot events for state tracking.
+            if event.type == "snapshot":
+                _process_snapshot_for_summary(
+                    event.data,
+                    event.ts,
+                    last_state,
+                    last_activity,
+                )
+            continue
+
+        # Update activity time.
+        ts = _parse_iso_timestamp(event.ts)
+        if ts:
+            last_activity[worker_id] = ts
+
+        if event.type == "worker_started":
+            started.append(worker_id)
+            last_state[worker_id] = "active"
+        elif event.type == "worker_closed":
+            closed.append(worker_id)
+            last_state[worker_id] = "closed"
+        elif event.type == "worker_idle":
+            idle.append(worker_id)
+            last_state[worker_id] = "idle"
+        elif event.type == "worker_active":
+            active.append(worker_id)
+            last_state[worker_id] = "active"
+
+    # Compute stuck workers: active with last_activity > threshold.
+    stuck: list[str] = []
+    now = datetime.now(timezone.utc)
+    threshold_seconds = stale_threshold_minutes * 60
+
+    for worker_id, state in last_state.items():
+        if state != "active":
+            continue
+        activity_ts = last_activity.get(worker_id)
+        if activity_ts is None:
+            continue
+        elapsed = (now - activity_ts).total_seconds()
+        if elapsed > threshold_seconds:
+            stuck.append(worker_id)
+
+    return {
+        "started": started,
+        "closed": closed,
+        "idle": idle,
+        "active": active,
+        "stuck": stuck,
+        "last_event_ts": last_event_ts,
+    }
+
+
+def _process_snapshot_for_summary(
+    data: dict,
+    event_ts: str,
+    last_state: dict[str, str],
+    last_activity: dict[str, datetime],
+) -> None:
+    """Update state tracking from a snapshot event."""
+    workers = data.get("workers")
+    if not isinstance(workers, list):
+        return
+
+    ts = _parse_iso_timestamp(event_ts)
+
+    for worker in workers:
+        if not isinstance(worker, dict):
+            continue
+
+        # Find worker ID from various possible keys.
+        worker_id = None
+        for key in ("session_id", "worker_id", "id"):
+            value = worker.get(key)
+            if value:
+                worker_id = str(value)
+                break
+
+        if not worker_id:
+            continue
+
+        # Extract state from snapshot.
+        state = worker.get("state")
+        if isinstance(state, str) and state:
+            last_state[worker_id] = state
+            if ts and state == "active":
+                last_activity[worker_id] = ts
+
+
+def register_tools(mcp: FastMCP) -> None:
+    """Register worker_events tool on the MCP server."""
+
+    @mcp.tool()
+    async def worker_events(
+        ctx: Context[ServerSession, "AppContext"],
+        since: str | None = None,
+        limit: int = 1000,
+        include_snapshot: bool = False,
+        include_summary: bool = False,
+        stale_threshold_minutes: int = 10,
+        project_filter: str | None = None,
+    ) -> dict:
+        """
+        Query worker events from the event log.
+
+        Provides access to the persisted worker event log with optional summary
+        aggregation and snapshot inclusion. This is the primary API for external
+        consumers to monitor worker lifecycle events.
+
+        Args:
+            since: ISO 8601 timestamp; returns events at or after this time.
+                If omitted, returns most recent events (bounded by limit).
+            limit: Maximum number of events returned (default 1000).
+            include_snapshot: If true, include the latest snapshot event in response.
+            include_summary: If true, include summary aggregates (started, closed,
+                idle, active, stuck lists).
+            stale_threshold_minutes: Minutes without activity before a worker is
+                marked stuck (only used when include_summary=true, default 10).
+            project_filter: Optional project path substring to filter events.
+
+        Returns:
+            Dict with:
+                - events: List of worker events [{ts, type, worker_id, data}]
+                - count: Number of events returned
+                - summary: (if include_summary) Aggregates from event window:
+                    - started: worker IDs that started
+                    - closed: worker IDs that closed
+                    - idle: worker IDs that became idle
+                    - active: worker IDs that became active
+                    - stuck: active workers with last_activity > stale_threshold
+                    - last_event_ts: newest event timestamp
+                - snapshot: (if include_snapshot) Latest snapshot {ts, data}
+        """
+        # Parse the since timestamp if provided.
+        parsed_since = None
+        if since is not None and since.strip():
+            parsed_since = _parse_iso_timestamp(since)
+            if parsed_since is None:
+                return {
+                    "error": f"Invalid since timestamp: {since}",
+                    "hint": "Use ISO format like 2026-01-27T11:40:00Z",
+                }
+
+        # Read events from the log.
+        events = events_module.read_events_since(parsed_since, limit=limit)
+
+        # Apply project filter if specified.
+        if project_filter:
+            events = _filter_by_project(events, project_filter)
+
+        # Build the response.
+        response: dict = {
+            "events": [_serialize_event(event) for event in events],
+            "count": len(events),
+        }
+
+        # Add summary if requested.
+        if include_summary:
+            response["summary"] = _build_summary(events, stale_threshold_minutes)
+
+        # Add snapshot if requested.
+        if include_snapshot:
+            snapshot_data = events_module.get_latest_snapshot()
+            if snapshot_data is not None:
+                # Find the timestamp from the snapshot data or use a sentinel.
+                snapshot_ts = snapshot_data.get("ts")
+                response["snapshot"] = {
+                    "ts": snapshot_ts,
+                    "data": snapshot_data,
+                }
+            else:
+                response["snapshot"] = None
+
+        return response

claude_team_mcp/worktree.py

@@ -333,7 +333,7 @@ def create_local_worktree(
     if bead_id:
         # Bead-based naming: {bead_id}-{annotation}
         if annotation:
-            dir_name = f"{bead_id}-{slugify(annotation)}"
+            dir_name = f"{bead_id}-{short_slug(annotation)}"
         else:
             dir_name = bead_id
     else:
@@ -341,7 +341,7 @@ def create_local_worktree(
         short_uuid = uuid.uuid4().hex[:8]
         name_slug = slugify(worker_name)
         if annotation:
-            dir_name = f"{name_slug}-{short_uuid}-{slugify(annotation)}"
+            dir_name = f"{name_slug}-{short_uuid}-{short_slug(annotation)}"
         else:
             dir_name = f"{name_slug}-{short_uuid}"