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

opencode_python_sdk-0.1.3/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+Releases are published automatically on every merge to `main`. Release notes for each version are on the
+[GitHub releases page](https://github.com/shrijayan/opencode-python-sdk/releases).
+
+## Unreleased
+
+- `client.events`: a shared event stream with one connection for all subscribers, bounded per-subscriber queues,
+  `server.connected` replay, `of_type` / `for_session` / `where` filters, `on_activity` keepalive hook, cancellation,
+  and opt-in reconnection with backoff (`EventHub(client, reconnect=True)`).
+- `client.rpc(Definition)`: typed plugin RPC calls and event subscriptions declared with `RpcDefinition`,
+  `rpc_method` and `rpc_event`; RPC failures raise `RpcCallError` / `RpcCallInternalError`.
+- `Stream.on_activity` and `Stream.interrupt()`.
+
+## 0.1.0
+
+First release, generated from OpenCode 2.1.2: sync and async clients for all 142 operations, typed models and
+events, typed errors, pagination, event streams, retries, and the `OpencodeServer` launcher.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: opencode-python-sdk
-Version: 0.1.1
+Version: 0.1.3
 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,103 @@ 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.
 
+### Shared event stream
+
+`client.events` shares one connection among every subscriber, like `client.event` in the TypeScript client. The
+connection opens with the first subscriber and closes when the last one leaves. Each subscriber has its own queue of
+up to 4096 events; one that falls further behind fails with `EventOverflowError` without affecting the others. The
+latest `server.connected` event is replayed to subscribers that join later.
+
+```python
+from opencode.types import SessionIdleEvent
+
+with client.events.of_type(SessionIdleEvent).for_session(session.id) as idle:
+    client.session.prompt(session.id, text="Hello")
+    event = idle.get(timeout=300)  # typed as SessionIdleEvent
+```
+
+- Filters chain: `of_type(*classes)` narrows the yielded type, `for_session(id)` keeps one session's events, and
+  `where(predicate)` takes any test. Entering the `with` block joins the stream, so nothing published after that is
+  missed.
+- `subscribe(on_activity=callback)` calls `callback` for every chunk received, keepalive comments included, as a
+  liveness signal.
+- `close()` (or leaving the `with` block) ends the subscription, also from another thread. In async code, cancel a wait
+  with `anyio.fail_after`, `asyncio.timeout` or a trio cancel scope; the subscription stays usable.
+- Reconnection is opt-in: `EventHub(client, reconnect=True)` (or `AsyncEventHub`, or a `Reconnect(...)` policy) reopens
+  the connection with exponential backoff after connection errors, 5xx and 429. Subscribers see `server.connected`
+  once. **The stream is volatile**: events published while disconnected are lost, so re-read state through the API
+  after a reconnect when it matters.
+
+The async hub works the same way under asyncio and trio:
+
+```python
+async with client.events.for_session(session.id) as events:
+    async for event in events:
+        print(event.type)
+```
+
+`client.event.subscribe()` still opens a dedicated connection.
+
+### Plugin RPC
+
+Declare a plugin RPC once as a class, then call it with typed inputs and outputs:
+
+```python
+from pydantic import BaseModel
+from opencode import RpcCallError, RpcDefinition, rpc_event, rpc_method
+
+
+class AddInput(BaseModel):
+    amount: int
+
+
+class Total(BaseModel):
+    total: int
+
+
+class Counter(RpcDefinition, id="counter"):
+    add = rpc_method(AddInput, Total)
+    reset = rpc_method(None, Total)
+    changed = rpc_event(Total)
+
+
+counter = client.rpc(Counter)
+try:
+    print(counter.call(Counter.add, AddInput(amount=2)).total)
+except RpcCallError as error:
+    print(error.type, error.message, error.data)
+
+with counter.subscribe(Counter.changed) as changes:  # only rpc.counter.changed, with validated data
+    for change in changes:
+        print(change.data.total)
+```
+
+Any type pydantic validates works for inputs, outputs and event data. `rpc_method(..., errors={"not_found": Model})`
+validates the `data` of declared errors. Failures raise `RpcCallError`; crashes and outputs that do not match the
+declared type raise `RpcCallInternalError`. `counter.events()` yields every raw event of the RPC. The untyped
+`client.rpc.call(rpc_id, method, input=...)` is still available.
+
+## 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.3}/README.md

@@ -169,6 +169,103 @@ 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.
 
+### Shared event stream
+
+`client.events` shares one connection among every subscriber, like `client.event` in the TypeScript client. The
+connection opens with the first subscriber and closes when the last one leaves. Each subscriber has its own queue of
+up to 4096 events; one that falls further behind fails with `EventOverflowError` without affecting the others. The
+latest `server.connected` event is replayed to subscribers that join later.
+
+```python
+from opencode.types import SessionIdleEvent
+
+with client.events.of_type(SessionIdleEvent).for_session(session.id) as idle:
+    client.session.prompt(session.id, text="Hello")
+    event = idle.get(timeout=300)  # typed as SessionIdleEvent
+```
+
+- Filters chain: `of_type(*classes)` narrows the yielded type, `for_session(id)` keeps one session's events, and
+  `where(predicate)` takes any test. Entering the `with` block joins the stream, so nothing published after that is
+  missed.
+- `subscribe(on_activity=callback)` calls `callback` for every chunk received, keepalive comments included, as a
+  liveness signal.
+- `close()` (or leaving the `with` block) ends the subscription, also from another thread. In async code, cancel a wait
+  with `anyio.fail_after`, `asyncio.timeout` or a trio cancel scope; the subscription stays usable.
+- Reconnection is opt-in: `EventHub(client, reconnect=True)` (or `AsyncEventHub`, or a `Reconnect(...)` policy) reopens
+  the connection with exponential backoff after connection errors, 5xx and 429. Subscribers see `server.connected`
+  once. **The stream is volatile**: events published while disconnected are lost, so re-read state through the API
+  after a reconnect when it matters.
+
+The async hub works the same way under asyncio and trio:
+
+```python
+async with client.events.for_session(session.id) as events:
+    async for event in events:
+        print(event.type)
+```
+
+`client.event.subscribe()` still opens a dedicated connection.
+
+### Plugin RPC
+
+Declare a plugin RPC once as a class, then call it with typed inputs and outputs:
+
+```python
+from pydantic import BaseModel
+from opencode import RpcCallError, RpcDefinition, rpc_event, rpc_method
+
+
+class AddInput(BaseModel):
+    amount: int
+
+
+class Total(BaseModel):
+    total: int
+
+
+class Counter(RpcDefinition, id="counter"):
+    add = rpc_method(AddInput, Total)
+    reset = rpc_method(None, Total)
+    changed = rpc_event(Total)
+
+
+counter = client.rpc(Counter)
+try:
+    print(counter.call(Counter.add, AddInput(amount=2)).total)
+except RpcCallError as error:
+    print(error.type, error.message, error.data)
+
+with counter.subscribe(Counter.changed) as changes:  # only rpc.counter.changed, with validated data
+    for change in changes:
+        print(change.data.total)
+```
+
+Any type pydantic validates works for inputs, outputs and event data. `rpc_method(..., errors={"not_found": Model})`
+validates the `data` of declared errors. Failures raise `RpcCallError`; crashes and outputs that do not match the
+declared type raise `RpcCallInternalError`. `counter.events()` yields every raw event of the RPC. The untyped
+`client.rpc.call(rpc_id, method, input=...)` is still available.
+
+## 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.3}/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.3}/src/opencode/__init__.py

@@ -75,11 +75,39 @@ 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
 from ._version import __version__
 
+# isort: split
+# Hand-written helpers, kept apart from the generated error-import block above.
+from ._events import (
+    SUBSCRIBER_CAPACITY,
+    AsyncEventHub,
+    AsyncSubscription,
+    EventHub,
+    EventOverflowError,
+    Reconnect,
+    Subscription,
+    session_id_of,
+)
+from ._rpc import (
+    AsyncRpcClient,
+    AsyncRpcEvents,
+    RpcCallError,
+    RpcCallInternalError,
+    RpcClient,
+    RpcDefinition,
+    RpcEventDefinition,
+    RpcEventPayload,
+    RpcEvents,
+    RpcMethod,
+    rpc_event,
+    rpc_method,
+)
+
 # <generated:api-version>
 API_VERSION = "2.1.2"
 """The OpenCode server version this client was generated from."""
@@ -97,6 +125,7 @@ __all__ = [
     "AsyncOpencode",
     "AsyncOpencodeServer",
     "AsyncPaginator",
+    "AsyncPtyConnection",
     "AsyncStream",
     "AuthenticationError",
     "BadRequestError",
@@ -111,6 +140,8 @@ __all__ = [
     "OpencodeError",
     "OpencodeServer",
     "PermissionDeniedError",
+    "PtyConnection",
+    "PtyConnectionError",
     "RateLimitError",
     "ServerStartError",
     "ServiceUnavailableError",
@@ -119,6 +150,27 @@ __all__ = [
     "UnprocessableEntityError",
     "__version__",
     "types",
+    # Shared event stream and typed plugin RPC
+    "SUBSCRIBER_CAPACITY",
+    "AsyncEventHub",
+    "AsyncRpcClient",
+    "AsyncRpcEvents",
+    "AsyncSubscription",
+    "EventHub",
+    "EventOverflowError",
+    "Reconnect",
+    "RpcCallError",
+    "RpcCallInternalError",
+    "RpcClient",
+    "RpcDefinition",
+    "RpcEventDefinition",
+    "RpcEventPayload",
+    "RpcEvents",
+    "RpcMethod",
+    "Subscription",
+    "rpc_event",
+    "rpc_method",
+    "session_id_of",
     # <generated:error-exports>
     "AgentNotFoundError",
     "CommandExecutionError",

{opencode_python_sdk-0.1.1 → opencode_python_sdk-0.1.3}/src/opencode/_client.py

@@ -1,11 +1,14 @@
 from __future__ import annotations
 
+from functools import cached_property
 from typing import TYPE_CHECKING
 
 from typing_extensions import Self
 
 from ._base_client import AsyncAPIClient, SyncAPIClient
 from ._constants import DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT, DEFAULT_USERNAME
+from ._events import AsyncEventHub, EventHub
+from ._rpc import AsyncTypedRpcResource, TypedRpcResource
 from ._types import NOT_GIVEN, NotGiven, Timeout
 from .resources import AsyncResources, SyncResources
 
@@ -70,6 +73,16 @@ class Opencode(SyncAPIClient, SyncResources):
             http_client=http_client,
         )
 
+    @cached_property
+    def events(self) -> EventHub:
+        """The shared event stream: one connection for every subscriber. See :class:`opencode.EventHub`."""
+        return EventHub(self)
+
+    @cached_property
+    def rpc(self) -> TypedRpcResource:
+        """Plugin RPC calls: ``client.rpc.call(...)``, or ``client.rpc(Definition)`` for typed access."""
+        return TypedRpcResource(self)
+
     def with_options(
         self,
         *,
@@ -138,6 +151,16 @@ class AsyncOpencode(AsyncAPIClient, AsyncResources):
             http_client=http_client,
         )
 
+    @cached_property
+    def events(self) -> AsyncEventHub:
+        """The shared event stream: one connection for every subscriber. See :class:`opencode.AsyncEventHub`."""
+        return AsyncEventHub(self)
+
+    @cached_property
+    def rpc(self) -> AsyncTypedRpcResource:
+        """Plugin RPC calls: ``client.rpc.call(...)``, or ``client.rpc(Definition)`` for typed access."""
+        return AsyncTypedRpcResource(self)
+
     def with_options(
         self,
         *,