Guide

OpenCode as a seat

An engine adapter is different from a system adapter: it does not wrap an API, it wraps the agent itself. OpenCode keeps its own sessions, and the adapter's job is to hand it work, keep the binding to the origin conversation, and report what actually happened.

Two transports

The adapter ships two ways to reach a router. Only the transport differs; the job processing underneath is the same.

v2-legacy — the default: a fixed seat address on a loopback router (8791). The consumer renews its own lease and reconnects to SSE.
v3-autoreg — a private router (8797) where the pc-agent registers the seat. The address changes on every registration, the seat token stays in memory, and the adapter holds only file paths to the endpoint and local token.

What happens to a job

The order matters: an idempotency journal first, then a handover into a session, then verification of the result. A process that exits 0 is not a success on its own.

job ─▶ journal (job_id seen?) ─▶ handover: fixed model, new session
                                     │
                                     ▼
                           opencode runs the work
                                     │
                                     ▼
                         verify (evidence, diff cap)
                                     │
              completed ◀────────────┴──────────▶ completed-output-unverified

When the world moves

A seat address can change, a stream can die, a PC can sleep. The adapter treats each case explicitly instead of retrying forever.

SSE fatal (401/403/404/410) → release the seat and reconnect with backoff from 250 ms to 20 s, as a new seat id.
Address changed (v3 re-registration) → drop the old cursor; the new stream starts fresh.
In-flight job at restart → parked as blocked instead of re-running, because a model may have already acted.
Duplicate delivery → the journal stops a second run of the same job id.

Configuration and limits

The config file names a transport, a seat, a router credential reference, the OpenCode command with an absolute path, the model, allowed directories and a timeout. Credentials are references; values stay in the deployment.

Limits: OpenCode must be installed and its binary on the configured path; Windows npm shims are not spawnable, so use the real executable. Model costs are separate from WMOS. The adapter does not wake a sleeping machine and does not claim automatic thread return.