opencode-python-sdk 0.1.2__py3-none-any.whl → 0.2.0__py3-none-any.whl

opencode/testing.py

@@ -0,0 +1,508 @@
+"""An in-process fake OpenCode server for your own tests.
+
+:class:`FakeServer` is an ``httpx`` transport that answers like an OpenCode server, keeping sessions, messages and
+events in memory. Plug it into a client and test code that uses the SDK without starting ``opencode serve`` or
+calling a model::
+
+    from opencode import Opencode
+    from opencode.testing import FakeServer
+
+    fake = FakeServer(reply="Done.")
+    client = Opencode.fake(fake)  # or Opencode(transport=fake)
+
+    result = client.session.run("Fix the bug", agent="build")
+    assert result.text == "Done."
+    assert fake.prompts == ["Fix the bug"]
+
+It covers sessions (create, get, list, remove, switch agent or model), prompts, waiting, interrupts, messages,
+agents, MCP servers, server info and the event stream. Every payload is built from the generated models, so it
+has the shape the real server sends. Other routes answer ``404``. Use :meth:`FakeServer.fail` to make a route fail.
+"""
+
+from __future__ import annotations
+
+import itertools
+import json
+import os
+import re
+import time
+from collections.abc import Callable, Iterable, Mapping
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+from ._models import BaseModel
+from .types import (
+    AgentInfo,
+    AgentListResponse,
+    LocationPublicRef,
+    McpListResponse,
+    McpServer,
+    ModelRef,
+    ServerConnectedEvent,
+    ServerInfo,
+    SessionCreatedEvent,
+    SessionIdleEvent,
+    SessionInboxUser,
+    SessionInfo,
+    SessionInterruptResponse,
+    SessionMessageAssistant,
+    SessionMessageAssistantText,
+    SessionMessageIdle,
+    SessionMessageUser,
+    TokenUsageInfo,
+)
+
+__all__ = ["DEFAULT_MODEL", "FakeServer"]
+
+DEFAULT_MODEL = ModelRef(id="fake-model", provider_id="fake")
+"""Model reported for sessions created without one."""
+
+Reply = str | Callable[[str], str]
+"""Assistant reply: fixed text, or a function from the prompt text to the reply."""
+
+
+@dataclass
+class _Failure:
+    method: str
+    path: re.Pattern[str]
+    status: int
+    body: object
+    exception: BaseException | None
+    times: int | None
+
+
+class FakeServer(httpx.MockTransport):
+    """An in-memory OpenCode server, usable as the ``transport`` of :class:`opencode.Opencode` and
+    :class:`opencode.AsyncOpencode`.
+
+    Args:
+        reply: What the assistant answers to each prompt: text, or a function of the prompt text.
+        agents: Agent ids :meth:`opencode.Opencode.agent.list` reports. Add more later with :meth:`add_agent`.
+        mcp_servers: MCP server names mapped to their status (``connected``, ``pending``, ``failed``, ...).
+        directory: Project directory reported as every session's location.
+        cost: Cost in USD reported for each assistant reply.
+        tokens: Input and output tokens reported for each assistant reply.
+
+    Attributes:
+        sessions: Sessions by id.
+        messages: Messages of each session, oldest first.
+        events: Events the stream replays after ``server.connected``.
+        requests: Every request received, in order.
+    """
+
+    def __init__(
+        self,
+        *,
+        reply: Reply = "OK",
+        agents: Iterable[str] = ("build", "plan"),
+        mcp_servers: Mapping[str, str] | None = None,
+        directory: str = "/fake/project",
+        cost: float = 0.001,
+        tokens: tuple[int, int] = (10, 5),
+    ) -> None:
+        super().__init__(self._handle)
+        self.reply: Reply = reply
+        self.directory = directory
+        self.cost = cost
+        self.tokens = tokens
+        self.sessions: dict[str, SessionInfo] = {}
+        self.messages: dict[str, list[BaseModel]] = {}
+        self.inbox: dict[str, list[SessionInboxUser]] = {}
+        self.events: list[BaseModel] = []
+        self.requests: list[httpx.Request] = []
+        self._agents: list[tuple[str, int]] = [(agent, 0) for agent in agents]
+        self._mcp: dict[str, tuple[str, int]] = {name: (status, 0) for name, status in (mcp_servers or {}).items()}
+        self._polls = {"agent": 0, "mcp": 0}
+        self._failures: list[_Failure] = []
+        self._ids = itertools.count(1)
+
+    # -- configuration --------------------------------------------------------------------------------------
+
+    def add_agent(self, agent: str, *, after_polls: int = 0) -> None:
+        """Lists ``agent`` once ``GET /api/agent`` has been called ``after_polls`` more times, like an agent that
+        loads after boot."""
+        self._agents.append((agent, self._polls["agent"] + after_polls))
+
+    def set_mcp_status(self, name: str, status: str = "connected", *, after_polls: int = 0) -> None:
+        """Reports MCP server ``name`` with ``status`` once ``GET /api/mcp`` has been called ``after_polls`` more
+        times."""
+        self._mcp[name] = (status, self._polls["mcp"] + after_polls)
+
+    def fail(
+        self,
+        method: str,
+        path: str,
+        *,
+        status: int = 500,
+        body: object = None,
+        exception: BaseException | None = None,
+        times: int | None = 1,
+    ) -> None:
+        """Makes matching requests fail.
+
+        Args:
+            method: HTTP method, such as ``POST``.
+            path: Regular expression matched against the whole request path, such as ``/api/session/[^/]+/prompt``.
+            status: Status of the error response.
+            body: JSON error body. Defaults to an untagged body, so the error class follows ``status``.
+            exception: Raise this from the transport instead of answering, for example ``httpx.ConnectError(...)``
+                or ``KeyboardInterrupt()``.
+            times: How many requests fail; ``None`` for all of them.
+        """
+        if body is None:
+            body = {"message": f"Injected failure ({status})"}
+        self._failures.append(_Failure(method.upper(), re.compile(path), status, body, exception, times))
+
+    @property
+    def prompts(self) -> list[str]:
+        """Text of every prompt received, in order."""
+        texts: list[str] = []
+        for request in self.requests:
+            if request.method == "POST" and request.url.path.endswith("/prompt"):
+                texts.append(json.loads(request.content)["text"])
+        return texts
+
+    # -- helpers --------------------------------------------------------------------------------------------
+
+    def _id(self, prefix: str) -> str:
+        return f"{prefix}_{next(self._ids):026d}"
+
+    @staticmethod
+    def _now() -> float:
+        return float(time.time_ns() // 1_000_000)
+
+    @property
+    def _location(self) -> LocationPublicRef:
+        return LocationPublicRef(directory=self.directory)
+
+    def _session(self, session_id: str) -> SessionInfo:
+        try:
+            return self.sessions[session_id]
+        except KeyError:
+            raise _ErrorResponse(
+                404,
+                {
+                    "_tag": "SessionNotFoundError",
+                    "sessionID": session_id,
+                    "message": f"Session not found: {session_id}",
+                },
+            ) from None
+
+    @staticmethod
+    def _body(request: httpx.Request) -> dict[str, Any]:
+        if not request.content:
+            return {}
+        try:
+            payload = json.loads(request.content)
+        except ValueError:
+            raise _invalid("Request body is not JSON") from None
+        if not isinstance(payload, dict):
+            raise _invalid("Request body must be an object")
+        return dict(payload)  # pyright: ignore[reportUnknownArgumentType]
+
+    def _record(self, event: BaseModel) -> None:
+        self.events.append(event)
+
+    def _run(self, session: SessionInfo, text: str) -> None:
+        """Answers one prompt synchronously: assistant reply, idle marker, usage, events."""
+        reply = self.reply(text) if callable(self.reply) else self.reply
+        now = self._now()
+        input_tokens, output_tokens = self.tokens
+        usage = {"input": input_tokens, "output": output_tokens, "reasoning": 0, "cache": {"read": 0, "write": 0}}
+        self.messages[session.id] += [
+            SessionMessageAssistant.model_validate(
+                {
+                    "id": self._id("msg"),
+                    "type": "assistant",
+                    "time": {"created": now, "completed": now},
+                    "agent": session.agent or "build",
+                    "model": (session.model or DEFAULT_MODEL).to_dict(),
+                    "content": [SessionMessageAssistantText(type="text", text=reply).to_dict()],
+                    "finish": "stop",
+                    "cost": self.cost,
+                    "tokens": usage,
+                }
+            ),
+            SessionMessageIdle.model_validate(
+                {"id": self._id("msg"), "type": "idle", "time": {"created": now}, "outcome": "succeeded"}
+            ),
+        ]
+        session.cost += self.cost
+        session.tokens = TokenUsageInfo.model_validate(
+            {
+                "input": session.tokens.input + input_tokens,
+                "output": session.tokens.output + output_tokens,
+                "reasoning": session.tokens.reasoning,
+                "cache": session.tokens.cache.to_dict(),
+            }
+        )
+        session.outcome = "succeeded"
+        session.time.updated = session.time.idle = now
+        self._record(
+            SessionIdleEvent.model_validate(
+                {"id": self._id("evt"), "created": now, "type": "session.idle", "data": {"sessionID": session.id}}
+            )
+        )
+
+    # -- routes ---------------------------------------------------------------------------------------------
+
+    def _server_info(self, request: httpx.Request, match: re.Match[str]) -> httpx.Response:
+        info = ServerInfo.model_validate(
+            {
+                "version": "fake",
+                "pid": os.getpid(),
+                "urls": [str(request.url.copy_with(path="/"))],
+                "paths": {"tmp": "/tmp"},
+            }
+        )
+        return _json(info)
+
+    def _agent_list(self, request: httpx.Request, match: re.Match[str]) -> httpx.Response:
+        self._polls["agent"] += 1
+        visible = [agent for agent, after in self._agents if self._polls["agent"] > after]
+        agents = [
+            AgentInfo.model_validate(
+                {
+                    "id": agent,
+                    "name": agent,
+                    "mode": "primary",
+                    "hidden": False,
+                    "request": {"settings": {}, "headers": {}, "body": {}},
+                    "permissions": [],
+                }
+            )
+            for agent in dict.fromkeys(visible)
+        ]
+        return _json(AgentListResponse(location=self._location, data=agents))
+
+    def _mcp_list(self, request: httpx.Request, match: re.Match[str]) -> httpx.Response:
+        self._polls["mcp"] += 1
+        servers = [
+            McpServer.model_validate(
+                {"name": name, "status": _mcp_status(status if self._polls["mcp"] > after else "pending")}
+            )
+            for name, (status, after) in self._mcp.items()
+        ]
+        return _json(McpListResponse(location=self._location, data=servers))
+
+    def _session_create(self, request: httpx.Request, match: re.Match[str]) -> httpx.Response:
+        body = self._body(request)
+        now = self._now()
+        session_id = body.get("id") or self._id("ses")
+        if session_id in self.sessions:
+            raise _ErrorResponse(409, {"_tag": "ConflictError", "message": f"Session already exists: {session_id}"})
+        session = SessionInfo.model_validate(
+            {
+                "id": session_id,
+                "parentID": body.get("parentID"),
+                "projectID": "prj_fake",
+                "agent": body.get("agent"),
+                "model": body.get("model") or DEFAULT_MODEL.to_dict(),
+                "cost": 0,
+                "tokens": {"input": 0, "output": 0, "reasoning": 0, "cache": {"read": 0, "write": 0}},
+                "time": {"created": now, "updated": now},
+                "title": body.get("title"),
+                "metadata": body.get("metadata"),
+                "location": self._location.to_dict(),
+            }
+        )
+        self.sessions[session.id] = session
+        self.messages[session.id] = []
+        self.inbox[session.id] = []
+        self._record(
+            SessionCreatedEvent.model_validate(
+                {
+                    "id": self._id("evt"),
+                    "created": now,
+                    "type": "session.created",
+                    "durable": {"aggregate_id": session.id, "seq": 0, "version": 1},
+                    "data": {
+                        "sessionID": session.id,
+                        "projectID": session.project_id,
+                        "location": {"directory": self.directory},
+                        "slug": session.id,
+                        "title": session.title,
+                        "agent": session.agent,
+                        "version": "fake",
+                    },
+                }
+            )
+        )
+        return _json({"data": session.to_dict()})
+
+    def _session_list(self, request: httpx.Request, match: re.Match[str]) -> httpx.Response:
+        sessions = list(self.sessions.values())
+        return _page(request, [session.to_dict() for session in sessions], newest_first_default=True)
+
+    def _session_get(self, request: httpx.Request, match: re.Match[str]) -> httpx.Response:
+        return _json({"data": self._session(match["id"]).to_dict()})
+
+    def _session_remove(self, request: httpx.Request, match: re.Match[str]) -> httpx.Response:
+        self._session(match["id"])
+        del self.sessions[match["id"]]
+        self.messages.pop(match["id"], None)
+        self.inbox.pop(match["id"], None)
+        return httpx.Response(204)
+
+    def _session_agent(self, request: httpx.Request, match: re.Match[str]) -> httpx.Response:
+        session = self._session(match["id"])
+        agent = self._body(request).get("agent")
+        if not isinstance(agent, str):
+            raise _invalid("agent is required", field="agent")
+        session.agent = agent
+        return httpx.Response(204)
+
+    def _session_model(self, request: httpx.Request, match: re.Match[str]) -> httpx.Response:
+        session = self._session(match["id"])
+        session.model = ModelRef.model_validate(self._body(request).get("model"))
+        return httpx.Response(204)
+
+    def _session_prompt(self, request: httpx.Request, match: re.Match[str]) -> httpx.Response:
+        session = self._session(match["id"])
+        body = self._body(request)
+        text = body.get("text")
+        if not isinstance(text, str):
+            raise _invalid("text is required", field="text")
+        now = self._now()
+        message_id = body.get("id") or self._id("msg")
+        payload = {key: body[key] for key in ("text", "files", "agents", "skills", "metadata") if key in body}
+        queued = SessionInboxUser.model_validate(
+            {
+                "id": message_id,
+                "sessionID": session.id,
+                "time": {"created": now},
+                "type": "user",
+                "payload": payload,
+                "delivery": body.get("delivery") or "queue",
+            }
+        )
+        if body.get("resume") is False:
+            self.inbox[session.id].append(queued)
+        else:
+            self.messages[session.id].append(
+                SessionMessageUser.model_validate(
+                    {
+                        "id": message_id,
+                        "type": "user",
+                        "time": {"created": now},
+                        "text": text,
+                        "metadata": body.get("metadata"),
+                    }
+                )
+            )
+            self._run(session, text)
+        return _json({"data": queued.to_dict()})
+
+    def _session_wait(self, request: httpx.Request, match: re.Match[str]) -> httpx.Response:
+        self._session(match["id"])
+        return httpx.Response(204)
+
+    def _session_interrupt(self, request: httpx.Request, match: re.Match[str]) -> httpx.Response:
+        self._session(match["id"])
+        return _json(SessionInterruptResponse(interrupted=False))
+
+    def _message_list(self, request: httpx.Request, match: re.Match[str]) -> httpx.Response:
+        self._session(match["id"])
+        wanted = request.url.params.get("type")
+        items = [
+            m.to_dict() for m in self.messages[match["id"]] if wanted is None or getattr(m, "type", None) == wanted
+        ]
+        return _page(request, items, newest_first_default=False)
+
+    def _event_stream(self, request: httpx.Request, match: re.Match[str]) -> httpx.Response:
+        connected = ServerConnectedEvent.model_validate({"id": self._id("evt"), "type": "server.connected", "data": {}})
+        chunks = [f"data: {json.dumps(event.to_dict())}\n\n" for event in [connected, *self.events]]
+        return httpx.Response(200, headers={"content-type": "text/event-stream"}, content="".join(chunks).encode())
+
+    _ROUTES: tuple[tuple[str, str, Callable[..., httpx.Response]], ...] = (
+        ("GET", r"/api/info", _server_info),
+        ("GET", r"/api/agent", _agent_list),
+        ("GET", r"/api/mcp", _mcp_list),
+        ("GET", r"/api/event", _event_stream),
+        ("POST", r"/api/session", _session_create),
+        ("GET", r"/api/session", _session_list),
+        ("GET", r"/api/session/(?P<id>[^/]+)", _session_get),
+        ("DELETE", r"/api/session/(?P<id>[^/]+)", _session_remove),
+        ("POST", r"/api/session/(?P<id>[^/]+)/agent", _session_agent),
+        ("POST", r"/api/session/(?P<id>[^/]+)/model", _session_model),
+        ("POST", r"/api/session/(?P<id>[^/]+)/prompt", _session_prompt),
+        ("POST", r"/api/session/(?P<id>[^/]+)/interrupt", _session_interrupt),
+        ("GET", r"/api/session/(?P<id>[^/]+)/message", _message_list),
+        ("POST", r"/api/experimental/session/(?P<id>[^/]+)/wait", _session_wait),
+    )
+
+    def _handle(self, request: httpx.Request) -> httpx.Response:
+        self.requests.append(request)
+        path = request.url.path
+        for failure in self._failures:
+            if failure.method == request.method and failure.path.fullmatch(path) and failure.times != 0:
+                if failure.times is not None:
+                    failure.times -= 1
+                if failure.exception is not None:
+                    raise failure.exception
+                return httpx.Response(failure.status, json=failure.body)
+        for method, pattern, handler in self._ROUTES:
+            match = re.fullmatch(pattern, path)
+            if match and method == request.method:
+                try:
+                    return handler(self, request, match)
+                except _ErrorResponse as error:
+                    return httpx.Response(error.status, json=error.body)
+        return httpx.Response(
+            404, json={"_tag": "NotFoundError", "message": f"FakeServer does not implement {request.method} {path}"}
+        )
+
+
+class _ErrorResponse(Exception):
+    def __init__(self, status: int, body: dict[str, object]) -> None:
+        super().__init__(body.get("message"))
+        self.status = status
+        self.body = body
+
+
+def _mcp_status(status: str) -> dict[str, object]:
+    if status == "failed":
+        return {"status": status, "error": "Fake MCP server failed to start"}
+    return {"status": status}
+
+
+def _invalid(message: str, *, field: str | None = None) -> _ErrorResponse:
+    return _ErrorResponse(400, {"_tag": "InvalidRequestError", "message": message, "field": field})
+
+
+def _json(payload: BaseModel | dict[str, Any]) -> httpx.Response:
+    return httpx.Response(200, json=payload.to_dict() if isinstance(payload, BaseModel) else payload)
+
+
+def _page(request: httpx.Request, items: list[dict[str, Any]], *, newest_first_default: bool) -> httpx.Response:
+    """Cursor pagination over ``items`` (oldest first). Cursors encode the order and offset, like the server's."""
+    params = request.url.params
+    cursor = params.get("cursor")
+    if cursor is not None:
+        if "order" in params:
+            return httpx.Response(
+                400, json={"_tag": "InvalidRequestError", "message": "order cannot be combined with cursor"}
+            )
+        order, _, offset_text = cursor.partition(":")
+        if order not in ("asc", "desc") or not offset_text.isdigit():
+            return httpx.Response(400, json={"_tag": "InvalidCursorError", "message": f"Invalid cursor: {cursor}"})
+        offset = int(offset_text)
+    else:
+        order = params.get("order") or ("desc" if newest_first_default else "asc")
+        offset = 0
+    limit = int(params.get("limit") or 50)
+    ordered = list(reversed(items)) if order == "desc" else items
+    data = ordered[offset : offset + limit]
+    end = offset + len(data)
+    return httpx.Response(
+        200,
+        json={
+            "data": data,
+            "cursor": {
+                "previous": f"{order}:{max(offset - limit, 0)}" if offset > 0 else None,
+                "next": f"{order}:{end}" if end < len(ordered) else None,
+            },
+        },
+    )

{opencode_python_sdk-0.1.2.dist-info → opencode_python_sdk-0.2.0.dist-info}/METADATA

@@ -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: