Initial public release v0.0.1.alpha2

opencode-ruby — idiomatic Ruby client for OpenCode (HTTP + SSE).

Hand-rolled, opinionated Ruby SDK with block-form streaming, value-
object responses, and automatic SSE reconnection. Pluggable
Opencode::Instrumentation adapter for routing events to
ActiveSupport::Notifications, OpenTelemetry, stdout, or any custom
emitter. Companion to opencode-rails for AR-coupled Rails apps.

What this version ships:
  - Opencode::Client (Net::HTTP + SSE)
  - Opencode::Reply / Reply::Result / ReplyObserver
  - Opencode::Tracer, Opencode::Prompts
  - Opencode::ResponseParser, ToolPart, PartSource, Todo
  - Opencode::Instrumentation (instrument + notify)
  - Opencode::Error and seven subclasses
  - examples/conversation_recipe.rb — canonical Rails wiring blueprint

15 smoke tests. CI on Ruby 3.2/3.3/3.4.

Ruby >= 3.2. Runtime dep: activesupport >= 6.1, < 9.0.

See CHANGELOG.md for the alpha1 -> alpha2 delta.

lib/opencode/instrumentation.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Opencode
+  # Pluggable instrumentation adapter. opencode-ruby ships zero
+  # dependencies on Rails or any specific instrumentation library. Users
+  # plug in their own emitter:
+  #
+  #   # ActiveSupport::Notifications (Rails apps):
+  #   Opencode::Instrumentation.adapter = ->(name, payload, &block) {
+  #     ActiveSupport::Notifications.instrument(name, payload, &block)
+  #   }
+  #
+  #   # stdout (debugging, non-Rails scripts):
+  #   Opencode::Instrumentation.adapter = ->(name, payload, &block) {
+  #     puts "[#{name}] #{payload.inspect}"
+  #     block.call
+  #   }
+  #
+  # When no adapter is set (default), instrumentation is a no-op pass-
+  # through that yields the block and returns its value. The Client emits
+  # events for HTTP requests, SSE stream lifecycle, and recovery paths.
+  #
+  # Event names the Client emits:
+  #
+  #   - opencode.request       — every HTTP request to OpenCode server
+  #
+  # If you wire a real adapter, the payload hash carries `:method` and
+  # `:path` for opencode.request. Other events may add fields in future
+  # versions; treat the payload as forward-compatible.
+  #
+  # Two emission shapes:
+  #
+  #   .instrument(name, payload) { ... }  — wrap a block; the duration
+  #                                          of the block becomes part
+  #                                          of the event (when the
+  #                                          adapter is ActiveSupport::
+  #                                          Notifications-shaped).
+  #
+  #   .notify(name, payload)              — fire-and-forget; no block,
+  #                                          no duration. Use for
+  #                                          point-in-time observations
+  #                                          (e.g. "this artifact was
+  #                                          dropped").
+  module Instrumentation
+    class << self
+      attr_accessor :adapter
+    end
+
+    # Yields the block, optionally routed through the adapter if one is
+    # set. Always returns the block's return value (so call sites can
+    # wrap their work transparently).
+    def self.instrument(name, payload = {})
+      return yield unless adapter
+
+      adapter.call(name, payload) { yield }
+    end
+
+    # Fire-and-forget event. No block, no return value (the adapter's
+    # return is ignored). Use for point-in-time observations where
+    # duration doesn't apply — apply_patch.artifacts_dropped,
+    # session.recreated, etc.
+    #
+    # Implementation: invokes the same adapter as #instrument but with
+    # an empty block. Hosts that adapt to ActiveSupport::Notifications
+    # will see a zero-duration event; hosts that adapt to a structured-
+    # event API (Rails.event.notify, OpenTelemetry span events) can
+    # detect the empty-block convention if they need to. Most hosts
+    # don't need to care.
+    def self.notify(name, payload = {})
+      return unless adapter
+
+      adapter.call(name, payload) { }
+      nil
+    end
+  end
+end