Crate opencode_codes 

A typed Rust interface for the opencode agent server.

Maturity warning: this crate is new and should be considered highly untested — it is under active development. The types are generated from opencode’s published OpenAPI spec and the suite passes against a live server, but real-world mileage is minimal and the API may change between releases while the surface settles. Bug reports and wire captures that break the types are very welcome at https://github.com/meawoppl/rust-code-agent-sdks/issues.

Unlike its sibling crates (claude-codes and codex-codes), which wrap CLIs that speak a JSON-Lines protocol over stdio, opencode runs a local HTTP server with a Server-Sent Events (SSE) stream. This crate models that server’s OpenAPI 3.1 wire contract with serde types, and offers an async (Tokio) client plus a managed launcher for the opencode serve process.

Architecture

opencode exposes a REST + SSE surface:

• REST — session lifecycle and prompt submission are ordinary JSON request/response calls (POST /session, POST /session/{sessionID}/prompt_async, GET /session/{sessionID}/message, POST /session/{sessionID}/abort, POST /session/{sessionID}/permissions/{permissionID}).
• SSE — GET /event is a long-lived event stream carrying incremental message parts, tool activity, and permission requests.

The conversation lifecycle is:

1. Create a session — POST /session.
2. Subscribe — open the GET /event SSE stream.
3. Prompt — POST /session/{sessionID}/prompt_async returns immediately; the agent’s work is observed on the SSE stream.
4. Handle permissions — a permission request arrives on the stream; the reply is a separate REST call (POST /session/{sessionID}/permissions/{permissionID}). Correlating a request to its reply is the consumer’s responsibility — the pending permission surface is kept explicit rather than hidden behind a callback.
5. Reconcile — SSE is best-effort and must not be trusted alone. Poll GET /session/{sessionID}/message to reconcile the authoritative message state against what the stream delivered. This crate documents and exposes that poll path deliberately.
6. Abort — POST /session/{sessionID}/abort cancels in-flight work.

Authentication is HTTP Basic when OPENCODE_SERVER_PASSWORD is set; the username defaults to "opencode".

Feature Flags

Feature	Description	WASM-compatible
types	Core protocol types only (serde)	Yes
async-client	Async HTTP/SSE client using reqwest + tokio	No
server	Managed opencode serve launcher (picks a free port)	No
integration-tests	Enables tests that require a live opencode server	No

default = ["types", "async-client"]. For WASM or type-sharing use cases:

[dependencies]
opencode-codes = { version = "1.18", default-features = false, features = ["types"] }

Provenance

Module layout, SSE handling, and server-lifecycle lessons were informed by the Apache-2.0 licensed opencode_rs reference SDK. No code is copied verbatim; it is credited here as a design reference in keeping with its license.

Tested against: opencode 1.18.5.

Re-exports

pub use error::Error;

pub use error::Result;

pub use sse::EventStream;

pub use sse::RetryConfig;

pub use sse::StreamEvent;

pub use client_async::OpencodeClient;

pub use client_async::OpencodeClientBuilder;

Modules

client_async

High-level async client for the opencode server.

error

Error types for the opencode-codes crate.

http

Low-level REST transport for the opencode server.

protocol_generated

Generated serde models of the opencode OpenAPI 3.1 wire contract.

sse

Server-Sent Events stream handling for GET /event.