claude-team-mcp 0.1.0__py3-none-any.whl → 0.2.1__py3-none-any.whl

claude_team_mcp/colors.py

@@ -9,7 +9,7 @@ import colorsys
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
-    import iterm2
+    from iterm2.color import Color as ItermColor
 
 
 # Golden ratio conjugate (φ - 1), used for even hue distribution
@@ -24,7 +24,7 @@ def generate_tab_color(
     index: int,
     saturation: float = DEFAULT_SATURATION,
     lightness: float = DEFAULT_LIGHTNESS,
-) -> "iterm2.Color":
+) -> "ItermColor":
     """
     Generate a distinct tab color for a given index.
 
@@ -51,7 +51,7 @@ def generate_tab_color(
         # Colors remain visually distinct even for many sessions
         color10 = generate_tab_color(10)
     """
-    import iterm2
+    from iterm2.color import Color
 
     # Calculate hue using golden ratio distribution
     # Multiply index by golden ratio conjugate and take fractional part
@@ -62,7 +62,7 @@ def generate_tab_color(
     r, g, b = colorsys.hls_to_rgb(hue, lightness, saturation)
 
     # iterm2.Color expects integer RGB values 0-255
-    return iterm2.Color(
+    return Color(
         r=int(r * 255),
         g=int(g * 255),
         b=int(b * 255),

claude_team_mcp/formatting.py

@@ -11,18 +11,18 @@ from typing import Optional
 def format_session_title(
     session_name: str,
     issue_id: Optional[str] = None,
-    task_desc: Optional[str] = None,
+    annotation: Optional[str] = None,
 ) -> str:
     """
     Format a session title for iTerm2 tab display.
 
     Creates a formatted title string combining session name, optional issue ID,
-    and optional task description.
+    and optional annotation.
 
     Args:
         session_name: Session identifier (e.g., "worker-1")
         issue_id: Optional issue/ticket ID (e.g., "cic-3dj")
-        task_desc: Optional task description (e.g., "profile module")
+        annotation: Optional task annotation (e.g., "profile module")
 
     Returns:
         Formatted title string.
@@ -31,7 +31,7 @@ def format_session_title(
         >>> format_session_title("worker-1", "cic-3dj", "profile module")
         '[worker-1] cic-3dj: profile module'
 
-        >>> format_session_title("worker-2", task_desc="refactor auth")
+        >>> format_session_title("worker-2", annotation="refactor auth")
         '[worker-2] refactor auth'
 
         >>> format_session_title("worker-3")
@@ -40,69 +40,66 @@ def format_session_title(
     # Build the title in parts
     title_parts = [f"[{session_name}]"]
 
-    if issue_id and task_desc:
-        # Both issue ID and description: "issue_id: task_desc"
-        title_parts.append(f"{issue_id}: {task_desc}")
+    if issue_id and annotation:
+        # Both issue ID and annotation: "issue_id: annotation"
+        title_parts.append(f"{issue_id}: {annotation}")
     elif issue_id:
         # Only issue ID
         title_parts.append(issue_id)
-    elif task_desc:
-        # Only description
-        title_parts.append(task_desc)
+    elif annotation:
+        # Only annotation
+        title_parts.append(annotation)
 
     return " ".join(title_parts)
 
 
 def format_badge_text(
-    issue_id: Optional[str] = None,
-    task_desc: Optional[str] = None,
-    max_length: int = 25,
+    name: str,
+    bead: Optional[str] = None,
+    annotation: Optional[str] = None,
+    max_annotation_length: int = 30,
 ) -> str:
     """
-    Format abbreviated badge text for iTerm2 badge display.
+    Format badge text with bead/name on first line, annotation on second.
 
-    Creates a compact string suitable for display in an iTerm2 badge,
-    truncating with ellipsis if necessary.
+    Creates a multi-line string suitable for iTerm2 badge display:
+    - Line 1: bead ID if provided, otherwise worker name
+    - Line 2: annotation (if provided), truncated if too long
 
     Args:
-        issue_id: Optional issue/ticket ID (e.g., "cic-3dj")
-        task_desc: Optional task description (e.g., "profile module")
-        max_length: Maximum length of the output string (default 25)
+        name: Worker name (used if bead not provided)
+        bead: Optional bead/issue ID (e.g., "cic-3dj")
+        annotation: Optional task annotation
+        max_annotation_length: Maximum length for annotation line (default 30)
 
     Returns:
-        Abbreviated badge text, truncated with "..." if needed.
+        Badge text, potentially multi-line.
 
     Examples:
-        >>> format_badge_text("cic-3dj", "profile module", max_length=25)
-        'cic-3dj: profile module'
+        >>> format_badge_text("Groucho", "cic-3dj", "profile module")
+        'cic-3dj\\nprofile module'
 
-        >>> format_badge_text("cic-3dj", "implement user authentication system", max_length=25)
-        'cic-3dj: implement us...'
+        >>> format_badge_text("Groucho", annotation="quick task")
+        'Groucho\\nquick task'
 
-        >>> format_badge_text(task_desc="quick fix", max_length=25)
-        'quick fix'
+        >>> format_badge_text("Groucho", "cic-3dj")
+        'cic-3dj'
 
-        >>> format_badge_text()
-        ''
-    """
-    if max_length < 4:
-        # Too short to meaningfully truncate
-        max_length = 4
+        >>> format_badge_text("Groucho")
+        'Groucho'
 
-    # Build the full text
-    if issue_id and task_desc:
-        full_text = f"{issue_id}: {task_desc}"
-    elif issue_id:
-        full_text = issue_id
-    elif task_desc:
-        full_text = task_desc
-    else:
-        return ""
-
-    # Truncate if necessary
-    if len(full_text) <= max_length:
-        return full_text
-
-    # Reserve 3 characters for ellipsis
-    truncated = full_text[: max_length - 3].rstrip()
-    return f"{truncated}..."
+        >>> format_badge_text("Groucho", annotation="a very long annotation here", max_annotation_length=20)
+        'Groucho\\na very long annot...'
+    """
+    # First line: bead if provided, otherwise name
+    first_line = bead if bead else name
+
+    # Second line: annotation if provided, with truncation
+    if annotation:
+        if len(annotation) > max_annotation_length:
+            # Reserve 3 chars for ellipsis
+            truncated = annotation[: max_annotation_length - 3].rstrip()
+            annotation = f"{truncated}..."
+        return f"{first_line}\n{annotation}"
+
+    return first_line

claude_team_mcp/idle_detection.py

@@ -0,0 +1,208 @@
+"""
+Idle Detection for Claude Team Workers
+
+Detects when workers are idle (finished responding) using Stop hook signals.
+Workers are spawned with a Stop hook that fires when Claude finishes responding.
+The hook embeds a session ID marker in the JSONL - if it fired with no subsequent
+messages, the worker is idle.
+
+Binary state model:
+- Idle: Stop hook fired, no messages after it
+- Working: Either no stop hook yet, or messages exist after the last one
+"""
+
+import asyncio
+import logging
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+from .session_state import is_session_stopped
+
+logger = logging.getLogger("claude-team-mcp")
+
+# Default timeout for waiting operations (10 minutes)
+DEFAULT_TIMEOUT = 600.0
+DEFAULT_POLL_INTERVAL = 2.0
+
+
+def is_idle(jsonl_path: Path, session_id: str) -> bool:
+    """
+    Check if a session is idle (finished responding).
+
+    A session is idle if its Stop hook has fired and no messages
+    have been sent after it.
+
+    Args:
+        jsonl_path: Path to the session JSONL file
+        session_id: The session ID (matches marker in Stop hook)
+
+    Returns:
+        True if idle, False if working or file not found
+    """
+    if not jsonl_path.exists():
+        return False
+    return is_session_stopped(jsonl_path, session_id)
+
+
+async def wait_for_idle(
+    jsonl_path: Path,
+    session_id: str,
+    timeout: float = DEFAULT_TIMEOUT,
+    poll_interval: float = DEFAULT_POLL_INTERVAL,
+) -> dict:
+    """
+    Wait for a session to become idle.
+
+    Polls until the Stop hook fires or timeout is reached.
+
+    Args:
+        jsonl_path: Path to session JSONL file
+        session_id: The session ID to check
+        timeout: Maximum seconds to wait (default 600s / 10 min)
+        poll_interval: Seconds between checks
+
+    Returns:
+        Dict with {idle: bool, session_id: str, waited_seconds: float, timed_out: bool}
+    """
+    start = time.time()
+
+    while time.time() - start < timeout:
+        if is_idle(jsonl_path, session_id):
+            return {
+                "idle": True,
+                "session_id": session_id,
+                "waited_seconds": time.time() - start,
+                "timed_out": False,
+            }
+        await asyncio.sleep(poll_interval)
+
+    # Timeout
+    return {
+        "idle": False,
+        "session_id": session_id,
+        "waited_seconds": timeout,
+        "timed_out": True,
+    }
+
+
+@dataclass
+class SessionInfo:
+    """Info needed to check a session's idle state."""
+
+    jsonl_path: Path
+    session_id: str
+
+
+async def wait_for_any_idle(
+    sessions: list[SessionInfo],
+    timeout: float = DEFAULT_TIMEOUT,
+    poll_interval: float = DEFAULT_POLL_INTERVAL,
+) -> dict:
+    """
+    Wait for ANY session to become idle.
+
+    Returns as soon as the first session becomes idle.
+    Useful for pipeline patterns where you want to process results
+    as they become available.
+
+    Args:
+        sessions: List of SessionInfo to monitor
+        timeout: Maximum seconds to wait
+        poll_interval: Seconds between checks
+
+    Returns:
+        Dict with {
+            idle_session_id: str | None,  # First session to become idle
+            idle: bool,                    # True if any session became idle
+            waited_seconds: float,
+            timed_out: bool,
+        }
+    """
+    start = time.time()
+
+    while time.time() - start < timeout:
+        for session in sessions:
+            if is_idle(session.jsonl_path, session.session_id):
+                return {
+                    "idle_session_id": session.session_id,
+                    "idle": True,
+                    "waited_seconds": time.time() - start,
+                    "timed_out": False,
+                }
+        await asyncio.sleep(poll_interval)
+
+    return {
+        "idle_session_id": None,
+        "idle": False,
+        "waited_seconds": timeout,
+        "timed_out": True,
+    }
+
+
+async def wait_for_all_idle(
+    sessions: list[SessionInfo],
+    timeout: float = DEFAULT_TIMEOUT,
+    poll_interval: float = DEFAULT_POLL_INTERVAL,
+) -> dict:
+    """
+    Wait for ALL sessions to become idle.
+
+    Returns when every session has become idle, or on timeout.
+    Useful for fan-out/fan-in patterns where you need all results
+    before proceeding.
+
+    Args:
+        sessions: List of SessionInfo to monitor
+        timeout: Maximum seconds to wait
+        poll_interval: Seconds between checks
+
+    Returns:
+        Dict with {
+            idle_session_ids: list[str],   # Sessions that are idle
+            all_idle: bool,                 # True if all sessions became idle
+            waiting_on: list[str],          # Sessions still working (if timed out)
+            waited_seconds: float,
+            timed_out: bool,
+        }
+    """
+    start = time.time()
+
+    while time.time() - start < timeout:
+        idle_sessions = []
+        working_sessions = []
+
+        for session in sessions:
+            if is_idle(session.jsonl_path, session.session_id):
+                idle_sessions.append(session.session_id)
+            else:
+                working_sessions.append(session.session_id)
+
+        if not working_sessions:
+            # All idle!
+            return {
+                "idle_session_ids": idle_sessions,
+                "all_idle": True,
+                "waiting_on": [],
+                "waited_seconds": time.time() - start,
+                "timed_out": False,
+            }
+
+        await asyncio.sleep(poll_interval)
+
+    # Timeout - return final state
+    idle_sessions = []
+    working_sessions = []
+    for session in sessions:
+        if is_idle(session.jsonl_path, session.session_id):
+            idle_sessions.append(session.session_id)
+        else:
+            working_sessions.append(session.session_id)
+
+    return {
+        "idle_session_ids": idle_sessions,
+        "all_idle": False,
+        "waiting_on": working_sessions,
+        "waited_seconds": timeout,
+        "timed_out": True,
+    }