stcode 0.0.1a0__py3-none-any.whl

stcode/cli/services/client.py

@@ -0,0 +1,393 @@
+"""
+DaemonClient — the UI's end of the daemon's JSONL socket.
+
+    async with await DaemonClient.connect(Address()) as client:
+        await client.create(cwd=Path.cwd())
+        await client.push("Add rate limiting")
+        async for frame in client.events():
+            ...
+
+Shares nothing with `stcode/core` but the wire format: messages go out as dicts and
+come back as dicts. It renders and interprets nothing.
+
+**Requests and events share one socket.** `create`, `attach`, `sessions`, `info` and
+the config verbs expect an answer while deltas arrive, so one reader routes each frame
+to a waiter parked on that frame's type, else to the event queue. Type is enough: a
+client has at most one of those in flight, and everything else is fire-and-forget or
+keyed by `execution_id`.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import uuid
+from dataclasses import dataclass, field
+from pathlib import Path
+from types import TracebackType
+from typing import Any, AsyncIterator
+
+from stcode.cli.services.paths import stcode_home
+
+STREAM_LIMIT = 64 * 1024 * 1024
+"""Longest line either end accepts. `history` is one line carrying a whole transcript,
+and asyncio's 64 KiB default would make a session unresumable after ~30 tool calls."""
+
+REPLY_TIMEOUT = 30.0
+"""How long a synchronous verb waits. Long enough for `create` to sample git and
+connect MCP servers on a cold repo; short enough that a wedged daemon is reported
+rather than hung on."""
+
+
+@dataclass
+class Address:
+    """Where a daemon listens."""
+
+    transport: str = "unix"
+    socket: Path = field(default_factory=lambda: stcode_home() / "daemon.sock")
+    host: str = "127.0.0.1"
+    port: int = 7717
+
+    def __str__(self) -> str:
+        return (
+            str(self.socket) if self.transport == "unix" else f"{self.host}:{self.port}"
+        )
+
+    def daemon_args(self) -> list[str]:
+        """The same address as `stcode-daemon` flags."""
+        if self.transport == "unix":
+            return ["--transport", "unix", "--socket", str(self.socket)]
+        return ["--transport", "tcp", "--host", self.host, "--port", str(self.port)]
+
+
+class DaemonClosed(Exception):
+    """The daemon went away, refused a request, or did not answer it."""
+
+
+class RequestRefused(DaemonClosed):
+    """A request was rejected while the daemon connection remains usable."""
+
+
+class DaemonClient:
+    """One connection to one daemon."""
+
+    def __init__(
+        self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter
+    ) -> None:
+        self._reader = reader
+        self._writer = writer
+        self._events: "asyncio.Queue[dict[str, Any]]" = asyncio.Queue()
+        self._waiters: dict[str, "asyncio.Future[dict[str, Any]]"] = {}
+        self._workspace_waiters: dict[str, asyncio.Future[dict[str, Any]]] = {}
+        self._closed = asyncio.Event()
+        self._read_task = asyncio.create_task(
+            self._read_loop(), name="stcode-client-reader"
+        )
+        self.session_id: str = ""
+
+    @classmethod
+    async def connect(cls, address: Address) -> "DaemonClient":
+        """Open the transport. `OSError` when nothing is listening — the caller's cue to
+        start a daemon or ask for another address, not an error to hide."""
+        if address.transport == "unix":
+            reader, writer = await asyncio.open_unix_connection(
+                str(address.socket.expanduser()), limit=STREAM_LIMIT
+            )
+        else:
+            reader, writer = await asyncio.open_connection(
+                address.host, address.port, limit=STREAM_LIMIT
+            )
+        return cls(reader, writer)
+
+    # ---- io ----
+
+    async def _read_loop(self) -> None:
+        try:
+            async for line in self._reader:
+                if not line.strip():
+                    continue
+                try:
+                    frame = json.loads(line)
+                except json.JSONDecodeError:
+                    continue  # A line we cannot parse is the daemon's bug, not a reason to drop.
+                if not isinstance(frame, dict):
+                    continue
+                request_id = str(frame.get("request_id", ""))
+                if request_id:
+                    waiter = self._workspace_waiters.pop(request_id, None)
+                    if waiter is not None and not waiter.done():
+                        waiter.set_result(frame)
+                    continue
+                waiter = self._waiters.pop(str(frame.get("type", "")), None)
+                if waiter is not None and not waiter.done():
+                    waiter.set_result(frame)
+                else:
+                    self._events.put_nowait(frame)
+        except ValueError as exc:
+            # A line longer than `STREAM_LIMIT`: the framing cannot be recovered, so the
+            # connection ends — saying so.
+            self._events.put_nowait(
+                {
+                    "type": "error",
+                    "message": f"frame too large for the connection: {exc}",
+                }
+            )
+        finally:
+            self._closed.set()
+            for waiter in [*self._waiters.values(), *self._workspace_waiters.values()]:
+                if not waiter.done():
+                    waiter.set_exception(
+                        DaemonClosed("the daemon closed the connection")
+                    )
+            self._waiters.clear()
+            self._workspace_waiters.clear()
+
+    async def _fire(self, kind: str, **fields: Any) -> None:
+        message = {
+            "type": kind,
+            **{key: value for key, value in fields.items() if value is not None},
+        }
+        self._writer.write(
+            (json.dumps(message, ensure_ascii=False) + "\n").encode("utf-8")
+        )
+        await self._writer.drain()
+
+    async def _request(self, kind: str, expect: str, **fields: Any) -> dict[str, Any]:
+        """Send, then wait for the one frame type that answers it.
+
+        An `error` frame resolves the wait too — a refused request must raise rather
+        than sit until the timeout, because the refusal *is* the answer.
+        """
+        loop = asyncio.get_running_loop()
+        reply: "asyncio.Future[dict[str, Any]]" = loop.create_future()
+        error: "asyncio.Future[dict[str, Any]]" = loop.create_future()
+        self._waiters[expect] = reply
+        self._waiters["error"] = error
+        try:
+            await self._fire(kind, **fields)
+            done, pending = await asyncio.wait(
+                {reply, error},
+                timeout=REPLY_TIMEOUT,
+                return_when=asyncio.FIRST_COMPLETED,
+            )
+        finally:
+            self._waiters.pop(expect, None)
+            self._waiters.pop("error", None)
+        # Cancel the loser: a future holding an exception nobody retrieves is a warning
+        # printed from the garbage collector.
+        for future in pending:
+            future.cancel()
+        if not done:
+            raise DaemonClosed(
+                f"the daemon did not answer `{kind}` in {REPLY_TIMEOUT:.0f}s"
+            )
+        if error in done:
+            frame = error.result()  # raises DaemonClosed if the socket died first
+            raise RequestRefused(
+                str(frame.get("message", "the daemon reported an error"))
+            )
+        return reply.result()
+
+    async def next_event(self, timeout: float | None = None) -> dict[str, Any]:
+        """The next frame, for a caller that wants one rather than a stream."""
+        return await asyncio.wait_for(self._events.get(), timeout)
+
+    def events(self) -> AsyncIterator[dict[str, Any]]:
+        """Everything the daemon sends that was not an answer to a request.
+
+        Waits on the next frame and the socket closing at once, and cancels both in
+        `finally`: a task left parked there is finalised by the garbage collector,
+        possibly after the loop has closed.
+        """
+
+        async def stream() -> AsyncIterator[dict[str, Any]]:
+            pending: set["asyncio.Future[Any]"] = set()
+            try:
+                while True:
+                    getter = asyncio.ensure_future(self._events.get())
+                    closed = asyncio.ensure_future(self._closed.wait())
+                    pending = {getter, closed}
+                    done, _ = await asyncio.wait(
+                        pending, return_when=asyncio.FIRST_COMPLETED
+                    )
+                    if getter in done:
+                        closed.cancel()
+                        pending = set()
+                        yield getter.result()
+                        continue
+                    # Closed: drain what already arrived, so the last frame is not lost.
+                    getter.cancel()
+                    pending = set()
+                    while not self._events.empty():
+                        yield self._events.get_nowait()
+                    return
+            finally:
+                for future in pending:
+                    if not future.done():
+                        future.cancel()
+
+        return stream()
+
+    async def wait_closed(self, timeout: float) -> bool:
+        """Whether the daemon closed this connection within `timeout` seconds."""
+        try:
+            await asyncio.wait_for(self._closed.wait(), timeout)
+        except asyncio.TimeoutError:
+            return False
+        return True
+
+    # ---- the protocol ----
+
+    async def create(
+        self,
+        *,
+        cwd: str | Path | None = None,
+        role: str = "",
+        approval_mode: str | None = None,
+    ) -> dict[str, Any]:
+        frame = await self._request(
+            "create",
+            "session",
+            cwd=str(cwd or ""),
+            role=role,
+            approval_mode=approval_mode,
+        )
+        self.session_id = str(frame.get("id", ""))
+        return frame
+
+    async def attach(self, session_id: str, *, replay: bool = True) -> dict[str, Any]:
+        frame = await self._request(
+            "attach", "session", session=session_id, replay=replay
+        )
+        self.session_id = str(frame.get("id", ""))
+        return frame
+
+    async def sessions(self, limit: int = 20) -> list[dict[str, Any]]:
+        frame = await self._request("sessions", "sessions", limit=limit)
+        rows = frame.get("sessions", [])
+        return list(rows) if isinstance(rows, list) else []
+
+    async def detach(self, session_id: str = "") -> None:
+        await self._fire("detach", session=session_id)
+
+    async def push(self, text: str, session_id: str = "") -> None:
+        await self._fire("push", text=text, session=session_id)
+
+    async def interrupt(self, session_id: str = "") -> None:
+        await self._fire("interrupt", session=session_id)
+
+    async def approve(
+        self, execution_id: str, approved: bool, session_id: str = ""
+    ) -> None:
+        await self._fire(
+            "approval", execution_id=execution_id, approved=approved, session=session_id
+        )
+
+    async def answer(self, execution_id: str, text: str, session_id: str = "") -> None:
+        await self._fire(
+            "answer", execution_id=execution_id, text=text, session=session_id
+        )
+
+    async def set_mode(self, mode: str, session_id: str = "") -> None:
+        """Answered by a `session` frame with the mode now in force."""
+        await self._fire("set_mode", mode=mode, session=session_id)
+
+    async def set_meta(
+        self,
+        *,
+        model: str | None = None,
+        provider: str | None = None,
+        reasoning_effort: str | None = None,
+        session_id: str = "",
+    ) -> None:
+        """Override this session's model, provider or effort. Answered by a `session`
+        frame saying what the settings now are."""
+        await self._fire(
+            "set_meta",
+            model=model or None,
+            provider=provider or None,
+            reasoning_effort=reasoning_effort or None,
+            session=session_id,
+        )
+
+    async def info(self, session_id: str = "") -> dict[str, Any]:
+        """Skills, MCP servers, tools and paths — as the **daemon's** machine sees them."""
+        return await self._request("info", "info", session=session_id)
+
+    async def _workspace_request(
+        self, kind: str, *, request_timeout: float = REPLY_TIMEOUT, **fields: Any
+    ) -> dict[str, Any]:
+        request_id = uuid.uuid4().hex
+        reply: asyncio.Future[dict[str, Any]] = asyncio.get_running_loop().create_future()
+        self._workspace_waiters[request_id] = reply
+        try:
+            await self._fire(kind, request_id=request_id, session=self.session_id, **fields)
+            frame = await asyncio.wait_for(reply, request_timeout)
+            if frame.get("error"):
+                raise RequestRefused(str(frame["error"]))
+            return frame
+        except asyncio.TimeoutError as exc:
+            raise DaemonClosed(f"the daemon did not answer `{kind}`") from exc
+        finally:
+            self._workspace_waiters.pop(request_id, None)
+            if not reply.done():
+                reply.cancel()
+
+    async def workspace_files(self) -> list[str]:
+        frame = await self._workspace_request("workspace_files")
+        return [str(path) for path in frame.get("files", [])]
+
+    async def workspace_shell(self, command: str, timeout: float = 10) -> dict[str, Any]:
+        duration = max(1.0, min(120.0, timeout))
+        # The shell's deadline may exceed the ordinary request deadline.
+        return await self._workspace_request(
+            "workspace_shell", request_timeout=duration + REPLY_TIMEOUT,
+            command=command, timeout=duration,
+        )
+
+    async def get_config(self) -> dict[str, Any]:
+        """The daemon's `config` frame: default provider and model, effort, mode, the
+        configured providers (without keys) and the libraries a new one can use."""
+        return await self._request("get_config", "config")
+
+    async def set_config(self, **fields: Any) -> dict[str, Any]:
+        """Persist `provider`, `model`, `api_key`, `reasoning_effort` or `approval_mode`
+        in the daemon's config file. Raises `DaemonClosed` with the reason if refused."""
+        return await self._request("set_config", "config", **fields)
+
+    async def shutdown(self) -> None:
+        """Ask the daemon to stop. Honoured over a unix socket only."""
+        await self._fire("shutdown")
+
+    # ---- lifecycle ----
+
+    async def aclose(self) -> None:
+        self._read_task.cancel()
+        with contextlib.suppress(asyncio.CancelledError):
+            await self._read_task
+        with contextlib.suppress(ConnectionError, OSError):
+            self._writer.close()
+            await self._writer.wait_closed()
+        self._closed.set()
+
+    async def __aenter__(self) -> "DaemonClient":
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        await self.aclose()
+
+
+__all__ = [
+    "REPLY_TIMEOUT",
+    "STREAM_LIMIT",
+    "Address",
+    "DaemonClient",
+    "DaemonClosed",
+    "stcode_home",
+]

stcode/cli/services/launcher.py

@@ -0,0 +1,159 @@
+"""
+Launcher — find the daemon at an address, or start one there as a subprocess.
+
+    launcher = Launcher(address)
+    client = await launcher.connect()      # reuse a listening daemon, else start one
+    ...
+    await launcher.stop()                  # stops only a daemon this launcher started
+
+The daemon is a separate program (`stcode-daemon`), reached only through its socket, so
+this is the whole of what the UI knows about how one runs. Its output goes to
+`daemon.log` beside the socket, and when it dies on start-up the tail of that log is
+the error the user sees.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+from stcode.cli.services.client import Address, DaemonClient
+from stcode.cli.services.paths import stcode_home
+
+START_TIMEOUT = 20.0
+"""How long a fresh daemon gets to start listening. MCP-free start-up is well under a
+second; the margin is for a cold Python import on a slow disk."""
+
+STOP_TIMEOUT = 5.0
+
+
+class DaemonFailed(Exception):
+    """The daemon could not be started, or exited before it listened."""
+
+
+def daemon_command() -> list[str]:
+    """`stcode-daemon` from this environment when installed, else the module."""
+    search = os.pathsep.join(
+        [str(Path(sys.executable).parent), os.environ.get("PATH", "")]
+    )
+    found = shutil.which("stcode-daemon", path=search)
+    return [found] if found else [sys.executable, "-m", "stcode.core"]
+
+
+class Launcher:
+    """Connects to the daemon at one address, starting it when nothing listens."""
+
+    def __init__(
+        self,
+        address: Address,
+        *,
+        config: Path | None = None,
+        log_path: Path | None = None,
+    ) -> None:
+        self.address = address
+        self.config = config
+        self.log_path = log_path or stcode_home() / "daemon.log"
+        self.process: subprocess.Popen[bytes] | None = None
+
+    @property
+    def started(self) -> bool:
+        """Whether this launcher started the daemon it is connected to."""
+        return self.process is not None
+
+    async def connect(self, *, restart: bool = False) -> DaemonClient:
+        """Reuse a listening daemon, or start one. `restart` stops a running one first."""
+        if restart:
+            await self.shutdown_running()
+        try:
+            return await DaemonClient.connect(self.address)
+        except OSError:
+            pass
+        self._spawn()
+        return await self._wait_until_listening()
+
+    async def shutdown_running(self) -> None:
+        """Stop whatever daemon is listening at the address, and wait until it is gone."""
+        try:
+            client = await DaemonClient.connect(self.address)
+        except OSError:
+            return
+        async with client:
+            await client.shutdown()
+            if not await client.wait_closed(STOP_TIMEOUT):
+                raise DaemonFailed(
+                    f"the daemon at {self.address} did not stop (shutdown needs a unix socket)"
+                )
+        # The daemon closes clients before its listening socket. EOF alone can race
+        # with connect() and hand the caller the very daemon it asked us to replace.
+        deadline = asyncio.get_running_loop().time() + STOP_TIMEOUT
+        while True:
+            try:
+                probe = await DaemonClient.connect(self.address)
+            except OSError:
+                return
+            await probe.aclose()
+            if asyncio.get_running_loop().time() >= deadline:
+                raise DaemonFailed(
+                    f"the daemon at {self.address} is still listening after shutdown"
+                )
+            await asyncio.sleep(0.05)
+
+    async def stop(self) -> None:
+        """Stop the daemon this launcher started. A reused one is left running."""
+        process, self.process = self.process, None
+        if process is None or process.poll() is not None:
+            return
+        process.terminate()
+        try:
+            await asyncio.to_thread(process.wait, STOP_TIMEOUT)
+        except subprocess.TimeoutExpired:
+            process.kill()
+
+    def _spawn(self) -> None:
+        command = [*daemon_command(), *self.address.daemon_args()]
+        if self.config is not None:
+            command += ["--config", str(self.config)]
+        self.log_path.parent.mkdir(parents=True, exist_ok=True)
+        with self.log_path.open("wb") as log:
+            # Its own session, so a ctrl-c meant for the UI is not also delivered here.
+            self.process = subprocess.Popen(
+                command,
+                stdin=subprocess.DEVNULL,
+                stdout=log,
+                stderr=log,
+                start_new_session=True,
+            )
+
+    async def _wait_until_listening(self) -> DaemonClient:
+        assert self.process is not None
+        deadline = asyncio.get_running_loop().time() + START_TIMEOUT
+        while True:
+            try:
+                return await DaemonClient.connect(self.address)
+            except OSError:
+                pass
+            if self.process.poll() is not None:
+                self.process = None
+                raise DaemonFailed(
+                    self._log_tail() or "the daemon exited before it listened"
+                )
+            if asyncio.get_running_loop().time() > deadline:
+                await self.stop()
+                raise DaemonFailed(
+                    f"the daemon did not listen on {self.address} in {START_TIMEOUT:.0f}s"
+                )
+            await asyncio.sleep(0.1)
+
+    def _log_tail(self, lines: int = 5) -> str:
+        try:
+            text = self.log_path.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            return ""
+        return "\n".join(text.strip().splitlines()[-lines:])
+
+
+__all__ = ["DaemonFailed", "Launcher", "daemon_command"]

stcode/cli/services/paths.py

@@ -0,0 +1,18 @@
+"""Local paths shared by client I/O services."""
+
+import os
+from pathlib import Path
+
+
+def stcode_home() -> Path:
+    """`~/.stcode`, or `%APPDATA%\\stcode` on Windows. Override with `STCODE_HOME`.
+    The same rule the daemon uses, so both find the same socket."""
+    env_path = os.environ.get("STCODE_HOME")
+    if env_path:
+        return Path(env_path).expanduser()
+    if os.name == "nt":
+        return (
+            Path(os.environ.get("APPDATA", Path.home() / "AppData" / "Roaming"))
+            / "stcode"
+        )
+    return Path.home() / ".stcode"

stcode/cli/services/preferences.py

@@ -0,0 +1,107 @@
+"""
+UI preferences — `~/.stcode/ui.toml`, and nothing else reads it.
+
+Two keys: the theme, and the folders you have trusted. Both are facts about *this
+terminal on this machine*, which is exactly why they are not in `config.toml` — that
+file is read by the daemon, including one inside a container, and a container has no
+theme and trusts nothing. → `docs/decisions/0003-what-the-tui-owns.md`
+
+Flat rather than `[ui]`-sectioned: the file *is* the UI's, so a section header would be
+the same word twice.
+
+It lives in the stcode home (`STCODE_HOME`, default `~/.stcode`). It is deliberately
+**not** moved by `--config`: that flag chooses an agent configuration for one run, and
+one run should not be able to forget which folders you trust.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import tomli_w
+from stcode.cli.models import (
+    UiPrefs,
+    ThemePreference,
+    THEME_PREFERENCES,
+    DEFAULT_THEME,
+    DEFAULT_SHELL_TIMEOUT,
+    MAX_SHELL_TIMEOUT,
+)
+
+from stcode.cli.services.paths import stcode_home
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:  # pragma: no cover - exercised by the 3.10 CI job
+    import tomli as tomllib
+
+UI_FILENAME = "ui.toml"
+
+
+def clamp_shell_timeout(value: float) -> float:
+    """Keep a hand-edited `shell_timeout` inside the range the UI can honour."""
+    return max(1.0, min(float(value), MAX_SHELL_TIMEOUT))
+
+
+def ui_path() -> Path:
+    return stcode_home() / UI_FILENAME
+
+
+def load_prefs(path: Path | None = None) -> UiPrefs:
+    """Read the preferences, falling back to the defaults for anything unreadable.
+
+    **Fails closed and never raises.** A file somebody hand-edited badly must not be
+    the reason stcode will not start — and must not be the reason it runs somewhere
+    nobody approved, so a broken `trusted` list reads as an empty one rather than as a
+    permissive one.
+    """
+    path = path or ui_path()
+    try:
+        with path.open("rb") as handle:
+            data = tomllib.load(handle)
+    except (OSError, tomllib.TOMLDecodeError):
+        return UiPrefs()
+    if not isinstance(data, dict):
+        return UiPrefs()
+
+    theme = data.get("theme")
+    trusted = data.get("trusted")
+    timeout = data.get("shell_timeout")
+    return UiPrefs(
+        # Per key, not whole-file: an unknown theme name is no reason to forget the
+        # trusted list sitting two lines below it.
+        theme=theme if theme in THEME_PREFERENCES else DEFAULT_THEME,
+        trusted=[str(entry) for entry in trusted if isinstance(entry, str)]
+        if isinstance(trusted, list)
+        else [],
+        shell_timeout=clamp_shell_timeout(timeout)
+        if isinstance(timeout, (int, float)) and not isinstance(timeout, bool)
+        else DEFAULT_SHELL_TIMEOUT,
+    )
+
+
+def save_prefs(prefs: UiPrefs, path: Path | None = None) -> Path:
+    """Write them out, atomically. No secrets in here, so no 0600 dance — but an
+    interrupted write must not leave a file that reads as "nothing is trusted"."""
+    path = path or ui_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_name(path.name + ".tmp")
+    tmp.write_text(tomli_w.dumps(prefs.model_dump(mode="json")))
+    tmp.replace(path)
+    return path
+
+
+__all__ = [
+    "DEFAULT_SHELL_TIMEOUT",
+    "DEFAULT_THEME",
+    "MAX_SHELL_TIMEOUT",
+    "THEME_PREFERENCES",
+    "UI_FILENAME",
+    "ThemePreference",
+    "UiPrefs",
+    "clamp_shell_timeout",
+    "load_prefs",
+    "save_prefs",
+    "ui_path",
+]