opencode-ruby/README.md

# opencode-ruby

Idiomatic Ruby client for [OpenCode](https://opencode.ai). Block-form streaming, value-object responses, automatic SSE reconnection.

```ruby
require "opencode-ruby"

client  = Opencode::Client.new(base_url: "http://localhost:4096")
session = client.create_session(title: "My session")

reply = client.stream(session[:id], "Explain monads in two sentences.") do |part|
  print part["content"] if part["type"] == "text"
end

puts
puts reply.full_text
puts "(#{reply.tool_parts.size} tool calls, #{reply.parts_json.size} parts total)"
```

Three lines of setup, four lines of work. Block fires every time a part appears, grows, finalizes, or (for tool calls) advances state. The final return value is a typed `Opencode::Reply::Result` you can persist or inspect.

## Install

```ruby
# Gemfile
gem "opencode-ruby"
```

Or:

```sh
gem install opencode-ruby
```

Then `require "opencode-ruby"`.

## Configuration

```ruby
client = Opencode::Client.new(
  base_url: "http://localhost:4096",   # or ENV["OPENCODE_BASE_URL"]
  password: "secret",                   # or ENV["OPENCODE_SERVER_PASSWORD"]
  timeout:  120                         # or ENV["OPENCODE_TIMEOUT"], seconds
)
```

Multi-tenant apps construct multiple clients with different `base_url`s — each `Opencode::Client` holds its own Net::HTTP connection, no shared state.

## Core API

### Configured and parent-linked sessions

OpenCode can create a session under an existing parent and select its agent,
model, metadata, workspace, and permission policy in the same request:

```ruby
child = client.create_session(
  title: "Destination curator",
  parent_id: parent_session_id,
  agent: "destination-list-curator",
  model: "openai/gpt-5.5",
  metadata: { run_id: "9" },
  workspace_id: workspace_id,
  permissions: permission_rules
)
```

Model strings use OpenCode's `provider/model` form; a preformatted model hash
with `providerID` and `id` keys is also accepted. These configured-session
fields first appeared in OpenCode 1.16.1. That is an API-introduction note,
not evidence that every later server is compatible; use the
[certified compatibility evidence](#compatibility) for deployment choices.

### Streaming (the headline)

```ruby
reply = client.stream(session_id, "What's 2 + 2?") do |part|
  case part["type"]
  when "text"      then print part["content"]
  when "reasoning" then # ignore, or render in a separate UI
  when "tool"      then puts "  [tool: #{part['tool']} → #{part['status']}]"
  end
end

reply.full_text       # => "2 + 2 = 4."
reply.tool_parts      # => array of terminal tool-call parts
reply.reasoning_text  # => the model's hidden reasoning, if any
reply.parts_json      # => the full ordered parts array, ready for persistence
```

`stream` waits for OpenCode's initial `server.connected` SSE readiness frame
before it submits the asynchronous prompt. If the event connection drops
afterward, the client reconnects only the subscription; it never reposts the
prompt. This prevents both missed fast responses and duplicate turns.

### Synchronous send (no streaming)

```ruby
result = client.send_message(session_id, "Quick yes/no: is Ruby fun?")
# result is the OpenCode response hash; see API docs for fields.
```

### Updating session permissions

```ruby
client.update_session(session_id, permissions: permission_rules)
```

OpenCode appends PATCHed permission rules and evaluates the last matching
rule. Hosts should send a complete ordered policy and fingerprint it so the
same policy is not appended on every turn. This endpoint first appeared in
OpenCode 1.16.1; that version floor describes endpoint availability, not
compatibility with every later server.

### Lower-level event firehose

If you need raw SSE events (every server tick, todo update, prompt asked/replied), use `stream_events` directly:

```ruby
client.stream_events(session_id: session_id) do |event|
  puts event[:type] # "message.part.delta", "todo.updated", "session.status", ...
end
```

Orchestrators that submit their own async prompt must do so through
`on_subscribed`; the callback runs only after the first `server.connected`
frame and at most once across automatic reconnects:

```ruby
client.stream_events(
  session_id: session_id,
  on_subscribed: -> { client.send_message_async(session_id, prompt) }
) do |event|
  reply.apply(event)
end
```

If the callback raises, `stream_events` propagates that error and does not
retry it. This is intentional: a timed-out prompt response is ambiguous, so
reposting could duplicate the model turn and its cost.

### Interactive prompts

When the agent uses the `question` or `permission` tools, opencode emits `question.asked` / `permission.asked` events. Answer them via:

```ruby
client.reply_question(request_id: "que_...", answers: [["yes"]])
client.reply_permission(request_id: "per_...", reply: "always")
```

## Error model

Every method that hits the network raises `Opencode::Error` (or a subclass) on failure. Catch the parent or the specific subclass:

```ruby
begin
  client.health
rescue Opencode::ConnectionError      # server unreachable
rescue Opencode::TimeoutError         # client-side timeout
rescue Opencode::SessionNotFoundError # 404 on a session
rescue Opencode::StaleSessionError    # no session event arrived after the prompt
rescue Opencode::IdleStreamError      # mid-turn SSE wedge
rescue Opencode::ServerError          # 5xx
rescue Opencode::BadRequestError      # 4xx other than 404
rescue Opencode::Error                # catch-all
end
```

## Instrumentation

Want to see what the gem is doing? Plug in an adapter. Default behaviour is silent no-op — the gem ships zero opinion about your observability stack.

```ruby
# stdout for debugging:
Opencode::Instrumentation.adapter = ->(name, payload, &block) {
  puts "[#{name}] #{payload.inspect}"
  block.call
}

# ActiveSupport::Notifications in a Rails app:
Opencode::Instrumentation.adapter = ->(name, payload, &block) {
  ActiveSupport::Notifications.instrument(name, payload, &block)
}
```

Event names emitted today:

| Event | Payload |
|---|---|
| `opencode.request` | `:method`, `:path` |

## Want this in a Rails app?

See [`examples/conversation_recipe.rb`](examples/conversation_recipe.rb) for a ~60-line plain-ActiveRecord blueprint covering session lifecycle (`with_lock`, `update_columns` mid-stream snapshots, CAS-safe finalize). Drop it into your app and adapt.

If enough Rails developers do that and want it as a one-liner, we'll ship `opencode-rails` with `acts_as_opencode_session`. **File an issue if that's you** — your issue is the signal.

## Position against `opencode_client`

Want every OpenCode endpoint auto-generated from the OpenAPI spec? Use [`opencode_client`](https://rubygems.org/gems/opencode_client). This gem is the hand-rolled idiomatic alternative — smaller surface, opinionated defaults, block-form streaming. Pick whichever fits how you want to write Ruby.

## Compatibility

- Ruby ≥ 3.2
- Runtime dependency: `activesupport (>= 6.1, < 9.0)` — *not* Rails. ActiveSupport is a standalone helpers gem (`blank?`, `present?`, `presence`, `truncate`, etc.).
- Runtime dependency: `marcel (~> 1.0)` for artifact MIME type detection.

OpenCode server compatibility is evidence-based, not an open-ended SemVer
promise. OpenCode's HTTP, SSE, and runtime behavior can change independently
of a numeric version floor, so this gem does not infer compatibility from a
constraint such as `>= 1.15`.

Use the [OpenCode compatibility corpus](https://github.com/ajaynomics/opencode-compat)
as the source of current evidence. Its
[image matrix](https://github.com/ajaynomics/opencode-compat/blob/main/manifests/image-matrix.json)
records the exact gem commit and immutable OpenCode OCI digest exercised by
the `ruby-rest-sse` profile. Its
[runtime tuples](https://github.com/ajaynomics/opencode-compat/blob/main/manifests/runtime-tuples.json)
add the exact consumer commit and canary evidence needed for promotion and
rollback. A version label or image tag is provenance only, never the execution
coordinate.

A combination absent from passing evidence is **unverified**, not necessarily
incompatible. Run the corpus against the exact gem, image digest, and consumer
commit before adopting or promoting it. See the
[certification policy](https://github.com/ajaynomics/opencode-compat/blob/main/docs/certification.md)
for the full process.

## Development

```sh
bundle install
bundle exec rake test
```

The smoke suite covers Client end-to-end against WebMock-stubbed OpenCode
endpoints, including subscription-before-prompt ordering and
reconnect-without-repost.

The mistakenly published `0.0.1.alpha8` package contained unrepaired source and
was yanked; use `0.0.1.alpha9` or later. The repository contains a tag-triggered
`release.yml` workflow intended for RubyGems trusted publishing, but its
trusted-publisher registration is not confirmed for alpha9. A `v*` tag push
therefore does not currently guarantee publication. Before a future release,
verify the RubyGems registry result explicitly. Once the workflow is registered
as a trusted publisher for the `release` environment, it can build, attest, and
publish without a long-lived RubyGems API key.

## License

MIT. See [LICENSE](LICENSE).