claude-team-mcp 0.6.1__py3-none-any.whl → 0.7.0__py3-none-any.whl

claude_team_mcp/session_state.py

@@ -15,6 +15,8 @@ from typing import Any, Optional
 
 # Claude projects directory
 CLAUDE_PROJECTS_DIR = Path.home() / ".claude" / "projects"
+# Codex sessions directory
+CODEX_SESSIONS_DIR = Path.home() / ".codex" / "sessions"
 
 
 def parse_timestamp(entry: dict) -> datetime:
@@ -207,10 +209,22 @@ MARKER_SUFFIX = "!>"
 ITERM_MARKER_PREFIX = "<!claude-team-iterm:"
 ITERM_MARKER_SUFFIX = "!>"
 
+# Tmux-specific marker for session discovery/recovery
+# Tmux pane ids can change across restarts, so we log the pane id in JSONL
+# to recover sessions that were started by claude-team.
+TMUX_MARKER_PREFIX = "<!claude-team-tmux:"
+TMUX_MARKER_SUFFIX = "!>"
+
+# Project path marker for Codex session recovery
+PROJECT_MARKER_PREFIX = "<!claude-team-project:"
+PROJECT_MARKER_SUFFIX = "!>"
+
 
 def generate_marker_message(
     session_id: str,
     iterm_session_id: Optional[str] = None,
+    tmux_pane_ids: Optional[list[str]] = None,
+    project_path: Optional[str] = None,
 ) -> str:
     """
     Generate a marker message to send to a session for JSONL correlation.
@@ -222,15 +236,33 @@ def generate_marker_message(
         session_id: The managed session ID (e.g., "worker-1")
         iterm_session_id: Optional iTerm2 session ID for discovery/recovery.
             When provided, an additional iTerm-specific marker is emitted.
+        tmux_pane_ids: Optional tmux pane IDs for discovery/recovery.
+            When provided, tmux-specific markers are emitted for each pane.
+        project_path: Optional project path for Codex session recovery.
+            When provided, a project marker is emitted.
 
     Returns:
         A message string to send to the session
     """
-    marker = f"{MARKER_PREFIX}{session_id}{MARKER_SUFFIX}"
+    marker_lines = [f"{MARKER_PREFIX}{session_id}{MARKER_SUFFIX}"]
 
     # Add iTerm-specific marker if provided (for session recovery after MCP restart)
     if iterm_session_id:
-        marker += f"\n{ITERM_MARKER_PREFIX}{iterm_session_id}{ITERM_MARKER_SUFFIX}"
+        marker_lines.append(
+            f"{ITERM_MARKER_PREFIX}{iterm_session_id}{ITERM_MARKER_SUFFIX}"
+        )
+
+    if tmux_pane_ids:
+        for pane_id in tmux_pane_ids:
+            marker_lines.append(f"{TMUX_MARKER_PREFIX}{pane_id}{TMUX_MARKER_SUFFIX}")
+
+    # Add project path marker if provided (used for Codex recovery)
+    if project_path:
+        marker_lines.append(
+            f"{PROJECT_MARKER_PREFIX}{project_path}{PROJECT_MARKER_SUFFIX}"
+        )
+
+    marker = "\n".join(marker_lines)
 
     return (
         f"{marker}\n\n"
@@ -280,6 +312,46 @@ def extract_iterm_session_id(text: str) -> Optional[str]:
     return text[start:end]
 
 
+def extract_project_path(text: str) -> Optional[str]:
+    """
+    Extract a project path from marker text if present.
+
+    Args:
+        text: Text that may contain a project path marker
+
+    Returns:
+        The project path from the marker, or None if no marker found
+    """
+    start = text.find(PROJECT_MARKER_PREFIX)
+    if start == -1:
+        return None
+    start += len(PROJECT_MARKER_PREFIX)
+    end = text.find(PROJECT_MARKER_SUFFIX, start)
+    if end == -1:
+        return None
+    return text[start:end]
+
+
+def extract_tmux_pane_id(text: str) -> Optional[str]:
+    """
+    Extract a tmux pane ID from marker text if present.
+
+    Args:
+        text: Text that may contain a tmux marker
+
+    Returns:
+        The tmux pane ID from the marker, or None if no marker found
+    """
+    start = text.find(TMUX_MARKER_PREFIX)
+    if start == -1:
+        return None
+    start += len(TMUX_MARKER_PREFIX)
+    end = text.find(TMUX_MARKER_SUFFIX, start)
+    if end == -1:
+        return None
+    return text[start:end]
+
+
 def find_jsonl_by_marker(
     project_path: str,
     session_id: str,
@@ -344,6 +416,199 @@ class ItermSessionMatch:
     project_path: str  # Recovered from directory slug
 
 
+@dataclass
+class TmuxSessionMatch:
+    """Result of matching a tmux pane ID to a JSONL file."""
+
+    tmux_pane_id: str
+    internal_session_id: str  # Our claude-team session ID
+    jsonl_path: Path
+    project_path: str  # Recovered from directory slug
+
+
+@dataclass
+class CodexSessionMatch:
+    """Result of matching a Codex session marker to a JSONL file."""
+
+    iterm_session_id: Optional[str]
+    internal_session_id: str
+    jsonl_path: Path
+    project_path: str
+
+
+# Helper to iterate recent Codex session files for marker scans.
+def _iter_recent_codex_session_files(max_age_seconds: int) -> list[Path]:
+    now = time.time()
+    cutoff = now - max_age_seconds
+    recent_dirs: list[Path] = []
+
+    # Walk newest date directories first (limit to a few days to avoid scanning too much).
+    if not CODEX_SESSIONS_DIR.exists():
+        return []
+
+    # Build a short list of recent day directories (YYYY/MM/DD) to scan.
+    for year_dir in sorted(CODEX_SESSIONS_DIR.iterdir(), reverse=True):
+        if not year_dir.is_dir():
+            continue
+        for month_dir in sorted(year_dir.iterdir(), reverse=True):
+            if not month_dir.is_dir():
+                continue
+            for day_dir in sorted(month_dir.iterdir(), reverse=True):
+                if not day_dir.is_dir():
+                    continue
+                recent_dirs.append(day_dir)
+                if len(recent_dirs) >= 3:
+                    break
+            if len(recent_dirs) >= 3:
+                break
+        if len(recent_dirs) >= 3:
+            break
+
+    candidates: list[Path] = []
+
+    # Collect JSONL files in the recent directories, filtering by age.
+    for day_dir in recent_dirs:
+        for jsonl_file in day_dir.glob("rollout-*.jsonl"):
+            try:
+                mtime = jsonl_file.stat().st_mtime
+            except OSError:
+                continue
+            if mtime < cutoff:
+                continue
+            candidates.append(jsonl_file)
+
+    return candidates
+
+
+# Helper to scan a Codex JSONL file for our markers.
+def _scan_codex_markers(
+    jsonl_path: Path,
+    *,
+    iterm_session_id: Optional[str] = None,
+    internal_session_id: Optional[str] = None,
+    tmux_pane_id: Optional[str] = None,
+) -> Optional[CodexSessionMatch]:
+    try:
+        with open(jsonl_path, "r") as fp:
+            # Scan line-by-line so we can short-circuit as soon as markers are found.
+            for line in fp:
+                if (
+                    MARKER_PREFIX not in line
+                    and ITERM_MARKER_PREFIX not in line
+                    and TMUX_MARKER_PREFIX not in line
+                    and PROJECT_MARKER_PREFIX not in line
+                ):
+                    continue
+
+                # Extract markers directly from the JSON line string (no full JSON parse).
+                found_internal = extract_marker_session_id(line)
+                found_iterm = extract_iterm_session_id(line)
+                found_tmux = extract_tmux_pane_id(line)
+                found_project = extract_project_path(line)
+
+                # Enforce target filters if provided.
+                if internal_session_id and found_internal != internal_session_id:
+                    continue
+                if iterm_session_id and found_iterm != iterm_session_id:
+                    continue
+                if tmux_pane_id and found_tmux != tmux_pane_id:
+                    continue
+
+                # Require both internal ID and project path for a valid match.
+                if found_internal and found_project:
+                    return CodexSessionMatch(
+                        iterm_session_id=found_iterm,
+                        internal_session_id=found_internal,
+                        jsonl_path=jsonl_path,
+                        project_path=found_project,
+                    )
+    except OSError:
+        return None
+
+    return None
+
+
+def find_codex_session_by_iterm_id(
+    iterm_session_id: str,
+    max_age_seconds: int = 3600,
+) -> Optional[CodexSessionMatch]:
+    """
+    Find a Codex session file containing a specific iTerm session marker.
+
+    Scans recent Codex session files for our markers and returns the
+    first match that includes the iTerm session ID.
+
+    Args:
+        iterm_session_id: The iTerm2 session ID to search for
+        max_age_seconds: Only check files modified within this many seconds
+
+    Returns:
+        CodexSessionMatch with recovery info, or None if not found
+    """
+    for jsonl_path in _iter_recent_codex_session_files(max_age_seconds):
+        match = _scan_codex_markers(
+            jsonl_path,
+            iterm_session_id=iterm_session_id,
+        )
+        if match:
+            return match
+    return None
+
+
+def find_codex_session_by_tmux_id(
+    tmux_pane_id: str,
+    max_age_seconds: int = 3600,
+) -> Optional[CodexSessionMatch]:
+    """
+    Find a Codex session file containing a specific tmux pane marker.
+
+    Scans recent Codex session files for our markers and returns the
+    first match that includes the tmux pane ID.
+
+    Args:
+        tmux_pane_id: The tmux pane ID to search for
+        max_age_seconds: Only check files modified within this many seconds
+
+    Returns:
+        CodexSessionMatch with recovery info, or None if not found
+    """
+    for jsonl_path in _iter_recent_codex_session_files(max_age_seconds):
+        match = _scan_codex_markers(
+            jsonl_path,
+            tmux_pane_id=tmux_pane_id,
+        )
+        if match:
+            return match
+    return None
+
+
+def find_codex_session_by_internal_id(
+    session_id: str,
+    max_age_seconds: int = 3600,
+) -> Optional[CodexSessionMatch]:
+    """
+    Find a Codex session file containing a specific internal session marker.
+
+    Scans recent Codex session files for our internal session marker and
+    returns the first matching file.
+
+    Args:
+        session_id: The internal session ID to search for
+        max_age_seconds: Only check files modified within this many seconds
+
+    Returns:
+        CodexSessionMatch with recovery info, or None if not found
+    """
+    for jsonl_path in _iter_recent_codex_session_files(max_age_seconds):
+        match = _scan_codex_markers(
+            jsonl_path,
+            internal_session_id=session_id,
+        )
+        if match:
+            return match
+    return None
+
+
 def find_jsonl_by_iterm_id(
     iterm_session_id: str,
     max_age_seconds: int = 3600,
@@ -441,6 +706,103 @@ def find_jsonl_by_iterm_id(
     return None
 
 
+def find_jsonl_by_tmux_id(
+    tmux_pane_id: str,
+    max_age_seconds: int = 3600,
+) -> Optional[TmuxSessionMatch]:
+    """
+    Find a JSONL file containing a specific tmux pane marker.
+
+    Scans all project directories in ~/.claude/projects/ for JSONLs
+    that contain the tmux-specific marker. This enables session recovery
+    after MCP server restart.
+
+    Only looks at root user messages (type="user", parentUuid=null) and
+    extracts markers from the message.content field for reliability.
+
+    Args:
+        tmux_pane_id: The tmux pane ID to search for
+        max_age_seconds: Only check files modified within this many seconds
+
+    Returns:
+        TmuxSessionMatch with full recovery info, or None if not found
+    """
+    tmux_marker = f"{TMUX_MARKER_PREFIX}{tmux_pane_id}{TMUX_MARKER_SUFFIX}"
+    now = time.time()
+
+    # Scan all project directories
+    if not CLAUDE_PROJECTS_DIR.exists():
+        return None
+
+    for project_dir in CLAUDE_PROJECTS_DIR.iterdir():
+        if not project_dir.is_dir():
+            continue
+
+        # Check JSONL files in this project
+        for f in project_dir.glob("*.jsonl"):
+            # Skip agent files
+            if f.name.startswith("agent-"):
+                continue
+
+            # Skip old files
+            try:
+                if now - f.stat().st_mtime > max_age_seconds:
+                    continue
+            except OSError:
+                continue
+
+            # Parse JSONL looking for root user message with our markers
+            try:
+                with open(f, "r") as fp:
+                    for line in fp:
+                        line = line.strip()
+                        if not line:
+                            continue
+
+                        try:
+                            entry = json.loads(line)
+                        except json.JSONDecodeError:
+                            continue
+
+                        # Only look at root user messages (our marker message)
+                        if entry.get("type") != "user":
+                            continue
+                        if entry.get("parentUuid") is not None:
+                            continue
+
+                        # Extract message content
+                        message = entry.get("message", {})
+                        content = message.get("content", "")
+                        if not isinstance(content, str):
+                            continue
+
+                        # Check for tmux marker in message content
+                        if tmux_marker not in content:
+                            continue
+
+                        # Extract internal session ID from the same content
+                        internal_id = extract_marker_session_id(content)
+                        if not internal_id:
+                            continue
+
+                        # Recover project path from directory slug
+                        project_path = unslugify_path(project_dir.name)
+                        if not project_path:
+                            continue
+
+                        return TmuxSessionMatch(
+                            tmux_pane_id=tmux_pane_id,
+                            internal_session_id=internal_id,
+                            jsonl_path=f,
+                            project_path=project_path,
+                        )
+
+            except Exception:
+                continue
+
+    return None
+
+
 async def await_marker_in_jsonl(
     project_path: str,
     session_id: str,

claude_team_mcp/terminal_backends/__init__.py

@@ -0,0 +1,31 @@
+"""Terminal backend implementations and interfaces."""
+
+from __future__ import annotations
+
+import os
+from typing import Mapping
+
+from .base import TerminalBackend, TerminalSession
+from .iterm import ItermBackend, MAX_PANES_PER_TAB
+from .tmux import TmuxBackend
+
+
+def select_backend_id(env: Mapping[str, str] | None = None) -> str:
+    """Select a terminal backend id based on environment configuration."""
+    environ = env or os.environ
+    configured = environ.get("CLAUDE_TEAM_TERMINAL_BACKEND")
+    if configured:
+        return configured.strip().lower()
+    if environ.get("TMUX"):
+        return "tmux"
+    return "iterm"
+
+
+__all__ = [
+    "TerminalBackend",
+    "TerminalSession",
+    "ItermBackend",
+    "TmuxBackend",
+    "MAX_PANES_PER_TAB",
+    "select_backend_id",
+]

claude_team_mcp/terminal_backends/base.py

@@ -0,0 +1,106 @@
+"""
+Terminal backend abstractions for Claude Team MCP.
+
+Defines the backend protocol and a backend-agnostic session handle.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Protocol, runtime_checkable
+
+
+@dataclass(frozen=True)
+class TerminalSession:
+    """
+    Backend-agnostic handle to a terminal session or pane.
+
+    Attributes:
+        backend_id: Identifier for the backend ("iterm", "tmux", etc.)
+        native_id: Backend-native session or pane id
+        handle: Backend-specific handle object (if any)
+        metadata: Optional backend-specific metadata
+    """
+
+    backend_id: str
+    native_id: str
+    handle: Any
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@runtime_checkable
+class TerminalBackend(Protocol):
+    """
+    Protocol for terminal backend implementations.
+
+    Backends should provide thin adapters over their native APIs so
+    claude-team can manage sessions without hard-coding terminals.
+    """
+
+    @property
+    def backend_id(self) -> str:
+        """Return a stable backend identifier ("iterm", "tmux", etc.)."""
+        ...
+
+    def wrap_session(self, handle: Any) -> TerminalSession:
+        """Wrap a backend-native handle in a TerminalSession."""
+        ...
+
+    def unwrap_session(self, session: TerminalSession) -> Any:
+        """Extract the backend-native handle from a TerminalSession."""
+        ...
+
+    async def create_session(
+        self,
+        name: str | None = None,
+        *,
+        project_path: str | None = None,
+        issue_id: str | None = None,
+        coordinator_annotation: str | None = None,
+        profile: str | None = None,
+        profile_customizations: Any | None = None,
+    ) -> TerminalSession:
+        """Create a new terminal session/pane and return it."""
+        ...
+
+    async def send_text(self, session: TerminalSession, text: str) -> None:
+        """Send raw text to the terminal session."""
+        ...
+
+    async def send_key(self, session: TerminalSession, key: str) -> None:
+        """Send a special key (enter, ctrl-c, etc.) to the session."""
+        ...
+
+    async def read_screen_text(self, session: TerminalSession) -> str:
+        """Read visible screen content as text."""
+        ...
+
+    async def split_pane(
+        self,
+        session: TerminalSession,
+        *,
+        vertical: bool = True,
+        before: bool = False,
+        profile: str | None = None,
+        profile_customizations: Any | None = None,
+    ) -> TerminalSession:
+        """Split a session pane and return the new pane."""
+        ...
+
+    async def close_session(self, session: TerminalSession, force: bool = False) -> None:
+        """Close the session/pane, optionally forcing termination."""
+        ...
+
+    async def create_multi_pane_layout(
+        self,
+        layout: str,
+        *,
+        profile: str | None = None,
+        profile_customizations: dict[str, Any] | None = None,
+    ) -> dict[str, TerminalSession]:
+        """Create a new multi-pane layout and return pane mapping."""
+        ...
+
+    async def list_sessions(self) -> list[TerminalSession]:
+        """List all sessions known to the backend."""
+        ...