opencode-python-sdk 0.1.1__tar.gz → 0.1.2__tar.gz

{opencode_python_sdk-0.1.1 → opencode_python_sdk-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: opencode-python-sdk
-Version: 0.1.1
+Version: 0.1.2
 Summary: Typed Python client for the OpenCode 2.x server API
 Project-URL: Homepage, https://github.com/shrijayan/opencode-python-sdk
 Project-URL: Documentation, https://shrijayan.github.io/opencode-python-sdk/
@@ -31,6 +31,8 @@ Requires-Dist: anyio<5,>=4.4
 Requires-Dist: httpx<1,>=0.27
 Requires-Dist: pydantic<3,>=2.12
 Requires-Dist: typing-extensions>=4.12
+Provides-Extra: pty
+Requires-Dist: websockets<17,>=14; extra == 'pty'
 Description-Content-Type: text/markdown
 
 # opencode-python-sdk
@@ -204,6 +206,27 @@ Events are typed (`SessionCreatedEvent`, `SessionTextDeltaEvent`, and so on). Ev
 not know arrive as `UnknownEvent` with all their fields kept. Streams apply only the connect timeout by default, since
 they stay open between events.
 
+## Terminals
+
+`client.pty.attach()` opens an interactive connection to a PTY over a WebSocket. It needs the `pty` extra:
+`pip install "opencode-python-sdk[pty]"`.
+
+```python
+pty = client.pty.create(command="/bin/sh").data
+with client.pty.attach(pty.id) as term:
+    term.resize(120, 40)
+    term.send("echo hi\n")
+    for chunk in term:  # output bytes, until the shell exits
+        print(chunk.decode(errors="replace"), end="")
+```
+
+`recv(timeout=...)` reads one chunk and returns `None` once the terminal has ended. `term.cursor` holds the output
+position to pass as `cursor=` when reattaching; `cursor=-1` skips the replay of earlier output. Persistent terminals
+work the same way through `client.experimental.persistent_pty.attach(pty_id, role=..., takeover=...)`. The async
+client returns `AsyncPtyConnection` (asyncio only): `async with await client.pty.attach(...) as term`. A connection
+the server refuses or closes abnormally raises `PtyConnectionError`. See
+[`examples/terminal.py`](examples/terminal.py) for a full TTY bridge.
+
 ## Errors
 
 Every error derives from `opencode.OpencodeError`. Errors the server declares are raised as their own class, with a

{opencode_python_sdk-0.1.1 → opencode_python_sdk-0.1.2}/README.md

@@ -169,6 +169,27 @@ Events are typed (`SessionCreatedEvent`, `SessionTextDeltaEvent`, and so on). Ev
 not know arrive as `UnknownEvent` with all their fields kept. Streams apply only the connect timeout by default, since
 they stay open between events.
 
+## Terminals
+
+`client.pty.attach()` opens an interactive connection to a PTY over a WebSocket. It needs the `pty` extra:
+`pip install "opencode-python-sdk[pty]"`.
+
+```python
+pty = client.pty.create(command="/bin/sh").data
+with client.pty.attach(pty.id) as term:
+    term.resize(120, 40)
+    term.send("echo hi\n")
+    for chunk in term:  # output bytes, until the shell exits
+        print(chunk.decode(errors="replace"), end="")
+```
+
+`recv(timeout=...)` reads one chunk and returns `None` once the terminal has ended. `term.cursor` holds the output
+position to pass as `cursor=` when reattaching; `cursor=-1` skips the replay of earlier output. Persistent terminals
+work the same way through `client.experimental.persistent_pty.attach(pty_id, role=..., takeover=...)`. The async
+client returns `AsyncPtyConnection` (asyncio only): `async with await client.pty.attach(...) as term`. A connection
+the server refuses or closes abnormally raises `PtyConnectionError`. See
+[`examples/terminal.py`](examples/terminal.py) for a full TTY bridge.
+
 ## Errors
 
 Every error derives from `opencode.OpencodeError`. Errors the server declares are raised as their own class, with a

{opencode_python_sdk-0.1.1 → opencode_python_sdk-0.1.2}/pyproject.toml

@@ -39,6 +39,11 @@ Repository = "https://github.com/shrijayan/opencode-python-sdk"
 Issues = "https://github.com/shrijayan/opencode-python-sdk/issues"
 Changelog = "https://github.com/shrijayan/opencode-python-sdk/blob/main/CHANGELOG.md"
 
+[project.optional-dependencies]
+pty = [
+    "websockets>=14,<17",
+]
+
 [dependency-groups]
 dev = [
   "mypy>=1.18",
@@ -48,6 +53,7 @@ dev = [
   "respx>=0.22",
   "ruff>=0.14",
   "trio>=0.31",
+  "websockets>=14",
 ]
 docs = [
     "mkdocs-material[imaging]>=9.6",

{opencode_python_sdk-0.1.1 → opencode_python_sdk-0.1.2}/src/opencode/__init__.py

@@ -75,6 +75,7 @@ from ._exceptions import (
 )
 from ._models import BaseModel
 from ._pagination import AsyncCursorPage, AsyncPaginator, SyncCursorPage
+from ._pty import AsyncPtyConnection, PtyConnection, PtyConnectionError
 from ._server import AsyncOpencodeServer, OpencodeServer, ServerStartError
 from ._streaming import AsyncStream, Stream
 from ._types import NOT_GIVEN, NotGiven
@@ -97,6 +98,7 @@ __all__ = [
     "AsyncOpencode",
     "AsyncOpencodeServer",
     "AsyncPaginator",
+    "AsyncPtyConnection",
     "AsyncStream",
     "AuthenticationError",
     "BadRequestError",
@@ -111,6 +113,8 @@ __all__ = [
     "OpencodeError",
     "OpencodeServer",
     "PermissionDeniedError",
+    "PtyConnection",
+    "PtyConnectionError",
     "RateLimitError",
     "ServerStartError",
     "ServiceUnavailableError",

opencode_python_sdk-0.1.2/src/opencode/_pty.py

@@ -0,0 +1,586 @@
+"""Interactive terminals: the PTY WebSocket endpoints.
+
+The generator skips ``pty.connect`` and ``persistentPty.connect`` because they are WebSockets, so this module
+implements them by hand and the generated ``client.pty`` and ``client.experimental.persistent_pty`` resources
+mix the ``attach`` methods in. It needs the optional ``websockets`` dependency::
+
+    pip install "opencode-python-sdk[pty]"
+
+Protocol (OpenCode 2.1.2):
+
+- Opening a socket takes a single-use ticket from ``POST .../connect-token`` (sent with
+  ``x-opencode-ticket: 1``), passed as the ``ticket`` query parameter. Tickets expire after 60 seconds.
+- ``GET /api/pty/:ptyID/connect`` takes ``location[directory]`` and an optional ``cursor`` (``-1`` skips the
+  replay). The server replays buffered output, then sends one binary control frame, ``0x00`` followed by
+  ``{"cursor": n}`` JSON, then live output. Output frames are UTF-8 text. Input frames are UTF-8 text or binary;
+  invalid UTF-8 is dropped. Resizing goes through ``PUT /api/pty/:ptyID``.
+- ``GET /api/experimental/persistent-pty/:ptyID/connect`` takes ``cursor`` (byte offset, default ``0``),
+  ``role`` (``controller`` or ``observer``), ``attachment_id``, ``takeover`` and ``input_protocol``. Output frames
+  are binary; text frames are JSON events: ``attached`` first, then ``replay_complete`` after the replay, and
+  later ones such as ``resized``. With ``input_protocol=1`` every input frame is binary: one type byte (``0``
+  control, ``1`` input), big-endian ``uint16`` columns and rows, then the input bytes. A control frame claims
+  control at that size.
+- Close code ``1000`` means the terminal ended; ``4404`` means it was not found, has exited or is unavailable.
+"""
+
+from __future__ import annotations
+
+import json
+import struct
+import uuid
+from typing import TYPE_CHECKING, Any, Literal, cast
+from urllib.parse import urlencode
+
+from typing_extensions import Self
+
+from ._exceptions import OpencodeError
+from ._qs import encode_path_segment, encode_query
+from ._resource import AsyncAPIResource, SyncAPIResource
+from ._types import NOT_GIVEN, NotGiven
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator, Awaitable, Callable, Iterator, Mapping
+    from types import TracebackType
+
+    import httpx
+    from websockets.asyncio.client import ClientConnection as AsyncWebSocket
+    from websockets.sync.client import ClientConnection as SyncWebSocket
+
+    from .types import Location, PtyID
+
+__all__ = [
+    "AsyncPersistentPtyAttachMixin",
+    "AsyncPtyAttachMixin",
+    "AsyncPtyConnection",
+    "PersistentPtyAttachMixin",
+    "PtyAttachMixin",
+    "PtyConnection",
+    "PtyConnectionError",
+]
+
+TICKET_HEADER = "x-opencode-ticket"
+CLOSE_NORMAL = 1000
+CLOSE_NOT_FOUND = 4404
+_FRAME_CONTROL = 0
+_FRAME_INPUT = 1
+
+
+class PtyConnectionError(OpencodeError):
+    """The terminal WebSocket could not be opened or closed abnormally.
+
+    Attributes:
+        status: HTTP status of a refused handshake (``403`` for a bad ticket, ``404`` for an unknown PTY).
+        code: WebSocket close code (``4404`` when the terminal is not found, exited or unavailable).
+        reason: WebSocket close reason.
+    """
+
+    def __init__(self, message: str, *, status: int | None = None, code: int | None = None, reason: str = "") -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.reason = reason
+
+
+def _missing() -> PtyConnectionError:
+    return PtyConnectionError(
+        'Terminal support needs the websockets package. Install it with: pip install "opencode-python-sdk[pty]"'
+    )
+
+
+def _ws_url(base_url: httpx.URL, path: str, query: Mapping[str, object]) -> str:
+    url = base_url.join(path.lstrip("/"))
+    scheme = "wss" if url.scheme == "https" else "ws"
+    return str(url.copy_with(scheme=scheme, query=urlencode(encode_query(query)).encode("ascii")))
+
+
+def _headers(username: str, password: str | None, extra: Mapping[str, str] | None) -> dict[str, str]:
+    import base64
+
+    headers: dict[str, str] = {}
+    if password is not None:
+        headers["Authorization"] = "Basic " + base64.b64encode(f"{username}:{password}".encode()).decode("ascii")
+    headers.update(extra or {})
+    return headers
+
+
+def _handshake_error(exc: Exception) -> PtyConnectionError:
+    response = getattr(exc, "response", None)
+    status = cast("int | None", getattr(response, "status_code", None))
+    return PtyConnectionError(f"Could not open the terminal WebSocket: {exc}", status=status)
+
+
+class _Protocol:
+    """Frame handling shared by the sync and async connections."""
+
+    def __init__(self, *, persistent: bool, cols: int, rows: int) -> None:
+        self.persistent = persistent
+        self.cols = cols
+        self.rows = rows
+        self.cursor: int | None = None
+        self.attached: dict[str, Any] | None = None
+
+    def encode_input(self, data: bytes | str) -> bytes | str:
+        if not self.persistent:
+            return data
+        payload = data.encode() if isinstance(data, str) else data
+        return struct.pack(">BHH", _FRAME_INPUT, self.cols, self.rows) + payload
+
+    def encode_control(self, cols: int, rows: int) -> bytes:
+        return struct.pack(">BHH", _FRAME_CONTROL, cols, rows)
+
+    def decode(self, frame: bytes | str) -> tuple[bytes | None, dict[str, Any] | None]:
+        """Returns ``(output, event)``; control frames update the connection state and return no output."""
+        if self.persistent:
+            if isinstance(frame, bytes):
+                # Output frames are the daemon's byte range, so the resume offset advances by their length.
+                if self.cursor is not None:
+                    self.cursor += len(frame)
+                return frame, None
+            event = cast("dict[str, Any]", json.loads(frame))
+            self._apply(event)
+            return None, event
+        if isinstance(frame, str):
+            return frame.encode(), None
+        if frame[:1] == b"\x00":
+            meta = cast("dict[str, Any]", json.loads(frame[1:]))
+            self.cursor = int(meta["cursor"])
+            return None, meta
+        return frame, None
+
+    def _apply(self, event: dict[str, Any]) -> None:
+        kind = event.get("type")
+        if kind == "attached":
+            self.attached = event
+            size = cast("dict[str, int]", event.get("info", {}).get("size") or {})
+            self.cols = size.get("cols", self.cols)
+            self.rows = size.get("rows", self.rows)
+            self.cursor = cast("int | None", event.get("replay", {}).get("endOffset", self.cursor))
+        elif kind == "replay_complete":
+            self.cursor = int(event["endOffset"])
+        elif kind == "resized":
+            self.cols = int(event.get("cols", self.cols))
+            self.rows = int(event.get("rows", self.rows))
+
+
+def _closed(code: int | None, reason: str) -> PtyConnectionError | None:
+    if code in (CLOSE_NORMAL, None):
+        return None
+    return PtyConnectionError(
+        f"Terminal connection closed with code {code}: {reason or 'no reason'}", code=code, reason=reason
+    )
+
+
+class PtyConnection:
+    """A synchronous connection to a remote terminal.
+
+    Iterate over it, or call :meth:`recv`, for output bytes; it stops when the terminal ends. Control frames
+    are handled internally: :attr:`cursor` holds the latest output position the server reported, and
+    ``on_event`` (persistent terminals) receives every JSON event.
+
+    Example::
+
+        with client.pty.attach(pty.id) as term:
+            term.send("echo hi\\n")
+            for chunk in term:
+                print(chunk.decode(errors="replace"), end="")
+    """
+
+    def __init__(
+        self,
+        ws: SyncWebSocket,
+        protocol: _Protocol,
+        resize: Callable[[int, int], object],
+        on_event: Callable[[dict[str, Any]], object] | None = None,
+    ) -> None:
+        self._ws = ws
+        self._protocol = protocol
+        self._resize = resize
+        self._on_event = on_event
+
+    @property
+    def cursor(self) -> int | None:
+        """Output position to pass as ``cursor`` when reattaching, once the server has reported one."""
+        return self._protocol.cursor
+
+    @property
+    def attached(self) -> dict[str, Any] | None:
+        """The ``attached`` event of a persistent terminal (attachment id, role, info, replay offsets)."""
+        return self._protocol.attached
+
+    @property
+    def close_code(self) -> int | None:
+        """The WebSocket close code once the connection has closed."""
+        return self._ws.protocol.close_code
+
+    def send(self, data: bytes | str) -> None:
+        """Writes input to the terminal. ``str`` is sent as UTF-8."""
+        self._ws.send(self._protocol.encode_input(data))
+
+    def resize(self, cols: int, rows: int) -> None:
+        """Resizes the terminal."""
+        if self._protocol.persistent:
+            self._protocol.cols, self._protocol.rows = cols, rows
+            self._ws.send(self._protocol.encode_control(cols, rows))
+        else:
+            self._resize(cols, rows)
+
+    def recv(self, timeout: float | None = None) -> bytes | None:
+        """Returns the next output chunk, or ``None`` once the terminal has ended.
+
+        Raises:
+            TimeoutError: No output within ``timeout`` seconds.
+            PtyConnectionError: The server closed the connection abnormally (``4404``: terminal unavailable).
+        """
+        while (output := self._next(timeout)) == b"":
+            pass
+        return output
+
+    def _next(self, timeout: float | None) -> bytes | None:
+        """Reads one frame: output bytes, ``b""`` for a control frame, ``None`` after a normal close."""
+        from websockets.exceptions import ConnectionClosed
+
+        try:
+            frame = self._ws.recv(timeout)
+        except ConnectionClosed as exc:
+            error = _closed(exc.rcvd.code if exc.rcvd else None, exc.rcvd.reason if exc.rcvd else "")
+            if error is not None:
+                raise error from None
+            return None
+        output, event = self._protocol.decode(frame)
+        if event is not None and self._on_event is not None and self._protocol.persistent:
+            self._on_event(event)
+        return output or b""
+
+    def wait_attached(self, timeout: float | None) -> None:
+        """Reads frames until the ``attached`` event of a persistent terminal; ``attach`` already does this."""
+        while self._protocol.attached is None:
+            if self._next(timeout) is None:
+                raise PtyConnectionError("Terminal connection closed before it was attached", code=self.close_code)
+
+    def __iter__(self) -> Iterator[bytes]:
+        while (chunk := self.recv()) is not None:
+            yield chunk
+
+    def close(self) -> None:
+        """Closes the connection. The terminal keeps running on the server."""
+        self._ws.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(
+        self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: TracebackType | None
+    ) -> None:
+        self.close()
+
+
+class AsyncPtyConnection:
+    """An asyncio connection to a remote terminal. Same interface as :class:`PtyConnection`, with awaitables.
+
+    Example::
+
+        async with await client.pty.attach(pty.id) as term:
+            await term.send("echo hi\\n")
+            async for chunk in term:
+                print(chunk.decode(errors="replace"), end="")
+    """
+
+    def __init__(
+        self,
+        ws: AsyncWebSocket,
+        protocol: _Protocol,
+        resize: Callable[[int, int], Awaitable[object]],
+        on_event: Callable[[dict[str, Any]], object] | None = None,
+    ) -> None:
+        self._ws = ws
+        self._protocol = protocol
+        self._resize = resize
+        self._on_event = on_event
+
+    @property
+    def cursor(self) -> int | None:
+        """Output position to pass as ``cursor`` when reattaching, once the server has reported one."""
+        return self._protocol.cursor
+
+    @property
+    def attached(self) -> dict[str, Any] | None:
+        """The ``attached`` event of a persistent terminal (attachment id, role, info, replay offsets)."""
+        return self._protocol.attached
+
+    @property
+    def close_code(self) -> int | None:
+        """The WebSocket close code once the connection has closed."""
+        return self._ws.protocol.close_code
+
+    async def send(self, data: bytes | str) -> None:
+        """Writes input to the terminal. ``str`` is sent as UTF-8."""
+        await self._ws.send(self._protocol.encode_input(data))
+
+    async def resize(self, cols: int, rows: int) -> None:
+        """Resizes the terminal."""
+        if self._protocol.persistent:
+            self._protocol.cols, self._protocol.rows = cols, rows
+            await self._ws.send(self._protocol.encode_control(cols, rows))
+        else:
+            await self._resize(cols, rows)
+
+    async def recv(self) -> bytes | None:
+        """Returns the next output chunk, or ``None`` once the terminal has ended.
+
+        Raises:
+            PtyConnectionError: The server closed the connection abnormally (``4404``: terminal unavailable).
+        """
+        while (output := await self._next()) == b"":
+            pass
+        return output
+
+    async def _next(self) -> bytes | None:
+        """Reads one frame: output bytes, ``b""`` for a control frame, ``None`` after a normal close."""
+        from websockets.exceptions import ConnectionClosed
+
+        try:
+            frame = await self._ws.recv()
+        except ConnectionClosed as exc:
+            error = _closed(exc.rcvd.code if exc.rcvd else None, exc.rcvd.reason if exc.rcvd else "")
+            if error is not None:
+                raise error from None
+            return None
+        output, event = self._protocol.decode(frame)
+        if event is not None and self._on_event is not None and self._protocol.persistent:
+            self._on_event(event)
+        return output or b""
+
+    async def wait_attached(self) -> None:
+        """Reads frames until the ``attached`` event of a persistent terminal; ``attach`` already does this."""
+        while self._protocol.attached is None:
+            if await self._next() is None:
+                raise PtyConnectionError("Terminal connection closed before it was attached", code=self.close_code)
+
+    async def __aiter__(self) -> AsyncIterator[bytes]:
+        while (chunk := await self.recv()) is not None:
+            yield chunk
+
+    async def close(self) -> None:
+        """Closes the connection. The terminal keeps running on the server."""
+        await self._ws.close()
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(
+        self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: TracebackType | None
+    ) -> None:
+        await self.close()
+
+
+def _open_sync(url: str, headers: dict[str, str], open_timeout: float | None) -> SyncWebSocket:
+    try:
+        from websockets.exceptions import InvalidHandshake
+        from websockets.sync.client import connect
+    except ImportError:
+        raise _missing() from None
+    try:
+        return connect(url, additional_headers=headers, max_size=None, open_timeout=open_timeout)
+    except InvalidHandshake as exc:
+        raise _handshake_error(exc) from exc
+
+
+async def _open_async(url: str, headers: dict[str, str], open_timeout: float | None) -> AsyncWebSocket:
+    try:
+        from websockets.asyncio.client import connect
+        from websockets.exceptions import InvalidHandshake
+    except ImportError:
+        raise _missing() from None
+    try:
+        return await connect(url, additional_headers=headers, max_size=None, open_timeout=open_timeout)
+    except InvalidHandshake as exc:
+        raise _handshake_error(exc) from exc
+
+
+def _require_websockets() -> None:
+    try:
+        import websockets  # noqa: F401  # pyright: ignore[reportUnusedImport]
+    except ImportError:
+        raise _missing() from None
+
+
+def _pty_query(location: object, cursor: int | None, ticket: str) -> dict[str, object]:
+    return {"location": location, "cursor": NOT_GIVEN if cursor is None else cursor, "ticket": ticket}
+
+
+def _persistent_query(
+    cursor: int, role: Literal["controller", "observer"], attachment_id: str, takeover: bool, ticket: str
+) -> dict[str, object]:
+    return {
+        "ticket": ticket,
+        "cursor": cursor,
+        "role": role,
+        "attachment_id": attachment_id,
+        "takeover": takeover,
+        "input_protocol": 1,
+    }
+
+
+class PtyAttachMixin(SyncAPIResource):
+    """Adds :meth:`attach` to ``client.pty``."""
+
+    def attach(
+        self,
+        pty_id: PtyID,
+        *,
+        location: Location | NotGiven | None = NOT_GIVEN,
+        cursor: int | None = None,
+        open_timeout: float | None = 10,
+        extra_headers: Mapping[str, str] | None = None,
+    ) -> PtyConnection:
+        """Opens an interactive connection to a PTY created with :meth:`create`.
+
+        Args:
+            pty_id: The PTY to attach to.
+            location: Project location; defaults to the client's ``directory``.
+            cursor: Output position to resume from (:attr:`PtyConnection.cursor` of an earlier connection).
+                ``None`` replays the whole buffer, ``-1`` skips the replay.
+            open_timeout: Seconds to wait for the WebSocket handshake.
+            extra_headers: Additional handshake headers.
+
+        Raises:
+            PtyConnectionError: ``websockets`` is not installed, or the server refused the connection.
+
+        ``GET /api/pty/:ptyID/connect`` (WebSocket)
+        """
+        _require_websockets()
+        client = self._client
+        token = client.pty.connect.token(pty_id, location=location, x_opencode_ticket="1")
+        url = _ws_url(
+            client.base_url,
+            f"/api/pty/{encode_path_segment(pty_id)}/connect",
+            _pty_query(self._location(location), cursor, token.data.ticket),
+        )
+        ws = _open_sync(url, _headers(client.username, client.password, extra_headers), open_timeout)
+
+        def resize(cols: int, rows: int) -> object:
+            from .types import PtyUpdateSize
+
+            return client.pty.update(pty_id, location=location, size=PtyUpdateSize(cols=cols, rows=rows))
+
+        return PtyConnection(ws, _Protocol(persistent=False, cols=0, rows=0), resize)
+
+
+class AsyncPtyAttachMixin(AsyncAPIResource):
+    """Adds :meth:`attach` to ``client.pty``."""
+
+    async def attach(
+        self,
+        pty_id: PtyID,
+        *,
+        location: Location | NotGiven | None = NOT_GIVEN,
+        cursor: int | None = None,
+        open_timeout: float | None = 10,
+        extra_headers: Mapping[str, str] | None = None,
+    ) -> AsyncPtyConnection:
+        """Opens an interactive connection to a PTY. See :meth:`PtyAttachMixin.attach`. Needs asyncio.
+
+        ``GET /api/pty/:ptyID/connect`` (WebSocket)
+        """
+        _require_websockets()
+        client = self._client
+        token = await client.pty.connect.token(pty_id, location=location, x_opencode_ticket="1")
+        url = _ws_url(
+            client.base_url,
+            f"/api/pty/{encode_path_segment(pty_id)}/connect",
+            _pty_query(self._location(location), cursor, token.data.ticket),
+        )
+        ws = await _open_async(url, _headers(client.username, client.password, extra_headers), open_timeout)
+
+        async def resize(cols: int, rows: int) -> object:
+            from .types import PtyUpdateSize
+
+            return await client.pty.update(pty_id, location=location, size=PtyUpdateSize(cols=cols, rows=rows))
+
+        return AsyncPtyConnection(ws, _Protocol(persistent=False, cols=0, rows=0), resize)
+
+
+class PersistentPtyAttachMixin(SyncAPIResource):
+    """Adds :meth:`attach` to ``client.experimental.persistent_pty``."""
+
+    def attach(
+        self,
+        pty_id: PtyID,
+        *,
+        cursor: int = 0,
+        role: Literal["controller", "observer"] = "controller",
+        attachment_id: str | None = None,
+        takeover: bool = False,
+        on_event: Callable[[dict[str, Any]], object] | None = None,
+        open_timeout: float | None = 10,
+        extra_headers: Mapping[str, str] | None = None,
+    ) -> PtyConnection:
+        """Opens an interactive connection to a persistent terminal. *(experimental)*
+
+        Args:
+            pty_id: The terminal to attach to.
+            cursor: Byte offset to replay from; ``0`` replays everything the server kept.
+            role: ``controller`` sends input and sets the size; ``observer`` only watches.
+            attachment_id: Identifies this client across reconnects; a random id by default.
+            takeover: Take control from the current controller.
+            on_event: Called with each JSON event (``attached``, ``replay_complete``, ``resized``, ...).
+            open_timeout: Seconds to wait for the WebSocket handshake.
+            extra_headers: Additional handshake headers.
+
+        Raises:
+            PtyConnectionError: ``websockets`` is not installed, or the server refused the connection.
+
+        ``GET /api/experimental/persistent-pty/:ptyID/connect`` (WebSocket)
+        """
+        _require_websockets()
+        client = self._client
+        token = client.experimental.persistent_pty.connect_token(pty_id, x_opencode_ticket="1")
+        url = _ws_url(
+            client.base_url,
+            f"/api/experimental/persistent-pty/{encode_path_segment(pty_id)}/connect",
+            _persistent_query(cursor, role, attachment_id or str(uuid.uuid4()), takeover, token.ticket),
+        )
+        ws = _open_sync(url, _headers(client.username, client.password, extra_headers), open_timeout)
+        protocol = _Protocol(persistent=True, cols=0, rows=0)
+        connection = PtyConnection(ws, protocol, lambda cols, rows: None, on_event)
+        connection.wait_attached(open_timeout)
+        return connection
+
+
+class AsyncPersistentPtyAttachMixin(AsyncAPIResource):
+    """Adds :meth:`attach` to ``client.experimental.persistent_pty``."""
+
+    async def attach(
+        self,
+        pty_id: PtyID,
+        *,
+        cursor: int = 0,
+        role: Literal["controller", "observer"] = "controller",
+        attachment_id: str | None = None,
+        takeover: bool = False,
+        on_event: Callable[[dict[str, Any]], object] | None = None,
+        open_timeout: float | None = 10,
+        extra_headers: Mapping[str, str] | None = None,
+    ) -> AsyncPtyConnection:
+        """Opens an interactive connection to a persistent terminal. See
+        :meth:`PersistentPtyAttachMixin.attach`. Needs asyncio. *(experimental)*
+
+        ``GET /api/experimental/persistent-pty/:ptyID/connect`` (WebSocket)
+        """
+        _require_websockets()
+        client = self._client
+        token = await client.experimental.persistent_pty.connect_token(pty_id, x_opencode_ticket="1")
+        url = _ws_url(
+            client.base_url,
+            f"/api/experimental/persistent-pty/{encode_path_segment(pty_id)}/connect",
+            _persistent_query(cursor, role, attachment_id or str(uuid.uuid4()), takeover, token.ticket),
+        )
+        ws = await _open_async(url, _headers(client.username, client.password, extra_headers), open_timeout)
+        protocol = _Protocol(persistent=True, cols=0, rows=0)
+
+        async def resize(cols: int, rows: int) -> None:
+            return None
+
+        connection = AsyncPtyConnection(ws, protocol, resize, on_event)
+        await connection.wait_attached()
+        return connection

{opencode_python_sdk-0.1.1 → opencode_python_sdk-0.1.2}/src/opencode/resources/experimental.py

@@ -11,6 +11,7 @@ from functools import cached_property
 from typing import cast
 
 from .._base_client import RequestOptions
+from .._pty import AsyncPersistentPtyAttachMixin, PersistentPtyAttachMixin
 from .._qs import encode_path_segment
 from .._resource import AsyncAPIResource, SyncAPIResource
 from .._types import NOT_GIVEN, Body, Headers, NotGiven, Query, Timeout
@@ -30,7 +31,7 @@ from ..types import (
 __all__ = ["ExperimentalResource", "AsyncExperimentalResource"]
 
 
-class ExperimentalPersistentPtyResource(SyncAPIResource):
+class ExperimentalPersistentPtyResource(PersistentPtyAttachMixin):
     """Operations under ``client.experimental.persistent_pty`` (OpenCode ``experimental.persistentPty``)."""
 
     def read(
@@ -396,7 +397,7 @@ class ExperimentalResource(SyncAPIResource):
         return ExperimentalPersistentPtyResource(self._client)
 
 
-class AsyncExperimentalPersistentPtyResource(AsyncAPIResource):
+class AsyncExperimentalPersistentPtyResource(AsyncPersistentPtyAttachMixin):
     """Operations under ``client.experimental.persistent_pty`` (OpenCode ``experimental.persistentPty``)."""
 
     async def read(

{opencode_python_sdk-0.1.1 → opencode_python_sdk-0.1.2}/src/opencode/resources/pty.py

@@ -10,6 +10,7 @@ from functools import cached_property
 from typing import cast
 
 from .._base_client import RequestOptions
+from .._pty import AsyncPtyAttachMixin, PtyAttachMixin
 from .._qs import encode_path_segment
 from .._resource import AsyncAPIResource, SyncAPIResource
 from .._types import NOT_GIVEN, Body, Headers, NotGiven, Query, Timeout
@@ -72,7 +73,7 @@ class PtyConnectResource(SyncAPIResource):
         )
 
 
-class PtyResource(SyncAPIResource):
+class PtyResource(PtyAttachMixin):
     """Operations under ``client.pty`` (OpenCode ``pty``)."""
 
     @cached_property
@@ -318,7 +319,7 @@ class AsyncPtyConnectResource(AsyncAPIResource):
         )
 
 
-class AsyncPtyResource(AsyncAPIResource):
+class AsyncPtyResource(AsyncPtyAttachMixin):
     """Operations under ``client.pty`` (OpenCode ``pty``)."""
 
     @cached_property

{opencode_python_sdk-0.1.1 → opencode_python_sdk-0.1.2}/tests/test_live.py

@@ -87,3 +87,19 @@ async def test_async_server(tmp_path: Path) -> None:
         info = await client.server.info()
     assert info.version
     assert not running.running
+
+
+def test_pty_attach_echo(client: Opencode) -> None:
+    pytest.importorskip("websockets")
+    pty = client.pty.create(command="/bin/sh").data
+    try:
+        with client.pty.attach(pty.id) as term:
+            term.resize(100, 30)
+            term.send("echo hi\n")
+            output = b""
+            while b"hi\r\n" not in output.split(b"echo hi", 1)[-1]:
+                chunk = term.recv(timeout=15)
+                assert chunk is not None
+                output += chunk
+    finally:
+        client.pty.remove(pty.id)

opencode_python_sdk-0.1.2/tests/test_pty.py

@@ -0,0 +1,236 @@
+"""PTY WebSocket attach against an in-process fake server."""
+
+from __future__ import annotations
+
+import json
+import struct
+import sys
+import threading
+from collections.abc import Iterator
+from dataclasses import dataclass, field
+from typing import Any
+from urllib.parse import parse_qs, urlsplit
+
+import httpx
+import pytest
+import respx
+from websockets.datastructures import Headers
+from websockets.http11 import Request, Response
+from websockets.sync.server import Server, ServerConnection, serve
+
+from opencode import AsyncOpencode, Opencode, PtyConnectionError
+
+PASSWORD = "test-password"
+TICKET = "ticket-1"
+
+
+@dataclass
+class Fake:
+    """Records what the client sent and decides how the fake server behaves."""
+
+    close_code: int = 1000
+    refuse: bool = False
+    paths: list[str] = field(default_factory=list)
+    queries: list[dict[str, list[str]]] = field(default_factory=list)
+    headers: list[Headers] = field(default_factory=list)
+    received: list[bytes | str] = field(default_factory=list)
+
+
+def _handler(fake: Fake) -> Any:
+    def handle(ws: ServerConnection) -> None:
+        assert ws.request is not None
+        path = urlsplit(ws.request.path).path
+        if fake.close_code != 1000:
+            ws.close(fake.close_code, "session not found")
+            return
+        if "persistent-pty" in path:
+            ws.send(
+                json.dumps({"type": "attached", "info": {"size": {"cols": 80, "rows": 24}}, "replay": {"endOffset": 0}})
+            )
+            ws.send(b"replay")
+            ws.send(json.dumps({"type": "replay_complete", "endOffset": 6}))
+        else:
+            ws.send("replay")
+            ws.send(b"\x00" + json.dumps({"cursor": 6}).encode())
+        for message in ws:
+            fake.received.append(message)
+            if "persistent-pty" in path:
+                assert isinstance(message, bytes)
+                kind, cols, rows = struct.unpack(">BHH", message[:5])
+                if kind == 0:
+                    ws.send(json.dumps({"type": "resized", "cols": cols, "rows": rows}))
+                    continue
+                payload = message[5:]
+            else:
+                payload = message.encode() if isinstance(message, str) else message
+            if payload == b"exit\n":
+                ws.close(1000)
+                return
+            ws.send(payload if "persistent-pty" in path else payload.decode())
+
+    return handle
+
+
+def _process_request(fake: Fake) -> Any:
+    def process(ws: ServerConnection, request: Request) -> Response | None:
+        split = urlsplit(request.path)
+        fake.paths.append(split.path)
+        fake.queries.append(parse_qs(split.query))
+        fake.headers.append(request.headers)
+        if fake.refuse:
+            return ws.respond(403, "forbidden\n")
+        return None
+
+    return process
+
+
+@pytest.fixture
+def fake() -> Fake:
+    return Fake()
+
+
+@pytest.fixture
+def ws_server(fake: Fake) -> Iterator[str]:
+    server: Server = serve(_handler(fake), "127.0.0.1", 0, process_request=_process_request(fake))
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+    host, port = server.socket.getsockname()[:2]
+    try:
+        yield f"http://{host}:{port}"
+    finally:
+        server.shutdown()
+        thread.join()
+
+
+@pytest.fixture
+def api(ws_server: str) -> Iterator[respx.MockRouter]:
+    with respx.mock(base_url=ws_server, assert_all_called=False) as router:
+        router.post("/api/pty/pty_1/connect-token").respond(
+            json={"location": {"directory": "/repo"}, "data": {"ticket": TICKET, "expires_in": 60}}
+        )
+        router.post("/api/experimental/persistent-pty/pty_1/connect-token").respond(
+            json={"data": {"ticket": TICKET, "expires_in": 60}}
+        )
+        yield router
+
+
+def test_pty_attach_round_trip(ws_server: str, api: respx.MockRouter, fake: Fake) -> None:
+    update = api.put("/api/pty/pty_1").respond(
+        json={
+            "location": {"directory": "/repo"},
+            "data": {
+                "id": "pty_1",
+                "title": "t",
+                "command": "bash",
+                "args": [],
+                "cwd": "/repo",
+                "status": "running",
+                "pid": 1,
+            },
+        }
+    )
+    with (
+        Opencode(ws_server, password=PASSWORD, directory="/repo") as client,
+        client.pty.attach("pty_1", cursor=3) as term,
+    ):
+        assert term.recv(timeout=5) == b"replay"
+        term.send("echo hi\n")
+        assert term.recv(timeout=5) == b"echo hi\n"
+        assert term.cursor == 6
+        term.resize(120, 40)
+        term.send(b"exit\n")
+        assert list(term) == []
+        assert term.close_code == 1000
+    assert api.calls[0].request.headers["x-opencode-ticket"] == "1"
+    assert json.loads(update.calls[0].request.content) == {"size": {"rows": 40, "cols": 120}}
+    assert fake.paths == ["/api/pty/pty_1/connect"]
+    assert fake.queries[0] == {"location[directory]": ["/repo"], "cursor": ["3"], "ticket": [TICKET]}
+    assert fake.headers[0]["Authorization"].startswith("Basic ")
+    assert fake.received == ["echo hi\n", b"exit\n"]
+
+
+def test_persistent_closed_before_attached(ws_server: str, api: respx.MockRouter, fake: Fake) -> None:
+    fake.close_code = 4404
+    with Opencode(ws_server, password=PASSWORD) as client, pytest.raises(PtyConnectionError) as caught:
+        client.experimental.persistent_pty.attach("pty_1")
+    assert caught.value.code == 4404
+
+
+def test_persistent_pty_attach_frames(ws_server: str, api: respx.MockRouter, fake: Fake) -> None:
+    events: list[dict[str, Any]] = []
+    with Opencode(ws_server, password=PASSWORD) as client:
+        term = client.experimental.persistent_pty.attach("pty_1", attachment_id="a1", on_event=events.append)
+        with term:
+            assert term.recv(timeout=5) == b"replay"
+            assert term.attached is not None
+            term.send("ls\n")
+            assert term.recv(timeout=5) == b"ls\n"
+            assert term.cursor == 9
+            term.resize(132, 50)
+            term.send("exit\n")
+            assert list(term) == []
+    assert [event["type"] for event in events] == ["attached", "replay_complete", "resized"]
+    assert fake.queries[0] == {
+        "ticket": [TICKET],
+        "cursor": ["0"],
+        "role": ["controller"],
+        "attachment_id": ["a1"],
+        "takeover": ["false"],
+        "input_protocol": ["1"],
+    }
+    # Input frames carry the size from the attached event, then the size set by resize.
+    assert fake.received == [
+        struct.pack(">BHH", 1, 80, 24) + b"ls\n",
+        struct.pack(">BHH", 0, 132, 50),
+        struct.pack(">BHH", 1, 132, 50) + b"exit\n",
+    ]
+
+
+def test_not_found_close_raises(ws_server: str, api: respx.MockRouter, fake: Fake) -> None:
+    fake.close_code = 4404
+    with (
+        Opencode(ws_server, password=PASSWORD) as client,
+        client.pty.attach("pty_1") as term,
+        pytest.raises(PtyConnectionError) as caught,
+    ):
+        term.recv(timeout=5)
+    assert caught.value.code == 4404
+    assert caught.value.reason == "session not found"
+
+
+def test_refused_handshake_raises(ws_server: str, api: respx.MockRouter, fake: Fake) -> None:
+    fake.refuse = True
+    with Opencode(ws_server, password=PASSWORD) as client, pytest.raises(PtyConnectionError) as caught:
+        client.pty.attach("pty_1")
+    assert caught.value.status == 403
+
+
+def test_missing_websockets(monkeypatch: pytest.MonkeyPatch, mock_api: respx.MockRouter, client: Opencode) -> None:
+    monkeypatch.setitem(sys.modules, "websockets", None)
+    with pytest.raises(PtyConnectionError, match=r"opencode-python-sdk\[pty\]"):
+        client.pty.attach("pty_1")
+    assert not mock_api.calls
+
+
+@pytest.mark.anyio
+async def test_async_pty_attach(ws_server: str, api: respx.MockRouter, fake: Fake) -> None:
+    async with AsyncOpencode(ws_server, password=PASSWORD) as client:
+        async with await client.pty.attach("pty_1") as term:
+            assert await term.recv() == b"replay"
+            await term.send("echo hi\n")
+            assert await term.recv() == b"echo hi\n"
+            await term.send("exit\n")
+            assert [chunk async for chunk in term] == []
+        async with await client.experimental.persistent_pty.attach("pty_1") as persistent:
+            assert await persistent.recv() == b"replay"
+            await persistent.resize(90, 20)
+            await persistent.send(b"exit\n")
+            assert [chunk async for chunk in persistent] == []
+    assert fake.received[-1] == struct.pack(">BHH", 1, 90, 20) + b"exit\n"
+
+
+def test_wss_for_https() -> None:
+    from opencode._pty import _ws_url
+
+    url = _ws_url(httpx.URL("https://example.com/base/"), "/api/pty/x/connect", {"ticket": "t"})
+    assert url == "wss://example.com/base/api/pty/x/connect?ticket=t"