claude-team-mcp 0.8.2__py3-none-any.whl → 0.9.1__py3-none-any.whl

claude_team_mcp/tools/discover_workers.py

@@ -33,7 +33,7 @@ def register_tools(mcp: FastMCP, ensure_connection) -> None:
     @mcp.tool()
     async def discover_workers(
         ctx: Context[ServerSession, "AppContext"],
-        max_age: int = 3600,
+        max_age: int | None = 3600,
     ) -> dict:
         """
         Discover existing Claude Code and Codex sessions running in the active terminal backend.
@@ -69,6 +69,9 @@ def register_tools(mcp: FastMCP, ensure_connection) -> None:
                 - count: Total number of sessions found
                 - unmanaged_count: Number not yet in registry (available to adopt)
         """
+        # Handle None values from MCP clients that send explicit null for omitted params
+        max_age = max_age if max_age is not None else 3600
+
         app_ctx = ctx.request_context.lifespan_context
         registry = app_ctx.registry
 

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/list_worktrees.py

@@ -31,7 +31,7 @@ def register_tools(mcp: FastMCP) -> None:
     async def list_worktrees(
         ctx: Context[ServerSession, "AppContext"],
         repo_path: str,
-        remove_orphans: bool = False,
+        remove_orphans: bool | None = False,
     ) -> dict:
         """
         List worktrees in a repository's .worktrees/ directory.
@@ -58,6 +58,9 @@ def register_tools(mcp: FastMCP) -> None:
                 - orphan_count: Number of orphaned worktrees
                 - removed_count: Number of orphans removed (when remove_orphans=True)
         """
+        # Handle None values from MCP clients that send explicit null for omitted params
+        remove_orphans = remove_orphans if remove_orphans is not None else False
+
         resolved_path = Path(repo_path).resolve()
         if not resolved_path.exists():
             return error_response(

claude_team_mcp/tools/message_workers.py

@@ -131,8 +131,8 @@ def register_tools(mcp: FastMCP) -> None:
         ctx: Context[ServerSession, "AppContext"],
         session_ids: list[str],
         message: str,
-        wait_mode: str = "none",
-        timeout: float = 600.0,
+        wait_mode: str | None = "none",
+        timeout: float | None = 600.0,
     ) -> dict:
         """
         Send a message to one or more Claude Code worker sessions.
@@ -163,6 +163,10 @@ def register_tools(mcp: FastMCP) -> None:
                 - all_idle: Whether all sessions are idle (only if wait_mode != "none")
                 - timed_out: Whether the wait timed out (only if wait_mode != "none")
         """
+        # Handle None values from MCP clients that send explicit null for omitted params
+        wait_mode = wait_mode or "none"
+        timeout = timeout if timeout is not None else 600.0
+
         app_ctx = ctx.request_context.lifespan_context
         registry = app_ctx.registry
         backend = app_ctx.terminal_backend

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,8 +121,8 @@ def register_tools(mcp: FastMCP) -> None:
     async def poll_worker_changes(
         ctx: Context[ServerSession, "AppContext"],
         since: str | None = None,
-        stale_threshold_minutes: int = 20,
-        include_snapshots: bool = False,
+        stale_threshold_minutes: int | None = None,
+        include_snapshots: bool | None = False,
     ) -> dict:
         """
         Poll worker event changes since a timestamp.
@@ -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:
@@ -142,9 +144,17 @@ def register_tools(mcp: FastMCP) -> None:
                 - idle_count: Count of idle workers
                 - poll_ts: Timestamp when poll was generated
         """
+        # Handle None values from MCP clients that send explicit null for omitted params
+        include_snapshots = include_snapshots if include_snapshots is not None else False
+
         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/read_worker_logs.py

@@ -22,8 +22,8 @@ def register_tools(mcp: FastMCP) -> None:
     async def read_worker_logs(
         ctx: Context[ServerSession, "AppContext"],
         session_id: str,
-        pages: int = 1,
-        offset: int = 0,
+        pages: int | None = 1,
+        offset: int | None = 0,
     ) -> dict:
         """
         Get conversation history from a Claude Code session with reverse pagination.
@@ -51,6 +51,10 @@ def register_tools(mcp: FastMCP) -> None:
                 - page_info: Pagination metadata (total_messages, total_pages, etc.)
                 - session_id: The session ID
         """
+        # Handle None values from MCP clients that send explicit null for omitted params
+        pages = pages if pages is not None else 1
+        offset = offset if offset is not None else 0
+
         app_ctx = ctx.request_context.lifespan_context
         registry = app_ctx.registry
 

claude_team_mcp/tools/wait_idle_workers.py

@@ -28,9 +28,9 @@ def register_tools(mcp: FastMCP) -> None:
     async def wait_idle_workers(
         ctx: Context[ServerSession, "AppContext"],
         session_ids: list[str],
-        mode: str = "all",
-        timeout: float = 600.0,
-        poll_interval: float = 2.0,
+        mode: str | None = "all",
+        timeout: float | None = 600.0,
+        poll_interval: float | None = 2.0,
     ) -> dict:
         """
         Wait for worker sessions to become idle.
@@ -56,6 +56,11 @@ def register_tools(mcp: FastMCP) -> None:
                 - waited_seconds: How long we waited
                 - timed_out: Whether we hit the timeout
         """
+        # Handle None values from MCP clients that send explicit null for omitted params
+        mode = mode or "all"
+        timeout = timeout if timeout is not None else 600.0
+        poll_interval = poll_interval if poll_interval is not None else 2.0
+
         app_ctx = ctx.request_context.lifespan_context
         registry = app_ctx.registry
 

claude_team_mcp/tools/worker_events.py

@@ -0,0 +1,279 @@
+"""
+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 | None = 1000,
+        include_snapshot: bool | None = False,
+        include_summary: bool | None = False,
+        stale_threshold_minutes: int | None = 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}
+        """
+        # Handle None values from MCP clients that send explicit null for omitted params
+        limit = limit if limit is not None else 1000
+        include_snapshot = include_snapshot if include_snapshot is not None else False
+        include_summary = include_summary if include_summary is not None else False
+        stale_threshold_minutes = stale_threshold_minutes if stale_threshold_minutes is not None else 10
+
+        # 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