[shrijayan]

Adds high-level helpers for the headless use case in anomalyco/opencode#54300 (run an agent, wait, read the result), a fake server for users' tests, and a faster import opencode.

What's new

• client.session.run(text, *, agent, model, files, session_id, timeout) (sync + async). It creates a session or reuses session_id (switching agent/model if given), prompts it, blocks on session.wait, and returns opencode.lib.RunResult with session, the new messages, text, outcome, error, and per-run cost/tokens. If the wait ends early (KeyboardInterrupt, async cancellation, timeout, or any error), it calls session.interrupt before re-raising. The async version shields that call from cancellation.
• Codegen hook: HELPER_BASES in codegen/render.py lets a generated resource class inherit from a hand-written base in src/opencode/lib/. SessionResource(SessionHelpers) uses it.
• client.wait_until_ready(*, agents=(), mcp_servers=(), timeout=60) (sync + async) polls server.info, agent.list and mcp.list. Connection errors and 503s count as still booting. On timeout it raises TimeoutError naming what is missing.
• transport= on both client constructors (additive; can't be combined with http_client), plus Opencode.fake() / AsyncOpencode.fake().
• opencode.testing.FakeServer is an httpx.MockTransport with in-memory sessions, prompts (including resume=False queueing), wait, interrupt, paged messages, agents, MCP status, server info and the SSE event stream. Payloads are built from the generated models. Test hooks: fail() for error/exception injection, add_agent/set_mcp_status(after_polls=...), requests, prompts.
• Docs: README sections, docs/guides/headless.md, docs/guides/testing.md, docs/reference/testing.md.

Import time (separate commit perf: load opencode.types on first use)

Generated resources now name response types as strings, which type_adapter resolves on first use, and import models only under TYPE_CHECKING. opencode.types is loaded lazily. Wall clock for import opencode, median of 9 runs on macOS with Python 3.14:

	import opencode
before	~400 ms
after	~265 ms

The model build (~130 ms) now happens on the first request. What remains at import is mostly httpx, pydantic and typing_extensions. A subprocess test guards that import opencode doesn't load opencode.types._generated.

Tests

• tests/test_helpers.py (19 tests, all on the fake): run, reuse, paging, interrupt on 503, KeyboardInterrupt and async cancel, wait_until_ready, and fake CRUD/errors/events.
• Live: wait_until_ready, plus run against a model of a nonexistent provider. That flow fails before any network call, so no model is called. Note: a default-model prompt on a sandboxed server uses OpenCode's hosted free model, which is why the test pins an unroutable model.

Don't merge without review: every merge to main publishes a release.