Struct OpencodeClient 

pub struct OpencodeClient { /* private fields */ }

Async client for the opencode HTTP/SSE server.

Cloning is cheap; the underlying reqwest::Client is shared.

Implementations

impl OpencodeClient

pub fn builder() -> OpencodeClientBuilder

Start building a client. Equivalent to OpencodeClientBuilder::new.

pub fn transport(&self) -> &HttpTransport

The underlying transport, exposing base-URL, auth, and the GET /event URL for an SSE subscriber.

pub fn event_stream(&self, retry: RetryConfig) -> Result<EventStream>

Open the GET /event SSE stream, reusing this client’s base URL, auth, directory/workspace scope, and reqwest connection pool.

This is the ergonomic counterpart to OpencodeClient::list_messages: the same client drives both the low-latency event stream and the authoritative reconciliation poll, so credentials configured with OpencodeClientBuilder::auth flow to the stream without a detour through the OPENCODE_SERVER_PASSWORD environment variable.

Errors

Returns crate::Error if the request cannot be prepared for streaming.

pub async fn create_session( &self, params: &SessionCreateParams, ) -> Result<Session>

Create a new session — POST /session.

The response is the freshly created Session; its id (a ses… string) is used to address every subsequent per-session call.

pub async fn prompt_async( &self, session_id: &str, params: &PromptAsyncParams, ) -> Result<()>

Submit a prompt — POST /session/{sessionID}/prompt_async.

Returns as soon as the server accepts the work (HTTP 204); the agent’s output is observed on the GET /event SSE stream and reconciled via OpencodeClient::list_messages.

pub async fn list_messages( &self, session_id: &str, ) -> Result<Vec<MessageWithParts>>

List a session’s messages — GET /session/{sessionID}/message.

Returns every message with its parts. This is the authoritative reconciliation path for the best-effort SSE stream. For pagination use OpencodeClient::list_messages_page.

pub async fn list_messages_page( &self, session_id: &str, limit: Option<u64>, before: Option<&str>, ) -> Result<Vec<MessageWithParts>>

Paginated variant of OpencodeClient::list_messages.

limit caps the number of messages returned; before is a message id cursor (results strictly older than it) for walking history backwards.

pub async fn abort(&self, session_id: &str) -> Result<bool>

Abort in-flight work — POST /session/{sessionID}/abort.

Returns true when the session had work that was aborted.

pub async fn respond_permission( &self, session_id: &str, permission_id: &str, reply: &PermissionReplyParams, ) -> Result<bool>

Reply to a permission request — POST /session/{sessionID}/permissions/{permissionID}.

Deprecation

In the 1.18.5 spec this route (operation permission.respond) is marked deprecated in favor of the newer reply endpoints POST /permission/{requestID}/reply (operation permission.reply) and POST /api/session/{sessionID}/permission/{requestID}/reply (operation v2.session.permission.reply), neither of which this crate wraps yet. Reach either through the raw OpencodeClient::request escape hatch using those exact paths — note the session-scoped one requires the /api/ prefix. This deprecated route remains the reply channel for the permission.asked event and works on 1.18.5; a future opencode release may remove it.

Correlation contract

Permission handling is deliberately split across two channels and correlating them is the consumer’s responsibility:

1. A permission request arrives on the GET /event SSE stream as an Event::PermissionAsked event (wire type permission.asked), whose properties carry a ses… session id and a per… permission id. This is the only ask event that pairs with this call: the coexisting Event::PermissionV2Asked (permission.v2.asked) belongs to the unwrapped v2 reply endpoints, so do not feed its id here.
2. The reply is this separate REST call, addressed by exactly those two ids. There is no server-side callback and no implicit pairing: the caller must remember which pending (session_id, permission_id) a reply answers.

PermissionReplyParams::response is one of PermissionReplyResponse::Once, Always, or Reject. Returns true when the reply was accepted; a stale or unknown permission id yields crate::Error::Http with status 404.

pub async fn request<T: DeserializeOwned>( &self, method: Method, path: &str, body: Option<Value>, ) -> Result<T>

Raw escape hatch for endpoints this crate does not hand-wrap.

path is joined onto the configured base URL (leading slash optional) and used verbatim; body, when present, is sent as a JSON request body. The 2xx response is deserialized into T; non-2xx becomes crate::Error::Http.

pub async fn request_unit( &self, method: Method, path: &str, body: Option<Value>, ) -> Result<()>

Raw escape hatch for endpoints that answer with an empty body.

Identical to OpencodeClient::request but discards the response body instead of deserializing it. Many opencode POST endpoints reply 204 No Content (e.g. prompt_async and several unwrapped routes); calling those through OpencodeClient::request would fail deserializing the empty body, so use this variant for them.

Trait Implementations

impl Clone for OpencodeClient

fn clone(&self) -> OpencodeClient

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for OpencodeClient

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.