tsugite-pty 0.17.0__tar.gz

tsugite_pty-0.17.0/.gitignore

@@ -0,0 +1,184 @@
+# ---> Python
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+.env
+.env
+benchmark_results/
+test_output/
+.claude/settings.local.json
+std*.txt
+secrets/*
+
+
+# TODO: temp - I need to clean up the docs
+docs-old/
+docs/design/
+examples/*
+!examples/tsugite-example-plugin/
+agents/
+.claude/
+.tsugite/
+benchmarks/
+docker-compose.test.yml
+#### TODO ^^^

tsugite_pty-0.17.0/PKG-INFO

@@ -0,0 +1,6 @@
+Metadata-Version: 2.4
+Name: tsugite-pty
+Version: 0.17.0
+Summary: Tsugite plugin: PTY terminal runtime and tools (daemon-only)
+Requires-Python: >=3.11
+Requires-Dist: tsugite-cli==0.17.0

tsugite_pty-0.17.0/pyproject.toml

@@ -0,0 +1,25 @@
+[project]
+name = "tsugite-pty"
+version = "0.17.0"
+description = "Tsugite plugin: PTY terminal runtime and tools (daemon-only)"
+requires-python = ">=3.11"
+dependencies = ["tsugite-cli==0.17.0"]
+
+[project.entry-points."tsugite.plugins"]
+pty = "tsugite_pty.tools"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["tsugite_pty"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "/tsugite_pty",
+  "/pyproject.toml",
+]
+
+[tool.uv.sources]
+tsugite-cli = { workspace = true }

tsugite_pty-0.17.0/tsugite_pty/__init__.py

@@ -0,0 +1,28 @@
+"""Tsugite plugin: PTY terminal runtime + tools (daemon-only).
+
+`tsugite-daemon` depends on this package and wires the runtime via
+`tools.set_terminal_runtime`. The `pty_*` tools register through the
+`tsugite.plugins` entry point (`tsugite_pty.tools`) and degrade gracefully when no
+runtime is wired (i.e. outside the daemon).
+"""
+
+from tsugite_pty.pty_manager import DEFAULT_BUFFER_CAP, PtyManager, PtyProcess
+from tsugite_pty.terminal_runtime import set_session_sandbox_resolver, spawn_terminal
+from tsugite_pty.terminal_store import (
+    TerminalSession,
+    TerminalSessionStore,
+    TerminalState,
+    TerminalStateTransitionError,
+)
+
+__all__ = [
+    "DEFAULT_BUFFER_CAP",
+    "PtyManager",
+    "PtyProcess",
+    "TerminalSession",
+    "TerminalSessionStore",
+    "TerminalState",
+    "TerminalStateTransitionError",
+    "set_session_sandbox_resolver",
+    "spawn_terminal",
+]

tsugite_pty-0.17.0/tsugite_pty/pty_manager.py

@@ -0,0 +1,401 @@
+"""Daemon-managed PTY processes for the terminal viewer.
+
+Uses stdlib `os.openpty` + `subprocess.Popen` (no external dep). One background
+thread per PTY drains the master fd into a ring buffer and dispatches each chunk
+to any subscribed callbacks. Subscribers (e.g. the SSE handler) get raw bytes
+including ANSI escapes; encoding/JSON-framing is left to the caller.
+
+The ring buffer is capped (default 1 MB). Output beyond the cap drops from the
+buffer but `bytes_out` keeps counting, and a `truncated` flag flips True so the
+UI can show "+47 MB truncated" without us holding 47 MB of memory.
+
+State + persistence lives in `terminal_store.py`. This module is the runtime
+side: spawn, read, write stdin, kill.
+"""
+
+from __future__ import annotations
+
+import errno
+import fcntl
+import logging
+import os
+import pty
+import signal
+import subprocess
+import termios
+import threading
+import time
+from typing import Callable, Optional
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_BUFFER_CAP = 1024 * 1024  # 1 MB
+
+
+def _acquire_controlling_tty() -> None:
+    """preexec_fn for PTY children: new session + claim the slave as ctty.
+
+    Runs in the forked child after subprocess has dup'd the slave onto fds
+    0/1/2 but before exec. ``setsid()`` makes the child a session leader (so we
+    can signal the whole tree by pgid); ``TIOCSCTTY`` then makes the slave
+    (fd 0) the session's controlling terminal with the child as its foreground
+    process group. Without that step a Ctrl+C byte written to the master is not
+    guaranteed to raise SIGINT - it works on some kernels and silently no-ops on
+    others (notably CI runners), so terminal-driven interrupts must not rely on
+    ``setsid`` alone.
+    """
+    os.setsid()
+    fcntl.ioctl(0, termios.TIOCSCTTY, 0)
+
+
+SIGKILL_GRACE_SECONDS = 2.0
+_READ_CHUNK_SIZE = 8192
+
+
+class PtyProcess:
+    """A single PTY-backed subprocess with a ring-buffered output stream.
+
+    Construct via `PtyProcess.spawn(...)`. The reader thread starts immediately
+    so subscribers attached after spawn still get every chunk after subscription;
+    chunks emitted before subscription are NOT replayed (the buffer is for that).
+    """
+
+    def __init__(
+        self,
+        proc: subprocess.Popen,
+        master_fd: int,
+        cmd: list[str],
+        buffer_cap: int = DEFAULT_BUFFER_CAP,
+    ):
+        self._proc = proc
+        self._master_fd = master_fd
+        self.cmd = cmd
+        self._buffer_cap = buffer_cap
+        # `deque` with a maxlen would auto-evict, but we need byte-granularity
+        # eviction (not per-chunk), so we maintain a flat bytearray and trim.
+        self._buffer = bytearray()
+        self.bytes_out = 0
+        self.lines_out = 0
+        self.last_line = ""
+        self.truncated = False
+        self.killed = False  # True once kill() has been called at least once
+        self.exit_code: Optional[int] = None
+        self._subscribers: list[Callable[[bytes], None]] = []
+        self._exit_callbacks: list[Callable[["PtyProcess"], None]] = []
+        self._subscribers_lock = threading.Lock()
+        self._buffer_lock = threading.Lock()
+        self._closed = threading.Event()
+        self._first_kill_at: Optional[float] = None
+        self._reader_thread = threading.Thread(target=self._reader_loop, name=f"pty-{proc.pid}", daemon=True)
+        self._reader_thread.start()
+
+    @classmethod
+    def spawn(
+        cls,
+        cmd: list[str],
+        cwd: Optional[str] = None,
+        env: Optional[dict] = None,
+        buffer_cap: int = DEFAULT_BUFFER_CAP,
+    ) -> "PtyProcess":
+        """Allocate a PTY pair and exec `cmd` inside the slave.
+
+        env defaults to the daemon's env if not provided. We merge user-provided
+        env on top so callers can override individual vars without losing PATH.
+        """
+        master_fd, slave_fd = pty.openpty()
+        try:
+            full_env = dict(os.environ)
+            if env:
+                full_env.update(env)
+            # `TERM=xterm-256color` gives the child program a sane default for
+            # ANSI-aware output; callers can override via env.
+            full_env.setdefault("TERM", "xterm-256color")
+            proc = subprocess.Popen(
+                cmd,
+                stdin=slave_fd,
+                stdout=slave_fd,
+                stderr=slave_fd,
+                cwd=cwd,
+                env=full_env,
+                # New session (its own process group, so we can signal the
+                # whole tree via -pgid) plus claiming the slave as the
+                # controlling terminal so a Ctrl+C byte written to the master
+                # actually raises SIGINT. See _acquire_controlling_tty.
+                preexec_fn=_acquire_controlling_tty,
+                close_fds=True,
+            )
+        except Exception:
+            os.close(master_fd)
+            os.close(slave_fd)
+            raise
+        finally:
+            # The slave end is owned by the child process now; the parent must
+            # close its copy or the master read will never see EOF.
+            try:
+                os.close(slave_fd)
+            except OSError:
+                pass
+        return cls(proc, master_fd, cmd, buffer_cap=buffer_cap)
+
+    @property
+    def pid(self) -> int:
+        return self._proc.pid
+
+    @property
+    def buffer(self) -> bytes:
+        """Snapshot of the current ring-buffer contents (oldest dropped if over cap)."""
+        with self._buffer_lock:
+            return bytes(self._buffer)
+
+    def subscribe(self, callback: Callable[[bytes], None]) -> Callable[[], None]:
+        """Register a callback fired on every output chunk. Returns an unsubscribe fn."""
+        with self._subscribers_lock:
+            self._subscribers.append(callback)
+        return self._make_unsubscribe(callback)
+
+    def snapshot_and_subscribe(self, callback: Callable[[bytes], None]) -> tuple[bytes, Callable[[], None]]:
+        """Atomically snapshot the buffer AND register a chunk subscriber.
+
+        Holding `_buffer_lock` across both ensures no chunk slips between the
+        snapshot and the subscription: the reader appends under `_buffer_lock`
+        before dispatching under `_subscribers_lock`, so any chunk not in the
+        returned snapshot is guaranteed to reach `callback`. A boundary chunk may
+        be delivered both ways (in the snapshot and to the callback); duplicating
+        is the safe failure mode, dropping is not.
+        """
+        with self._buffer_lock:
+            snapshot = bytes(self._buffer)
+            with self._subscribers_lock:
+                self._subscribers.append(callback)
+        return snapshot, self._make_unsubscribe(callback)
+
+    def _make_unsubscribe(self, callback: Callable[[bytes], None]) -> Callable[[], None]:
+        def _unsubscribe() -> None:
+            with self._subscribers_lock:
+                try:
+                    self._subscribers.remove(callback)
+                except ValueError:
+                    pass
+
+        return _unsubscribe
+
+    def on_exit(self, callback: Callable[["PtyProcess"], None]) -> Callable[[], None]:
+        """Register a callback fired once the PTY exits. Returns an unregister fn.
+
+        If the process has already exited by the time on_exit is called, the
+        callback fires synchronously - callers can register late without racing
+        the reader thread's exit cleanup. In that case the returned unregister fn
+        is a no-op (the callback already ran and was never queued).
+        """
+        with self._subscribers_lock:
+            if self.exit_code is not None:
+                fire_now = True
+            else:
+                self._exit_callbacks.append(callback)
+                fire_now = False
+        if fire_now:
+            try:
+                callback(self)
+            except Exception:
+                logger.exception("PtyProcess on_exit callback failed (late registration)")
+            return lambda: None
+
+        def _unregister() -> None:
+            with self._subscribers_lock:
+                try:
+                    self._exit_callbacks.remove(callback)
+                except ValueError:
+                    pass
+
+        return _unregister
+
+    def write_stdin(self, data: bytes) -> int:
+        """Write bytes to the PTY master. Returns count written. No-op after exit.
+
+        Serialized with fd teardown under `_buffer_lock` so we never write to a
+        closed (and possibly OS-reused) fd while the reader thread is closing it.
+        """
+        with self._buffer_lock:
+            if self.exit_code is not None or self._master_fd < 0:
+                return 0
+            try:
+                return os.write(self._master_fd, data)
+            except OSError as e:
+                if e.errno in (errno.EIO, errno.EBADF):
+                    # Slave closed / fd torn down. Treat as no-op like exit case.
+                    return 0
+                raise
+
+    def kill(self) -> None:
+        """Send SIGTERM the first time; SIGKILL on subsequent calls or after grace.
+
+        Signals the child's process group so the whole tree dies (shell + nested).
+        Safe to call multiple times and after the process has already exited.
+        """
+        if self.exit_code is not None:
+            return
+        now = time.monotonic()
+        try:
+            pgid = os.getpgid(self.pid)
+        except OSError:
+            return  # Already gone.
+
+        if self._first_kill_at is None:
+            self._first_kill_at = now
+            sig = signal.SIGTERM
+        elif now - self._first_kill_at >= SIGKILL_GRACE_SECONDS:
+            sig = signal.SIGKILL
+        else:
+            sig = signal.SIGKILL  # explicit second call = escalate immediately
+        self.killed = True
+        try:
+            os.killpg(pgid, sig)
+        except OSError as e:
+            if e.errno != errno.ESRCH:  # already dead
+                raise
+
+    def wait_drain(self, timeout: float = 1.0) -> None:
+        """Block until the reader thread finishes (or timeout). Tests use this
+        to make sure all pending PTY output has landed in the buffer before
+        asserting. Production code should never need to block on this."""
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            if self._closed.is_set() and not self._reader_thread.is_alive():
+                return
+            time.sleep(0.02)
+
+    # ── internals ──
+
+    def _reader_loop(self) -> None:
+        try:
+            while True:
+                try:
+                    chunk = os.read(self._master_fd, _READ_CHUNK_SIZE)
+                except OSError as e:
+                    # EIO is the canonical "PTY slave is gone" indicator on Linux.
+                    if e.errno in (errno.EIO, errno.EBADF):
+                        break
+                    raise
+                if not chunk:
+                    break
+                self._append(chunk)
+                self._dispatch(chunk)
+        finally:
+            try:
+                # Reap the child if it's done so exit_code populates.
+                self.exit_code = self._proc.wait()
+            except Exception:
+                logger.exception("PtyProcess: error waiting on child pid=%s", self.pid)
+                self.exit_code = self._proc.returncode
+            with self._buffer_lock:
+                fd, self._master_fd = self._master_fd, -1
+            if fd >= 0:
+                try:
+                    os.close(fd)
+                except OSError:
+                    pass
+            with self._subscribers_lock:
+                callbacks = list(self._exit_callbacks)
+                self._exit_callbacks.clear()
+            for cb in callbacks:
+                try:
+                    cb(self)
+                except Exception:
+                    logger.exception("PtyProcess on_exit callback failed")
+            self._closed.set()
+
+    def _append(self, chunk: bytes) -> None:
+        with self._buffer_lock:
+            self.bytes_out += len(chunk)
+            self.lines_out += chunk.count(b"\n")
+            self._buffer.extend(chunk)
+            if len(self._buffer) > self._buffer_cap:
+                drop = len(self._buffer) - self._buffer_cap
+                del self._buffer[:drop]
+                self.truncated = True
+            # Most recent line: scan the bytearray from the end for the last
+            # newline (skipping a trailing one) and slice only that tail. Avoids
+            # the ~1 MB memcpy that `bytes(self._buffer)` would do per chunk.
+            end = len(self._buffer)
+            if end and self._buffer[end - 1] == 0x0A:
+                end -= 1
+            nl = self._buffer.rfind(b"\n", 0, end)
+            last = bytes(self._buffer[nl + 1 : end])  # noqa: E203
+            self.last_line = last.decode("utf-8", errors="replace")[-200:]
+
+    def _dispatch(self, chunk: bytes) -> None:
+        with self._subscribers_lock:
+            subs = list(self._subscribers)
+        for cb in subs:
+            try:
+                cb(chunk)
+            except Exception:
+                logger.exception("PtyProcess subscriber failed")
+
+
+class PtyManager:
+    """Tracks all live PtyProcess instances by terminal_id.
+
+    A "singleton" in practice (one per daemon, wired through gateway), but the
+    class is plain so tests can construct throw-away instances.
+    """
+
+    def __init__(self):
+        self._procs: dict[str, PtyProcess] = {}
+        self._lock = threading.Lock()
+
+    def spawn(
+        self,
+        terminal_id: str,
+        cmd: list[str],
+        cwd: Optional[str] = None,
+        env: Optional[dict] = None,
+        buffer_cap: int = DEFAULT_BUFFER_CAP,
+    ) -> PtyProcess:
+        """Spawn a PTY for `terminal_id`. Raises ValueError on duplicate id."""
+        with self._lock:
+            if terminal_id in self._procs:
+                raise ValueError(f"Terminal already exists: {terminal_id}")
+        proc = PtyProcess.spawn(cmd, cwd=cwd, env=env, buffer_cap=buffer_cap)
+        with self._lock:
+            self._procs[terminal_id] = proc
+        return proc
+
+    def get(self, terminal_id: str) -> Optional[PtyProcess]:
+        return self._procs.get(terminal_id)
+
+    def kill(self, terminal_id: str) -> None:
+        """Kill a tracked terminal. No-op if unknown or already gone."""
+        proc = self._procs.get(terminal_id)
+        if proc is None:
+            return
+        proc.kill()
+
+    def write_stdin(self, terminal_id: str, data: bytes) -> int:
+        proc = self._procs.get(terminal_id)
+        if proc is None:
+            return 0
+        return proc.write_stdin(data)
+
+    def subscribe(self, terminal_id: str, callback: Callable[[bytes], None]) -> Optional[Callable[[], None]]:
+        """Subscribe to chunk callbacks. Returns the unsubscribe fn, or None if unknown."""
+        proc = self._procs.get(terminal_id)
+        if proc is None:
+            return None
+        return proc.subscribe(callback)
+
+    def remove(self, terminal_id: str) -> None:
+        """Drop the entry. Caller is responsible for kill-and-drain semantics."""
+        with self._lock:
+            self._procs.pop(terminal_id, None)
+
+    def shutdown(self) -> None:
+        """Kill every tracked PTY. Used at daemon stop and in test teardown."""
+        with self._lock:
+            procs = list(self._procs.values())
+            self._procs.clear()
+        for p in procs:
+            try:
+                p.kill()
+            except Exception:
+                logger.exception("PtyManager.shutdown: kill failed")

tsugite_pty-0.17.0/tsugite_pty/terminal_runtime.py

@@ -0,0 +1,242 @@
+"""Glue between `pty_manager` (runtime) and `terminal_store` (persistence).
+
+Owns the lifecycle hook that translates PTY exit codes into TerminalState
+transitions and persists final byte counts. Kept out of both pty_manager and
+terminal_store so neither has to know about the other.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import threading
+from typing import Optional
+
+from tsugite_pty.pty_manager import DEFAULT_BUFFER_CAP, PtyManager, PtyProcess
+from tsugite_pty.terminal_store import (
+    TerminalSession,
+    TerminalSessionStore,
+    TerminalState,
+    TerminalStateTransitionError,
+)
+
+logger = logging.getLogger(__name__)
+
+# Grace before an exited PTY is evicted from the manager, so a late SSE
+# reconnect can still replay the final buffer before the 1 MB record is freed.
+EVICT_GRACE_SECONDS = 30.0
+
+
+def parse_command(cmd: str) -> list[str]:
+    """Split a user-typed `/run` command into argv. Wrapped in a sh -c so users
+    can use pipes/redirection/`&&` without us re-implementing shell semantics."""
+    cmd = cmd.strip()
+    if not cmd:
+        raise ValueError("Command cannot be empty")
+    # Always shell out so things like `ls | grep foo` work. The PTY hands the
+    # shell stdin/stdout; we don't need to be the parser.
+    return ["/bin/sh", "-c", cmd]
+
+
+# Resolver wired by the gateway: session_id -> Optional[SandboxContext], so a
+# terminal opened outside an agent turn (the /run command, the HTTP API) still
+# inherits its parent session's agent sandbox config.
+_session_sandbox_resolver = None
+
+
+def set_session_sandbox_resolver(fn) -> None:
+    """Wire the session -> sandbox-policy resolver (called from the gateway)."""
+    global _session_sandbox_resolver
+    _session_sandbox_resolver = fn
+
+
+def resolve_terminal_sandbox(parent_session_id: Optional[str]):
+    """Sandbox policy for a terminal: the running agent's thread-local context if
+    present (agent-turn pty_create), else the parent session's agent config
+    (terminals opened via /run or the API). None when nothing is sandboxed."""
+    from tsugite.agent_runner import get_sandbox_context
+
+    ctx = get_sandbox_context()
+    if ctx is not None:
+        return ctx
+    if _session_sandbox_resolver is not None and parent_session_id:
+        return _session_sandbox_resolver(parent_session_id)
+    return None
+
+
+def maybe_sandbox_argv(argv: list[str], cwd: Optional[str], sandbox_ctx=None) -> list[str]:
+    """Wrap a PTY command in bwrap when its agent runs sandboxed.
+
+    PTYs run in the daemon (parent) process, so without this a sandboxed agent
+    could use pty_create to execute outside the sandbox. Sandboxed PTYs are
+    filesystem-isolated to the workspace and get no network (no filtering proxy
+    is wired for the long-lived PTY path) - the agent's own code/shell still
+    reach the network through the executor's filtered proxy.
+
+    Returns argv unchanged when sandbox_ctx is None (not sandboxed). Fails closed
+    if a policy is active but no workspace dir is known.
+    """
+    if sandbox_ctx is None:
+        return argv
+
+    from pathlib import Path
+
+    from tsugite.core.sandbox import SandboxConfig, get_sandbox_class
+
+    workspace_dir = sandbox_ctx.workspace_dir or (Path(cwd) if cwd else None)
+    if workspace_dir is None:
+        raise RuntimeError("Cannot sandbox PTY: no workspace directory in the active sandbox policy")
+
+    sandbox_cls = get_sandbox_class()
+    if sandbox_cls is None:
+        raise RuntimeError("Cannot sandbox PTY: no sandbox backend installed (pip install tsugite-sandbox)")
+
+    sandbox = sandbox_cls(
+        config=SandboxConfig(
+            no_network=True,
+            extra_ro_binds=list(sandbox_ctx.extra_ro_binds),
+            extra_rw_binds=list(sandbox_ctx.extra_rw_binds),
+        ),
+        workspace_dir=Path(workspace_dir),
+        state_dir=None,
+    )
+    return sandbox.build_command(argv)
+
+
+def spawn_terminal(
+    *,
+    store: TerminalSessionStore,
+    manager: PtyManager,
+    cmd: str,
+    cwd: Optional[str] = None,
+    env: Optional[dict] = None,
+    parent_session_id: Optional[str] = None,
+    buffer_cap: int = DEFAULT_BUFFER_CAP,
+    on_state_change=None,
+) -> TerminalSession:
+    """Create a TerminalSession record + spawn its PTY in one step.
+
+    Wires the PTY's on_exit hook to drive state transitions so callers don't
+    have to. Returns the persisted TerminalSession with state=RUNNING (the
+    first chunk of output flips STARTING -> RUNNING immediately on spawn).
+
+    on_state_change: optional callback(terminal_id, new_state) for broadcasting
+    state changes to SSE subscribers. Caller is responsible for thread-safe
+    dispatch (we may call it from the reader thread).
+    """
+    session = store.add(
+        TerminalSession(
+            id="",
+            cmd=cmd,
+            cwd=cwd,
+            parent_session_id=parent_session_id,
+        )
+    )
+
+    try:
+        argv = parse_command(cmd)
+        argv = maybe_sandbox_argv(argv, cwd, resolve_terminal_sandbox(parent_session_id))
+        proc = manager.spawn(session.id, argv, cwd=cwd, env=env, buffer_cap=buffer_cap)
+    except Exception as e:
+        logger.exception("Failed to spawn PTY for terminal '%s': %s", session.id, e)
+        try:
+            store.update_state(session.id, TerminalState.FAILED.value)
+            store.update(session.id, last_line=f"spawn failed: {e}")
+        except TerminalStateTransitionError:
+            pass
+        if on_state_change:
+            try:
+                on_state_change(session.id, TerminalState.FAILED.value)
+            except Exception:
+                logger.exception("on_state_change failed during spawn-failure path")
+        raise
+
+    store.update(session.id, pid=proc.pid)
+    try:
+        store.update_state(session.id, TerminalState.RUNNING.value)
+    except TerminalStateTransitionError:
+        pass
+    if on_state_change:
+        try:
+            on_state_change(session.id, TerminalState.RUNNING.value)
+        except Exception:
+            logger.exception("on_state_change failed during RUNNING transition")
+
+    proc.on_exit(lambda p: _on_pty_exit(p, store, manager, session.id, on_state_change))
+    return store.get(session.id)
+
+
+def _on_pty_exit(
+    proc: PtyProcess,
+    store: TerminalSessionStore,
+    manager: PtyManager,
+    terminal_id: str,
+    on_state_change=None,
+) -> None:
+    """Translate the PTY's exit code into a TerminalState transition.
+
+    - kill() was called → CANCELLED
+    - exit_code == 0 → SUCCEEDED
+    - exit_code != 0 → FAILED
+    - exit_code is None (shouldn't happen, but defensive) → STREAM_LOST
+    """
+    terminal = store.get(terminal_id)
+    if terminal is None:
+        logger.warning("PTY exit hook fired for unknown terminal '%s'", terminal_id)
+        return
+
+    try:
+        store.update(
+            terminal_id,
+            exit_code=proc.exit_code,
+            bytes_out=proc.bytes_out,
+            lines_out=proc.lines_out,
+            last_line=proc.last_line,
+        )
+    except KeyError:
+        return
+
+    if proc.killed:
+        target = TerminalState.CANCELLED.value
+    elif proc.exit_code is None:
+        target = TerminalState.STREAM_LOST.value
+    elif proc.exit_code == 0:
+        target = TerminalState.SUCCEEDED.value
+    else:
+        target = TerminalState.FAILED.value
+
+    try:
+        store.update_state(terminal_id, target)
+    except TerminalStateTransitionError:
+        # Already terminal - e.g. the caller manually transitioned us first.
+        pass
+
+    if on_state_change:
+        try:
+            on_state_change(terminal_id, target)
+        except Exception:
+            logger.exception("on_state_change failed in PTY exit handler")
+
+    # Persist the captured output to disk so the SSE stream handler can replay
+    # it for clients that re-open the terminal after the in-memory PtyProcess
+    # gets evicted. Skip empty buffers (no point writing 0 bytes).
+    try:
+        buf = proc.buffer
+        if buf:
+            log_path = store.log_path(terminal_id)
+            log_path.parent.mkdir(parents=True, exist_ok=True)
+            tmp = log_path.with_suffix(".tmp")
+            tmp.write_bytes(buf)
+            os.replace(str(tmp), str(log_path))
+    except Exception:
+        logger.exception("Failed to persist terminal log for '%s'", terminal_id)
+
+    # The final record is already persisted above; free the in-memory PtyProcess
+    # (which pins a ~1 MB ring buffer) after a grace window so late SSE reconnects
+    # can still hit the in-memory replay path before we drop the buffer.
+    timer = threading.Timer(EVICT_GRACE_SECONDS, manager.remove, args=(terminal_id,))
+    timer.daemon = True
+    timer.start()
+
+
+__all__ = ["parse_command", "spawn_terminal"]

tsugite_pty-0.17.0/tsugite_pty/terminal_store.py

@@ -0,0 +1,132 @@
+"""Persistent TerminalSession store backed by a JSON file.
+
+Mirrors `WebhookStore` / `JobStore`: in-memory dict + atomic tmpfile-swap saves.
+State transitions are guarded by `_VALID_TRANSITIONS` to prevent invalid moves.
+
+PAUSED-FOLLOW from the design brief is intentionally NOT modeled here - it's a
+frontend-only concern (the user scrolled up; output keeps streaming). The backend
+state machine tracks only what the daemon needs to know to drive the PTY.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+from typing import Optional
+from uuid import uuid4
+
+from tsugite.core.record_store import JsonRecordStore, now_iso
+
+logger = logging.getLogger(__name__)
+
+
+class TerminalState(str, Enum):
+    STARTING = "starting"
+    RUNNING = "running"
+    SUCCEEDED = "succeeded"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+    STREAM_LOST = "stream_lost"
+
+
+_TERMINAL_STATES = frozenset(
+    {
+        TerminalState.SUCCEEDED.value,
+        TerminalState.FAILED.value,
+        TerminalState.CANCELLED.value,
+        TerminalState.STREAM_LOST.value,
+    }
+)
+
+# Unidirectional state machine. STARTING can transition to RUNNING (PTY produced
+# its first byte) or directly to a failure mode (PTY spawn failed → FAILED;
+# user killed before output → CANCELLED). RUNNING is the only state with all
+# terminal exits available. Terminal states are sinks (no outgoing edges).
+_VALID_TRANSITIONS: dict[str, frozenset[str]] = {
+    TerminalState.STARTING.value: frozenset(
+        {TerminalState.RUNNING.value, TerminalState.FAILED.value, TerminalState.CANCELLED.value}
+    ),
+    TerminalState.RUNNING.value: frozenset(
+        {
+            TerminalState.SUCCEEDED.value,
+            TerminalState.FAILED.value,
+            TerminalState.CANCELLED.value,
+            TerminalState.STREAM_LOST.value,
+        }
+    ),
+    TerminalState.SUCCEEDED.value: frozenset(),
+    TerminalState.FAILED.value: frozenset(),
+    TerminalState.CANCELLED.value: frozenset(),
+    TerminalState.STREAM_LOST.value: frozenset(),
+}
+
+
+class TerminalStateTransitionError(ValueError):
+    """Raised when a TerminalSession state change violates the state machine."""
+
+
+@dataclass
+class TerminalSession:
+    id: str
+    cmd: str
+    cwd: Optional[str] = None
+    state: str = TerminalState.STARTING.value
+    pid: Optional[int] = None
+    exit_code: Optional[int] = None
+    created_at: str = ""
+    updated_at: str = ""
+    resolved_at: Optional[str] = None
+    bytes_out: int = 0
+    lines_out: int = 0
+    last_line: str = ""
+    # The chat session that spawned this terminal via /run, if any. Lets the UI
+    # render the terminal's sidebar row underneath / alongside its parent chat.
+    parent_session_id: Optional[str] = None
+
+    def __post_init__(self):
+        if not self.id:
+            self.id = f"term-{uuid4().hex[:8]}"
+        now = now_iso()
+        if not self.created_at:
+            self.created_at = now
+        if not self.updated_at:
+            self.updated_at = now
+
+
+class TerminalSessionStore(JsonRecordStore):
+    """JSON-backed persistent store for TerminalSession records."""
+
+    record_cls = TerminalSession
+    collection_key = "terminals"
+    record_label = "terminal"
+    valid_transitions = _VALID_TRANSITIONS
+    terminal_states = _TERMINAL_STATES
+    transition_error_cls = TerminalStateTransitionError
+
+    def log_path(self, terminal_id: str) -> Path:
+        """Path to the on-disk output log for a terminal.
+
+        The log is written once when the PTY exits (by `terminal_runtime`) so
+        the SSE stream can replay output for the client even after the
+        in-memory PtyProcess has been evicted. The file may not exist if the
+        PTY hasn't exited yet or produced no output; callers check `.exists()`.
+        """
+        return self._path.parent / "terminal_logs" / f"{terminal_id}.log"
+
+    def _after_load(self) -> bool:
+        """Records persisted as starting/running belong to a dead daemon process -
+        the fresh PtyManager has no proc for them, so kill would no-op and restart
+        would 409 forever. Resolve them as stream_lost."""
+        reconciled = 0
+        for terminal in self._records.values():
+            if terminal.state not in _TERMINAL_STATES:
+                terminal.state = TerminalState.STREAM_LOST.value
+                terminal.updated_at = now_iso()
+                if not terminal.resolved_at:
+                    terminal.resolved_at = terminal.updated_at
+                reconciled += 1
+        if reconciled:
+            logger.info("Marked %d stale terminal(s) from previous daemon run as stream_lost", reconciled)
+        return reconciled > 0

tsugite_pty-0.17.0/tsugite_pty/tools.py

@@ -0,0 +1,320 @@
+"""Agent-facing PTY tools that wrap the daemon's PtyManager + TerminalSessionStore.
+
+These tools let an agent spawn interactive CLIs (Claude Code, ssh, psql, REPLs)
+and drive them via stdin keystrokes + ring-buffer captures. PTYs appear in the
+web UI's terminal sidebar and stream live via SSE.
+
+Wiring: the daemon gateway calls `set_terminal_runtime(pty_manager, terminal_store)`
+once the runtime is up. Tools resolve the manager + store via module-level refs;
+they raise a friendly error dict when called outside daemon mode.
+
+Lifetime: every PTY is session-scoped (parent = current daemon session).
+Long-lived daemon-scope PTYs are deferred for v1.
+"""
+
+from __future__ import annotations
+
+import logging
+import signal as _signal
+from typing import Optional
+
+from tsugite.tools import tool
+
+logger = logging.getLogger(__name__)
+
+_pty_manager = None
+_terminal_store = None
+_state_change_callback = None
+
+_SIGNAL_MAP = {
+    "TERM": _signal.SIGTERM,
+    "KILL": _signal.SIGKILL,
+    "INT": _signal.SIGINT,
+}
+
+
+def set_terminal_runtime(pty_manager, terminal_store, state_change_callback=None) -> None:
+    """Wire the daemon-owned PtyManager + TerminalSessionStore into this module.
+
+    Called from the gateway alongside the HTTPServer wiring. No-op when called
+    with None (used in shutdown to drop the references).
+
+    Args:
+        pty_manager: The daemon's PtyManager instance.
+        terminal_store: The daemon's TerminalSessionStore instance.
+        state_change_callback: Optional callable(terminal_id, new_state) used by
+            spawn_terminal to broadcast PTY lifecycle transitions to the SSE feed.
+    """
+    global _pty_manager, _terminal_store, _state_change_callback
+    _pty_manager = pty_manager
+    _terminal_store = terminal_store
+    _state_change_callback = state_change_callback
+
+
+def runtime_available() -> bool:
+    """True when the daemon wired a PtyManager + TerminalSessionStore in here.
+    Also consulted by the adapters to decide whether to render PTY guidance."""
+    return _pty_manager is not None and _terminal_store is not None
+
+
+def _missing_runtime() -> dict:
+    return {"error": "PTY runtime not available (not running in daemon mode)"}
+
+
+def _get_terminal(terminal_id: str):
+    """Return the TerminalSession or an error dict (caller forwards it)."""
+    terminal = _terminal_store.get(terminal_id)
+    if terminal is None:
+        return None, {"error": f"Unknown terminal: {terminal_id}"}
+    return terminal, None
+
+
+@tool(require_daemon=True, category="terminal")
+def pty_create(
+    cmd: str,
+    cwd: Optional[str] = None,
+    env: Optional[dict] = None,
+    name: Optional[str] = None,
+    cols: int = 120,
+    rows: int = 40,
+) -> dict:
+    """Spawn a PTY-backed process. Returns {terminal_id, pid, started_at, cmd}.
+
+    The PTY appears in the web UI's terminal sidebar and streams live via SSE.
+    Output is captured into a ring buffer for later `pty_capture` reads.
+
+    Use this for *interactive* programs (ssh, psql, claude, python REPL, vim).
+    For one-shot commands that exit on their own, prefer `run()`.
+
+    Args:
+        cmd: Shell command line (passed through `sh -c`).
+        cwd: Working directory. Defaults to the daemon's cwd.
+        env: Extra environment variables merged on top of the daemon env.
+        name: Optional human-readable label (currently unused; reserved for v2).
+        cols: PTY column width (informational; xterm.js does not reflow today).
+        rows: PTY row height (informational).
+
+    Returns:
+        Dict with terminal_id, pid, started_at, cmd.
+    """
+    if not runtime_available():
+        return _missing_runtime()
+
+    from tsugite_daemon.session_runner import get_current_session_id
+
+    from tsugite_pty.terminal_runtime import spawn_terminal
+
+    parent_session_id = get_current_session_id()
+
+    try:
+        session = spawn_terminal(
+            store=_terminal_store,
+            manager=_pty_manager,
+            cmd=cmd,
+            cwd=cwd,
+            env=env,
+            parent_session_id=parent_session_id,
+            on_state_change=_state_change_callback,
+        )
+    except Exception as e:
+        logger.exception("pty_create failed for cmd=%r", cmd)
+        return {"error": f"Failed to spawn PTY: {e}"}
+
+    return {
+        "terminal_id": session.id,
+        "pid": session.pid,
+        "started_at": session.created_at,
+        "cmd": session.cmd,
+    }
+
+
+@tool(require_daemon=True, category="terminal")
+def pty_send_keys(terminal_id: str, keys: str, enter: bool = True) -> dict:
+    """Write keystrokes to the PTY's stdin. `enter=True` appends \\n.
+
+    For escape sequences (Ctrl+C, arrow keys), pass raw escape bytes:
+    Ctrl+C = "\\x03", up arrow = "\\x1b[A", Esc = "\\x1b". Pair these with
+    `enter=False` so we don't tack a newline on the end.
+
+    Args:
+        terminal_id: TerminalSession id returned by `pty_create`.
+        keys: Literal characters / control bytes to send.
+        enter: When True (default), append a newline.
+
+    Returns:
+        Dict with terminal_id and bytes_written, or {error: ...}.
+    """
+    if not runtime_available():
+        return _missing_runtime()
+
+    terminal, err = _get_terminal(terminal_id)
+    if err:
+        return err
+
+    payload = keys
+    if enter:
+        payload = payload + "\n"
+
+    try:
+        data = payload.encode("utf-8")
+    except UnicodeEncodeError as e:
+        return {"error": f"Failed to encode keys: {e}"}
+
+    written = _pty_manager.write_stdin(terminal_id, data)
+    return {"terminal_id": terminal_id, "bytes_written": written}
+
+
+@tool(require_daemon=True, category="terminal")
+def pty_capture(terminal_id: str, lines: int = 50, tail: bool = True) -> dict:
+    """Read the current PTY output buffer.
+
+    Use this to confirm a command finished or to read a prompt before responding.
+    `tail=True` returns the last N lines; `tail=False` returns the first N.
+
+    Args:
+        terminal_id: TerminalSession id.
+        lines: Number of lines to return from the buffer.
+        tail: When True (default), return the last `lines`. Else return the first.
+
+    Returns:
+        Dict with text, bytes_out, lines_out, truncated, state, exit_code.
+    """
+    if not runtime_available():
+        return _missing_runtime()
+
+    terminal, err = _get_terminal(terminal_id)
+    if err:
+        return err
+
+    proc = _pty_manager.get(terminal_id)
+    if proc is not None:
+        raw = proc.buffer
+        bytes_out = proc.bytes_out
+        lines_out = proc.lines_out
+        truncated = proc.truncated
+    else:
+        # PTY has exited and been evicted from the manager. The exit hook
+        # persisted the full ring buffer to disk - replay that. Fall back to
+        # the one-line last_line snapshot only if the log never got written.
+        bytes_out = terminal.bytes_out
+        lines_out = terminal.lines_out
+        truncated = False
+        log_path = _terminal_store.log_path(terminal_id)
+        try:
+            raw = log_path.read_bytes()
+        except OSError:
+            raw = (terminal.last_line or "").encode("utf-8", errors="replace")
+
+    text = raw.decode("utf-8", errors="replace")
+    split = text.splitlines()
+    if tail:
+        selected = split[-lines:] if lines > 0 else []
+    else:
+        selected = split[:lines] if lines > 0 else []
+    rendered = "\n".join(selected)
+
+    return {
+        "terminal_id": terminal_id,
+        "text": rendered,
+        "bytes_out": bytes_out,
+        "lines_out": lines_out,
+        "truncated": truncated,
+        "state": terminal.state,
+        "exit_code": terminal.exit_code,
+    }
+
+
+@tool(require_daemon=True, category="terminal")
+def pty_kill(terminal_id: str, signal: str = "TERM") -> dict:
+    """Send a signal to the PTY. Returns {state, exit_code}.
+
+    - TERM (default): SIGTERM to the PTY's process group. Transitions the
+      TerminalSession to CANCELLED once the process actually exits.
+    - KILL: SIGKILL, the escalation if TERM doesn't take.
+    - INT: SIGINT (Ctrl+C), for graceful cancel of a running command without
+      killing the shell itself.
+
+    Args:
+        terminal_id: TerminalSession id.
+        signal: One of "TERM", "KILL", "INT" (case-insensitive).
+
+    Returns:
+        Dict with terminal_id, state, exit_code, signal.
+    """
+    if not runtime_available():
+        return _missing_runtime()
+
+    terminal, err = _get_terminal(terminal_id)
+    if err:
+        return err
+
+    sig_name = (signal or "TERM").upper()
+    sig = _SIGNAL_MAP.get(sig_name)
+    if sig is None:
+        return {"error": f"Unsupported signal '{signal}'. Use TERM, KILL, or INT."}
+
+    proc = _pty_manager.get(terminal_id)
+    if proc is None:
+        # Already exited and reaped.
+        return {
+            "terminal_id": terminal_id,
+            "state": terminal.state,
+            "exit_code": terminal.exit_code,
+            "signal": sig_name,
+        }
+
+    if sig_name == "INT":
+        # SIGINT goes through stdin as the conventional Ctrl+C byte so the
+        # *foreground* program in the PTY catches it, not the shell parent.
+        _pty_manager.write_stdin(terminal_id, b"\x03")
+    else:
+        # TERM / KILL hit the process group via PtyManager.kill; double-calls
+        # auto-escalate per PtyProcess.kill's grace logic.
+        _pty_manager.kill(terminal_id)
+        if sig_name == "KILL":
+            # Force the escalation by calling again immediately.
+            _pty_manager.kill(terminal_id)
+
+    # State may not have updated yet (kill is async - the reader thread sees
+    # EIO before exit_code populates). Re-read for the snapshot we return.
+    terminal = _terminal_store.get(terminal_id)
+    return {
+        "terminal_id": terminal_id,
+        "state": terminal.state if terminal else "unknown",
+        "exit_code": terminal.exit_code if terminal else None,
+        "signal": sig_name,
+    }
+
+
+@tool(require_daemon=True, category="terminal")
+def pty_list(state: Optional[str] = None) -> list[dict]:
+    """List all terminals the daemon owns, optionally filtered by state.
+
+    Args:
+        state: Filter by TerminalState value (running, succeeded, failed,
+            cancelled, stream_lost, starting).
+
+    Returns:
+        List of dicts with terminal_id, cmd, state, pid, created_at,
+        resolved_at, exit_code, parent_session_id.
+    """
+    if not runtime_available():
+        return [_missing_runtime()]
+
+    terminals = _terminal_store.list_all()
+    if state:
+        terminals = [t for t in terminals if t.state == state]
+
+    return [
+        {
+            "terminal_id": t.id,
+            "cmd": t.cmd,
+            "state": t.state,
+            "pid": t.pid,
+            "created_at": t.created_at,
+            "resolved_at": t.resolved_at,
+            "exit_code": t.exit_code,
+            "parent_session_id": t.parent_session_id,
+        }
+        for t in terminals
+    ]