muxplex-client 0.19.0__py3-none-any.whl

muxplex_client/__init__.py

@@ -0,0 +1,95 @@
+"""muxplex_client -- typed sync/async HTTP client for the muxplex API.
+
+Basic usage:
+
+    >>> from muxplex_client import MuxplexClient
+    >>> with MuxplexClient("https://your-server:8088", "federation-key") as client:
+    ...     sessions = client.sessions()
+
+Async usage:
+
+    >>> from muxplex_client import AsyncMuxplexClient
+    >>> async with AsyncMuxplexClient("https://your-server:8088", "federation-key") as client:
+    ...     sessions = await client.sessions()
+
+See ../README.md and ../../muxplex-client-design.md for the full design
+rationale (why this is a second distribution, version-alignment policy, the
+sentinel's digit-anchor rule, and what was deliberately excluded).
+"""
+
+from __future__ import annotations
+
+import importlib.metadata
+
+from .async_client import AsyncMuxplexClient
+from .constants import (
+    DEFAULT_CAPTURE_LINES,
+    KNOWN_KEYS,
+    MAX_CAPTURE_LINES,
+    MAX_KEYS,
+    MIN_SERVER_VERSION,
+)
+from .errors import (
+    ApiError,
+    AuthError,
+    CommandTimeout,
+    InputForbidden,
+    MuxplexError,
+    SessionNotFound,
+    UnreachableError,
+)
+from .models import (
+    Bell,
+    CommandResult,
+    ConnectResult,
+    InputResult,
+    InstanceInfo,
+    ServerState,
+    Session,
+    SessionSnapshot,
+    Settings,
+    View,
+    ViewResult,
+    ViewSession,
+)
+from .sentinel import Sentinel, make_sentinel
+from .sync_client import MuxplexClient
+
+try:
+    __version__ = importlib.metadata.version("muxplex-client")
+except importlib.metadata.PackageNotFoundError:
+    # Editable/workspace checkout with no build metadata yet (e.g. running
+    # straight from a source tree before an initial `uv sync`).
+    __version__ = "0.0.0.dev0"
+
+__all__ = [
+    "__version__",
+    "ApiError",
+    "AsyncMuxplexClient",
+    "AuthError",
+    "Bell",
+    "CommandResult",
+    "CommandTimeout",
+    "ConnectResult",
+    "DEFAULT_CAPTURE_LINES",
+    "InputForbidden",
+    "InputResult",
+    "InstanceInfo",
+    "KNOWN_KEYS",
+    "MAX_CAPTURE_LINES",
+    "MAX_KEYS",
+    "MIN_SERVER_VERSION",
+    "MuxplexClient",
+    "MuxplexError",
+    "Sentinel",
+    "ServerState",
+    "Session",
+    "SessionNotFound",
+    "SessionSnapshot",
+    "Settings",
+    "UnreachableError",
+    "View",
+    "ViewResult",
+    "ViewSession",
+    "make_sentinel",
+]

muxplex_client/_protocol.py

@@ -0,0 +1,215 @@
+"""Pure protocol logic: response parsing and error mapping.
+
+No I/O, no httpx import -- tested once in `tests/test_protocol.py` with no
+network. `sync_client.py` and `async_client.py` are each a thin, ~120-line
+await-shaped (or not) shell that calls into this module; duplication is
+confined to that shell, where it is honest and cheap (this is what httpx
+itself does for its own sync/async split).
+
+`.get()`-based parsing throughout, deliberately: AGENTS.md requires clients
+to tolerate unknown fields and the server to tolerate their absence. Missing
+keys fall back to a sane default rather than raising KeyError.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Mapping, Sequence
+
+from .constants import DEFAULT_CAPTURE_LINES
+from .errors import ApiError, AuthError, InputForbidden, MuxplexError, SessionNotFound
+from .models import (
+    Bell,
+    ConnectResult,
+    InputResult,
+    InstanceInfo,
+    ServerState,
+    Session,
+    SessionSnapshot,
+    Settings,
+    View,
+    ViewResult,
+    ViewSession,
+)
+
+__all__ = [
+    "map_status_error",
+    "parse_bell",
+    "parse_session",
+    "parse_sessions",
+    "parse_session_snapshot",
+    "parse_view_session",
+    "parse_view_result",
+    "parse_server_state",
+    "parse_view",
+    "parse_settings",
+    "parse_instance_info",
+    "parse_connect_result",
+    "parse_input_result",
+    "version_tuple",
+]
+
+
+# ---------------------------------------------------------------------------
+# Response parsing
+# ---------------------------------------------------------------------------
+
+
+def parse_bell(raw: Mapping[str, Any]) -> Bell:
+    return Bell(
+        last_fired_at=raw.get("last_fired_at"),
+        seen_at=raw.get("seen_at"),
+        unseen_count=int(raw.get("unseen_count", 0)),
+    )
+
+
+def parse_session(raw: Mapping[str, Any]) -> Session:
+    return Session(
+        name=raw["name"],
+        snapshot=raw.get("snapshot", ""),
+        bell=parse_bell(raw.get("bell") or {}),
+        last_activity_at=raw.get("last_activity_at"),
+    )
+
+
+def parse_sessions(raw: Sequence[Mapping[str, Any]]) -> list[Session]:
+    return [parse_session(item) for item in raw]
+
+
+def parse_session_snapshot(raw: Mapping[str, Any]) -> SessionSnapshot:
+    return SessionSnapshot(
+        name=raw["name"],
+        snapshot=raw.get("snapshot", ""),
+        lines=int(raw.get("lines", DEFAULT_CAPTURE_LINES)),
+        bell=parse_bell(raw.get("bell") or {}),
+        last_activity_at=raw.get("last_activity_at"),
+    )
+
+
+def parse_view_session(raw: Mapping[str, Any]) -> ViewSession:
+    return ViewSession(
+        name=raw["name"],
+        active=bool(raw.get("active", False)),
+        needs_attention=bool(raw.get("needs_attention", False)),
+        bell=parse_bell(raw.get("bell") or {}),
+        last_activity_at=raw.get("last_activity_at"),
+    )
+
+
+def parse_view_result(raw: Mapping[str, Any]) -> ViewResult:
+    return ViewResult(
+        view=raw.get("view", "all"),
+        views=tuple(raw.get("views") or ()),
+        sort=raw.get("sort", "server"),
+        sessions=tuple(parse_view_session(s) for s in (raw.get("sessions") or ())),
+    )
+
+
+def parse_server_state(raw: Mapping[str, Any]) -> ServerState:
+    return ServerState(
+        active_session=raw.get("active_session"),
+        active_view=raw.get("active_view") or "all",
+        settings_updated_at=raw.get("settings_updated_at"),
+        raw=raw,
+    )
+
+
+def parse_view(raw: Mapping[str, Any]) -> View:
+    return View(
+        name=raw.get("name", ""),
+        sessions=frozenset(raw.get("sessions") or ()),
+    )
+
+
+def parse_settings(raw: Mapping[str, Any]) -> Settings:
+    return Settings(
+        views=tuple(parse_view(v) for v in (raw.get("views") or ())),
+        hidden_sessions=frozenset(raw.get("hidden_sessions") or ()),
+        sort_order=raw.get("sort_order", "manual"),
+        raw=raw,
+    )
+
+
+def parse_instance_info(raw: Mapping[str, Any]) -> InstanceInfo:
+    return InstanceInfo(
+        name=raw.get("name", ""),
+        device_id=raw.get("device_id", ""),
+        version=raw.get("version", ""),
+        federation_enabled=bool(raw.get("federation_enabled", False)),
+        tmux_socket_dir=raw.get("tmux_socket_dir"),
+        bell_hook_armed=raw.get("bell_hook_armed"),
+        raw=raw,
+    )
+
+
+def parse_connect_result(raw: Mapping[str, Any]) -> ConnectResult:
+    return ConnectResult(
+        active_session=raw["active_session"],
+        ttyd_port=int(raw["ttyd_port"]),
+    )
+
+
+def parse_input_result(raw: Mapping[str, Any]) -> InputResult:
+    return InputResult(
+        session=raw["session"],
+        snapshot=raw.get("snapshot", ""),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Error mapping
+# ---------------------------------------------------------------------------
+
+
+def map_status_error(
+    status: int,
+    path: str,
+    detail: str,
+    *,
+    session_name: str | None = None,
+) -> MuxplexError:
+    """Map an HTTP error status + path to the matching MuxplexError subclass.
+
+    Rules (applied in order):
+      - 401 -> AuthError (credential rejected).
+      - 403 from a path ending in "/input" -> InputForbidden (the operator's
+        allowlist fence, NOT a bad credential).
+      - 403 from any other path -> AuthError.
+      - 404 -> SessionNotFound (session_name is whatever the caller was
+        targeting; right after create_session() this can be the read-model
+        poll cache rather than a real failure).
+      - Anything else -> ApiError(status, detail).
+    """
+    if status == 401:
+        return AuthError(detail)
+    if status == 403:
+        if path.endswith("/input"):
+            return InputForbidden(session_name or "", detail)
+        return AuthError(detail)
+    if status == 404:
+        return SessionNotFound(session_name or "", detail)
+    return ApiError(status, detail)
+
+
+# ---------------------------------------------------------------------------
+# Version comparison (backs the opt-in check_server() helper)
+# ---------------------------------------------------------------------------
+
+
+def version_tuple(version: str) -> tuple[int, ...]:
+    """Parse a dotted version string into a comparable tuple of ints.
+
+    Deliberately lenient: non-numeric suffixes (e.g. "1.2.3rc1") are reduced
+    to their leading digits, and an entirely non-numeric segment becomes 0
+    rather than raising -- this is a convenience comparison for an opt-in
+    caller, not a strict semver parser.
+    """
+    parts: list[int] = []
+    for piece in version.split("."):
+        digits = ""
+        for ch in piece:
+            if ch.isdigit():
+                digits += ch
+            else:
+                break
+        parts.append(int(digits) if digits else 0)
+    return tuple(parts)

muxplex_client/async_client.py

@@ -0,0 +1,262 @@
+"""Asynchronous muxplex API client (httpx.AsyncClient transport).
+
+Signature-identical to `sync_client.MuxplexClient` with `await` and an
+`Async` prefix. Required for Amplifier tool modules: `async def mount(...)`
+tool execution is awaited, and a synchronous httpx call inside an async tool
+would block the event loop for its duration -- for `run_shell_command`
+polling a ten-minute build, that blocks the provider stream, every other
+tool, and every hook. See _protocol.py's docstring for the shared logic this
+wraps.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from pathlib import Path
+from typing import Any, Self, Sequence
+
+import httpx
+
+from . import _protocol as protocol
+from .constants import MIN_SERVER_VERSION
+from .errors import CommandTimeout, MuxplexError, UnreachableError
+from .models import (
+    CommandResult,
+    ConnectResult,
+    InputResult,
+    InstanceInfo,
+    ServerState,
+    Session,
+    SessionSnapshot,
+    Settings,
+    ViewResult,
+)
+from .sentinel import make_sentinel
+from .sync_client import _extract_detail
+
+
+class AsyncMuxplexClient:
+    """Thin, typed, asynchronous HTTP client for the muxplex API.
+
+    See `sync_client.MuxplexClient` for the full rationale behind every
+    behavior here (Accept header, follow_redirects, ca_file, federation_key)
+    -- this class mirrors it exactly, `await`-shaped.
+    """
+
+    def __init__(
+        self,
+        server_url: str,
+        federation_key: str | None = None,
+        *,
+        ca_file: Path | str | None = None,
+        timeout: float = 5.0,
+        client: httpx.AsyncClient | None = None,
+    ) -> None:
+        if client is not None:
+            self._client = client
+            self._owns_client = False
+            return
+        headers = {"Accept": "application/json"}
+        if federation_key:
+            headers["Authorization"] = f"Bearer {federation_key}"
+        verify: bool | str = str(ca_file) if ca_file else True
+        self._client = httpx.AsyncClient(
+            base_url=server_url,
+            headers=headers,
+            verify=verify,
+            timeout=timeout,
+            follow_redirects=False,
+        )
+        self._owns_client = True
+
+    async def aclose(self) -> None:
+        if self._owns_client:
+            await self._client.aclose()
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: dict[str, Any] | None = None,
+        session_name: str | None = None,
+    ) -> Any:
+        try:
+            response = await self._client.request(
+                method, path, params=params, json=json
+            )
+        except httpx.HTTPError as exc:
+            raise UnreachableError(f"{method} {path} failed: {exc}") from exc
+        if response.status_code >= 400:
+            raise protocol.map_status_error(
+                response.status_code,
+                path,
+                _extract_detail(response),
+                session_name=session_name,
+            )
+        return response.json()
+
+    # ---- read ----
+
+    async def instance_info(self) -> InstanceInfo:
+        return protocol.parse_instance_info(
+            await self._request("GET", "/api/instance-info")
+        )
+
+    async def sessions(self) -> list[Session]:
+        return protocol.parse_sessions(await self._request("GET", "/api/sessions"))
+
+    async def session(self, name: str, *, lines: int | None = None) -> SessionSnapshot:
+        params = {"lines": lines} if lines is not None else None
+        return protocol.parse_session_snapshot(
+            await self._request(
+                "GET", f"/api/sessions/{name}", params=params, session_name=name
+            )
+        )
+
+    async def view(self, *, sort: str | None = None) -> ViewResult:
+        params = {"sort": sort} if sort is not None else None
+        return protocol.parse_view_result(
+            await self._request("GET", "/api/view", params=params)
+        )
+
+    async def state(self) -> ServerState:
+        return protocol.parse_server_state(await self._request("GET", "/api/state"))
+
+    async def settings(self) -> Settings:
+        return protocol.parse_settings(await self._request("GET", "/api/settings"))
+
+    # ---- lifecycle ----
+
+    async def create_session(
+        self,
+        name: str,
+        *,
+        wait: bool = True,
+        timeout: float = 6.0,
+        interval: float = 0.3,
+    ) -> None:
+        await self._request(
+            "POST", "/api/sessions", json={"name": name}, session_name=name
+        )
+        if wait and not await self.wait_for_session(
+            name, timeout=timeout, interval=interval
+        ):
+            raise TimeoutError(
+                f"session {name!r} did not appear in the read cache within {timeout}s"
+            )
+
+    async def delete_session(self, name: str) -> None:
+        await self._request("DELETE", f"/api/sessions/{name}", session_name=name)
+
+    async def wait_for_session(
+        self, name: str, *, timeout: float = 6.0, interval: float = 0.3
+    ) -> bool:
+        deadline = time.monotonic() + timeout
+        while True:
+            sessions = await self.sessions()
+            if any(s.name == name for s in sessions):
+                return True
+            if time.monotonic() >= deadline:
+                return False
+            await asyncio.sleep(interval)
+
+    async def connect(self, name: str) -> ConnectResult:
+        return protocol.parse_connect_result(
+            await self._request(
+                "POST", f"/api/sessions/{name}/connect", session_name=name
+            )
+        )
+
+    async def set_active_view(self, view: str) -> None:
+        await self._request("PATCH", "/api/state", json={"active_view": view})
+
+    # ---- input ----
+
+    async def send_input(
+        self,
+        name: str,
+        *,
+        text: str = "",
+        keys: Sequence[str] = (),
+        enter: bool = False,
+        lines: int | None = None,
+    ) -> InputResult:
+        body: dict[str, Any] = {"text": text, "keys": list(keys), "enter": enter}
+        if lines is not None:
+            body["lines"] = lines
+        return protocol.parse_input_result(
+            await self._request(
+                "POST", f"/api/sessions/{name}/input", json=body, session_name=name
+            )
+        )
+
+    async def run_shell_command(
+        self,
+        name: str,
+        command: str,
+        *,
+        timeout: float = 600.0,
+        poll_interval: float = 2.0,
+        lines: int = 500,
+        bell_on_failure: bool = True,
+        exit_expr: str = "$?",
+        token: str | None = None,
+    ) -> CommandResult:
+        """Run *command* to completion and return its real exit code.
+
+        See `sync_client.MuxplexClient.run_shell_command` for the full
+        assumptions and rationale -- identical here, `await`-shaped. This is
+        the operation that matters most for the async client: it never
+        blocks the event loop while polling, unlike a synchronous call
+        parked inside an async tool.
+        """
+        sentinel = make_sentinel(token)
+        wrapped = sentinel.wrap(
+            command, bell_on_failure=bell_on_failure, exit_expr=exit_expr
+        )
+        await self.send_input(name, text=wrapped, enter=True)
+
+        start = time.monotonic()
+        deadline = start + timeout
+        while True:
+            snap = await self.session(name, lines=lines)
+            exit_code = sentinel.search(snap.snapshot)
+            if exit_code is not None:
+                return CommandResult(
+                    session=name,
+                    exit_code=exit_code,
+                    snapshot=snap.snapshot,
+                    elapsed=time.monotonic() - start,
+                    token=sentinel.token,
+                )
+            if time.monotonic() >= deadline:
+                raise CommandTimeout(
+                    session=name,
+                    token=sentinel.token,
+                    elapsed=time.monotonic() - start,
+                    snapshot=snap.snapshot,
+                )
+            await asyncio.sleep(poll_interval)
+
+    # ---- opt-in version check ----
+
+    async def check_server(self, min_version: str = MIN_SERVER_VERSION) -> InstanceInfo:
+        """Fetch instance-info and raise MuxplexError if the server is older.
+
+        Never called automatically.
+        """
+        info = await self.instance_info()
+        if protocol.version_tuple(info.version) < protocol.version_tuple(min_version):
+            raise MuxplexError(
+                f"server version {info.version!r} is older than required {min_version!r}"
+            )
+        return info

muxplex_client/constants.py

@@ -0,0 +1,46 @@
+"""Mirrored server constants.
+
+These are convenience mirrors of values defined authoritatively on the
+muxplex server (`muxplex.sessions`, `muxplex.terminal_input`). The client
+does NOT pre-validate against them -- the server is authoritative and fails
+closed; a client-side copy that silently disagreed with the server would be
+exactly the drift `AGENTS.md` warns about. They exist so a caller can build a
+tool schema enum or a UI without a round trip.
+
+`muxplex/tests/test_client_contract.py` (in the server's own test suite)
+asserts each of these equals its server original, converting what would
+otherwise be a silent drift hazard into a CI-enforced invariant.
+"""
+
+from __future__ import annotations
+
+# Cut-against server version. Provenance, not a runtime requirement -- see
+# MuxplexClient.check_server()/AsyncMuxplexClient.check_server(), which is
+# opt-in and never called automatically.
+MIN_SERVER_VERSION = "0.18.0"
+
+# Mirrors muxplex.sessions.DEFAULT_CAPTURE_LINES.
+DEFAULT_CAPTURE_LINES = 30
+
+# Mirrors muxplex.sessions.MAX_CAPTURE_LINES.
+MAX_CAPTURE_LINES = 2000
+
+# Mirrors muxplex.terminal_input.ALLOWED_KEYS.
+KNOWN_KEYS: frozenset[str] = frozenset(
+    {
+        "Enter",
+        "Escape",
+        "Tab",
+        "C-c",
+        "C-d",
+        "Up",
+        "Down",
+        "Left",
+        "Right",
+        "PageUp",
+        "PageDown",
+    }
+)
+
+# Mirrors muxplex.terminal_input.MAX_KEYS.
+MAX_KEYS = 64

muxplex_client/errors.py

@@ -0,0 +1,80 @@
+"""Exception hierarchy for the muxplex client.
+
+Mapping from HTTP status to these types happens in `_protocol.map_status_error`
+and is applied by both transport classes (`sync_client.MuxplexClient`,
+`async_client.AsyncMuxplexClient`). See that function's docstring for the
+exact rules.
+"""
+
+from __future__ import annotations
+
+
+class MuxplexError(Exception):
+    """Base class for all muxplex client errors."""
+
+
+class UnreachableError(MuxplexError):
+    """Transport failure -- connection refused, timeout, DNS, TLS.
+
+    Raised when the request never got a response from the server at all
+    (an `httpx.HTTPError` other than an HTTP status response).
+    """
+
+
+class AuthError(MuxplexError):
+    """Credential rejected (401, or 403 from any endpoint except /input)."""
+
+
+class SessionNotFound(MuxplexError):
+    """404 for a session-scoped endpoint.
+
+    Right after a `create_session()` call, this can be the ~2s read-model
+    poll cache rather than a genuine failure -- see AGENT_GUIDE.md's "read
+    model is eventually consistent" section, and `wait_for_session()` /
+    `create_session(wait=True)`, which poll past this window.
+    """
+
+    def __init__(self, name: str, detail: str = "") -> None:
+        self.name = name
+        self.detail = detail
+        super().__init__(detail or f"Session {name!r} not found")
+
+
+class InputForbidden(MuxplexError):
+    """403 from POST /api/sessions/{name}/input -- the operator's fence.
+
+    Deliberately does NOT subclass `AuthError`: this is not a rejected
+    credential, it means the session is not allowlisted for input (see
+    `settings.input_enabled` / `settings.input_allowed_sessions` in the
+    muxplex server). The correct caller response is to stop and tell the
+    human what to add to `settings.json` -- a different action from
+    rotating a key (AGENT_GUIDE.md §7).
+    """
+
+    def __init__(self, name: str, detail: str) -> None:
+        self.name = name
+        self.detail = detail
+        super().__init__(detail)
+
+
+class ApiError(MuxplexError):
+    """Any other non-2xx response not covered by a more specific error."""
+
+    def __init__(self, status: int, detail: str) -> None:
+        self.status = status
+        self.detail = detail
+        super().__init__(f"HTTP {status}: {detail}")
+
+
+class CommandTimeout(MuxplexError):
+    """`run_shell_command()` did not observe the completion sentinel in time."""
+
+    def __init__(self, session: str, token: str, elapsed: float, snapshot: str) -> None:
+        self.session = session
+        self.token = token
+        self.elapsed = elapsed
+        self.snapshot = snapshot
+        super().__init__(
+            f"command in session {session!r} did not complete within "
+            f"{elapsed:.1f}s (sentinel token={token!r})"
+        )

muxplex_client/models.py

@@ -0,0 +1,164 @@
+"""Response shapes for the muxplex client.
+
+All frozen dataclasses, deliberately not pydantic -- see
+../muxplex-client-design.md §8 ("Rejected: pydantic models"): heavy for six
+shapes, and actively wrong here, since AGENTS.md requires clients to
+tolerate unknown fields. `.get()`-based parsing in `_protocol.py` satisfies
+that by construction; a strict model would have to be deliberately loosened
+to avoid violating the contract.
+
+Where a `raw` field appears (`ServerState`, `Settings`, `InstanceInfo` -- the
+single-object, evolution-likely shapes) it is excluded from `__eq__`/`__hash__`
+via `compare=False` so a frozen dataclass carrying a dict stays hashable, and
+it is how "clients tolerate unknown fields" becomes usable rather than lossy:
+a caller needing a field the model doesn't expose yet can still reach it.
+`Session`/`Bell`/etc. are hot-path list items with a stable shape and omit it.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Mapping
+
+
+@dataclass(frozen=True)
+class Bell:
+    """A session's bell-alert sub-state, as returned by GET /api/sessions."""
+
+    last_fired_at: float | None
+    seen_at: float | None
+    unseen_count: int
+
+    @property
+    def needs_attention(self) -> bool:
+        """unseen_count > 0 and (seen_at is None or last_fired_at > seen_at).
+
+        Mirrors the server's `muxplex.bells.needs_attention` exactly --
+        contract-tested for agreement in `test_client_contract.py` across a
+        truth table of (unseen_count, seen_at, last_fired_at). Defensive on
+        `last_fired_at is None` combined with a non-None `seen_at` (should
+        not occur in practice, but treated as "not newer than seen_at"
+        rather than raising, matching the server).
+        """
+        if self.unseen_count <= 0:
+            return False
+        if self.seen_at is None:
+            return True
+        if self.last_fired_at is None:
+            return False
+        return self.last_fired_at > self.seen_at
+
+
+@dataclass(frozen=True)
+class Session:
+    """One tmux session, as returned by GET /api/sessions."""
+
+    name: str
+    snapshot: str
+    bell: Bell
+    last_activity_at: float | None = None
+
+
+@dataclass(frozen=True)
+class SessionSnapshot:
+    """A single session's pane content at a caller-chosen depth.
+
+    Returned by GET /api/sessions/{name}. Unlike `Session` (the shared,
+    ~2s-cycle poll cache), this is one fresh `capture-pane` call scoped to
+    a single session.
+    """
+
+    name: str
+    snapshot: str
+    lines: int
+    bell: Bell
+    last_activity_at: float | None
+
+
+@dataclass(frozen=True)
+class ViewSession:
+    """One entry of GET /api/view's `sessions` list."""
+
+    name: str
+    active: bool
+    needs_attention: bool
+    bell: Bell
+    last_activity_at: float | None
+
+
+@dataclass(frozen=True)
+class ViewResult:
+    """The server-resolved current view: GET /api/view."""
+
+    view: str
+    views: tuple[str, ...]
+    sort: str  # "server" | "alphabetical" | "attention"
+    sessions: tuple[ViewSession, ...]
+
+
+@dataclass(frozen=True)
+class ServerState:
+    """GET /api/state."""
+
+    active_session: str | None
+    active_view: str  # defaults to "all" when absent/empty
+    settings_updated_at: float | None = None
+    raw: Mapping[str, Any] = field(default_factory=dict, compare=False, repr=False)
+
+
+@dataclass(frozen=True)
+class View:
+    """One user-defined view, as returned by GET /api/settings."""
+
+    name: str
+    sessions: frozenset[str]
+
+
+@dataclass(frozen=True)
+class Settings:
+    """GET /api/settings."""
+
+    views: tuple[View, ...]
+    hidden_sessions: frozenset[str]
+    sort_order: str  # default "manual"
+    raw: Mapping[str, Any] = field(default_factory=dict, compare=False, repr=False)
+
+
+@dataclass(frozen=True)
+class InstanceInfo:
+    """GET /api/instance-info."""
+
+    name: str
+    device_id: str
+    version: str
+    federation_enabled: bool
+    tmux_socket_dir: str | None
+    bell_hook_armed: bool | None  # None on servers < 0.18.0
+    raw: Mapping[str, Any] = field(default_factory=dict, compare=False, repr=False)
+
+
+@dataclass(frozen=True)
+class ConnectResult:
+    """POST /api/sessions/{name}/connect."""
+
+    active_session: str
+    ttyd_port: int
+
+
+@dataclass(frozen=True)
+class InputResult:
+    """POST /api/sessions/{name}/input."""
+
+    session: str
+    snapshot: str
+
+
+@dataclass(frozen=True)
+class CommandResult:
+    """Result of `run_shell_command()`."""
+
+    session: str
+    exit_code: int
+    snapshot: str
+    elapsed: float
+    token: str

muxplex_client/sentinel.py

@@ -0,0 +1,80 @@
+"""Completion sentinel for driving a shell command to completion over the API.
+
+Pure, no I/O -- fully testable without a server, and directly reusable by a
+caller who wants to run their own poll loop instead of `run_shell_command()`.
+
+ASSUMES the target pane is an idle POSIX-ish shell prompt. None of this holds
+for a pane running vim, a REPL, `less`, a TUI, an ssh session, or fish/nushell
+(`$status`, `$env.LAST_EXIT_CODE`) unless the caller supplies a matching
+`exit_expr`. See AGENT_GUIDE.md §6.2/§6.4 for the operational convention this
+implements.
+"""
+
+from __future__ import annotations
+
+import re
+import secrets
+from dataclasses import dataclass
+
+# Length (in random bytes, before urlsafe-base64 encoding) of an
+# auto-generated token. Short enough to keep the composed shell line
+# readable, long enough that two concurrent commands in the same session
+# don't collide.
+_TOKEN_BYTES = 6
+
+
+@dataclass(frozen=True)
+class Sentinel:
+    """A single-use completion marker: a token plus its digit-anchored regex."""
+
+    token: str
+    pattern: re.Pattern[str]  # MUXPLEX_DONE_<token>_EXIT_(\d+)
+
+    def wrap(
+        self, command: str, *, bell_on_failure: bool = True, exit_expr: str = "$?"
+    ) -> str:
+        """Compose the one-liner from AGENT_GUIDE.md §6.2/§6.4:
+
+            <cmd>; rc=<exit_expr>; [ $rc -ne 0 ] && printf '\\a'; \\
+                echo "MUXPLEX_DONE_<token>_EXIT_$rc"
+
+        With bell_on_failure=False, the `printf '\\a'` clause is omitted
+        entirely (never fire the bell for a routine, expected-to-fail
+        check, per AGENT_GUIDE.md §6.4's recommended convention: ring on
+        nonzero exit only, never on routine success).
+        """
+        parts = [command, f"rc={exit_expr}"]
+        if bell_on_failure:
+            parts.append("[ $rc -ne 0 ] && printf '\\a'")
+        parts.append(f'echo "MUXPLEX_DONE_{self.token}_EXIT_$rc"')
+        return "; ".join(parts)
+
+    def search(self, snapshot: str) -> int | None:
+        """Digit-anchored match. Returns the real exit code, or None.
+
+        The digit anchor is load-bearing: tmux echoes your input line into
+        the pane BEFORE the shell runs it, so the literal, unexpanded
+        "...EXIT_$?" text is visible in the pane immediately -- before the
+        command has even started, let alone finished. A bare-token
+        substring check (`"MUXPLEX_DONE_<token>" in snapshot`) false-matches
+        on that echo and reports "done" with a bogus exit code instantly.
+        Shell expansion never happens inside that echoed input line, so
+        `\\d+` only ever matches the version the shell actually wrote back
+        out after running the command to completion.
+
+        Do NOT "simplify" this to a bare-token check -- see
+        `tests/test_sentinel.py::test_digit_anchor_regression` for the
+        regression this guards against.
+        """
+        match = self.pattern.search(snapshot)
+        if match is None:
+            return None
+        return int(match.group(1))
+
+
+def make_sentinel(token: str | None = None) -> Sentinel:
+    """Create a new Sentinel. `token` defaults to a short random urlsafe string."""
+    if token is None:
+        token = secrets.token_urlsafe(_TOKEN_BYTES)
+    pattern = re.compile(rf"MUXPLEX_DONE_{re.escape(token)}_EXIT_(\d+)")
+    return Sentinel(token=token, pattern=pattern)

muxplex_client/sync_client.py

@@ -0,0 +1,295 @@
+"""Synchronous muxplex API client (httpx.Client transport).
+
+Thin await-free shell over `_protocol.py` -- see that module's docstring.
+Signature-identical to `async_client.AsyncMuxplexClient` with `await` and an
+`Async` prefix.
+"""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+from typing import Any, Self, Sequence
+
+import httpx
+
+from . import _protocol as protocol
+from .constants import MIN_SERVER_VERSION
+from .errors import CommandTimeout, MuxplexError, UnreachableError
+from .models import (
+    CommandResult,
+    ConnectResult,
+    InputResult,
+    InstanceInfo,
+    ServerState,
+    Session,
+    SessionSnapshot,
+    Settings,
+    ViewResult,
+)
+from .sentinel import make_sentinel
+
+
+class MuxplexClient:
+    """Thin, typed, synchronous HTTP client for the muxplex API.
+
+    Always sets `Accept: application/json` and `follow_redirects=False` in
+    the constructor -- not left to callers. Without the header the auth
+    middleware 307s an unauthenticated request to `/login`; a client that
+    follows redirects would get a `200 OK` full of login-page HTML instead
+    of the `401` it should see (AGENT_GUIDE.md §1).
+
+    `federation_key=None` means "no credential" -- a localhost caller needs
+    none (AGENT_GUIDE.md §1.1); an agent running on the same host as the
+    server should not be forced to invent one.
+    """
+
+    def __init__(
+        self,
+        server_url: str,
+        federation_key: str | None = None,
+        *,
+        ca_file: Path | str | None = None,
+        timeout: float = 5.0,
+        client: httpx.Client | None = None,
+    ) -> None:
+        if client is not None:
+            self._client = client
+            self._owns_client = False
+            return
+        headers = {"Accept": "application/json"}
+        if federation_key:
+            headers["Authorization"] = f"Bearer {federation_key}"
+        # ca_file must be the CA, never the leaf -- a documented, expensive
+        # footgun in this project (see AGENTS.md's "GET /api/ca" section).
+        verify: bool | str = str(ca_file) if ca_file else True
+        self._client = httpx.Client(
+            base_url=server_url,
+            headers=headers,
+            verify=verify,
+            timeout=timeout,
+            follow_redirects=False,
+        )
+        self._owns_client = True
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: dict[str, Any] | None = None,
+        session_name: str | None = None,
+    ) -> Any:
+        try:
+            response = self._client.request(method, path, params=params, json=json)
+        except httpx.HTTPError as exc:
+            raise UnreachableError(f"{method} {path} failed: {exc}") from exc
+        if response.status_code >= 400:
+            raise protocol.map_status_error(
+                response.status_code,
+                path,
+                _extract_detail(response),
+                session_name=session_name,
+            )
+        return response.json()
+
+    # ---- read ----
+
+    def instance_info(self) -> InstanceInfo:
+        """GET /api/instance-info -- public, no auth required."""
+        return protocol.parse_instance_info(self._request("GET", "/api/instance-info"))
+
+    def sessions(self) -> list[Session]:
+        """GET /api/sessions -- the shared, ~2s-cycle poll cache."""
+        return protocol.parse_sessions(self._request("GET", "/api/sessions"))
+
+    def session(self, name: str, *, lines: int | None = None) -> SessionSnapshot:
+        """GET /api/sessions/{name} -- one fresh capture-pane at a chosen depth."""
+        params = {"lines": lines} if lines is not None else None
+        return protocol.parse_session_snapshot(
+            self._request(
+                "GET", f"/api/sessions/{name}", params=params, session_name=name
+            )
+        )
+
+    def view(self, *, sort: str | None = None) -> ViewResult:
+        """GET /api/view -- the server-resolved current view."""
+        params = {"sort": sort} if sort is not None else None
+        return protocol.parse_view_result(
+            self._request("GET", "/api/view", params=params)
+        )
+
+    def state(self) -> ServerState:
+        """GET /api/state."""
+        return protocol.parse_server_state(self._request("GET", "/api/state"))
+
+    def settings(self) -> Settings:
+        """GET /api/settings."""
+        return protocol.parse_settings(self._request("GET", "/api/settings"))
+
+    # ---- lifecycle ----
+
+    def create_session(
+        self,
+        name: str,
+        *,
+        wait: bool = True,
+        timeout: float = 6.0,
+        interval: float = 0.3,
+    ) -> None:
+        """POST /api/sessions. With wait=True, polls until the session is
+        visible in the ~2s read cache -- 0.3s interval, 6s ceiling, the
+        measured schedule from AGENT_GUIDE.md §4. Raises TimeoutError if
+        it never appears.
+        """
+        self._request("POST", "/api/sessions", json={"name": name}, session_name=name)
+        if wait and not self.wait_for_session(name, timeout=timeout, interval=interval):
+            raise TimeoutError(
+                f"session {name!r} did not appear in the read cache within {timeout}s"
+            )
+
+    def delete_session(self, name: str) -> None:
+        """DELETE /api/sessions/{name}."""
+        self._request("DELETE", f"/api/sessions/{name}", session_name=name)
+
+    def wait_for_session(
+        self, name: str, *, timeout: float = 6.0, interval: float = 0.3
+    ) -> bool:
+        """Poll GET /api/sessions until *name* appears (poll-cache race)."""
+        deadline = time.monotonic() + timeout
+        while True:
+            if any(s.name == name for s in self.sessions()):
+                return True
+            if time.monotonic() >= deadline:
+                return False
+            time.sleep(interval)
+
+    def connect(self, name: str) -> ConnectResult:
+        """POST /api/sessions/{name}/connect.
+
+        WARNING: active_session is server-global. This moves the human's
+        browser view too.
+        """
+        return protocol.parse_connect_result(
+            self._request("POST", f"/api/sessions/{name}/connect", session_name=name)
+        )
+
+    def set_active_view(self, view: str) -> None:
+        """PATCH /api/state {"active_view": view}.
+
+        WARNING: active_view is server-global, last-writer-wins.
+        """
+        self._request("PATCH", "/api/state", json={"active_view": view})
+
+    # ---- input ----
+
+    def send_input(
+        self,
+        name: str,
+        *,
+        text: str = "",
+        keys: Sequence[str] = (),
+        enter: bool = False,
+        lines: int | None = None,
+    ) -> InputResult:
+        """POST /api/sessions/{name}/input.
+
+        At least one of text/keys/enter must be non-empty (else the server
+        400s). Send order is text -> keys -> enter. Note that
+        keys=["Enter"] with enter=True sends TWO Enters.
+        """
+        body: dict[str, Any] = {"text": text, "keys": list(keys), "enter": enter}
+        if lines is not None:
+            body["lines"] = lines
+        return protocol.parse_input_result(
+            self._request(
+                "POST", f"/api/sessions/{name}/input", json=body, session_name=name
+            )
+        )
+
+    def run_shell_command(
+        self,
+        name: str,
+        command: str,
+        *,
+        timeout: float = 600.0,
+        poll_interval: float = 2.0,
+        lines: int = 500,
+        bell_on_failure: bool = True,
+        exit_expr: str = "$?",
+        token: str | None = None,
+    ) -> CommandResult:
+        """Run *command* to completion and return its real exit code.
+
+        ASSUMES the target pane is an idle POSIX shell prompt. If it is not
+        (vim, a REPL, less, a TUI, an ssh session), this types a line into
+        whatever is running and raises CommandTimeout.
+
+        Composed entirely from send_input() + session() + Sentinel; rebuild
+        it yourself from those if this shape does not fit.
+
+        Raises CommandTimeout, InputForbidden, SessionNotFound.
+        """
+        sentinel = make_sentinel(token)
+        wrapped = sentinel.wrap(
+            command, bell_on_failure=bell_on_failure, exit_expr=exit_expr
+        )
+        self.send_input(name, text=wrapped, enter=True)
+
+        start = time.monotonic()
+        deadline = start + timeout
+        while True:
+            snap = self.session(name, lines=lines)
+            exit_code = sentinel.search(snap.snapshot)
+            if exit_code is not None:
+                return CommandResult(
+                    session=name,
+                    exit_code=exit_code,
+                    snapshot=snap.snapshot,
+                    elapsed=time.monotonic() - start,
+                    token=sentinel.token,
+                )
+            if time.monotonic() >= deadline:
+                raise CommandTimeout(
+                    session=name,
+                    token=sentinel.token,
+                    elapsed=time.monotonic() - start,
+                    snapshot=snap.snapshot,
+                )
+            time.sleep(poll_interval)
+
+    # ---- opt-in version check ----
+
+    def check_server(self, min_version: str = MIN_SERVER_VERSION) -> InstanceInfo:
+        """Fetch instance-info and raise MuxplexError if the server is older.
+
+        Never called automatically.
+        """
+        info = self.instance_info()
+        if protocol.version_tuple(info.version) < protocol.version_tuple(min_version):
+            raise MuxplexError(
+                f"server version {info.version!r} is older than required {min_version!r}"
+            )
+        return info
+
+
+def _extract_detail(response: httpx.Response) -> str:
+    """Best-effort extraction of a FastAPI-style {"detail": ...} error body."""
+    try:
+        body = response.json()
+        if isinstance(body, dict) and "detail" in body:
+            return str(body["detail"])
+    except Exception:
+        pass
+    return response.text

muxplex_client-0.19.0.dist-info/METADATA

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: muxplex-client
+Version: 0.19.0
+Summary: Typed sync/async HTTP client for the muxplex API
+Project-URL: Repository, https://github.com/bkrabach/muxplex
+Project-URL: Issues, https://github.com/bkrabach/muxplex/issues
+Author-email: Brian Krabach <brian@krabach.com>
+License: MIT
+Keywords: api,client,http,muxplex,tmux
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# muxplex-client
+
+Typed sync/async HTTP client for the [muxplex](https://github.com/bkrabach/muxplex)
+tmux-session-dashboard API.
+
+Ships as its own PyPI distribution (import name `muxplex_client`) so a
+consumer that only needs to make ~12 HTTP calls -- a Stream Deck sidecar, an
+Amplifier tool module -- never has to install the server's dependencies
+(fastapi, uvicorn, python-pam, ...) or its `muxplex` server console script.
+See [`../muxplex-client-design.md`](../muxplex-client-design.md) for the full
+design rationale.
+
+## Install
+
+```bash
+pip install muxplex-client
+```
+
+Runtime dependency: `httpx>=0.27.0`. Nothing else -- no `muxplex` server
+dependency, no console script installed.
+
+## Usage
+
+Synchronous:
+
+```python
+from muxplex_client import MuxplexClient
+
+with MuxplexClient("https://your-server:8088", "federation-key") as client:
+    for session in client.sessions():
+        if session.bell.needs_attention:
+            print(f"{session.name} needs attention")
+```
+
+Asynchronous (Amplifier tool modules, or any asyncio caller):
+
+```python
+from muxplex_client import AsyncMuxplexClient
+
+async with AsyncMuxplexClient("https://your-server:8088", "federation-key") as client:
+    result = await client.run_shell_command("my-session", "pytest -q")
+    print(result.exit_code, result.elapsed)
+```
+
+A localhost caller needs no credential -- `federation_key=None` is the
+default and is fine when running on the same host as the server.
+
+## What's in here vs. what isn't
+
+See `muxplex-client-design.md` §3 for the full included/excluded endpoint
+table and rationale. Notably excluded: `PATCH /api/settings` (highest
+blast-radius operation in the API; a v2 concern requiring CAS + 409 retry +
+backstop discrimination), all federation endpoints (server-to-server
+protocol, no client consumer), and `/api/internal/setup-hooks` (internal,
+self-healing as of server v0.18.0).
+
+## Version alignment
+
+`muxplex_client.__version__` is cut in lockstep with the muxplex server
+version -- one `vX.Y.Z` tag publishes both wheels. This is provenance
+("cut against server X"), not a runtime requirement: the client declares no
+dependency on the `muxplex` package and enforces no version at runtime.
+`MIN_SERVER_VERSION` backs an opt-in `check_server()` helper the caller may
+call; it is never invoked automatically.
+
+The load-bearing correctness mechanism is
+`muxplex/tests/test_client_contract.py`, living in the **server's** own test
+suite: it drives this client over `httpx.ASGITransport` against the real
+FastAPI app and asserts every field the client parses actually exists on the
+real response, that mirrored constants (`KNOWN_KEYS`, `MAX_CAPTURE_LINES`,
+`DEFAULT_CAPTURE_LINES`) equal their server originals, and that
+`Bell.needs_attention` agrees with the server's own predicate across a truth
+table.
+
+## The shell-command sentinel
+
+`run_shell_command()` (and the lower-level `muxplex_client.sentinel` module)
+implements the completion-detection convention from `AGENT_GUIDE.md` §6.2/§6.4:
+wrap a command with `; rc=$?; ... ; echo "MUXPLEX_DONE_<token>_EXIT_$rc"` and
+poll the pane for the marker.
+
+**This assumes the target pane is an idle POSIX shell prompt.** It is *not* a
+general HTTP contract -- it fails (types a garbage line into whatever is
+actually running, then hangs until timeout) against vim, a REPL, `less`, a
+TUI, an ssh session, or a non-POSIX shell without a matching `exit_expr`.
+
+The one correctness rule worth calling out explicitly: matching must be
+**digit-anchored** (`MUXPLEX_DONE_<token>_EXIT_(\d+)`), never a bare-token
+substring check. tmux echoes the literal, unexpanded `...EXIT_$?` into the
+pane the instant you send the line -- before the shell has even run it -- so
+a bare-token match reports "done" with a bogus exit code immediately. See
+`muxplex_client/sentinel.py`'s docstring and `tests/test_sentinel.py`'s
+digit-anchor regression test.
+
+## Development
+
+```bash
+uv sync --extra dev   # from this directory, or from the repo root via the
+                       # [tool.uv.workspace] declaration
+uv run pytest
+```
+
+`tests/` is pure -- no network, no server import, and passes with `muxplex`
+not installed at all.

muxplex_client-0.19.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+muxplex_client/__init__.py,sha256=soQxrx4jsGdQWk4VLCI1-rdIfPE7Z7vGtjx2_Tg7EpY,2263
+muxplex_client/_protocol.py,sha256=vazzprjvzLdJKjGm0uPQRe4_9GPZd0zK34wqFF7kgO8,6721
+muxplex_client/async_client.py,sha256=OgOP6SlnUIHcLmm5XCOTPaI-j9pBglCkZQ5J5cOdPe0,8765
+muxplex_client/constants.py,sha256=9ozPCO-RATK0rGaW3SMkdhzepToRGONUWIQcleYEfxI,1417
+muxplex_client/errors.py,sha256=JMll3s1XRXtC9fCWr5D-YbUXDhxJVK072ZoMmCxLJqQ,2759
+muxplex_client/models.py,sha256=b4xfBKKE9lmfiDVYw15oWiw-5tbUMQ8_9PX4UO9oKTg,4516
+muxplex_client/sentinel.py,sha256=Dl-omK35y4yHfbSYx26ARnvJBWcO-rQ_L3jlnZxs9EQ,3333
+muxplex_client/sync_client.py,sha256=Y4pfJpTdUWr5yPNgaCT0TXtR156RFCrfofIeWiyZ-5M,10168
+muxplex_client-0.19.0.dist-info/METADATA,sha256=94pqY8ebVaZZx8hJo2VIhWDO9QJRMXRwvPOSMDtussE,5073
+muxplex_client-0.19.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+muxplex_client-0.19.0.dist-info/RECORD,,

muxplex_client-0.19.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any