workstreams-cli 0.5.0__py3-none-any.whl

workstreams/multiplexer/__init__.py

@@ -0,0 +1,32 @@
+"""Terminal multiplexer implementations."""
+"""Terminal multiplexer implementations."""
+
+from .base import MultiplexerBase
+from .tmux import TmuxMultiplexer
+from .zellij import ZellijMultiplexer
+from .tmux_compatible import TmuxCompatibleMultiplexer
+
+__all__ = ["MultiplexerBase", "TmuxMultiplexer", "ZellijMultiplexer", "get_multiplexer"]
+
+_TMUX_COMPATIBLE = {
+    "nami": "nami",
+    "lmux": "lmux",
+    "wmux": "wmux",
+    "herdr": "herdr",
+}
+
+def get_multiplexer(name: str, config) -> MultiplexerBase:
+    """Get a multiplexer instance by name."""
+    multiplexers = {
+        "tmux": TmuxMultiplexer,
+        "zellij": ZellijMultiplexer,
+    }
+    if name in _TMUX_COMPATIBLE:
+        binary = _TMUX_COMPATIBLE[name]
+        return TmuxCompatibleMultiplexer(config, binary)
+    cls = multiplexers.get(name)
+    if not cls:
+        raise ValueError(
+            f"Unknown multiplexer: {name}. Supported: {', '.join(multiplexers)} plus tmux-compatible: {', '.join(_TMUX_COMPATIBLE)}"
+        )
+    return cls(config)

workstreams/multiplexer/base.py

@@ -0,0 +1,44 @@
+"""Base multiplexer interface."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List, Optional
+
+
+class MultiplexerBase(ABC):
+    """Base class for terminal multiplexers."""
+
+    #: Multiplexer name (used in logs / status)
+    name = "base"
+
+    def __init__(self, config: Any):
+        self.config = config
+
+    @abstractmethod
+    def start(self, workstreams: List[Dict[str, Any]], command: Optional[str] = None) -> None:
+        """Start workstreams in multiplexer."""
+
+    @abstractmethod
+    def attach(self, session: str) -> None:
+        """Attach to existing session (blocks until user exits)."""
+
+    @abstractmethod
+    def send_command(self, workstream_id: int, command: str) -> bool:
+        """Send a command to the workstream's pane/tab."""
+
+    @abstractmethod
+    def session_name(self) -> str:
+        """Return the session name used by start()."""
+
+    @abstractmethod
+    def pane_target(self, workstream_id: int) -> str:
+        """Return the pane target for a workstream (used for send_command)."""
+
+    def is_available(self) -> bool:
+        """Check if the multiplexer binary exists on PATH."""
+        import shutil
+        return shutil.which(self.binary_name()) is not None
+
+    def binary_name(self) -> str:
+        return self.name

workstreams/multiplexer/tmux.py

@@ -0,0 +1,202 @@
+"""Tmux multiplexer implementation.
+
+Addressing model (verified against tmux 3.4):
+- Each workstream gets its own tmux WINDOW named after the workstream
+  (`new-window -n <name>`). Windows can be targeted by NAME:
+  `<session>:<window-name>`.
+- Each window hosts a persistent `bash -i` so the detached session never
+  dies when its startup command exits.
+- In the "tiled" layout all workstreams live in one window as panes and
+  are targeted by index: `<session>:1.<pane-index>`.
+
+NOTE: `select-pane -T` only sets a *display title* in tmux; it does NOT
+make a pane addressable by that title. Window names (via `new-window -n`
+/ `rename-window`) are the reliable target mechanism.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from typing import Any, Dict, List, Optional
+
+from .base import MultiplexerBase
+
+# Start a persistent interactive shell in every window/pane so detached
+# sessions stay alive after their first command finishes.
+_PERSIST_SHELL = "exec bash -i"
+
+
+class TmuxMultiplexer(MultiplexerBase):
+    """Tmux-based workstream management."""
+
+    name = "tmux"
+
+    def __init__(self, config: Any):
+        super().__init__(config)
+        self.session = f"workstreams-{config.project}"
+
+    # -- helpers -----------------------------------------------------------
+
+    def _tmux(self, *args: str, check: bool = False, capture: bool = True) -> subprocess.CompletedProcess:
+        cmd = ["tmux"] + list(args)
+        if capture:
+            return subprocess.run(cmd, check=check, capture_output=True, text=True)
+        return subprocess.run(cmd, check=check, text=True)
+
+    def _run_quiet(self, *args: str) -> None:
+        """Run a tmux command, swallowing non-zero exits (best-effort layout)."""
+        self._tmux(*args)
+
+    def _ensure_session(self, base_dir: str) -> None:
+        """Create the session if it does not exist yet."""
+        result = self._tmux("has-session", "-t", self.session)
+        if result.returncode != 0:
+            create = self._tmux(
+                "new-session", "-d", "-s", self.session, "-c", base_dir,
+                _PERSIST_SHELL,
+            )
+            if create.returncode != 0:
+                raise RuntimeError(
+                    f"failed to create tmux session '{self.session}': "
+                    f"{(create.stderr or '').strip() or create.stdout.strip()}"
+                )
+        # Warm the server / confirm session is up.
+        self._tmux("list-windows", "-t", self.session)
+
+    def _session_alive(self) -> bool:
+        return self._tmux("has-session", "-t", self.session).returncode == 0
+
+    def _window_target(self, window_name: str) -> str:
+        """Target a window by its name."""
+        return f"{self.session}:{window_name}"
+
+    def session_name(self) -> str:
+        return self.session
+
+    def pane_target(self, workstream_id: int) -> str:
+        """Return the target for a workstream.
+
+        Tab/window layout: target by window NAME -> `<session>:<ws-name>`.
+        Tiled layout: target by pane index -> `<session>:0.<pane-index>`.
+        """
+        ws = self.config.workstream(workstream_id)
+        name = ws.name if ws else f"ws{workstream_id}"
+        if self.config.layout in ("tiled", "grid"):
+            idx = workstream_id - 1
+            return f"{self.session}:0.{idx}"
+        # Window-per-workstream: each workstream is a window named after it.
+        return self._window_target(name)
+
+    # -- required interface --------------------------------------------------
+
+    def start(self, workstreams: List[Dict[str, Any]], command: Optional[str] = None) -> None:
+        base_dir = self.config.base_path
+        self._ensure_session(base_dir)
+
+        layout = self.config.layout
+        if layout in ("tiled", "grid"):
+            self._layout_single_window_panes(workstreams, base_dir)
+        else:
+            self._layout_tab_windows(workstreams, base_dir)
+
+        # Send each command to its window/pane.
+        for i, ws in enumerate(workstreams):
+            target = self._pane_target_for_index(i, layout)
+            ws_command = command or ws.get("command") or ""
+            if ws_command:
+                ws_path = ws.get("path", "")
+                pane_env = ws.get("env") or {}
+                env_prefix = " ".join(f"{k}={v}" for k, v in pane_env.items())
+                cd_part = f"cd {base_dir}/{ws_path} && " if ws_path else ""
+                full = f"{cd_part}{env_prefix} {ws_command}".strip()
+                self._run_quiet("send-keys", "-t", target, full, "Enter")
+
+        print(f"Started {len(workstreams)} workstream(s) in tmux session '{self.session}'")
+        print(f"  Attach: tmux attach -t {self.session}")
+        print(f"  Or:     workstreams attach --multiplexer tmux")
+
+    # -- layouts --------------------------------------------------------------
+
+    def _layout_tab_windows(self, workstreams: List[Dict[str, Any]], base_dir: str) -> None:
+        """One window per workstream - cleanest for coding agents."""
+        first = True
+        for i, ws in enumerate(workstreams):
+            ws_name = ws.get("name", f"ws{ws.get('id', i + 1)}")
+            ws_path = f"{base_dir}/{ws.get('path', '')}"
+            if first:
+                # Reuse the initial window: rename it to the first workstream.
+                # Window indices start at 0. The session was created with a
+                # single initial window at index 0, so target ":0".
+                self._run_quiet("rename-window", "-t", f"{self.session}:0", ws_name)
+                self._run_quiet("send-keys", "-t", f"{self.session}:0", f"cd {ws_path}", "Enter")
+                first = False
+            else:
+                self._run_quiet(
+                    "new-window", "-t", self.session,
+                    "-n", ws_name, "-c", ws_path, _PERSIST_SHELL,
+                )
+
+    def _layout_single_window_panes(self, workstreams: List[Dict[str, Any]], base_dir: str) -> None:
+        """All workstreams in one window as tiled panes."""
+        for i, ws in enumerate(workstreams):
+            ws_name = ws.get("name", f"ws{ws.get('id', i + 1)}")
+            ws_path = f"{base_dir}/{ws.get('path', '')}"
+            if i == 0:
+                # First pane already exists; just cd it.
+                self._run_quiet("send-keys", "-t", f"{self.session}:0.0", f"cd {ws_path}", "Enter")
+                _ = ws_name
+            else:
+                split = "-h" if i % 2 == 1 else "-v"
+                self._run_quiet(
+                    "split-window", "-t", f"{self.session}:0", split,
+                    "-c", ws_path, _PERSIST_SHELL,
+                )
+        self._run_quiet("select-layout", "-t", f"{self.session}:0", "tiled")
+
+    def _pane_target_for_index(self, i: int, layout: str) -> str:
+        """Target the i-th workstream given the layout."""
+        if layout in ("tiled", "grid"):
+            return f"{self.session}:0.{i}"
+        # Window-per-workstream: window NAMES equal the workstream name.
+        # Resolve the name from the config so we always hit the right window.
+        ws = self.config.workstreams[i] if i < len(self.config.workstreams) else None
+        name = ws.name if ws else f"ws{i + 1}"
+        return self._window_target(name)
+
+    # -- lifecycle -------------------------------------------------------------
+
+    def attach(self, session: Optional[str] = None) -> None:
+        target = session or self.session
+        result = self._tmux("attach", "-t", target, capture=False, check=False)
+        # attach blocks until the user detaches.
+        _ = result
+
+    def send_command(self, workstream_id: int, command: str) -> bool:
+        target = self.pane_target(workstream_id)
+        if not self._session_alive():
+            print(
+                f"[workstreams] tmux session '{self.session}' is not running. "
+                "Run `workstreams start` first.",
+                flush=True,
+            )
+            return False
+        result = self._tmux("send-keys", "-t", target, command, "Enter")
+        return result.returncode == 0
+
+    def capture(self, workstream_id: int, lines: int = 20) -> str:
+        """Return the last `lines` of a workstream pane's output."""
+        target = self.pane_target(workstream_id)
+        result = self._tmux("capture-pane", "-t", target, "-p", "-S", f"-{lines}")
+        return result.stdout.strip()
+
+    def is_running(self) -> bool:
+        return self._session_alive()
+
+    def list_windows(self) -> List[str]:
+        result = self._tmux("list-windows", "-t", self.session)
+        if result.returncode != 0:
+            return []
+        return [w for w in result.stdout.strip().split("\n") if w]
+
+    def kill(self) -> None:
+        self._run_quiet("kill-session", "-t", self.session)

workstreams/multiplexer/tmux_compatible.py

@@ -0,0 +1,22 @@
+"""Tmux-compatible multiplexer wrappers (nami, lmux, wmux, herdr)."""
+
+from __future__ import annotations
+from typing import Any
+from .tmux import TmuxMultiplexer
+
+class TmuxCompatibleMultiplexer(TmuxMultiplexer):
+    """Wrapper for tmux-compatible multiplexers that use the same CLI semantics."""
+
+    def __init__(self, config: Any, binary: str):
+        super().__init__(config)
+        self._binary = binary
+
+    def binary_name(self) -> str:
+        return self._binary
+
+    def _tmux(self, *args: str, check: bool = False, capture: bool = True):
+        import subprocess
+        cmd = [self._binary] + list(args)
+        if capture:
+            return subprocess.run(cmd, check=check, capture_output=True, text=True)
+        return subprocess.run(cmd, check=check, text=True)

workstreams/multiplexer/zellij.py

@@ -0,0 +1,109 @@
+"""Zellij multiplexer implementation.
+
+Zellij uses tabs; each workstream gets its own tab. Zellij's scripting
+surface is less mature than tmux's, so we use `zellij action` and
+`zellij run` where available.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from typing import Any, Dict, List, Optional
+
+from .base import MultiplexerBase
+
+
+class ZellijMultiplexer(MultiplexerBase):
+    """Zellij-based workstream management."""
+
+    name = "zellij"
+
+    def __init__(self, config: Any):
+        super().__init__(config)
+        self.session = f"workstreams-{config.project}"
+
+    def _zj(self, *args: str, check: bool = False, capture: bool = True) -> subprocess.CompletedProcess:
+        cmd = ["zellij"] + list(args)
+        if capture:
+            return subprocess.run(cmd, check=check, capture_output=True, text=True)
+        return subprocess.run(cmd, check=check, text=True)
+
+    def session_name(self) -> str:
+        return self.session
+
+    def pane_target(self, workstream_id: int) -> str:
+        ws = self.config.workstream(workstream_id)
+        return ws.name if ws else f"ws{workstream_id}"
+
+    def start(self, workstreams: List[Dict[str, Any]], command: Optional[str] = None) -> None:
+        base_dir = self.config.base_path
+
+        # Create (or attach to) the session in the background
+        result = self._zj(
+            "attach", self.session, "--create",
+            "--", "sleep", "999999",
+            check=False,
+        )
+        _ = result
+
+        for i, ws in enumerate(workstreams):
+            ws_name = ws.get("name", f"ws{ws.get('id', i + 1)}")
+            # Create a tab per workstream
+            self._zj("action", "new-tab", "--name", ws_name, check=False)
+            ws_path = f"{base_dir}/{ws.get('path', '')}"
+            ws_command = command or ws.get("command") or ""
+            if ws_command:
+                pane_env = ws.get("env") or {}
+                env_prefix = " ".join(f"{k}={v}" for k, v in pane_env.items())
+                full = f"cd {ws_path} && {env_prefix} {ws_command}".strip()
+                self._zj("run", "--", "bash", "-lc", full, check=False)
+
+        print(f"Started {len(workstreams)} workstream(s) in zellij session '{self.session}'")
+        print(f"  Attach: zellij attach {self.session}")
+
+    def attach(self, session: Optional[str] = None) -> None:
+        self._zj("attach", session or self.session, check=False, capture=False)
+
+    def send_command(self, workstream_id: int, command: str) -> bool:
+        """Zellij has no simple `send-keys` equivalent; use `zellij run`.
+
+        This runs the command in the *current* tab of the session. For
+        per-tab targeting you'd need the Zellij RPC API; for now we log
+        a notice and run in the foreground tab.
+        """
+        import sys
+        print(
+            f"[workstreams] zellij: send_command targets current tab only; "
+            f"run: {command}",
+            file=sys.stderr,
+        )
+        self._zj("run", "--", "bash", "-lc", command, check=False)
+        return True
+
+    def capture(self, lines: int = 20) -> List[str]:
+        """Read the last N lines from the workstream's log file.
+
+        Zellij has no built-in pane-capture CLI like `tmux capture-pane`,
+        so we read from the per-workstream log file instead. This is the
+        most reliable cross-platform source and works even when the
+        zellij session is not attached.
+        """
+        import os
+        log_file = os.environ.get("WORKSTREAMS_ZELLIJ_LOG")
+        if not log_file:
+            return []
+        try:
+            with open(log_file, "r", encoding="utf-8", errors="replace") as f:
+                all_lines = f.readlines()
+            return [ln.rstrip("\n") for ln in all_lines[-lines:]]
+        except OSError:
+            return []
+
+    def is_available(self) -> bool:
+        import shutil
+        return shutil.which("zellij") is not None
+
+    def is_running(self) -> bool:
+        result = self._zj("list-sessions", check=False)
+        return self.session in (result.stdout or "")

workstreams/notifier.py

@@ -0,0 +1,147 @@
+"""Cross-terminal notifications (desktop + file-based for other workstreams)."""
+
+from __future__ import annotations
+
+import json
+import os
+import platform
+import subprocess
+import sys
+from datetime import datetime, UTC
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from .event_log import default_log_dir
+
+NOTIFY_SENDERS = [
+    "notify-send",
+    "terminal-notify",
+]
+
+
+class Notifier:
+    """Send notifications to other terminals / desktops."""
+
+    def __init__(self, project: str, log_dir: Optional[Path] = None):
+        self.project = project
+        self.notify_dir = Path(log_dir) if log_dir else default_log_dir(project)
+        self.notify_dir.mkdir(parents=True, exist_ok=True)
+        self.notify_file = self.notify_dir / "notifications.jsonl"
+
+    def send(self, title: str, message: str, urgency: str = "normal") -> bool:
+        """Send notification via desktop notification and file."""
+        sent = False
+        system = platform.system()
+
+        if system == "Darwin":
+            script = f'display notification {json.dumps(message)} with title {json.dumps(title)}'
+            try:
+                result = subprocess.run(
+                    ["osascript", "-e", script],
+                    capture_output=True,
+                    text=True,
+                    timeout=5,
+                )
+                sent = result.returncode == 0
+            except (OSError, subprocess.TimeoutExpired):
+                pass
+        elif system == "Windows":
+            # Windows: use PowerShell for desktop notification
+            ps_script = (
+                f"[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms') | Out-Null; "
+                f"$n = New-Object System.Windows.Forms.NotifyIcon; "
+                f"$n.Icon = [System.Drawing.SystemIcons]::Information; "
+                f"$n.Visible = $true; "
+                f"$n.ShowBalloonTip(5000, {json.dumps(title)}, {json.dumps(message)}, 'Info')"
+            )
+            try:
+                subprocess.run(
+                    ["powershell", "-Command", ps_script],
+                    capture_output=True,
+                    text=True,
+                    timeout=5,
+                )
+                sent = True
+            except (OSError, subprocess.TimeoutExpired):
+                pass
+        else:
+            # Linux: notify-send. Use --transient + --expire-time so the
+            # notification auto-dismisses instead of staying open. Critical
+            # urgency notifications are modal/blocking by spec — downgrade
+            # them and rely on expire-time so they don't pin forever.
+            effective_urgency = "normal" if urgency == "critical" else urgency
+            expire_ms = 15000 if urgency == "critical" else 8000
+            cmd = [
+                "notify-send",
+                "--transient",
+                "--expire-time", str(expire_ms),
+                "-u", effective_urgency,
+                title,
+                message,
+            ]
+            try:
+                result = subprocess.run(
+                    cmd,
+                    capture_output=True,
+                    text=True,
+                    timeout=5,
+                )
+                sent = result.returncode == 0
+            except (OSError, subprocess.TimeoutExpired):
+                # Fallback: terminal-notify writes to stdout of the terminal
+                try:
+                    result = subprocess.run(
+                        ["terminal-notify", title, message],
+                        capture_output=True,
+                        text=True,
+                        timeout=5,
+                    )
+                    sent = result.returncode == 0
+                except (OSError, subprocess.TimeoutExpired):
+                    pass
+
+        # Always write to notification file for other instances to pick up
+        notif = {
+            "title": title,
+            "message": message,
+            "urgency": urgency,
+            "timestamp": datetime.now(UTC).isoformat(),
+        }
+        try:
+            with open(self.notify_file, "a", encoding="utf-8") as f:
+                f.write(json.dumps(notif) + "\n")
+            sent = True
+        except OSError:
+            pass
+        return sent
+
+    def get_notifications(self, since: Optional[datetime] = None) -> List[Dict[str, Any]]:
+        """Get pending notifications."""
+        if not self.notify_file.exists():
+            return []
+        notifs: List[Dict[str, Any]] = []
+        with open(self.notify_file, encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    notif = json.loads(line)
+                    if since is not None:
+                        ts_raw = notif.get("timestamp", "")
+                        try:
+                            ts = datetime.fromisoformat(ts_raw)
+                            if ts.tzinfo is None:
+                                ts = ts.replace(tzinfo=UTC)
+                            if ts < since:
+                                continue
+                        except ValueError:
+                            pass
+                    notifs.append(notif)
+                except json.JSONDecodeError:
+                    continue
+        return notifs
+
+    def clear_notifications(self) -> None:
+        if self.notify_file.exists():
+            self.notify_file.unlink()

workstreams/subagent_client.py

@@ -0,0 +1,125 @@
+"""Subagent client helpers - report events from any process.
+
+Import these from your subagent (a Claude Code session, a Codex session,
+a script, a cron job...) so it can report progress to the main terminal:
+
+    from workstreams import subagent_progress
+    subagent_progress("myproject", 1, "claude-code", 42, "Fixed auth", {"files": 3})
+
+Or use the one-liner CLI that needs no Python import at all:
+
+    workstreams event started --project myproject --workstream 1 \
+        --subagent claude-code --issue 42 --message "Fix auth"
+
+All events land in ~/.workstreams/<project>/events.jsonl and show up in
+`workstreams monitor`, `workstreams events`, and any other terminal.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from .models import SubagentEvent
+from .event_log import get_event_log
+
+# Subagent identifiers are free-form (claude-code, codex, opencode, qwen-code,
+# mimocode, hermes, kilo-code, cline, ...). We do NOT restrict them: the whole
+# point of workstreams is agent-agnostic dispatch.
+
+
+def subagent_report(
+    project: str,
+    workstream_id: int,
+    subagent: str,
+    issue: int,
+    event_type: str,
+    message: str,
+    data: Optional[Dict[str, Any]] = None,
+) -> bool:
+    """Report an arbitrary event (cross-process)."""
+    event_log = get_event_log(project)
+    event = SubagentEvent(
+        workstream_id=workstream_id,
+        subagent=subagent,
+        issue=issue,
+        event_type=event_type,
+        message=message,
+        data=data or {},
+    )
+    return event_log.append(event)
+
+
+def subagent_started(
+    project: str,
+    workstream_id: int,
+    subagent: str,
+    issue: int,
+    prompt: str = "",
+    data: Optional[Dict[str, Any]] = None,
+) -> bool:
+    """Report subagent started."""
+    return subagent_report(
+        project, workstream_id, subagent, issue, "started",
+        f"{subagent} started on issue #{issue}" + (f": {prompt}" if prompt else ""),
+        {"prompt": prompt, **(data or {})},
+    )
+
+
+def subagent_progress(
+    project: str,
+    workstream_id: int,
+    subagent: str,
+    issue: int,
+    message: str,
+    data: Optional[Dict[str, Any]] = None,
+) -> bool:
+    """Report subagent progress."""
+    return subagent_report(project, workstream_id, subagent, issue, "progress", message, data)
+
+
+def subagent_completed(
+    project: str,
+    workstream_id: int,
+    subagent: str,
+    issue: int,
+    message: str,
+    data: Optional[Dict[str, Any]] = None,
+) -> bool:
+    """Report subagent completed."""
+    return subagent_report(project, workstream_id, subagent, issue, "completed", message, data)
+
+
+def subagent_failed(
+    project: str,
+    workstream_id: int,
+    subagent: str,
+    issue: int,
+    message: str,
+    data: Optional[Dict[str, Any]] = None,
+) -> bool:
+    """Report subagent failed."""
+    return subagent_report(project, workstream_id, subagent, issue, "failed", message, data)
+
+
+def subagent_error(
+    project: str,
+    workstream_id: int,
+    subagent: str,
+    issue: int,
+    message: str,
+    data: Optional[Dict[str, Any]] = None,
+) -> bool:
+    """Report a subagent error."""
+    return subagent_report(project, workstream_id, subagent, issue, "error", message, data)
+
+
+def subagent_done(
+    project: str,
+    workstream_id: int,
+    subagent: str,
+    issue: int,
+    message: str,
+    data: Optional[Dict[str, Any]] = None,
+) -> bool:
+    """Report a subagent finished (used by workstreams work --wait)."""
+    return subagent_report(project, workstream_id, subagent, issue, "done", message, data)