docs: guides for headless runs and the fake server, reference entries

Author: shrijayan

docs/guides/headless.md

@@ -0,0 +1,75 @@
+# Running agents headless
+
+The common embedded use of OpenCode is: start the server, wait until the agents you configured have loaded, run
+one prompt per unit of work, and read the result. Two helpers cover that on both clients.
+
+## Wait until the server is ready
+
+Agents load and MCP servers connect in the background after `opencode serve` starts listening, so the first
+requests can arrive before your agent exists. `wait_until_ready` polls until everything you name is there:
+
+```python
+client.wait_until_ready(agents=["reviewer"], mcp_servers=["github"], timeout=60)
+```
+
+It treats connection errors and `503` answers as "still booting". After `timeout` seconds it raises
+`TimeoutError` naming what is still missing.
+
+## Run a prompt to completion
+
+```python
+from opencode.types import ModelRef
+
+result = client.session.run(
+    "Review the staged changes",
+    agent="reviewer",
+    model=ModelRef(provider_id="anthropic", id="claude-sonnet-5-5"),
+    timeout=600,
+)
+print(result.outcome)  # "succeeded", "failed" or "interrupted"
+print(result.text)  # text of the last assistant message
+print(result.cost, result.tokens.input, result.tokens.output)
+```
+
+`run` creates a session with the agent and model, sends the prompt, blocks on `session.wait` until the session is
+idle, then returns a [`opencode.lib.RunResult`](../reference/testing.md#opencode.lib.RunResult):
+
+- `messages`: the messages this run added, oldest first, starting with the prompt
+- `text`, `outcome`, `error`: the final answer and how the run ended
+- `cost`, `tokens`: usage of this run; `session.cost` and `session.tokens` are the session totals
+
+Set `model` together with `agent` when creating a session: otherwise the session can run on a different model
+than the agent's.
+
+Pass `session_id=` to continue a session. `agent` and `model` then switch the session before the prompt, and
+`messages` holds only the new messages.
+
+### Interrupts
+
+If waiting ends early, through `KeyboardInterrupt`, cancelling the task (async), the `timeout`, or a connection
+error, `run` calls `session.interrupt` before re-raising, so the agent does not keep running on the server.
+
+### Files
+
+`files` takes `PromptInputFileAttachment`s. Images and other inline content can be `data:` URLs:
+
+```python
+import base64
+from opencode.types import PromptInputFileAttachment
+
+png = base64.b64encode(open("screenshot.png", "rb").read()).decode()
+client.session.run(
+    "What is wrong in this screenshot?",
+    files=[PromptInputFileAttachment(uri=f"data:image/png;base64,{png}", name="screenshot.png")],
+)
+```
+
+## Async
+
+The same helpers exist on `AsyncOpencode`:
+
+```python
+async with AsyncOpencode(url, password=password) as client:
+    await client.wait_until_ready(agents=["build"])
+    result = await client.session.run("Summarize README.md", agent="build")
+```

docs/guides/index.md

@@ -30,7 +30,7 @@ entry; the common ones also have a guide. CI fails if a group on the client is m
 | `client.reference` | References | - | [`ReferenceResource`](../reference/resources.md#opencode.resources.reference.ReferenceResource) |
 | `client.rpc` | Plugin RPC | [Plugin RPC](plugin-rpc.md) | [`RpcResource`](../reference/resources.md#opencode.resources.rpc.RpcResource) |
 | `client.server` | Server info and health | - | [`ServerResource`](../reference/resources.md#opencode.resources.server.ServerResource) |
-| `client.session` | Sessions, prompts and their sub-resources | [Guide](sessions.md) | [`SessionResource`](../reference/resources.md#opencode.resources.session.SessionResource) |
+| `client.session` | Sessions, prompts and their sub-resources; `run` for one-call prompts | [Guide](sessions.md), [headless](headless.md) | [`SessionResource`](../reference/resources.md#opencode.resources.session.SessionResource) |
 | `client.shell` | Shells | - | [`ShellResource`](../reference/resources.md#opencode.resources.shell.ShellResource) |
 | `client.skill` | Skills | - | [`SkillResource`](../reference/resources.md#opencode.resources.skill.SkillResource) |
 | `client.vcs` | Version control status and branches | - | [`VcsResource`](../reference/resources.md#opencode.resources.vcs.VcsResource) |

docs/guides/testing.md

@@ -0,0 +1,57 @@
+# Testing with the fake server
+
+`opencode.testing.FakeServer` lets you test code that uses the SDK without starting `opencode serve` or calling
+a model. It is an `httpx` transport (an `httpx.MockTransport`) that keeps sessions, messages and events in
+memory and answers with payloads built from the generated models.
+
+```python
+from opencode import Opencode
+from opencode.testing import FakeServer
+
+
+def test_review() -> None:
+    fake = FakeServer(reply=lambda prompt: "LGTM" if "diff" in prompt else "?")
+    client = Opencode.fake(fake)  # same as Opencode(transport=fake)
+
+    result = client.session.run("Review this diff", agent="build")
+
+    assert result.text == "LGTM"
+    assert fake.prompts == ["Review this diff"]
+```
+
+`AsyncOpencode.fake(fake)` works the same way.
+
+## What it implements
+
+Server info, agents, MCP servers, the event stream, and sessions: create, get, list, remove, switch agent or
+model, prompt (with `resume=False` queueing the prompt without running it), wait, interrupt and messages, with
+cursor pagination. Each prompt gets an assistant reply, an idle marker, cost and token usage. Other routes
+answer `404` with a message naming the route.
+
+## Simulating a slow boot
+
+```python
+fake = FakeServer(agents=["build"])
+fake.add_agent("reviewer", after_polls=3)  # listed from the 4th GET /api/agent
+fake.set_mcp_status("github", "connected", after_polls=2)
+Opencode.fake(fake).wait_until_ready(agents=["reviewer"], mcp_servers=["github"])
+```
+
+## Injecting failures
+
+```python
+fake.fail(
+    "POST",
+    r"/api/session/.+/prompt",
+    status=409,
+    body={"_tag": "SessionBusyError", "sessionID": "ses_1", "message": "busy"},
+)
+fake.fail("GET", "/api/info", exception=httpx.ConnectError("refused"), times=2)
+```
+
+`path` is a regular expression matched against the whole path. `times=None` fails every matching request.
+
+## Inspecting state
+
+`fake.requests` records every `httpx.Request`; `fake.sessions`, `fake.messages`, `fake.inbox` and `fake.events`
+hold the server state and can be changed directly.

docs/reference/clients.md

@@ -2,12 +2,12 @@
 
 ::: opencode.Opencode
     options:
-      members: [with_options, close]
+      members: [with_options, close, wait_until_ready, fake]
       show_bases: false
 
 ::: opencode.AsyncOpencode
     options:
-      members: [with_options, close]
+      members: [with_options, close, wait_until_ready, fake]
       show_bases: false
 
 ## Module constants

docs/reference/testing.md

@@ -0,0 +1,13 @@
+# Helpers and testing
+
+## `session.run` result
+
+::: opencode.lib.RunResult
+
+## Fake server
+
+::: opencode.testing.FakeServer
+    options:
+      members: [add_agent, set_mcp_status, fail, prompts]
+
+::: opencode.testing.DEFAULT_MODEL

mkdocs.yml

@@ -135,6 +135,8 @@ nav:
   - Guides:
       - guides/index.md
       - Sessions and prompts: guides/sessions.md
+      - Running agents headless: guides/headless.md
+      - Testing with the fake server: guides/testing.md
       - Async: guides/async.md
       - Models and unions: guides/models.md
       - Pagination: guides/pagination.md
@@ -155,6 +157,7 @@ nav:
       - Shared events and RPC: reference/events.md
       - Terminals: reference/terminals.md
       - Exceptions: reference/exceptions.md
+      - Helpers and testing: reference/testing.md
       - Types: reference/types/index.md
   - Project:
       - How it's built: project/how-its-built.md