workstreams-cli 0.6.2__tar.gz → 0.6.4__tar.gz

{workstreams_cli-0.6.2 → workstreams_cli-0.6.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: workstreams-cli
-Version: 0.6.2
+Version: 0.6.4
 Summary: Visually dispatch coding-agent work to subagents in real terminal windows and monitor it in one dashboard - for any coding agent (Claude Code, Codex, OpenCode, Qwen Code, Hermes, Cline, and more).
 Author: Dream-Pixels-Forge
 License: MIT
@@ -114,7 +114,7 @@ pip install -e ".[yaml,dev]"   # dev extras add pytest
 Verify:
 
 ```bash
-workstreams --version   # -> workstreams 0.6.2
+workstreams --version   # -> workstreams 0.6.4
 ```
 
 > **Note:** every command also accepts `--json` to emit machine-readable output (where supported), which coding agents can parse. All read-side commands work without a multiplexer installed; only `start`/`dispatch`/`work`/`attach` need one.

{workstreams_cli-0.6.2 → workstreams_cli-0.6.4}/README.md

@@ -84,7 +84,7 @@ pip install -e ".[yaml,dev]"   # dev extras add pytest
 Verify:
 
 ```bash
-workstreams --version   # -> workstreams 0.6.2
+workstreams --version   # -> workstreams 0.6.4
 ```
 
 > **Note:** every command also accepts `--json` to emit machine-readable output (where supported), which coding agents can parse. All read-side commands work without a multiplexer installed; only `start`/`dispatch`/`work`/`attach` need one.

{workstreams_cli-0.6.2 → workstreams_cli-0.6.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "workstreams-cli"
-version = "0.6.2"
+version = "0.6.4"
 description = "Visually dispatch coding-agent work to subagents in real terminal windows and monitor it in one dashboard - for any coding agent (Claude Code, Codex, OpenCode, Qwen Code, Hermes, Cline, and more)."
 readme = "README.md"
 requires-python = ">=3.9"

{workstreams_cli-0.6.2 → workstreams_cli-0.6.4}/src/workstreams/__init__.py

@@ -42,7 +42,7 @@ from .confidence import (
     extract_score,
 )
 
-__version__ = "0.6.2"
+__version__ = "0.6.4"
 
 __all__ = [
     # models

{workstreams_cli-0.6.2 → workstreams_cli-0.6.4}/src/workstreams/multiplexer/__init__.py

@@ -1,6 +1,7 @@
 """Terminal multiplexer implementations + platform-aware default detection."""
 
 import shutil
+import subprocess
 import sys
 from typing import Dict
 
@@ -8,25 +9,34 @@ from .base import MultiplexerBase
 from .tmux import TmuxMultiplexer
 from .zellij import ZellijMultiplexer
 from .tmux_compatible import TmuxCompatibleMultiplexer
+from .lmux import LmuxMultiplexer
+from .wmux import WmuxMultiplexer
 
 __all__ = [
     "MultiplexerBase",
     "TmuxMultiplexer",
     "ZellijMultiplexer",
+    "LmuxMultiplexer",
+    "WmuxMultiplexer",
     "get_multiplexer",
     "resolve_default_multiplexer",
 ]
 
 # Name -> binary that must be on PATH. The TmuxCompatibleMultiplexer wraps
 # any binary whose CLI is compatible with tmux (send-keys, new-window, ...).
+# NOTE: "lmux" and "wmux" are NOT tmux-compatible; they have native dialects
+# (LmuxMultiplexer JSON verbs / WmuxMultiplexer JSON-RPC) and are handled by
+# their own classes. The tmux-compat shim HANGS FOREVER on wmux (every wmux
+# invocation launches the Electron GUI and blocks), so wmux must never be
+# routed through it.
 _TMUX_COMPATIBLE = {
     "nami": "nami",
-    "lmux": "lmux",
-    "wmux": "wmux",
     "herdr": "herdr",
 }
 
 # Ordered preference list per platform. We pick the FIRST that is installed.
+# lmux is the top Linux choice because it is purpose-built for AI coding
+# agents and workstreams now drives it natively.
 _PLATFORM_PREFERENCE = {
     "win": ["wmux", "lmux", "zellij", "tmux"],
     "mac": ["tmux", "zellij", "nami", "lmux", "wmux"],
@@ -37,12 +47,25 @@ _PLATFORM_PREFERENCE = {
 def _installed(name: str) -> bool:
     """Return True if the CLI binary for `name` is on PATH.
 
-    For tmux-compatible wrappers (lmux, wmux, nami, herdr) we additionally
-    require that the binary actually exposes a tmux-style command, because
-    'installed' alone is not sufficient — e.g. `lmux` has a completely
-    different CLI (`workspace.create`, `surface.send-key`) and is not
-    tmux-compatible despite the name.
+    For the tmux-compatible wrappers (nami, wmux, herdr) we additionally
+    require that the binary actually exposes a tmux-style command.
+
+    `lmux` and `wmux` are special-cased: each speaks its OWN native dialect
+    and is driven by its dedicated class (LmuxMultiplexer / WmuxMultiplexer)
+    — never the tmux wrapper. wmux additionally requires a live RPC socket
+    for auto-detect, because probing it with a subprocess would launch the
+    Electron GUI and block.
     """
+    if name == "lmux":
+        if shutil.which("lmux") is None:
+            return False
+        return _supports_lmux_dialect("lmux")
+    if name == "wmux":
+        if shutil.which("wmux") is None:
+            return False
+        from .wmux import default_socket_path
+        import os
+        return os.path.exists(default_socket_path())
     if name in ("tmux", "zellij"):
         binary = name
     elif name in _TMUX_COMPATIBLE:
@@ -57,6 +80,30 @@ def _installed(name: str) -> bool:
 
 
 _tmux_dialect_cache: Dict[str, bool] = {}
+_lmux_dialect_cache: Dict[str, bool] = {}
+
+
+def _supports_lmux_dialect(binary: str) -> bool:
+    """Heuristic: does `binary` expose lmux's native verb-dialect?
+
+    Probes ``<binary> help`` for the canonical native verbs:
+    ``workspace.create`` AND ``surface.send_text``. A binary that has these
+    is driven natively by :class:`LmuxMultiplexer` (JSON socket protocol).
+    """
+    key = binary
+    if key in _lmux_dialect_cache:
+        return _lmux_dialect_cache[key]
+    result = False
+    try:
+        proc = subprocess.run([binary, "help"], capture_output=True, text=True, timeout=5)
+        help_text = (proc.stdout or "") + (proc.stderr or "")
+        has_workspace = "workspace.create" in help_text
+        has_send_text = "surface.send_text" in help_text or "surface.send-text" in help_text
+        result = has_workspace and has_send_text
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+        result = False
+    _lmux_dialect_cache[key] = result
+    return result
 
 
 def _supports_tmux_dialect(binary: str) -> bool:
@@ -159,15 +206,18 @@ def get_multiplexer(name: str, config) -> MultiplexerBase:
     multiplexers = {
         "tmux": TmuxMultiplexer,
         "zellij": ZellijMultiplexer,
+        "lmux": LmuxMultiplexer,
+        "wmux": WmuxMultiplexer,
     }
-    if name in _TMUX_COMPATIBLE:
-        binary = _TMUX_COMPATIBLE[name]
-        return TmuxCompatibleMultiplexer(config, binary)
     cls = multiplexers.get(name)
     if not cls:
+        # Fallback: a tmux-compatible wrapper binary (nami/herdr).
+        if name in _TMUX_COMPATIBLE:
+            binary = _TMUX_COMPATIBLE[name]
+            return TmuxCompatibleMultiplexer(config, binary)
         raise ValueError(
             f"Unknown multiplexer: {name}. "
-            f"Supported: {', '.join(multiplexers)} plus tmux-compatible: {', '.join(_TMUX_COMPATIBLE)} "
-            f"or 'default' (auto-detect)."
+            f"Supported: {', '.join(multiplexers)} plus tmux-compatible: "
+            f"{', '.join(_TMUX_COMPATIBLE)} or 'default' (auto-detect)."
         )
     return cls(config)

workstreams_cli-0.6.4/src/workstreams/multiplexer/lmux.py

@@ -0,0 +1,258 @@
+"""Native lmux multiplexer.
+
+lmux is a Linux terminal multiplexer built specifically for AI coding
+agents. It is NOT tmux-compatible: its CLI speaks its own verb-dialect
+(``workspace.create``, ``surface.send_text``, ``read-screen`` ...), backed
+by a JSON-over-Unix-socket protocol. This class drives that protocol
+directly via :class:`LmuxClient` — no tmux-dialect faking.
+
+Model mapping
+-------------
+- workspace  ≈ session (one per workstreams project)
+- surface    ≈ tab/window (one per workstream)
+- pane       ≈ split (lmux splits within a surface)
+
+The workstream->surface ID map is persisted to the shared JSONL event log
+so that re-invocations of ``dispatch``/``capture`` target the same surface
+deterministically.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from typing import Any, Dict, List, Optional
+
+from .base import MultiplexerBase
+from .lmux_client import LmuxClient, default_socket_path
+
+
+class LmuxMultiplexer(MultiplexerBase):
+    """Native lmux workstream management (JSON socket protocol)."""
+
+    name = "lmux"
+
+    def __init__(self, config: Any):
+        super().__init__(config)
+        self.session = f"workstreams-{config.project}"
+        self._client: Optional[LmuxClient] = None
+        self._workspace_id: Optional[int] = None
+        self._surface_map: Dict[int, int] = {}  # workstream_id -> surface_id
+
+    # ------------------------------------------------------------------ #
+    # Client
+    # ------------------------------------------------------------------ #
+    @property
+    def _cli(self) -> LmuxClient:
+        if self._client is None:
+            self._client = LmuxClient.ensure_daemon()
+        return self._client
+
+    # ------------------------------------------------------------------ #
+    # Base interface
+    # ------------------------------------------------------------------ #
+    def session_name(self) -> str:
+        return self.session
+
+    def pane_target(self, workstream_id: int) -> str:
+        """lmux targets surfaces by numeric id, not `session:win.pane` strings.
+
+        Return the recorded surface id as a string, or ``""`` if unknown.
+        """
+        self._restore_surface_map()
+        sid = self._surface_map.get(workstream_id)
+        return str(sid) if sid is not None else ""
+
+    def binary_name(self) -> str:
+        return "lmux"
+
+    def is_available(self) -> bool:
+        return LmuxClient.binary_available()
+
+    def start(self, workstreams: List[Dict[str, Any]], command: Optional[str] = None) -> None:
+        client = self._cli
+        # Idempotent: reuse an existing workspace with the same name.
+        existing = client.cmd("workspace.list", {})
+        workspace_id = self._find_workspace(existing)
+        if workspace_id is None:
+            reply = client.cmd("workspace.create", {"title": self.session})
+            workspace_id = self._as_int(reply, "id")
+        self._workspace_id = workspace_id
+
+        for i, ws in enumerate(workstreams):
+            ws_id = int(ws.get("id", i + 1))
+            ws_name = ws.get("name", f"ws{ws_id}")
+            reply = client.cmd(
+                "surface.create", {"workspace": workspace_id, "title": ws_name}
+            )
+            surface_id = self._as_int(reply, "id")
+            self._surface_map[ws_id] = surface_id
+
+            # Run the workstream's command (or a global default) in this surface.
+            ws_cmd = command or ws.get("command") or ""
+            if ws_cmd:
+                path = ws.get("path", "")
+                if path:
+                    ws_cmd = f"cd {path} && {ws_cmd}"
+                client.cmd(
+                    "surface.send_text",
+                    {"surface": surface_id, "workspace": workspace_id, "text": ws_cmd},
+                )
+
+        self._persist_surface_map()
+        print(f"Started {len(workstreams)} workstream(s) in lmux workspace '{self.session}'")
+        print(f"  Observe: lmux tree  ·  Attach a TUI: lmux (workspace '{self.session}')")
+
+    def attach(self, session: Optional[str] = None) -> None:
+        # lmux is spawn-and-observe oriented; interactive attach is best-effort.
+        target = session or self.session
+        print(f"Attach to lmux workspace '{target}': run `lmux` and select it, or `lmux tree`.")
+        print("  (lmux has no blocking attach; surfaces are spawned for agents to observe.)")
+
+    def send_command(self, workstream_id: int, command: str) -> bool:
+        """Send `command` to the recorded surface for `workstream_id`."""
+        self._restore_surface_map()
+        surface_id = self._surface_map.get(workstream_id)
+        if surface_id is None:
+            print(
+                f"[workstreams] lmux: no surface recorded for workstream "
+                f"{workstream_id}; run `workstreams start` first.",
+                file=sys.stderr,
+            )
+            return False
+        client = self._cli
+        reply = client.cmd(
+            "surface.send_text",
+            {"surface": surface_id, "workspace": self._workspace_id, "text": command},
+        )
+        return self._ok(reply)
+
+    def capture(self, workstream_id: int, lines: int = 20) -> List[str]:
+        """Read the recorded surface's terminal screen via ``read-screen``."""
+        self._restore_surface_map()
+        surface_id = self._surface_map.get(workstream_id)
+        if surface_id is None:
+            return []
+        return self._capture_surface(surface_id, lines=lines)
+
+    def _capture_surface(self, surface_id: int, lines: int = 20) -> List[str]:
+        client = self._cli
+        reply = client.cmd(
+            "read-screen", {"surface": surface_id, "workspace": self._workspace_id}
+        )
+        result = self._result(reply)
+        text = result.get("text", "") if isinstance(result, dict) else str(result)
+        raw_lines = [ln.rstrip() for ln in text.splitlines()]
+        return raw_lines[-lines:]
+
+    def list_windows(self) -> List[Dict[str, Any]]:
+        client = self._cli
+        reply = client.cmd("surface.list", {})
+        result = self._result(reply)
+        text = result.get("text", "") if isinstance(result, dict) else str(result)
+        out: List[Dict[str, Any]] = []
+        for ln in text.splitlines():
+            ln = ln.strip()
+            if not ln:
+                continue
+            out.append({"raw": ln})
+        return out
+
+    def kill(self) -> None:
+        if self._workspace_id is not None:
+            # workspace.close extracts the id as a string from the JSON args.
+            self._cli.cmd("workspace.close", {"id": str(self._workspace_id)})
+
+    # ------------------------------------------------------------------ #
+    # Helpers
+    # ------------------------------------------------------------------ #
+    @staticmethod
+    def _result(reply: Any) -> Any:
+        """Unwrap the lmux daemon envelope.
+
+        Every JSON reply is ``{"ok": bool, "result": {...}}`` (or
+        ``{"ok": false, "error": ...}``). Some text-only verbs return a
+        bare ``{"text": ...}`` payload with no envelope. Return the inner
+        result, or the payload itself when there is no envelope.
+        """
+        if isinstance(reply, dict):
+            if "result" in reply:
+                return reply["result"]
+            return reply
+        return reply
+
+    def _find_workspace(self, list_reply: Dict[str, Any]) -> Optional[int]:
+        """Find an existing workspace with our session name (idempotent start)."""
+        result = self._result(list_reply)
+        if not isinstance(result, dict):
+            return None
+        # workspace.list replies carry the list under "workspaces".
+        workspaces = result.get("workspaces")
+        if isinstance(workspaces, list):
+            for w in workspaces:
+                if isinstance(w, dict) and w.get("title") == self.session:
+                    wid = w.get("id")
+                    if isinstance(wid, int):
+                        return wid
+                    if isinstance(wid, str) and wid.isdigit():
+                        return int(wid)
+            return None
+        # Fall back to text form: parse "title (id=N)" lines.
+        import re
+        text = result.get("text", "") if "text" in result else json.dumps(result)
+        m = re.search(rf"{re.escape(self.session)}[^0-9]*\(?id=(\d+)\)?", text)
+        return int(m.group(1)) if m else None
+
+    @classmethod
+    def _as_int(cls, reply: Any, key: str = "id") -> int:
+        result = cls._result(reply)
+        if isinstance(result, dict):
+            v = result.get(key)
+            if isinstance(v, int):
+                return v
+            if isinstance(v, str) and v.isdigit():
+                return int(v)
+        raise RuntimeError(f"lmux: expected int id in reply: {reply!r}")
+
+    @staticmethod
+    def _ok(reply: Any) -> bool:
+        """Check if an lmux reply indicates success.
+
+        Returns True only if the reply explicitly indicates success
+        (has "ok" key with truthy value). Returns False for any
+        unknown or error status, including non-dict replies.
+        """
+        if not isinstance(reply, dict):
+            # Non-dict reply - unknown format, assume failure
+            return False
+        if "ok" in reply:
+            return bool(reply["ok"])
+        # Dict reply without "ok" key - cannot confirm success
+        return False
+
+    def _map_path(self) -> str:
+        data_dir = os.environ.get("WORKSTREAMS_DATA_DIR", ".workstreams")
+        return os.path.join(data_dir, f"{self.session}.surfaces.json")
+
+    def _persist_surface_map(self) -> None:
+        try:
+            os.makedirs(os.path.dirname(self._map_path()), exist_ok=True)
+            with open(self._map_path(), "w", encoding="utf-8") as f:
+                json.dump(
+                    {"workspace": self._workspace_id, "surfaces": self._surface_map},
+                    f,
+                )
+        except OSError:
+            pass
+
+    def _restore_surface_map(self) -> None:
+        if self._surface_map:
+            return
+        try:
+            with open(self._map_path(), "r", encoding="utf-8") as f:
+                data = json.load(f)
+            self._workspace_id = data.get("workspace") or self._workspace_id
+            self._surface_map = {int(k): int(v) for k, v in data.get("surfaces", {}).items()}
+        except (OSError, ValueError, json.JSONDecodeError):
+            self._surface_map = {}

workstreams_cli-0.6.4/src/workstreams/multiplexer/lmux_client.py

@@ -0,0 +1,123 @@
+"""Raw JSON-over-Unix-socket client for the lmux daemon.
+
+lmux (Linux terminal multiplexer built for AI coding agents) is NOT
+tmux-compatible: its CLI speaks its own verb-dialect
+(``workspace.create``, ``surface.send_text``, ``read-screen`` ...). Under the
+hood every one-shot subcommand is a JSON request over a Unix socket. This
+client reproduces that wire protocol so workstreams can drive lmux natively.
+
+Wire format (verified from ``lmux help`` + strace of the real binary):
+
+    connect -> /run/user/<uid>/lmux.sock   (env LMUX_SOCKET / XDG_RUNTIME_DIR)
+    write   -> {"cmd": "<name>", "args": {...}}\\n
+    read    -> <json reply>\\n
+    close
+
+The daemon lazy-warms a PTY on the first command, so the first call after a
+fresh daemon start can take a few seconds. We use a generous default timeout.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import socket
+import shutil
+from typing import Any, Dict, Optional
+
+
+def default_socket_path() -> str:
+    """Return the lmux daemon socket path for the current user."""
+    env = os.environ.get("LMUX_SOCKET")
+    if env:
+        return env
+    runtime = os.environ.get("XDG_RUNTIME_DIR", f"/run/user/{os.getuid()}")
+    return os.path.join(runtime, "lmux.sock")
+
+
+class LmuxClient:
+    """Minimal lmux daemon client."""
+
+    name = "lmux"
+
+    def __init__(self, socket_path: Optional[str] = None, timeout: float = 10.0):
+        self.socket_path = socket_path or default_socket_path()
+        self.timeout = timeout
+
+    # ------------------------------------------------------------------ #
+    # Protocol
+    # ------------------------------------------------------------------ #
+    def cmd(self, name: str, args: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        """Send a single JSON command and return the parsed JSON reply.
+
+        Raises ``RuntimeError`` if the socket is missing or the reply can't
+        be parsed.
+        """
+        args = args or {}
+        payload = (json.dumps({"cmd": name, "args": args}) + "\n").encode("utf-8")
+        if not os.path.exists(self.socket_path):
+            raise RuntimeError(
+                f"lmux daemon socket not found at {self.socket_path}. "
+                "Start it with: lmux daemon"
+            )
+        try:
+            sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+            sock.settimeout(self.timeout)
+            sock.connect(self.socket_path)
+            sock.sendall(payload)
+            data = b""
+            while not data.endswith(b"\n"):
+                chunk = sock.recv(4096)
+                if not chunk:
+                    break
+                data += chunk
+            sock.close()
+        except OSError as exc:
+            raise RuntimeError(f"lmux socket I/O error: {exc}") from exc
+
+        text = data.decode("utf-8", "replace").strip()
+        if not text:
+            # Some lmux verbs (tree, *.list) return human-readable text, not
+            # JSON. Return it as a text payload so callers can still use it.
+            return {"text": text}
+        try:
+            return json.loads(text)
+        except json.JSONDecodeError:
+            return {"text": text}
+
+    # ------------------------------------------------------------------ #
+    # Convenience
+    # ------------------------------------------------------------------ #
+    def ping(self) -> Dict[str, Any]:
+        return self.cmd("ping")
+
+    @staticmethod
+    def binary_available() -> bool:
+        """True if the lmux binary is on PATH."""
+        return shutil.which("lmux") is not None
+
+    @classmethod
+    def ensure_daemon(cls, socket_path: Optional[str] = None) -> "LmuxClient":
+        """Return a client, starting the daemon if the socket is missing.
+
+        No-op start (idempotent) when a live socket already exists. Guarded
+        by ``WORKSTREAMS_LMUX_NO_DAEMON`` to skip the auto-start.
+        """
+        client = cls(socket_path)
+        if os.path.exists(client.socket_path):
+            return client
+        if os.environ.get("WORKSTREAMS_LMUX_NO_DAEMON"):
+            return client  # caller will get a clean RuntimeError on .cmd()
+        if not cls.binary_available():
+            raise RuntimeError("lmux binary not found on PATH")
+        import subprocess
+        # Detached daemon; the socket appears within a couple seconds.
+        proc = subprocess.Popen(
+            ["lmux", "daemon"],
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            start_new_session=True,
+        )
+        proc.wait(timeout=15)  # lmux daemon backgrounds itself; wait is short.
+        return client