Initial opencode-ruby v0.0.1.alpha1 — hand-rolled HTTP+SSE client for OpenCode

Headline API:

  reply = client.stream(session_id, "Explain monads") do |part|
    print part["content"] if part["type"] == "text"
  end
  reply.full_text   # final accumulated text

Sources ported from ajaynomics/ajent-rails lib/opencode/client/ after
the Phase-1+2 tier carve + Phase-2.5 boundary cleanup (see ajent-rails
PRs #840 and #843). Rails-runtime coupling stripped:

  - Defaults read from ENV[OPENCODE_BASE_URL/SERVER_PASSWORD/TIMEOUT]
    instead of Rails.application.config.x.opencode_blackline.*
  - EventTraceable.timed_event(...) calls swapped for
    Opencode::Instrumentation.instrument(...) — pluggable adapter
    (default no-op) that callers wire to ActiveSupport::Notifications,
    OpenTelemetry, stdout, etc.

Runtime dependency: activesupport (>= 6.1, < 9.0) for the small
core_ext surface (blank?/present?/presence/truncate/duplicable?/
megabytes). ActiveSupport is NOT Rails — it's a standalone helpers
gem that most Ruby apps already have transitively.

What's in the gem:

  Opencode::Client          HTTP + SSE client; #stream block-form API
  Opencode::Reply           SSE-event accumulator with observer protocol
  Opencode::Reply::Result   typed Struct value object
  Opencode::ReplyObserver   observer protocol module (no-op defaults)
  Opencode::Prompts         per-Reply pending question/permission registry
  Opencode::Tracer          callable that prefixes event names
  Opencode::Instrumentation pluggable adapter
  Opencode::ResponseParser  wire-format extractors
  Opencode::ToolPart        canonical tool-part hash shape
  Opencode::PartSource      wire-vs-stream-only discriminator
  Opencode::Todo            todo status canonicalization
  Opencode::Error (+ 7 subclasses)

What's out (per design D18 — wait for demand signal):

  - acts_as_opencode_session concern
  - ActiveRecord-backed session lifecycle
  - rails generators
  - opencode-rails as a separate gem

Instead, examples/conversation_recipe.rb ships as a ~140-line
plain-ActiveRecord blueprint demonstrating session lifecycle,
with_lock, update_columns mid-stream pattern, and CAS-safe finalize.

Tests: 12 runs, 25 assertions, 0 failures (smoke test against
WebMock-stubbed OpenCode endpoints — covers the postcard, error
model, Instrumentation, and Reply::Result shape).

Authored against ajent-rails commit 02954eeb (opencode-gem/phase-3-prep).

lib/opencode/instrumentation.rb

@@ -0,0 +1,44 @@
+# 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.
+  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
+  end
+end