opencode-ruby 0.0.1.alpha2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5c85499ae01e9b85854d1738508f079c8e4b41d00d926f7c81cd537db2a30474
+  data.tar.gz: 9034a4c5697390f12f2c1d4c0566de11f1e44321c9f2497bc9b8c54d514e43fb
+SHA512:
+  metadata.gz: 8a73ddf71df4c272aa3676cdddd5deb9d0db71a10466f4f355df6f9e63ada55a9231773df56f74cf7c44544069bdfc5fa0be82ea5dc8c89732192f87d4bc980d
+  data.tar.gz: e8015d9f32e8f3e1712e1cdf21824eacb7f26f3244831d20c8bfdff513ebb8d692afa2360aaa90450625cf935a0eb744fed16a62c7e3ed2b8b5f421819fd288f

data/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+## 0.0.1.alpha2 — 2026-05-20
+
+### Added
+
+- `Opencode::Instrumentation.notify(name, payload)` — fire-and-forget
+  emission for point-in-time events that don't need duration measurement
+  (apply_patch.artifacts_dropped, session.recreated, etc.). Adapter
+  receives an empty block so AS::Notifications-shaped sinks see a
+  zero-duration event. Complements the existing block-form
+  `.instrument(name, payload) { ... }`.
+
+### Why
+
+The block-form `.instrument(name, payload) { }` with an empty block was
+awkward at fire-and-forget call sites in opencode-rails. Two named
+verbs (`instrument` for wrap-a-block, `notify` for fire-and-forget)
+match the host-side mental model and read better at the call site.
+
+## 0.0.1.alpha1 — Unreleased
+
+First public alpha. HTTP + SSE client for OpenCode REST API.
+
+### What's in
+
+- `Opencode::Client` — Net::HTTP-based HTTP client with SSE streaming + automatic reconnection.
+  - `#create_session(title:, permissions:)`, `#get_messages(session_id)`, `#list_sessions`, `#delete_session(id)`, `#abort_session(id)`.
+  - `#send_message(session_id, text, model:, ...)` — synchronous send-and-poll.
+  - `#send_message_async(session_id, text, ...)` — async send.
+  - `#stream(session_id, text, ...) { |part| ... } → Opencode::Reply::Result` — **the headline.** Block-form streaming with internal Reply accumulation and final-exchange merge.
+  - `#stream_events(session_id:, ...) { |event| ... }` — lower-level SSE event firehose for power users.
+  - `#reply_question(request_id:, answers:)` / `#reply_permission(request_id:, reply:)` — answer interactive prompts.
+- `Opencode::Reply` — live state machine accumulating SSE events into the assistant's reply. Documented observer protocol (`Opencode::ReplyObserver`).
+- `Opencode::Reply::Result` — typed Struct value object returned by `Client#stream` and `Reply#result`. Fields: `:parts_json`, `:full_text`, `:reasoning_text`, `:tool_parts`.
+- `Opencode::Instrumentation` — pluggable adapter (default no-op). Plug in `ActiveSupport::Notifications`, OpenTelemetry, stdout, etc.
+- `Opencode::ResponseParser`, `Opencode::ToolPart`, `Opencode::PartSource`, `Opencode::Todo` — wire-format helpers used by `Reply` and reusable by callers building their own SSE handling.
+- `Opencode::Prompts` — per-Reply registry of pending question/permission prompts (used by `Reply` internally; exposed for callers that need to peek).
+- `Opencode::Tracer` — callable that prefixes event names before forwarding to a host emitter.
+- Error hierarchy: `Opencode::Error` and seven subclasses (`ConnectionError`, `TimeoutError`, `SessionNotFoundError`, `StaleSessionError`, `IdleStreamError`, `ServerError`, `BadRequestError`).
+
+### What's out
+
+- ActiveRecord-backed session lifecycle, `acts_as_opencode_session`, generators — deferred to `opencode-rails` if external demand materializes. See `examples/conversation_recipe.rb` for the canonical Rails wiring pattern.
+- Multi-tenant per-user Docker container orchestration — application glue, not a gem's concern.
+
+### Compatibility
+
+- Ruby ≥ 3.2
+- OpenCode server ≥ 1.15 (tested against the message bus schema in `packages/opencode/src/session/message-v2.ts`)
+- Runtime dependency: `activesupport (>= 6.1)` for `blank?`/`present?`/`presence`/`truncate`/`duplicable?`/`megabytes`. ActiveSupport is *not* Rails — it's a standalone helpers gem.

data/LICENSE

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2026 ajaynomics
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and 
+associated documentation files (the "Software"), to deal in the Software without restriction, including 
+without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 
+copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the 
+following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial 
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT 
+LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO 
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER 
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE 
+USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,162 @@
+# 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
+
+### 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
+```
+
+### 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.
+```
+
+### 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.idle", ...
+end
+```
+
+### 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    # session.idle never arrived
+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
+- OpenCode server ≥ 1.15
+- Runtime dependency: `activesupport (>= 6.1)` — *not* Rails. ActiveSupport is a standalone helpers gem (`blank?`, `present?`, `presence`, `truncate`, etc.).
+
+## Development
+
+```sh
+bundle install
+bundle exec rake test
+```
+
+12-test smoke covers Client end-to-end against WebMock-stubbed OpenCode endpoints.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

data/examples/conversation_recipe.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+# Rails integration recipe — copy + adapt.
+#
+# This is NOT part of opencode-ruby. It's the canonical pattern showing
+# how to wire the gem's primitives into a Rails ActiveRecord app. Drop
+# this file into your `app/models/` (rename it), adapt the schema, and
+# you have a working block-streaming chat with row-locked session
+# lifecycle and CAS-safe finalize.
+#
+# What this recipe demonstrates:
+#
+#   1. Schema (below in a comment) — the migration you'll need
+#   2. Session lifecycle — idempotent ensure! with with_lock
+#   3. Mid-stream parts persistence via update_columns (bypasses
+#      AR callbacks so Turbo broadcasts don't fire per-part)
+#   4. CAS-safe finalize — concurrent cancel wins
+#   5. Recovery from SessionNotFoundError — recreate once + retry
+#
+# If you want this as a one-liner (`acts_as_opencode_session`), open
+# an issue on the repo. The gem ships this recipe instead of a concern
+# because the right shape depends on the host app's conventions — and
+# shipping a half-built concern is worse than shipping a clear
+# blueprint you can adapt.
+#
+# Suggested schema (adapt naming to your domain):
+#
+#   create_table :conversations do |t|
+#     t.references :user, null: false, foreign_key: true
+#     t.string :title
+#     t.string :opencode_session_id
+#     t.timestamps
+#     t.index :opencode_session_id, unique: true,
+#             where: "opencode_session_id IS NOT NULL"   # partial unique
+#   end
+#
+#   create_table :messages do |t|
+#     t.references :conversation, null: false, foreign_key: true
+#     t.string  :role,    null: false           # "user" or "assistant"
+#     t.integer :status,  null: false, default: 0   # see enum below
+#     t.text    :content, null: false, default: ""
+#     t.json    :parts_json,      null: false, default: []
+#     t.json    :tool_calls_json, null: false, default: []
+#     t.decimal :cost, precision: 10, scale: 6
+#     t.integer :input_tokens
+#     t.integer :output_tokens
+#     t.timestamps
+#   end
+
+class Conversation < ApplicationRecord
+  belongs_to :user
+  has_many :messages, dependent: :destroy
+
+  # Returns the OpenCode session id for this conversation, creating one
+  # if needed. Idempotent. Race-safe via row-lock + double-check.
+  def ensure_opencode_session!(client)
+    return opencode_session_id if opencode_session_id.present?
+
+    with_lock do
+      return opencode_session_id if opencode_session_id.present?
+      session = client.create_session(title: title)
+      update!(opencode_session_id: session[:id] || session["id"])
+    end
+    opencode_session_id
+  rescue ActiveRecord::RecordNotUnique
+    # Another worker raced past the partial unique index. Loser reloads.
+    reload
+    opencode_session_id
+  end
+
+  # Replace a stale upstream session. Used by SessionNotFoundError
+  # recovery in the streaming job below.
+  def recreate_opencode_session!(client)
+    pre_id = opencode_session_id
+    with_lock do
+      return opencode_session_id if opencode_session_id.present? && opencode_session_id != pre_id
+      session = client.create_session(title: title)
+      update!(opencode_session_id: session[:id] || session["id"])
+    end
+    opencode_session_id
+  end
+end
+
+class Message < ApplicationRecord
+  belongs_to :conversation
+
+  enum status: { pending: 0, streaming: 1, completed: 2, cancelled: 3, errored: 4 }
+end
+
+# The streaming job. Compose Opencode::Client + ActiveRecord; that's it.
+class GenerateAssistantReplyJob < ApplicationJob
+  def perform(message_id, user_prompt)
+    message = Message.find(message_id)
+    return unless message.pending?
+
+    client = Opencode::Client.new(
+      base_url: ENV.fetch("OPENCODE_BASE_URL"),
+      password: ENV["OPENCODE_SERVER_PASSWORD"]
+    )
+
+    session_id = message.conversation.ensure_opencode_session!(client)
+    message.update!(status: :streaming)
+
+    attempted_recreate = false
+    begin
+      reply = client.stream(session_id, user_prompt) do |part|
+        # Mid-stream snapshot: update_columns bypasses AR callbacks so
+        # an after_update_commit broadcasts_refreshes_to(conversation)
+        # doesn't fire per-part and clobber per-part Turbo broadcasts
+        # you might be doing separately. The final write below uses
+        # update! to fire callbacks deliberately.
+        message.update_columns(
+          parts_json: reply_parts_so_far(part, message),
+          updated_at: Time.current
+        )
+      end
+
+      # CAS-safe finalize: only land the final state if no concurrent
+      # cancel got there first.
+      message.with_lock do
+        return unless message.reload.pending? || message.streaming?
+        message.update!(
+          status: :completed,
+          content: reply.full_text,
+          parts_json: reply.parts_json,
+          tool_calls_json: reply.tool_parts
+        )
+      end
+    rescue Opencode::SessionNotFoundError, Opencode::StaleSessionError
+      raise if attempted_recreate
+      message.conversation.recreate_opencode_session!(client)
+      attempted_recreate = true
+      retry
+    end
+  rescue StandardError => e
+    message&.update!(status: :errored, content: "An error occurred: #{e.message.truncate(200)}")
+  end
+
+  private
+
+  # Builds the parts array up to (and including) the current part by
+  # poking the gem's internal Reply state. In practice you'd capture
+  # the Reply instance from the block via a closure, OR derive from
+  # `part` if you only need the latest part.
+  def reply_parts_so_far(part, message)
+    parts = (message.parts_json || []).dup
+    # Trivial dedup: replace or append by part id, if your wire-format
+    # includes one. For real merge logic, lift Opencode::Reply's
+    # part_index_by_id / append_part pattern.
+    parts << part unless parts.any? { |existing| existing["id"] == part["id"] }
+    parts
+  end
+end