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

opencode_python_sdk-0.2.0/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.2 → opencode_python_sdk-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: opencode-python-sdk
-Version: 0.1.2
+Version: 0.2.0
 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/
@@ -206,6 +206,82 @@ 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:
@@ -274,6 +350,55 @@ client.session.get("ses_...", timeout=5.0)  # per call
 
 The default timeout is 10 minutes with a 10 second connect timeout.
 
+## Running an agent headless
+
+`client.session.run` does the usual "prompt an agent and wait" round trip in one call: it creates a session (or
+reuses `session_id`), sends the prompt, blocks until the session is idle, and returns the new messages with the
+final text and usage. `client.wait_until_ready` waits until agents and MCP servers have loaded, which happens
+asynchronously after the server boots. Both have async versions on `AsyncOpencode`.
+
+```python
+from opencode import Opencode
+from opencode.types import ModelRef, PromptInputFileAttachment
+
+with Opencode("http://127.0.0.1:4096", password="...") as client:
+    client.wait_until_ready(agents=["reviewer"], mcp_servers=["github"], timeout=60)
+    result = client.session.run(
+        "Review the attached diff",
+        agent="reviewer",
+        model=ModelRef(provider_id="anthropic", id="claude-sonnet-5-5"),  # set it with the agent
+        files=[PromptInputFileAttachment(uri="data:text/plain;base64,...", name="diff.patch")],
+        timeout=600,
+    )
+    print(result.outcome, result.text)
+    print(result.cost, result.tokens.input, result.tokens.output)  # this run; result.session has the totals
+```
+
+If the wait ends early (Ctrl-C, task cancellation, `timeout`, a connection error), `run` interrupts the session
+on the server before re-raising, so the agent does not keep running unattended.
+
+## Testing your code
+
+`opencode.testing.FakeServer` is an in-process fake of the server: an `httpx` transport that keeps sessions,
+messages and events in memory and answers with the same payloads as the real server. No process, no model.
+
+```python
+from opencode import Opencode
+from opencode.testing import FakeServer
+
+
+def test_summarize() -> None:
+    fake = FakeServer(reply=lambda prompt: f"summary of {prompt!r}")
+    client = Opencode.fake(fake)  # same as Opencode(transport=fake)
+
+    assert client.session.run("README").text == "summary of 'README'"
+    assert fake.prompts == ["README"]
+```
+
+`fake.fail(method, path_regex, status=..., exception=...)` injects errors, `fake.add_agent(..., after_polls=n)`
+and `fake.set_mcp_status(...)` simulate slow boots, and `fake.requests` records every request. Routes the fake
+does not implement answer `404`.
+
 ## Running a server
 
 `OpencodeServer` runs `opencode serve` as a child process on a free local port with a random password:

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

@@ -169,6 +169,82 @@ 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:
@@ -237,6 +313,55 @@ client.session.get("ses_...", timeout=5.0)  # per call
 
 The default timeout is 10 minutes with a 10 second connect timeout.
 
+## Running an agent headless
+
+`client.session.run` does the usual "prompt an agent and wait" round trip in one call: it creates a session (or
+reuses `session_id`), sends the prompt, blocks until the session is idle, and returns the new messages with the
+final text and usage. `client.wait_until_ready` waits until agents and MCP servers have loaded, which happens
+asynchronously after the server boots. Both have async versions on `AsyncOpencode`.
+
+```python
+from opencode import Opencode
+from opencode.types import ModelRef, PromptInputFileAttachment
+
+with Opencode("http://127.0.0.1:4096", password="...") as client:
+    client.wait_until_ready(agents=["reviewer"], mcp_servers=["github"], timeout=60)
+    result = client.session.run(
+        "Review the attached diff",
+        agent="reviewer",
+        model=ModelRef(provider_id="anthropic", id="claude-sonnet-5-5"),  # set it with the agent
+        files=[PromptInputFileAttachment(uri="data:text/plain;base64,...", name="diff.patch")],
+        timeout=600,
+    )
+    print(result.outcome, result.text)
+    print(result.cost, result.tokens.input, result.tokens.output)  # this run; result.session has the totals
+```
+
+If the wait ends early (Ctrl-C, task cancellation, `timeout`, a connection error), `run` interrupts the session
+on the server before re-raising, so the agent does not keep running unattended.
+
+## Testing your code
+
+`opencode.testing.FakeServer` is an in-process fake of the server: an `httpx` transport that keeps sessions,
+messages and events in memory and answers with the same payloads as the real server. No process, no model.
+
+```python
+from opencode import Opencode
+from opencode.testing import FakeServer
+
+
+def test_summarize() -> None:
+    fake = FakeServer(reply=lambda prompt: f"summary of {prompt!r}")
+    client = Opencode.fake(fake)  # same as Opencode(transport=fake)
+
+    assert client.session.run("README").text == "summary of 'README'"
+    assert fake.prompts == ["README"]
+```
+
+`fake.fail(method, path_regex, status=..., exception=...)` injects errors, `fake.add_agent(..., after_polls=n)`
+and `fake.set_mcp_status(...)` simulate slow boots, and `fake.requests` records every request. Routes the fake
+does not implement answer `404`.
+
 ## Running a server
 
 `OpencodeServer` runs `opencode serve` as a child process on a free local port with a random password:

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

@@ -14,7 +14,8 @@ Quick start::
 
 from __future__ import annotations
 
-from . import types
+from typing import TYPE_CHECKING, Any
+
 from ._client import AsyncOpencode, Opencode
 
 # <generated:error-imports>
@@ -81,6 +82,36 @@ 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,
+)
+
+if TYPE_CHECKING:
+    from . import types
+
 # <generated:api-version>
 API_VERSION = "2.1.2"
 """The OpenCode server version this client was generated from."""
@@ -123,6 +154,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",
@@ -158,3 +210,12 @@ __all__ = [
     "WorktreeError",
     # </generated:error-exports>
 ]
+
+
+def __getattr__(name: str) -> Any:
+    # `opencode.types` builds several hundred models, so it is imported on first use rather than with the package.
+    if name == "types":
+        import importlib
+
+        return importlib.import_module(".types", __name__)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

{opencode_python_sdk-0.1.2 → opencode_python_sdk-0.2.0}/src/opencode/_base_client.py

@@ -7,6 +7,7 @@ transient failures, and turns responses into typed values or errors.
 from __future__ import annotations
 
 import base64
+import builtins
 import email.utils
 import functools
 import json
@@ -60,8 +61,18 @@ def _cached_adapter(tp: Any) -> pydantic.TypeAdapter[Any]:
     return pydantic.TypeAdapter(tp)
 
 
+@functools.cache
+def _resolve_type(expr: str) -> Any:
+    # Generated resources name their response types as strings, so `import opencode` does not build every model.
+    from . import types
+
+    return eval(expr, {**vars(types), "builtins": builtins})  # expressions come from the generator
+
+
 def type_adapter(tp: Any) -> pydantic.TypeAdapter[Any]:
-    """Returns a cached ``TypeAdapter`` for a response type."""
+    """Returns a cached ``TypeAdapter`` for a response type, or for a type expression over ``opencode.types``."""
+    if isinstance(tp, str):
+        tp = _resolve_type(tp)
     try:
         return _cached_adapter(tp)
     except TypeError:  # unhashable type expression
@@ -307,6 +318,7 @@ class SyncAPIClient(_BaseClient):
         default_headers: Mapping[str, str] | None,
         default_query: Mapping[str, object] | None,
         http_client: httpx.Client | None,
+        transport: httpx.BaseTransport | None = None,
     ) -> None:
         super().__init__(
             base_url=base_url,
@@ -319,7 +331,11 @@ class SyncAPIClient(_BaseClient):
             default_query=default_query,
         )
         self._owns_http = http_client is None
-        self._http = http_client or httpx.Client(limits=constants.DEFAULT_CONNECTION_LIMITS, follow_redirects=True)
+        if http_client is not None and transport is not None:
+            raise ValueError("Pass either http_client or transport, not both")
+        self._http = http_client or httpx.Client(
+            limits=constants.DEFAULT_CONNECTION_LIMITS, follow_redirects=True, transport=transport
+        )
 
     def close(self) -> None:
         """Closes the connection pool, unless it was passed in by the caller."""
@@ -421,6 +437,7 @@ class AsyncAPIClient(_BaseClient):
         default_headers: Mapping[str, str] | None,
         default_query: Mapping[str, object] | None,
         http_client: httpx.AsyncClient | None,
+        transport: httpx.AsyncBaseTransport | None = None,
     ) -> None:
         super().__init__(
             base_url=base_url,
@@ -433,7 +450,11 @@ class AsyncAPIClient(_BaseClient):
             default_query=default_query,
         )
         self._owns_http = http_client is None
-        self._http = http_client or httpx.AsyncClient(limits=constants.DEFAULT_CONNECTION_LIMITS, follow_redirects=True)
+        if http_client is not None and transport is not None:
+            raise ValueError("Pass either http_client or transport, not both")
+        self._http = http_client or httpx.AsyncClient(
+            limits=constants.DEFAULT_CONNECTION_LIMITS, follow_redirects=True, transport=transport
+        )
 
     async def close(self) -> None:
         """Closes the connection pool, unless it was passed in by the caller."""

{opencode_python_sdk-0.1.2 → opencode_python_sdk-0.2.0}/src/opencode/_client.py

@@ -1,22 +1,30 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
+from functools import cached_property
+from typing import TYPE_CHECKING, Any
 
 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
 
 if TYPE_CHECKING:
     import os
-    from collections.abc import Mapping
+    from collections.abc import Iterable, Mapping
 
     import httpx
 
+    from .testing import FakeServer
+
 __all__ = ["AsyncOpencode", "Opencode"]
 
+FAKE_BASE_URL = "http://opencode.fake"
+"""Base URL of clients made by ``Opencode.fake()``."""
+
 
 class Opencode(SyncAPIClient, SyncResources):
     """Synchronous client for an OpenCode server.
@@ -35,6 +43,8 @@ class Opencode(SyncAPIClient, SyncResources):
         default_query: Query parameters sent with every request.
         http_client: A preconfigured ``httpx.Client`` (proxies, custom transports, event hooks). The caller keeps
             ownership and must close it.
+        transport: An ``httpx`` transport for the client's own connection pool, such as
+            :class:`opencode.testing.FakeServer`. Cannot be combined with ``http_client``.
 
     Example::
 
@@ -57,6 +67,7 @@ class Opencode(SyncAPIClient, SyncResources):
         default_headers: Mapping[str, str] | None = None,
         default_query: Mapping[str, object] | None = None,
         http_client: httpx.Client | None = None,
+        transport: httpx.BaseTransport | None = None,
     ) -> None:
         super().__init__(
             base_url=base_url,
@@ -68,8 +79,46 @@ class Opencode(SyncAPIClient, SyncResources):
             default_headers=default_headers,
             default_query=default_query,
             http_client=http_client,
+            transport=transport,
         )
 
+    @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)
+
+    @classmethod
+    def fake(cls, server: FakeServer | None = None, **kwargs: Any) -> Self:
+        """Returns a client wired to an in-process :class:`opencode.testing.FakeServer`, for tests.
+
+        Pass your own ``server`` to configure replies and inspect requests; other arguments go to the constructor.
+        """
+        from .testing import FakeServer
+
+        kwargs.setdefault("password", "")
+        return cls(FAKE_BASE_URL, transport=server if server is not None else FakeServer(), **kwargs)
+
+    def wait_until_ready(
+        self, *, agents: Iterable[str] = (), mcp_servers: Iterable[str] = (), timeout: float = 60
+    ) -> None:
+        """Blocks until the server answers, the named ``agents`` are listed and the named ``mcp_servers`` are
+        connected.
+
+        Agents load asynchronously after the server starts, so call this before creating sessions on a freshly
+        booted server. Connection errors and 503s while the server boots count as not ready yet.
+
+        Raises:
+          TimeoutError: Something was still missing after ``timeout`` seconds. The message names it.
+        """
+        from .lib._ready import wait_until_ready
+
+        wait_until_ready(self, agents=agents, mcp_servers=mcp_servers, timeout=timeout)
+
     def with_options(
         self,
         *,
@@ -125,6 +174,7 @@ class AsyncOpencode(AsyncAPIClient, AsyncResources):
         default_headers: Mapping[str, str] | None = None,
         default_query: Mapping[str, object] | None = None,
         http_client: httpx.AsyncClient | None = None,
+        transport: httpx.AsyncBaseTransport | None = None,
     ) -> None:
         super().__init__(
             base_url=base_url,
@@ -136,8 +186,46 @@ class AsyncOpencode(AsyncAPIClient, AsyncResources):
             default_headers=default_headers,
             default_query=default_query,
             http_client=http_client,
+            transport=transport,
         )
 
+    @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)
+
+    @classmethod
+    def fake(cls, server: FakeServer | None = None, **kwargs: Any) -> Self:
+        """Returns a client wired to an in-process :class:`opencode.testing.FakeServer`, for tests.
+
+        Pass your own ``server`` to configure replies and inspect requests; other arguments go to the constructor.
+        """
+        from .testing import FakeServer
+
+        kwargs.setdefault("password", "")
+        return cls(FAKE_BASE_URL, transport=server if server is not None else FakeServer(), **kwargs)
+
+    async def wait_until_ready(
+        self, *, agents: Iterable[str] = (), mcp_servers: Iterable[str] = (), timeout: float = 60
+    ) -> None:
+        """Blocks until the server answers, the named ``agents`` are listed and the named ``mcp_servers`` are
+        connected.
+
+        Agents load asynchronously after the server starts, so call this before creating sessions on a freshly
+        booted server. Connection errors and 503s while the server boots count as not ready yet.
+
+        Raises:
+          TimeoutError: Something was still missing after ``timeout`` seconds. The message names it.
+        """
+        from .lib._ready import async_wait_until_ready
+
+        await async_wait_until_ready(self, agents=agents, mcp_servers=mcp_servers, timeout=timeout)
+
     def with_options(
         self,
         *,