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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: opencode-python-sdk
-Version: 0.1.3
+Version: 0.2.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/
@@ -350,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:
@@ -370,6 +419,27 @@ with server:
 The server runs in `--stdio` mode, so it also exits when the Python process dies. `AsyncOpencodeServer` is the
 async equivalent.
 
+### The background service
+
+OpenCode can also run one shared background server per user (`opencode serve --service`), which registers itself in
+`$XDG_STATE_HOME/opencode/service.json`. `Opencode.from_service()` connects to it, starting it first if it is not
+running:
+
+```python
+from opencode import Opencode, service
+
+with Opencode.from_service(version="2.1.2") as client:  # replaces a service running another version
+    print(client.server.info().version)
+
+endpoint = service.discover()  # an Endpoint, or None; never starts anything
+service.stop(pty="handoff")  # hand persistent terminals to the next service instead of closing them
+```
+
+`service.ensure()` returns the `Endpoint` (URL and credentials) without creating a client, and `service.headers()`
+gives its `Authorization` header for other HTTP clients. Concurrent callers are safe: they race to start the service
+and all get the one that won. `await AsyncOpencode.from_service()`, `service.async_discover()`,
+`service.async_ensure()` and `service.async_stop()` are the async equivalents.
+
 ## Advanced
 
 ```python

{opencode_python_sdk-0.1.3 → opencode_python_sdk-0.2.2}/README.md

@@ -313,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:
@@ -333,6 +382,27 @@ with server:
 The server runs in `--stdio` mode, so it also exits when the Python process dies. `AsyncOpencodeServer` is the
 async equivalent.
 
+### The background service
+
+OpenCode can also run one shared background server per user (`opencode serve --service`), which registers itself in
+`$XDG_STATE_HOME/opencode/service.json`. `Opencode.from_service()` connects to it, starting it first if it is not
+running:
+
+```python
+from opencode import Opencode, service
+
+with Opencode.from_service(version="2.1.2") as client:  # replaces a service running another version
+    print(client.server.info().version)
+
+endpoint = service.discover()  # an Endpoint, or None; never starts anything
+service.stop(pty="handoff")  # hand persistent terminals to the next service instead of closing them
+```
+
+`service.ensure()` returns the `Endpoint` (URL and credentials) without creating a client, and `service.headers()`
+gives its `Authorization` header for other HTTP clients. Concurrent callers are safe: they race to start the service
+and all get the one that won. `await AsyncOpencode.from_service()`, `service.async_discover()`,
+`service.async_ensure()` and `service.async_stop()` are the async equivalents.
+
 ## Advanced
 
 ```python

{opencode_python_sdk-0.1.3 → opencode_python_sdk-0.2.2}/pyproject.toml

@@ -55,9 +55,11 @@ dev = [
   "trio>=0.31",
   "websockets>=14",
 ]
+# Pillow (via [imaging]) only ships patched releases for Python 3.11+, so docs builds need 3.11+.
 docs = [
-    "mkdocs-material[imaging]>=9.6",
-    "mkdocstrings[python]>=0.30",
+    "mkdocs-material[imaging]>=9.6; python_version >= '3.11'",
+    "mkdocstrings[python]>=0.30; python_version >= '3.11'",
+    "pillow>=13; python_version >= '3.11'",
 ]
 
 [build-system]

{opencode_python_sdk-0.1.3 → opencode_python_sdk-0.2.2}/src/opencode/__init__.py

@@ -14,7 +14,9 @@ Quick start::
 
 from __future__ import annotations
 
-from . import types
+from typing import TYPE_CHECKING, Any
+
+from . import service
 from ._client import AsyncOpencode, Opencode
 
 # <generated:error-imports>
@@ -77,6 +79,7 @@ from ._models import BaseModel
 from ._pagination import AsyncCursorPage, AsyncPaginator, SyncCursorPage
 from ._pty import AsyncPtyConnection, PtyConnection, PtyConnectionError
 from ._server import AsyncOpencodeServer, OpencodeServer, ServerStartError
+from ._service import Endpoint, ServiceError
 from ._streaming import AsyncStream, Stream
 from ._types import NOT_GIVEN, NotGiven
 from ._version import __version__
@@ -108,6 +111,9 @@ from ._rpc import (
     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."""
@@ -132,6 +138,7 @@ __all__ = [
     "BaseModel",
     "ConflictError",
     "ContentTooLargeError",
+    "Endpoint",
     "InternalServerError",
     "NotFoundError",
     "NotGiven",
@@ -144,11 +151,13 @@ __all__ = [
     "PtyConnectionError",
     "RateLimitError",
     "ServerStartError",
+    "ServiceError",
     "ServiceUnavailableError",
     "Stream",
     "SyncCursorPage",
     "UnprocessableEntityError",
     "__version__",
+    "service",
     "types",
     # Shared event stream and typed plugin RPC
     "SUBSCRIBER_CAPACITY",
@@ -206,3 +215,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.3 → opencode_python_sdk-0.2.2}/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.2.2/src/opencode/_client.py

@@ -0,0 +1,361 @@
+from __future__ import annotations
+
+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 ._service import (
+    EnsureReason,
+    ServiceError,
+    Version,
+    async_discover,
+    async_ensure,
+    discover as discover_service,
+    ensure as ensure_service,
+)
+from ._types import NOT_GIVEN, NotGiven, Timeout
+from .resources import AsyncResources, SyncResources
+
+if TYPE_CHECKING:
+    import os
+    from collections.abc import Callable, Iterable, Mapping, Sequence
+
+    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.
+
+    Args:
+        base_url: Server URL, for example ``http://127.0.0.1:4096``. Defaults to ``OPENCODE_BASE_URL``.
+        password: Server password. Defaults to ``OPENCODE_PASSWORD``, then ``OPENCODE_SERVER_PASSWORD``. Pass ``""``
+            to send no credentials.
+        username: Basic auth user name. The OpenCode server uses ``opencode``.
+        directory: Default project directory. Sent as the ``location`` of every request that accepts one, unless
+            the call passes its own ``location``.
+        timeout: Default timeout in seconds, or an ``httpx.Timeout``. Event streams only apply the connect timeout.
+        max_retries: Retries for connection failures and transient statuses. Requests that may have changed state
+            on the server are only retried when the server refused them before acting (429 and 503).
+        default_headers: Headers sent with every request.
+        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::
+
+        from opencode import Opencode
+
+        with Opencode("http://127.0.0.1:4096", password="...") as client:
+            for agent in client.agent.list():
+                print(agent.id)
+    """
+
+    def __init__(
+        self,
+        base_url: str | httpx.URL | None = None,
+        *,
+        password: str | None = None,
+        username: str = DEFAULT_USERNAME,
+        directory: str | os.PathLike[str] | None = None,
+        timeout: Timeout = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        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,
+            password=password,
+            username=username,
+            directory=directory,
+            timeout=timeout,
+            max_retries=max_retries,
+            default_headers=default_headers,
+            default_query=default_query,
+            http_client=http_client,
+            transport=transport,
+        )
+
+    @classmethod
+    def from_service(
+        cls,
+        *,
+        start: bool = True,
+        file: str | os.PathLike[str] | None = None,
+        version: Version | None = None,
+        command: Sequence[str] | None = None,
+        env: Mapping[str, str] | None = None,
+        on_start: Callable[[EnsureReason, str | None], None] | None = None,
+        directory: str | os.PathLike[str] | None = None,
+        timeout: Timeout = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        default_headers: Mapping[str, str] | None = None,
+        default_query: Mapping[str, object] | None = None,
+    ) -> Self:
+        """Connect to the local background service, starting ``opencode serve --service`` if needed.
+
+        Uses :func:`opencode.service.ensure`, or :func:`opencode.service.discover` when ``start`` is false, and
+        sends the service's password with every request.
+
+        Args:
+            start: Start or replace the service when no matching one is running. When false, raise instead.
+            file: Registration file. Defaults to ``$XDG_STATE_HOME/opencode/service.json``.
+            version: Required exact version, or a predicate on the service version.
+            command: Service command and arguments, used when starting it.
+            env: Variables added to the environment of a started service.
+            on_start: Called once before a service process is started.
+            directory: Default project directory, as in the constructor.
+            timeout: Default request timeout, as in the constructor.
+            max_retries: Retries for failed requests, as in the constructor.
+            default_headers: Headers sent with every request.
+            default_query: Query parameters sent with every request.
+
+        Raises:
+            ServiceError: No matching service is running and ``start`` is false, or it could not be started.
+
+        Example::
+
+            with Opencode.from_service() as client:
+                print(client.server.info().version)
+        """
+        if start:
+            endpoint = ensure_service(file, version, command=command, env=env, on_start=on_start)
+        else:
+            found = discover_service(file, version)
+            if found is None:
+                raise ServiceError("No matching OpenCode background service is running")
+            endpoint = found
+        return cls(
+            endpoint.url,
+            # An empty password sends no credentials instead of falling back to OPENCODE_PASSWORD.
+            password="" if endpoint.auth is None else endpoint.auth.password,
+            username=DEFAULT_USERNAME if endpoint.auth is None else endpoint.auth.username,
+            directory=directory,
+            timeout=timeout,
+            max_retries=max_retries,
+            default_headers=default_headers,
+            default_query=default_query,
+        )
+
+    @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,
+        *,
+        base_url: str | httpx.URL | None = None,
+        password: str | NotGiven | None = NOT_GIVEN,
+        directory: str | os.PathLike[str] | NotGiven | None = NOT_GIVEN,
+        timeout: Timeout | NotGiven = NOT_GIVEN,
+        max_retries: int | None = None,
+        default_headers: Mapping[str, str] | None = None,
+        default_query: Mapping[str, object] | None = None,
+    ) -> Self:
+        """Returns a client with some options changed. It shares this client's connection pool.
+
+        ``default_headers`` and ``default_query`` are merged over the current values.
+        """
+        client = type(self)(
+            base_url=base_url or self.base_url,
+            password=self.password or "" if isinstance(password, NotGiven) else password,
+            username=self.username,
+            directory=self.directory if isinstance(directory, NotGiven) else directory,
+            timeout=self.timeout if isinstance(timeout, NotGiven) else timeout,
+            max_retries=self.max_retries if max_retries is None else max_retries,
+            default_headers={**self._default_headers, **(default_headers or {})},
+            default_query={**self._default_query, **(default_query or {})},
+            http_client=self._http,
+        )
+        return client
+
+
+class AsyncOpencode(AsyncAPIClient, AsyncResources):
+    """Asynchronous client for an OpenCode server. Works with asyncio and trio.
+
+    Takes the same arguments as :class:`Opencode`; ``http_client`` is an ``httpx.AsyncClient``.
+
+    Example::
+
+        from opencode import AsyncOpencode
+
+        async with AsyncOpencode("http://127.0.0.1:4096", password="...") as client:
+            for agent in await client.agent.list():
+                print(agent.id)
+    """
+
+    def __init__(
+        self,
+        base_url: str | httpx.URL | None = None,
+        *,
+        password: str | None = None,
+        username: str = DEFAULT_USERNAME,
+        directory: str | os.PathLike[str] | None = None,
+        timeout: Timeout = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        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,
+            password=password,
+            username=username,
+            directory=directory,
+            timeout=timeout,
+            max_retries=max_retries,
+            default_headers=default_headers,
+            default_query=default_query,
+            http_client=http_client,
+            transport=transport,
+        )
+
+    @classmethod
+    async def from_service(
+        cls,
+        *,
+        start: bool = True,
+        file: str | os.PathLike[str] | None = None,
+        version: Version | None = None,
+        command: Sequence[str] | None = None,
+        env: Mapping[str, str] | None = None,
+        on_start: Callable[[EnsureReason, str | None], None] | None = None,
+        directory: str | os.PathLike[str] | None = None,
+        timeout: Timeout = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        default_headers: Mapping[str, str] | None = None,
+        default_query: Mapping[str, object] | None = None,
+    ) -> Self:
+        """Async version of :meth:`Opencode.from_service`. Await it: ``client = await AsyncOpencode.from_service()``."""
+        if start:
+            endpoint = await async_ensure(file, version, command=command, env=env, on_start=on_start)
+        else:
+            found = await async_discover(file, version)
+            if found is None:
+                raise ServiceError("No matching OpenCode background service is running")
+            endpoint = found
+        return cls(
+            endpoint.url,
+            # An empty password sends no credentials instead of falling back to OPENCODE_PASSWORD.
+            password="" if endpoint.auth is None else endpoint.auth.password,
+            username=DEFAULT_USERNAME if endpoint.auth is None else endpoint.auth.username,
+            directory=directory,
+            timeout=timeout,
+            max_retries=max_retries,
+            default_headers=default_headers,
+            default_query=default_query,
+        )
+
+    @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,
+        *,
+        base_url: str | httpx.URL | None = None,
+        password: str | NotGiven | None = NOT_GIVEN,
+        directory: str | os.PathLike[str] | NotGiven | None = NOT_GIVEN,
+        timeout: Timeout | NotGiven = NOT_GIVEN,
+        max_retries: int | None = None,
+        default_headers: Mapping[str, str] | None = None,
+        default_query: Mapping[str, object] | None = None,
+    ) -> Self:
+        """Returns a client with some options changed. It shares this client's connection pool.
+
+        ``default_headers`` and ``default_query`` are merged over the current values.
+        """
+        client = type(self)(
+            base_url=base_url or self.base_url,
+            password=self.password or "" if isinstance(password, NotGiven) else password,
+            username=self.username,
+            directory=self.directory if isinstance(directory, NotGiven) else directory,
+            timeout=self.timeout if isinstance(timeout, NotGiven) else timeout,
+            max_retries=self.max_retries if max_retries is None else max_retries,
+            default_headers={**self._default_headers, **(default_headers or {})},
+            default_query={**self._default_query, **(default_query or {})},
+            http_client=self._http,
+        )
+        return client