machinaos 0.0.78 → 0.0.80

package/server/services/cli_agent/transports/__init__.py

@@ -0,0 +1,47 @@
+"""PTY transports for driving interactive CLI agents (claude) cross-platform.
+
+Public surface:
+
+  - ``PtyTransport`` / ``PtyHandle`` Protocols (in :mod:`.base`).
+  - ``get_pty_transport()`` factory picks the right backend for the
+    current platform — ``ptyprocess`` on POSIX, ``pywinpty>=3.0.3`` on
+    Windows. Both run in-process behind the same Protocol so the rest
+    of ``services/cli_agent/`` is platform-agnostic.
+
+If ``pywinpty`` / ``ptyprocess`` stability ever becomes an issue, the
+deferred upgrade path is an out-of-process Python pty-host subprocess
+(VSCode's ``ptyHostMain.ts`` pattern, in Python) — the Protocol
+boundary makes that swap cheap. See
+``docs-internal/claude_code_interactive_mode.md`` for the topology
+rationale.
+"""
+
+from __future__ import annotations
+
+import sys
+
+from .base import PtyHandle, PtyTransport
+
+__all__ = [
+    "PtyHandle",
+    "PtyTransport",
+    "get_pty_transport",
+]
+
+
+def get_pty_transport() -> PtyTransport:
+    """Return the appropriate ``PtyTransport`` for the current platform.
+
+    Lazy-imports the backend module so the heavy native dep (ptyprocess
+    on POSIX, pywinpty on Windows) is only loaded when something
+    actually needs to drive a PTY — keeps ``services.cli_agent``
+    importable in unit-test environments where the native dep may be
+    missing.
+    """
+    if sys.platform == "win32":
+        from .windows import WindowsPtyTransport
+
+        return WindowsPtyTransport()
+    from .posix import PosixPtyTransport
+
+    return PosixPtyTransport()

package/server/services/cli_agent/transports/base.py

@@ -0,0 +1,111 @@
+"""Structural Protocols for PTY transports.
+
+Two interfaces:
+
+  - ``PtyTransport`` — factory for spawning. One per process; obtained
+    from :func:`services.cli_agent.transports.get_pty_transport`.
+  - ``PtyHandle`` — one live PTY-attached subprocess. Owns the PTY
+    pair (master + slave), the spawned process, and the lifecycle
+    primitives (write, kill, alive-check) the session pool needs.
+
+The handles are intentionally minimal — they expose only what the
+``ClaudeSessionPool`` and ``AICliSession`` need to drive an interactive
+``claude`` while reading events from the on-disk session JSONL. We
+never read PTY stdout in the steady state (the TUI's ANSI output is
+discarded), so ``read``/``recv`` are deliberately absent — adding them
+would invite the same TUI-scraping rabbit hole NousResearch's Hermes
+Agent is in.
+
+The Protocols are intentionally not declared ``@runtime_checkable``:
+``isinstance(x, PtyTransport)`` would pass any object with the right
+method names but is misleading for Protocols carrying behavioural
+contracts (lifecycle, threading guarantees). Static type-checkers
+still enforce structural conformance at the factory call site.
+"""
+
+from __future__ import annotations
+
+import signal
+from pathlib import Path
+from typing import Dict, List, Protocol
+
+
+class PtyHandle(Protocol):
+    """One live PTY-attached subprocess.
+
+    Implementations:
+      - :class:`services.cli_agent.transports.posix.PosixPtyHandle` —
+        wraps ``ptyprocess.PtyProcess``.
+      - :class:`services.cli_agent.transports.windows.WindowsPtyHandle` —
+        wraps ``pywinpty.PTY``.
+
+    Thread-safety: not promised. The session pool serialises access
+    under a per-key ``asyncio.Lock`` so concurrent writes / kills don't
+    race. Backends should still treat ``write`` as a single point-in-time
+    operation (no internal buffering across calls).
+    """
+
+    @property
+    def pid(self) -> int:
+        """OS pid of the spawned subprocess. Used by ``Job Object``
+        enrollment and the operator log."""
+
+    def is_alive(self) -> bool:
+        """``True`` while the subprocess is running, ``False`` after it
+        exits or is killed. Cheap to call (no syscall on the hot path
+        when possible)."""
+
+    async def write(self, data: bytes) -> None:
+        """Write raw bytes to the PTY master.
+
+        Used both for the user's prompt and for slash commands
+        (``/clear``, ``/compact``). Callers append the right line
+        terminator — typically ``b"\\r"`` for interactive mode (claude's
+        Ink TUI listens for Enter, not stdin-close; see
+        `claude-code#15553 <https://github.com/anthropics/claude-code/issues/15553>`_).
+        """
+
+    async def kill(self, signal_: int = signal.SIGTERM) -> None:
+        """Terminate the subprocess.
+
+        First-stage ``SIGTERM``; backends may escalate to ``SIGKILL``
+        after a grace window if the process doesn't exit on its own.
+        Windows ignores ``signal_`` and uses
+        ``TerminateProcess``/``CTRL_BREAK_EVENT`` semantics depending
+        on what the pywinpty handle supports.
+        """
+
+
+class PtyTransport(Protocol):
+    """Factory for spawning interactive subprocesses inside a PTY.
+
+    Implementations:
+      - :class:`services.cli_agent.transports.posix.PosixPtyTransport`
+        (uses ``ptyprocess``).
+      - :class:`services.cli_agent.transports.windows.WindowsPtyTransport`
+        (uses ``pywinpty>=3.0.3``).
+
+    There is one transport per process; ``services.cli_agent.transports
+    .get_pty_transport()`` picks the right one for the current platform.
+    """
+
+    async def spawn(
+        self,
+        argv: List[str],
+        *,
+        cwd: Path,
+        env: Dict[str, str],
+    ) -> PtyHandle:
+        """Spawn ``argv`` inside a fresh PTY pair under ``cwd`` with
+        the given ``env``.
+
+        Returns a live :class:`PtyHandle`. Raises ``FileNotFoundError``
+        if ``argv[0]`` isn't executable, ``OSError`` for PTY allocation
+        failures, and ``RuntimeError`` for backend-specific errors
+        (e.g. ConPTY not available on a too-old Windows build).
+
+        The handle is registered with the process tree supervisor
+        (:mod:`machina.tree` on Windows, ``os.setsid`` on POSIX) so the
+        child is reaped on host shutdown — see the existing
+        ``BaseProcessSupervisor`` patterns.
+        """

package/server/services/cli_agent/transports/posix.py

@@ -0,0 +1,196 @@
+"""POSIX ``PtyTransport`` backed by ``ptyprocess``.
+
+``ptyprocess.PtyProcess.spawn(...)`` wraps ``os.forkpty()`` and returns
+a PtyProcess that owns the master fd. The child runs in its own
+session (``os.setsid()`` is the default), so SIGTERM-then-SIGKILL on the
+child pid reaps the whole TUI process group. We bridge ptyprocess's sync
+API to asyncio with ``loop.run_in_executor`` only at the spawn/kill
+boundary — writes are single fast syscalls and run on the event-loop
+thread.
+
+We do NOT register an ``loop.add_reader`` on the master fd: in the new
+architecture the on-disk session JSONL is the protocol surface; PTY
+stdout is rendered TUI we never look at. Keeping the read side empty
+means no buffering races between fd-readiness and JSONL-watcher events.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import signal
+import time
+from pathlib import Path
+from typing import Dict, List, Optional
+
+from core.logging import get_logger
+
+from .base import PtyHandle, PtyTransport
+
+logger = get_logger(__name__)
+
+# How long to wait between SIGTERM and SIGKILL when killing a child.
+# Matches ``BaseProcessSupervisor.terminate_grace_seconds`` so the two
+# lifecycle layers agree on grace.
+_TERMINATE_GRACE_SECONDS = 5.0
+
+
+class PosixPtyHandle:
+    """ptyprocess-backed handle for one live ``claude`` subprocess."""
+
+    __slots__ = ("_proc", "_exited")
+
+    def __init__(self, proc: object) -> None:
+        # ``proc`` is a ``ptyprocess.PtyProcess`` but we keep it typed
+        # as ``object`` so the import remains lazy in :meth:`spawn`.
+        self._proc = proc
+        self._exited = False
+
+    @property
+    def pid(self) -> int:
+        return int(getattr(self._proc, "pid", -1))
+
+    def is_alive(self) -> bool:
+        if self._exited:
+            return False
+        try:
+            alive = bool(self._proc.isalive())  # type: ignore[attr-defined]
+        except Exception:
+            return False
+        if not alive:
+            self._exited = True
+        return alive
+
+    async def write(self, data: bytes) -> None:
+        # ptyprocess's write() is a single ``os.write`` call; fast
+        # enough to run on the event-loop thread.
+        if not data:
+            return
+        try:
+            self._proc.write(data)  # type: ignore[attr-defined]
+        except OSError as exc:
+            # EIO = the slave end closed (process exited). Surface as a
+            # clean ConnectionError so callers can distinguish from a
+            # genuine permission / FD-leak bug.
+            raise ConnectionError(f"PTY write failed (pid={self.pid}): {exc}") from exc
+
+    async def kill(self, signal_: int = signal.SIGTERM) -> None:
+        """SIGTERM, wait briefly, escalate to SIGKILL if still alive.
+
+        Matches ``BaseProcessSupervisor.terminate_then_kill`` behaviour
+        and the grace window from the existing process-tree supervisor.
+        """
+        if self._exited:
+            return
+
+        loop = asyncio.get_running_loop()
+
+        # First-stage signal. ptyprocess exposes terminate(force=False)
+        # for SIGTERM and terminate(force=True) for SIGKILL. We want the
+        # SIGTERM-then-SIGKILL cascade with our own grace window so we
+        # call signal helpers directly.
+        try:
+            await loop.run_in_executor(
+                None,
+                self._proc.kill,
+                signal_,  # type: ignore[attr-defined]
+            )
+        except (ProcessLookupError, OSError) as exc:
+            logger.debug("PTY first-stage signal raced exit: %s", exc)
+            self._exited = True
+            return
+
+        # Wait up to grace for graceful exit.
+        deadline = time.monotonic() + _TERMINATE_GRACE_SECONDS
+        while time.monotonic() < deadline:
+            if not self.is_alive():
+                self._exited = True
+                return
+            await asyncio.sleep(0.05)
+
+        # Escalate. ``kill(SIGKILL)`` is the documented force-quit path.
+        try:
+            await loop.run_in_executor(
+                None,
+                self._proc.kill,
+                signal.SIGKILL,  # type: ignore[attr-defined]
+            )
+        except (ProcessLookupError, OSError):
+            pass
+        self._exited = True
+
+        # Drain the ptyprocess so the OS-level zombie is reaped on next
+        # alive-check. No-op if already reaped.
+        try:
+            await loop.run_in_executor(None, self._proc.close, True)  # type: ignore[attr-defined]
+        except Exception:
+            pass
+
+
+class PosixPtyTransport(PtyTransport):
+    """Spawn factory using ``ptyprocess``.
+
+    Lazy-imports ``ptyprocess`` so test environments missing the dep
+    can still import :mod:`services.cli_agent.transports` (the factory
+    only loads this backend on POSIX). Raises ``RuntimeError`` if the
+    dep is genuinely missing at spawn time.
+    """
+
+    def __init__(self) -> None:
+        # Cache the imported class on first use so we don't repeat the
+        # try/except on every spawn.
+        self._pty_process_cls: Optional[object] = None
+
+    def _load_ptyprocess(self) -> object:
+        if self._pty_process_cls is not None:
+            return self._pty_process_cls
+        try:
+            from ptyprocess import PtyProcess  # type: ignore[import-not-found]
+        except ImportError as exc:
+            raise RuntimeError(
+                "PosixPtyTransport requires the 'ptyprocess' package. "
+                "Install it (e.g. `pip install ptyprocess>=0.7.0`) — it's "
+                "declared in server/pyproject.toml with the marker "
+                "`sys_platform != 'win32'`."
+            ) from exc
+        self._pty_process_cls = PtyProcess
+        return PtyProcess
+
+    async def spawn(
+        self,
+        argv: List[str],
+        *,
+        cwd: Path,
+        env: Dict[str, str],
+    ) -> PtyHandle:
+        if not argv:
+            raise ValueError("PosixPtyTransport.spawn: empty argv")
+
+        PtyProcess = self._load_ptyprocess()  # noqa: N806 — class name
+
+        binary = argv[0]
+        if not os.path.exists(binary):
+            # Mirror BaseProcessSupervisor's pre-spawn check so the
+            # error matches the existing operator-log shape.
+            raise FileNotFoundError(f"PTY binary not found: {binary}")
+
+        loop = asyncio.get_running_loop()
+        proc = await loop.run_in_executor(
+            None,
+            lambda: PtyProcess.spawn(  # type: ignore[attr-defined]
+                argv,
+                cwd=str(cwd),
+                env=env,
+                # 80x24 default matches what Ink/most TUI libraries
+                # expect on a non-terminal-attached spawn. We don't
+                # render anywhere, so the dimensions are cosmetic.
+                dimensions=(24, 80),
+            ),
+        )
+        logger.info(
+            "[PtyTransport posix] spawned pid=%s cwd=%s argv0=%s",
+            getattr(proc, "pid", "?"),
+            cwd,
+            binary,
+        )
+        return PosixPtyHandle(proc)

package/server/services/cli_agent/transports/windows.py

@@ -0,0 +1,189 @@
+"""Windows ``PtyTransport`` backed by ``pywinpty>=3.0.3``.
+
+``pywinpty`` v3.x is Rust-backed via PyO3 + winpty-rs + Maturin. Mirrors
+ptyprocess's high-level API closely (``PtyProcess.spawn(argv, cwd=,
+env=, dimensions=)``, ``write``, ``isalive``, ``kill``, ``close``) so
+this file's shape mirrors :mod:`.posix`. The pywinpty maintainers ship
+prebuilt wheels for Python 3.9-3.14 including free-threading, so
+end-users don't need a C++ build toolchain.
+
+Used in production by Jupyter Lab terminals and Spyder's IPython
+console — same production maturity bar as ptyprocess on POSIX. See
+the upgrade-path note in :mod:`services.cli_agent.transports` for the
+out-of-process pty-host fallback if pywinpty stability ever degrades.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import signal
+import time
+from pathlib import Path
+from typing import Dict, List, Optional
+
+from core.logging import get_logger
+
+from .base import PtyHandle, PtyTransport
+
+logger = get_logger(__name__)
+
+# Match POSIX backend's grace window so the two lifecycle layers agree.
+_TERMINATE_GRACE_SECONDS = 5.0
+
+
+class WindowsPtyHandle:
+    """pywinpty-backed handle for one live ``claude`` subprocess."""
+
+    __slots__ = ("_proc", "_exited")
+
+    def __init__(self, proc: object) -> None:
+        self._proc = proc
+        self._exited = False
+
+    @property
+    def pid(self) -> int:
+        return int(getattr(self._proc, "pid", -1))
+
+    def is_alive(self) -> bool:
+        if self._exited:
+            return False
+        try:
+            alive = bool(self._proc.isalive())  # type: ignore[attr-defined]
+        except Exception:
+            return False
+        if not alive:
+            self._exited = True
+        return alive
+
+    async def write(self, data: bytes) -> None:
+        if not data:
+            return
+        # pywinpty v3's ``PtyProcess.write`` is str-only — the underlying
+        # Rust core's ``self.pty.write(s)`` raises
+        # ``TypeError: argument 'to_write': 'bytes' object cannot be cast
+        # as 'str'`` on bytes. POSIX ``ptyprocess`` is bytes-native; the
+        # ``PtyHandle`` Protocol picks bytes for that reason. We decode
+        # at this boundary so the rest of the stack stays bytes-only.
+        # Defer the actual WriteFile to a worker thread because ConPTY
+        # can briefly block under back-pressure
+        # (https://github.com/microsoft/node-pty/issues/388).
+        try:
+            text = data.decode("utf-8")
+        except UnicodeDecodeError as exc:
+            raise ConnectionError(f"PTY write failed (pid={self.pid}): non-UTF-8 payload: {exc}") from exc
+        loop = asyncio.get_running_loop()
+        try:
+            await loop.run_in_executor(
+                None,
+                self._proc.write,
+                text,  # type: ignore[attr-defined]
+            )
+        except OSError as exc:
+            raise ConnectionError(f"PTY write failed (pid={self.pid}): {exc}") from exc
+
+    async def kill(self, signal_: int = signal.SIGTERM) -> None:
+        """First-stage WM_CLOSE / SIGTERM equivalent, wait briefly,
+        escalate to TerminateProcess if still alive.
+
+        Windows doesn't have POSIX signals; pywinpty maps the
+        ``kill(signal_)`` call to the closest analogue (TerminateProcess
+        with the exit code, or ``CTRL_BREAK_EVENT`` when the process
+        was spawned into its own console group). ``force=True`` is the
+        unconditional escalation.
+        """
+        if self._exited:
+            return
+
+        loop = asyncio.get_running_loop()
+
+        try:
+            await loop.run_in_executor(
+                None,
+                self._proc.kill,
+                signal_,  # type: ignore[attr-defined]
+            )
+        except (ProcessLookupError, OSError) as exc:
+            logger.debug("ConPTY first-stage signal raced exit: %s", exc)
+            self._exited = True
+            return
+
+        deadline = time.monotonic() + _TERMINATE_GRACE_SECONDS
+        while time.monotonic() < deadline:
+            if not self.is_alive():
+                self._exited = True
+                return
+            await asyncio.sleep(0.05)
+
+        # Escalate. ``close(force=True)`` calls TerminateProcess on the
+        # child and frees the ConPTY handle.
+        try:
+            await loop.run_in_executor(None, self._proc.close, True)  # type: ignore[attr-defined]
+        except (ProcessLookupError, OSError):
+            pass
+        self._exited = True
+
+
+class WindowsPtyTransport(PtyTransport):
+    """Spawn factory using ``pywinpty>=3.0.3``.
+
+    Lazy-imports ``winpty`` (the importable package name for pywinpty)
+    so test environments missing the dep can still import this module
+    on non-Windows; the factory in
+    :mod:`services.cli_agent.transports` only loads this backend when
+    ``sys.platform == 'win32'``.
+    """
+
+    def __init__(self) -> None:
+        self._pty_process_cls: Optional[object] = None
+
+    def _load_winpty(self) -> object:
+        if self._pty_process_cls is not None:
+            return self._pty_process_cls
+        try:
+            from winpty import PtyProcess  # type: ignore[import-not-found]
+        except ImportError as exc:
+            raise RuntimeError(
+                "WindowsPtyTransport requires 'pywinpty>=3.0.3'. "
+                "Install it (e.g. `pip install pywinpty>=3.0.3`) — it's "
+                "declared in server/pyproject.toml with the marker "
+                "`sys_platform == 'win32'`. Prebuilt wheels are "
+                "available for Python 3.9-3.14; no C++ toolchain "
+                "required."
+            ) from exc
+        self._pty_process_cls = PtyProcess
+        return PtyProcess
+
+    async def spawn(
+        self,
+        argv: List[str],
+        *,
+        cwd: Path,
+        env: Dict[str, str],
+    ) -> PtyHandle:
+        if not argv:
+            raise ValueError("WindowsPtyTransport.spawn: empty argv")
+
+        PtyProcess = self._load_winpty()  # noqa: N806
+
+        binary = argv[0]
+        if not os.path.exists(binary):
+            raise FileNotFoundError(f"PTY binary not found: {binary}")
+
+        loop = asyncio.get_running_loop()
+        proc = await loop.run_in_executor(
+            None,
+            lambda: PtyProcess.spawn(  # type: ignore[attr-defined]
+                argv,
+                cwd=str(cwd),
+                env=env,
+                dimensions=(24, 80),
+            ),
+        )
+        logger.info(
+            "[PtyTransport windows] spawned pid=%s cwd=%s argv0=%s",
+            getattr(proc, "pid", "?"),
+            cwd,
+            binary,
+        )
+        return WindowsPtyHandle(proc)