unofficial-opencode-sdk 0.1.1

Unofficial Rust client SDK for the OpenCode server HTTP and SSE APIs
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
# unofficial-opencode-sdk

Unofficial Rust SDK for the OpenCode server HTTP and SSE APIs.

> **Unofficial:** this project is independent from OpenCode and is not affiliated
> with or endorsed by the OpenCode project.

The current compatibility snapshot targets OpenCode **1.18.31** and
`@opencode-ai/sdk` **1.18.31** at commit
`ba341c6cac5ed1ef867ef127245a42b5e33d4946` from the upstream `dev` branch.

OpenCode currently ships its preview V2 API from the official JavaScript
package's `@opencode-ai/sdk/v2` export while the npm package itself remains on
the 1.x version line. This crate mirrors that separation: legacy/current APIs
remain at the crate root and preview V2 APIs live under
`unofficial_opencode_sdk::v2`.

OpenCode **2.x** serves the `/api/*` contract natively (no `/global/*`
routes): the `v2` client detects the server dialect automatically and works
against both the 1.x preview surface and the native 2.x surface — see
[V2 dialect detection](#v2-dialect-detection).

## Scope

The SDK is deliberately client-only. It connects to an already running
OpenCode server and provides:

- a broad root V1/current surface matching all non-V2 current operations except
  explicit `experimental.*`, `worktree.*`, and `sync.*` families;
- root groups for global/project/pty/config/tool/instance/path/vcs/session/
  command/provider/find/file/app/mcp/lsp/formatter/tui/auth/permission/question/event;
- legacy/current SSE through `client.events().subscribe()` and
  `client.global().events()`;
- isolated `v2::Client` for OpenCode's preview `/api/*` contract;
- V2 session `list/create/get/active/switch-agent/switch-model/prompt/compact/wait/context/history/message/messages/events/interrupt`;
- V2 per-session revert, permission, and question operations;
- V2 health/location/agent/command/skill/reference discovery;
- V2 model/provider discovery;
- V2 integration discovery/connect/attempt APIs and credential update/remove;
- V2 filesystem read/list/find;
- V2 pending/saved permission discovery and saved-permission removal;
- V2 pending question discovery;
- V2 native server event subscription at `/api/event`;
- Basic Auth and directory/workspace context;
- a pinned, reproducible OpenAPI snapshot and operation manifest.

It contains no Temote-specific sandboxing, approvals, worktrees, broker,
checkpoint, task-state, or lifecycle code.

## Install

For the crates.io release:

```toml
[dependencies]
unofficial-opencode-sdk = "0.1"
```

The Rust crate import is `unofficial_opencode_sdk`.

Until the first crates.io release is published, the same package can be used
from Git:

```toml
[dependencies]
unofficial-opencode-sdk = { git = "https://github.com/f4ah6o/unofficial-opencode-sdk-rs" }
```

## Legacy/current client

```rust
use unofficial_opencode_sdk::Client;

let client = Client::builder()
    .base_url("http://127.0.0.1:4096")
    .build()?;
```

If OpenCode is started with `OPENCODE_SERVER_PASSWORD`, configure the matching
Basic Auth credentials. OpenCode defaults the username to `opencode`.

```rust
let client = Client::builder()
    .base_url("http://127.0.0.1:4096")
    .password(std::env::var("OPENCODE_SERVER_PASSWORD")?)
    .build()?;
```

Credentials are never persisted by the SDK.

### Sessions and prompts

```rust
use unofficial_opencode_sdk::{CreateSessionRequest, PromptPart, PromptRequest};

let session = client
    .session()
    .create(&CreateSessionRequest::default())
    .await?;

let response = client
    .session()
    .prompt(
        &session.id,
        &PromptRequest {
            parts: vec![PromptPart::text("Explain this repository")],
            ..Default::default()
        },
    )
    .await?;

client.session().abort(&session.id).await?;
```

Set root `ClientBuilder::directory(...)` and/or `workspace(...)` when the
legacy/current request must be routed to a specific OpenCode context.

The current surface is available directly from the root client:

```rust
let projects = client.project().list().await?;
let config = client.config().get().await?;
let providers = client.provider().list().await?;
let files = client.file().list(".").await?;
let permissions = client.permission().list().await?;
let questions = client.question().list().await?;
```

Complex upstream unions remain `serde_json::Value` where forcing a Rust enum
would make the preview/additive contract less forward-compatible. Endpoint,
method, path, query, and request-body wiring remain pinned by the generated
OpenAPI operation manifest.

### Events / SSE

```rust
use futures_util::StreamExt;
use unofficial_opencode_sdk::EventData;

let mut events = client.events().subscribe().await?;
while let Some(event) = events.next().await {
    match event?.data {
        EventData::Known(event) => println!("known: {:?}", event.kind),
        EventData::Unknown(value) => println!("future event: {value}"),
        EventData::Malformed { raw, error } => eprintln!("{error}: {raw}"),
    }
}
```

The handwritten SSE parser handles fragmented HTTP chunks, multiple events per
chunk, multiline `data:`, LF, CRLF, comments/unknown SSE fields, malformed
JSON, unknown future OpenCode event types, and disconnect/EOF flushing.

## V2 preview client

V2 is intentionally namespaced so evolving `/api/*` contracts cannot silently
change the legacy/current root API.

You can build a V2 client directly:

```rust
use unofficial_opencode_sdk::v2;

let client = v2::Client::builder()
    .base_url("http://127.0.0.1:4096")
    .directory("/path/to/project")
    .build()?;
```

Or reuse transport/authentication from an existing root client:

```rust
let v2 = client.v2();
```

A configured root-client directory is inherited when using `client.v2()`.
Direct V2 construction additionally supports `workspace_id(...)`.

### V2 dialect detection

The client detects once per client which `/api/*` dialect the server speaks
(`GET api/info` answers JSON `ServerInfo` only on 2.x) and adapts:

| Area | OpenCode 1.x preview | OpenCode 2.x native |
| --- | --- | --- |
| Liveness | `api/health` | `api/info` |
| Pending questions | `api/question/*` | `api/form` (+ `api/session/{id}/form*`) |
| Question reply | `answers` by position | `reply_answer` keyed by form field |
| Session events | `api/session/{id}/event` | global `api/event` (filter by `sessionID`) |
| Session wait | `api/session/{id}/wait` | `api/experimental/session/{id}/wait` |
| Revert clear | `POST .../revert/clear` | `DELETE .../revert` |
| Credential activate | n/a | `api/credential/{id}/activate` |

All other V2 routes are identical on both dialects. Payloads admit both wire
shapes: session `title` is optional (2.x), provider/model `api`/`request` are
optional (absent on 2.x), prompt admission normalizes the 1.x admission record
and the 2.x durable user message into `SessionInputAdmitted` (use
`SessionInputAdmitted::from_wire` for raw envelopes), and the prompt request
sends both the 1.x `prompt.text` and the 2.x top-level `text`.

Surfaces with no 2.x equivalent return `Error::Unsupported`: session
`history()` (use `messages()`), positional question `reply()` (use
`reply_answer()`), and `api/integration/attempt/*` polling (2.x moved it
under `api/integration/{id}/connect/{command|oauth}`).

Detected dialect is exposed via `v2.serve_dialect()`.

### V2 sessions

```rust
use unofficial_opencode_sdk::v2::{
    CreateSessionRequest, Delivery, ListSessionsOptions, PromptInput, PromptRequest,
};

let page = v2
    .session()
    .list(&ListSessionsOptions::default())
    .await?;

let session = v2
    .session()
    .create(&CreateSessionRequest::default())
    .await?;

let admitted = v2
    .session()
    .prompt(
        &session.id,
        &PromptRequest {
            prompt: Some(PromptInput::text("Explain this repository")),
            delivery: Some(Delivery::Steer),
            resume: Some(true),
            ..Default::default()
        },
    )
    .await?;

v2.session().wait(&session.id).await?;

let context = v2.session().context(&session.id).await?;
let history = v2.session().history(&session.id, Some(50), None).await?;
let messages = v2
    .session()
    .messages(&session.id, &Default::default())
    .await?;

let pending_permissions = v2.session().permission(&session.id).list().await?;
let pending_questions = v2.session().question(&session.id).list().await?;
```

V2 prompt admission is modeled separately from legacy/current message responses:
the endpoint durably admits input and returns its admission record.

Session message and durable-history unions are kept as raw JSON in this preview
surface because upstream V2 currently exposes several message/event variants.
The surrounding pagination and lifecycle structures remain typed.

Per-session helpers follow the official SDK grouping:

```rust
let permissions = v2.session().permission(&session.id);
let questions = v2.session().question(&session.id);
let revert = v2.session().revert(&session.id);
```

Permission/question reply and revert operations are available, but CI does not
create artificial pending approvals/questions or mutate repository files merely
to exercise destructive workflow paths.

### V2 discovery, integrations, filesystem, permissions, and questions

```rust
let health = v2.health().get().await?;
let location = v2.location().get(None).await?;
let agents = v2.agent().list(None).await?;
let commands = v2.command().list(None).await?;
let skills = v2.skill().list(None).await?;
let references = v2.reference().list(None).await?;
let integrations = v2.integration().list(None).await?;
```

Integration key/OAuth connect, OAuth attempt status/cancel/complete, and
credential update/remove are also exposed. CI does not use real integration
credentials or mutate stored credentials.


```rust
use unofficial_opencode_sdk::v2::FindFilesOptions;

let models = v2.model().list(None).await?;
let providers = v2.provider().list(None).await?;

let root = v2.fs().list(None, None).await?;
let matches = v2
    .fs()
    .find(&FindFilesOptions {
        query: "Cargo".into(),
        ..Default::default()
    })
    .await?;

let pending_permissions = v2.permission().request().list(None).await?;
let saved_permissions = v2.permission().saved().list(None).await?;
let pending_questions = v2.question().request().list(None).await?;
```

These location-aware V2 endpoints use OpenCode's deep-object query shape
(`location[directory]` / `location[workspace]`). The client's configured
directory/workspace is used by default; `LocationQuery` can override it for
one request.

Model/provider records type stable identity and status fields while retaining
preview provider-specific nested structures as JSON. This keeps the public Rust
surface useful without pretending the evolving V2 contract is stable.

### V2 events

```rust
use futures_util::StreamExt;

let mut events = v2.session().events(&session.id, None).await?;
while let Some(event) = events.next().await {
    let event = event?;
    println!("{:?}: {}", event.event, event.data);
}
```

V2 SSE data is retained as raw text instead of being forced into the
legacy/current event enum. Upstream's V2 durable-event schema is still evolving,
so this is deliberately forward-compatible.

## Contract and generation boundary

OpenCode does **not** check a permanent SDK OpenAPI artifact into
`packages/sdk/js`. At the pinned snapshot:

1. `Server.openapi()` builds the contract from the Effect `PublicApi`.
2. `matchLegacyOpenApi` normalizes that schema for the public/current API,
   including explicit SSE payload schemas.
3. `bun dev generate` emits the OpenAPI document used by the SDK build.
4. the official JS SDK uses `@hey-api/openapi-ts@0.90.10`, applies small
   generated-code compatibility patches, then deletes its temporary
   `openapi.json`.
5. the same generated contract contains preview V2 operation IDs such as
   `v2.session.create` and `v2.event.subscribe`.

This repository checks the generated contract into `spec/openapi.json` and
records the exact upstream version, official SDK version, commit, and V2 status
in `spec/upstream.json`.

Whole-document Rust model generation is **not** claimed in this first slice.
The current OpenAPI Generator Rust feature matrix lacks `anyOf`/union/null
support used by this OpenAPI 3.1 document, while Progenitor 0.15.0 documents
OpenAPI 3.0.x as its input target. Instead:

- `scripts/generate_contract.py` validates all stable V1/current operations
  plus the explicitly supported V2 preview operations from the authoritative snapshot;
- session/prompt compatibility models and ergonomic facades are handwritten,
  small, and preserve unknown fields where practical;
- SSE is handwritten because upstream itself must supplement the OpenAPI
  response schema for SSE.

This boundary favors protocol correctness over producing a large but misleading
generated Rust tree.

## Updating OpenCode

`spec/upstream.json` is the machine-readable compatibility pin. To update:

1. change `upstream_version` and `upstream_commit` after reviewing the desired
   OpenCode release/commit;
2. update `official_js_sdk.version` to match the pinned upstream SDK;
3. run `scripts/update-openapi`, or dispatch the
   `refresh-and-smoke-contract` GitHub Actions workflow;
4. review `spec/openapi.json` and `src/generated/operations.rs`;
5. run the Rust CI suite and the real-server contract smoke test.

Cargo package metadata also records the pinned OpenCode and official SDK
versions. The Rust crate's own SemVer remains independent so compatibility
updates and Rust-only fixes can be released separately.

## Compatibility policy

For `0.1.x`, compatibility is tied to the exact OpenCode commit in
`spec/upstream.json`.

The root surface tracks the stable legacy/current API. Explicit
`experimental.*`, `worktree.*`, and `sync.*` operation families are not
part of the V1/current completion target. The `v2` module tracks
OpenCode's preview `/api/*` and `@opencode-ai/sdk/v2` surface and may require
Rust SDK changes as upstream V2 evolves. Additive JSON fields are retained or
tolerated where practical. V2 SSE payloads remain raw. Breaking request/response
changes require a new snapshot and SDK update.

## Known limitations

- V1/current endpoint coverage is broad, but complex config/provider/MCP/TUI and
  message/part unions use `serde_json::Value` instead of exhaustive Rust enums;
- explicit `experimental.*`, `worktree.*`, and `sync.*` families are outside
  the V1/current completion target;
- V2 session coverage is broad, but message/durable-event variant payloads remain raw JSON while upstream V2 is preview;
- V2 remains preview upstream and is not claimed stable;
- full OpenAPI 3.1 model generation is not yet enabled;
- legacy/current non-text prompt parts currently use a JSON escape hatch;
- legacy/current prompt response message/part unions are retained as JSON;
- V2 admitted prompt output is retained losslessly as JSON while its event/input
  schema continues to evolve;
- `createOpencode()`-style process launching is intentionally not included;
- the required live contract smoke avoids a real model prompt because model
  credentials are not appropriate for repository CI.

## Validation

Normal CI runs:

```text
cargo fmt --check
cargo check --all-targets --all-features
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-features
cargo doc --no-deps --all-features
cargo publish --dry-run
```

CI also checks the declared Rust 1.87 MSRV.

The contract workflow additionally generates the OpenAPI snapshot from the
pinned upstream source, starts that exact OpenCode server, exercises broad
read-only/ephemeral V1/current coverage plus the V2 smoke paths, opens SSE
endpoints, and commits the verified snapshot back to `main` when it changed.

## Publishing

Release packaging and crates.io Trusted Publishing are documented in
[`PUBLISHING.md`](PUBLISHING.md). The repository does not store a crates.io
API token.