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

claude_team_mcp/config.py

@@ -53,10 +53,11 @@ class TerminalConfig:
 
 @dataclass
 class EventsConfig:
-    """Event log rotation configuration."""
+    """Event log rotation and polling configuration."""
 
     max_size_mb: int = 1
     recent_hours: int = 24
+    stale_threshold_minutes: int = 10
 
 
 @dataclass
@@ -230,9 +231,11 @@ def _parse_terminal(value: object) -> TerminalConfig:
 
 
 def _parse_events(value: object) -> EventsConfig:
-    # Parse event log rotation configuration.
+    # Parse event log rotation and polling configuration.
     data = _ensure_dict(value, "events")
-    _validate_keys(data, {"max_size_mb", "recent_hours"}, "events")
+    _validate_keys(
+        data, {"max_size_mb", "recent_hours", "stale_threshold_minutes"}, "events"
+    )
     return EventsConfig(
         max_size_mb=_optional_int(
             data.get("max_size_mb"),
@@ -246,6 +249,12 @@ def _parse_events(value: object) -> EventsConfig:
             EventsConfig.recent_hours,
             min_value=0,
         ),
+        stale_threshold_minutes=_optional_int(
+            data.get("stale_threshold_minutes"),
+            "events.stale_threshold_minutes",
+            EventsConfig.stale_threshold_minutes,
+            min_value=1,
+        ),
     )
 
 

claude_team_mcp/config_cli.py

@@ -132,6 +132,12 @@ def _apply_env_overrides(data: dict, env: Mapping[str, str]) -> None:
         if parsed is not None:
             data["events"]["recent_hours"] = parsed
 
+    stale_threshold_override = env.get("CLAUDE_TEAM_STALE_THRESHOLD_MINUTES")
+    if stale_threshold_override:
+        parsed = _parse_int_override(stale_threshold_override)
+        if parsed is not None:
+            data["events"]["stale_threshold_minutes"] = parsed
+
 
 def _parse_int_override(raw_value: str) -> int | None:
     # Parse env overrides as integers; invalid values are ignored.
@@ -253,6 +259,7 @@ _FIELD_PARSERS: dict[str, Callable[[str, str], object]] = {
     ),
     "events.max_size_mb": _parse_int,
     "events.recent_hours": _parse_int,
+    "events.stale_threshold_minutes": _parse_int,
     "issue_tracker.override": lambda value, field: _parse_optional_literal(
         value,
         field,

claude_team_mcp/registry.py

@@ -5,12 +5,17 @@ Tracks all spawned Claude Code sessions, maintaining the mapping between
 our session IDs, terminal session handles, and Claude JSONL session IDs.
 """
 
+from __future__ import annotations
+
 import uuid
 from dataclasses import dataclass, field
-from datetime import datetime
+from datetime import datetime, timezone
 from enum import Enum
 from pathlib import Path
-from typing import Literal, Optional
+from typing import TYPE_CHECKING, Literal, Optional, Union
+
+if TYPE_CHECKING:
+    from claude_team.events import WorkerEvent
 
 from .session_state import (
     find_codex_session_by_internal_id,
@@ -22,6 +27,12 @@ from .terminal_backends import TerminalSession
 # Type alias for supported agent types
 AgentType = Literal["claude", "codex"]
 
+# Type alias for event log states (from WorkerPoller snapshots)
+EventState = Literal["idle", "active", "closed"]
+
+# Type alias for session source provenance
+SessionSource = Literal["registry", "event_log"]
+
 
 @dataclass(frozen=True)
 class TerminalId:
@@ -65,6 +76,128 @@ class SessionStatus(str, Enum):
     BUSY = "busy"  # Claude is processing/responding
 
 
+@dataclass(frozen=True)
+class RecoveryReport:
+    """
+    Report from SessionRegistry.recover_from_events().
+
+    Provides counts of how sessions were handled during event log recovery.
+
+    Attributes:
+        added: Number of sessions added from event log
+        skipped: Number of sessions skipped (already in registry)
+        closed: Number of sessions marked as closed
+        timestamp: When recovery occurred
+    """
+
+    added: int
+    skipped: int
+    closed: int
+    timestamp: datetime
+
+
+@dataclass(frozen=True)
+class RecoveredSession:
+    """
+    Represents a session recovered from the event log.
+
+    This is a lightweight, read-only representation of a worker session
+    that was restored from persisted event snapshots. Unlike ManagedSession,
+    it has no terminal handle and cannot be controlled directly.
+
+    Used by SessionRegistry.recover_from_events() to populate the registry
+    with historical session data after MCP server restart.
+
+    Attributes:
+        session_id: Internal session ID (e.g., "a3f2b1c9")
+        name: Worker's friendly name (e.g., "Groucho")
+        project_path: Directory where the worker was running
+        terminal_id: Terminal identifier from snapshot (may be stale)
+        agent_type: "claude" or "codex"
+        status: Mapped SessionStatus (READY for idle, BUSY for active/closed)
+        last_activity: Last activity timestamp from snapshot
+        created_at: Session creation timestamp from snapshot
+        event_state: Raw state from event log ("idle", "active", or "closed")
+        recovered_at: Timestamp when this session was recovered
+        last_event_ts: Timestamp of the last event applied to this session
+    """
+
+    session_id: str
+    name: str
+    project_path: str
+    terminal_id: Optional[TerminalId]
+    agent_type: AgentType
+    status: SessionStatus
+    last_activity: datetime
+    created_at: datetime
+    event_state: EventState
+    recovered_at: datetime
+    last_event_ts: datetime
+
+    # Optional fields that may be present in snapshots
+    claude_session_id: Optional[str] = None
+    coordinator_annotation: Optional[str] = None
+    worktree_path: Optional[str] = None
+    main_repo_path: Optional[str] = None
+
+    @staticmethod
+    def map_event_state_to_status(event_state: EventState) -> SessionStatus:
+        """
+        Map event log state to SessionStatus.
+
+        Args:
+            event_state: State from event log ("idle", "active", "closed")
+
+        Returns:
+            Corresponding SessionStatus
+        """
+        if event_state == "idle":
+            return SessionStatus.READY
+        # Both "active" and "closed" map to BUSY
+        # (closed sessions were last known to be working)
+        return SessionStatus.BUSY
+
+    def to_dict(self) -> dict:
+        """
+        Convert to dictionary for MCP tool responses.
+
+        Matches ManagedSession.to_dict() output format but adds
+        source, event_state, recovered_at, and last_event_ts fields.
+        """
+        return {
+            # Core fields matching ManagedSession.to_dict()
+            "session_id": self.session_id,
+            "terminal_id": str(self.terminal_id) if self.terminal_id else None,
+            "name": self.name,
+            "project_path": self.project_path,
+            "claude_session_id": self.claude_session_id,
+            "status": self.status.value,
+            "created_at": self.created_at.isoformat(),
+            "last_activity": self.last_activity.isoformat(),
+            "coordinator_annotation": self.coordinator_annotation,
+            "worktree_path": self.worktree_path,
+            "main_repo_path": self.main_repo_path,
+            "agent_type": self.agent_type,
+            # Recovery-specific fields
+            "source": "event_log",
+            "event_state": self.event_state,
+            "recovered_at": self.recovered_at.isoformat(),
+            "last_event_ts": self.last_event_ts.isoformat(),
+        }
+
+    def is_idle(self) -> bool:
+        """
+        Check if this session is idle based on snapshot state.
+
+        Unlike ManagedSession.is_idle(), this does NOT access JSONL files.
+        It relies solely on the event_state from the snapshot.
+
+        Returns:
+            True if event_state is "idle", False otherwise
+        """
+        return self.event_state == "idle"
+
+
 @dataclass
 class ManagedSession:
     """
@@ -103,7 +236,12 @@ class ManagedSession:
             )
 
     def to_dict(self) -> dict:
-        """Convert to dictionary for MCP tool responses."""
+        """
+        Convert to dictionary for MCP tool responses.
+
+        Includes source='registry' to indicate this is a live session
+        (as opposed to source='event_log' for recovered sessions).
+        """
         result = {
             "session_id": self.session_id,
             "terminal_id": str(self.terminal_id) if self.terminal_id else None,
@@ -117,6 +255,8 @@ class ManagedSession:
             "worktree_path": str(self.worktree_path) if self.worktree_path else None,
             "main_repo_path": str(self.main_repo_path) if self.main_repo_path else None,
             "agent_type": self.agent_type,
+            # Source field for distinguishing live vs recovered sessions
+            "source": "registry",
         }
         return result
 
@@ -273,11 +413,15 @@ class SessionRegistry:
 
     Maintains a collection of ManagedSession objects and provides
     methods for adding, retrieving, updating, and removing sessions.
+
+    Also tracks RecoveredSession objects from event log recovery, which
+    represent sessions discovered from persisted events after MCP restart.
     """
 
     def __init__(self):
         """Initialize an empty registry."""
         self._sessions: dict[str, ManagedSession] = {}
+        self._recovered_sessions: dict[str, RecoveredSession] = {}
 
     def _generate_id(self) -> str:
         """Generate a unique session ID as short UUID."""
@@ -372,26 +516,43 @@ class SessionRegistry:
         # 3. Try name (last resort)
         return self.get_by_name(identifier)
 
-    def list_all(self) -> list[ManagedSession]:
+    def list_all(self) -> list[AnySession]:
         """
-        Get all registered sessions.
+        Get all registered and recovered sessions.
+
+        Returns merged list of live ManagedSession objects and RecoveredSession
+        entries from event log recovery. Live sessions take precedence (recovered
+        sessions with matching IDs are excluded).
 
         Returns:
-            List of all ManagedSession objects
+            List of all session objects (ManagedSession and RecoveredSession)
         """
-        return list(self._sessions.values())
+        result: list[AnySession] = list(self._sessions.values())
+        # Add recovered sessions not shadowed by live sessions.
+        for session_id, recovered in self._recovered_sessions.items():
+            if session_id not in self._sessions:
+                result.append(recovered)
+        return result
 
-    def list_by_status(self, status: SessionStatus) -> list[ManagedSession]:
+    def list_by_status(self, status: SessionStatus) -> list[AnySession]:
         """
         Get sessions filtered by status.
 
+        Includes both live ManagedSession and RecoveredSession entries that
+        match the specified status. Live sessions take precedence.
+
         Args:
             status: Status to filter by
 
         Returns:
-            List of matching ManagedSession objects
+            List of matching session objects (ManagedSession and RecoveredSession)
         """
-        return [s for s in self._sessions.values() if s.status == status]
+        result: list[AnySession] = [s for s in self._sessions.values() if s.status == status]
+        # Add recovered sessions not shadowed by live sessions.
+        for session_id, recovered in self._recovered_sessions.items():
+            if session_id not in self._sessions and recovered.status == status:
+                result.append(recovered)
+        return result
 
     def remove(self, session_id: str) -> Optional[ManagedSession]:
         """
@@ -428,6 +589,214 @@ class SessionRegistry:
             return True
         return False
 
+    def recover_from_events(
+        self,
+        snapshot: dict | None,
+        events: list[WorkerEvent],
+    ) -> RecoveryReport:
+        """
+        Recover session state from event log without overwriting live sessions.
+
+        Merges persisted event log state into the registry. Sessions already
+        in the registry are skipped to preserve live state. Sessions only
+        found in the event log are added as RecoveredSession entries.
+
+        Args:
+            snapshot: Output of get_latest_snapshot() (may be None)
+            events: Output of read_events_since(snapshot_ts) (may be empty)
+
+        Returns:
+            RecoveryReport with counts (added, skipped, closed)
+        """
+        now = datetime.now(timezone.utc)
+        added = 0
+        skipped = 0
+        closed = 0
+
+        # Build worker state from snapshot + events.
+        # worker_data[session_id] = dict with worker metadata
+        # worker_state[session_id] = "idle" | "active" | "closed"
+        # worker_last_event_ts[session_id] = datetime
+        worker_data: dict[str, dict] = {}
+        worker_state: dict[str, EventState] = {}
+        worker_last_event_ts: dict[str, datetime] = {}
+
+        # Process snapshot first to establish baseline state.
+        if snapshot is not None:
+            workers = snapshot.get("workers", [])
+            snapshot_ts_str = snapshot.get("ts")
+            snapshot_ts = self._parse_event_timestamp(snapshot_ts_str) if snapshot_ts_str else now
+            for worker in workers:
+                if not isinstance(worker, dict):
+                    continue
+                session_id = self._extract_worker_id(worker)
+                if not session_id:
+                    continue
+                worker_data[session_id] = worker
+                state = worker.get("state", "active")
+                if state in ("idle", "active", "closed"):
+                    worker_state[session_id] = state
+                else:
+                    worker_state[session_id] = "active"
+                worker_last_event_ts[session_id] = snapshot_ts
+
+        # Apply events in order to update state.
+        for event in events:
+            event_ts = self._parse_event_timestamp(event.ts)
+            if event.type == "snapshot":
+                # Process embedded workers in snapshot events.
+                workers = event.data.get("workers", [])
+                for worker in workers:
+                    if not isinstance(worker, dict):
+                        continue
+                    session_id = self._extract_worker_id(worker)
+                    if not session_id:
+                        continue
+                    worker_data[session_id] = worker
+                    state = worker.get("state", "active")
+                    if state in ("idle", "active", "closed"):
+                        worker_state[session_id] = state
+                    else:
+                        worker_state[session_id] = "active"
+                    worker_last_event_ts[session_id] = event_ts
+            elif event.worker_id:
+                # Handle individual worker events.
+                session_id = event.worker_id
+                worker_last_event_ts[session_id] = event_ts
+                # Update state based on event type.
+                if event.type == "worker_started":
+                    worker_state[session_id] = "active"
+                    # Merge event data into worker_data if not already present.
+                    if session_id not in worker_data:
+                        worker_data[session_id] = event.data or {}
+                    else:
+                        worker_data[session_id] = {**worker_data[session_id], **(event.data or {})}
+                elif event.type == "worker_idle":
+                    worker_state[session_id] = "idle"
+                elif event.type == "worker_active":
+                    worker_state[session_id] = "active"
+                elif event.type == "worker_closed":
+                    worker_state[session_id] = "closed"
+
+        # Create RecoveredSession entries for workers not in the live registry.
+        for session_id, data in worker_data.items():
+            # Skip if already in live registry.
+            if session_id in self._sessions:
+                skipped += 1
+                continue
+
+            # Skip if already recovered (idempotent).
+            if session_id in self._recovered_sessions:
+                skipped += 1
+                continue
+
+            # Build RecoveredSession from data.
+            state = worker_state.get(session_id, "active")
+            last_event_ts = worker_last_event_ts.get(session_id, now)
+
+            # Track closed sessions.
+            if state == "closed":
+                closed += 1
+
+            recovered = self._build_recovered_session(
+                session_id=session_id,
+                data=data,
+                event_state=state,
+                recovered_at=now,
+                last_event_ts=last_event_ts,
+            )
+            self._recovered_sessions[session_id] = recovered
+            added += 1
+
+        return RecoveryReport(
+            added=added,
+            skipped=skipped,
+            closed=closed,
+            timestamp=now,
+        )
+
+    def _parse_event_timestamp(self, ts_str: str | None) -> datetime:
+        """Parse ISO timestamp from event log, returning UTC datetime."""
+        if not ts_str:
+            return datetime.now(timezone.utc)
+        # Normalize Zulu timestamps.
+        if ts_str.endswith("Z"):
+            ts_str = ts_str[:-1] + "+00:00"
+        try:
+            parsed = datetime.fromisoformat(ts_str)
+            if parsed.tzinfo is None:
+                return parsed.replace(tzinfo=timezone.utc)
+            return parsed.astimezone(timezone.utc)
+        except ValueError:
+            return datetime.now(timezone.utc)
+
+    def _extract_worker_id(self, worker: dict) -> str | None:
+        """Extract session ID from worker snapshot data."""
+        for key in ("session_id", "worker_id", "id"):
+            value = worker.get(key)
+            if value:
+                return str(value)
+        return None
+
+    def _build_recovered_session(
+        self,
+        session_id: str,
+        data: dict,
+        event_state: EventState,
+        recovered_at: datetime,
+        last_event_ts: datetime,
+    ) -> RecoveredSession:
+        """
+        Build a RecoveredSession from event log data.
+
+        Args:
+            session_id: The worker session ID
+            data: Worker data from snapshot or events
+            event_state: Current state from events ("idle", "active", "closed")
+            recovered_at: When recovery is occurring
+            last_event_ts: Timestamp of last event for this worker
+
+        Returns:
+            RecoveredSession instance
+        """
+        # Extract fields from data with sensible defaults.
+        name = data.get("name") or session_id
+        project_path = data.get("project_path") or data.get("project") or ""
+        agent_type = data.get("agent_type", "claude")
+        if agent_type not in ("claude", "codex"):
+            agent_type = "claude"
+
+        # Parse terminal_id if present.
+        terminal_id = None
+        terminal_id_str = data.get("terminal_id")
+        if terminal_id_str:
+            terminal_id = TerminalId.from_string(str(terminal_id_str))
+
+        # Parse timestamps with fallbacks.
+        created_at = self._parse_event_timestamp(data.get("created_at"))
+        last_activity = self._parse_event_timestamp(data.get("last_activity")) or last_event_ts
+
+        # Map event state to SessionStatus.
+        status = RecoveredSession.map_event_state_to_status(event_state)
+
+        return RecoveredSession(
+            session_id=session_id,
+            name=name,
+            project_path=project_path,
+            terminal_id=terminal_id,
+            agent_type=agent_type,
+            status=status,
+            last_activity=last_activity,
+            created_at=created_at,
+            event_state=event_state,
+            recovered_at=recovered_at,
+            last_event_ts=last_event_ts,
+            claude_session_id=data.get("claude_session_id"),
+            coordinator_annotation=data.get("coordinator_annotation"),
+            worktree_path=data.get("worktree_path"),
+            main_repo_path=data.get("main_repo_path"),
+        )
+
     def count(self) -> int:
         """Return the number of registered sessions."""
         return len(self._sessions)
@@ -441,3 +810,8 @@ class SessionRegistry:
 
     def __contains__(self, session_id: str) -> bool:
         return session_id in self._sessions
+
+
+# Union type for session types returned by registry
+# Defined at module level after both classes for type checking
+AnySession = Union[ManagedSession, RecoveredSession]

claude_team_mcp/server.py

@@ -15,9 +15,10 @@ from dataclasses import dataclass
 from mcp.server.fastmcp import Context, FastMCP
 from mcp.server.session import ServerSession
 
+from claude_team.events import get_latest_snapshot, read_events_since
 from claude_team.poller import WorkerPoller
 
-from .registry import SessionRegistry
+from .registry import RecoveryReport, SessionRegistry
 from .terminal_backends import ItermBackend, TerminalBackend, TmuxBackend, select_backend_id
 from .tools import register_all_tools
 from .utils import error_response, HINTS
@@ -43,6 +44,7 @@ logger.info("=== Claude Team MCP Server Starting ===")
 
 _global_registry: SessionRegistry | None = None
 _global_poller: WorkerPoller | None = None
+_recovery_attempted: bool = False
 
 
 def get_global_registry() -> SessionRegistry:
@@ -63,6 +65,62 @@ def get_global_poller(registry: SessionRegistry) -> WorkerPoller:
     return _global_poller
 
 
+def recover_registry(registry: SessionRegistry) -> RecoveryReport | None:
+    """
+    Attempt to recover session state from the event log.
+
+    Reads the latest snapshot and subsequent events from ~/.claude-team/events.jsonl,
+    then feeds them into registry.recover_from_events() to seed the registry with
+    historical session data.
+
+    Args:
+        registry: The SessionRegistry to populate
+
+    Returns:
+        RecoveryReport if recovery was performed, None if no events available
+    """
+    global _recovery_attempted
+    _recovery_attempted = True
+
+    # Get the latest snapshot from the event log.
+    snapshot = get_latest_snapshot()
+
+    # Parse snapshot timestamp to filter subsequent events.
+    # The snapshot dict should contain a 'ts' field with the timestamp.
+    since = None
+    if snapshot is not None:
+        ts_str = snapshot.get("ts")
+        if ts_str:
+            from datetime import datetime, timezone
+
+            # Normalize Zulu timestamps.
+            if ts_str.endswith("Z"):
+                ts_str = ts_str[:-1] + "+00:00"
+            try:
+                since = datetime.fromisoformat(ts_str)
+                if since.tzinfo is None:
+                    since = since.replace(tzinfo=timezone.utc)
+            except ValueError:
+                since = None
+
+    # Read events since the snapshot (or all events if no snapshot).
+    events = read_events_since(since=since, limit=10000)
+
+    # If no snapshot and no events, nothing to recover.
+    if snapshot is None and not events:
+        logger.info("No event log data available for recovery")
+        return None
+
+    # Perform recovery.
+    report = registry.recover_from_events(snapshot, events)
+    return report
+
+
+def is_recovery_attempted() -> bool:
+    """Check whether recovery has been attempted this session."""
+    return _recovery_attempted
+
+
 # =============================================================================
 # Application Context
 # =============================================================================
@@ -216,6 +274,22 @@ async def app_lifespan(
         terminal_backend=backend,
         registry=get_global_registry(),
     )
+
+    # Attempt eager recovery from event log to seed the registry with historical
+    # session data. This ensures list_workers returns useful data after restart.
+    if not is_recovery_attempted():
+        logger.info("Attempting eager recovery from event log...")
+        report = recover_registry(ctx.registry)
+        if report is not None:
+            logger.info(
+                "Event log recovery complete: added=%d, skipped=%d, closed=%d",
+                report.added,
+                report.skipped,
+                report.closed,
+            )
+        else:
+            logger.info("No event log data available for recovery")
+
     poller: WorkerPoller | None = None
     if enable_poller:
         poller = get_global_poller(ctx.registry)

claude_team_mcp/tools/__init__.py

@@ -20,6 +20,7 @@ from . import poll_worker_changes
 from . import read_worker_logs
 from . import spawn_workers
 from . import wait_idle_workers
+from . import worker_events
 
 
 def register_all_tools(mcp: FastMCP, ensure_connection) -> None:
@@ -42,6 +43,7 @@ def register_all_tools(mcp: FastMCP, ensure_connection) -> None:
     poll_worker_changes.register_tools(mcp)
     read_worker_logs.register_tools(mcp)
     wait_idle_workers.register_tools(mcp)
+    worker_events.register_tools(mcp)
 
     # Tools that need ensure_connection for terminal backend operations
     adopt_worker.register_tools(mcp, ensure_connection)

claude_team_mcp/tools/adopt_worker.py

@@ -35,7 +35,7 @@ def register_tools(mcp: FastMCP, ensure_connection) -> None:
         iterm_session_id: str | None = None,
         tmux_pane_id: str | None = None,
         session_name: str | None = None,
-        max_age: int = 3600,
+        max_age: int | None = 3600,
     ) -> dict:
         """
         Adopt an existing terminal Claude Code or Codex session into the MCP registry.
@@ -53,6 +53,9 @@ def register_tools(mcp: FastMCP, ensure_connection) -> None:
         Returns:
             Dict with adopted worker info, or error if session not found
         """
+        # 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/close_workers.py

@@ -133,7 +133,7 @@ def register_tools(mcp: FastMCP) -> None:
     async def close_workers(
         ctx: Context[ServerSession, "AppContext"],
         session_ids: list[str],
-        force: bool = False,
+        force: bool | None = False,
     ) -> dict:
         """
         Close one or more managed Claude Code sessions.
@@ -163,6 +163,9 @@ def register_tools(mcp: FastMCP) -> None:
                 - success_count: Number of sessions closed successfully
                 - failure_count: Number of sessions that failed to close
         """
+        # Handle None values from MCP clients that send explicit null for omitted params
+        force = force if force is not None else False
+
         app_ctx = ctx.request_context.lifespan_context
         registry = app_ctx.registry
         backend = app_ctx.terminal_backend