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/tracer.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Opencode
+  # A namespacing trace emitter.
+  #
+  # Opencode::Turn emits unprefixed event names like "response.started"
+  # and "session.recreated". The host product wraps Turn in a Tracer
+  # whose job is to prepend a product prefix and forward to whatever
+  # actually emits trace events (typically the host job's
+  # `EventTraceable#trace_event`).
+  #
+  # Two responsibilities live here, and only here:
+  #
+  #   1. Callable interface: `tracer.call(name, **payload)` — the
+  #      contract Turn relies on.
+  #   2. Namespacing strategy: prepend "<prefix>." to every event name.
+  #
+  # Pre-extraction this lived in a closure at every Turn-construction
+  # site:
+  #
+  #     tracer: ->(name, **payload) { trace_event("blackline.#{name}", **payload) }
+  #
+  # That closure conflates the two responsibilities; every product had
+  # to rediscover the prefix-with-period rule, and a typo would only
+  # show up in production trace data. Making it a real role removes
+  # that risk and makes the rule visible at one place.
+  #
+  # Usage:
+  #
+  #   Opencode::Tracer.new(prefix: "blackline", emitter: self)
+  #
+  # `emitter` must respond to `trace_event(name, **payload)`.
+  class Tracer
+    def initialize(prefix:, emitter:)
+      @prefix = prefix
+      @emitter = emitter
+    end
+
+    # Tracer is callable so existing call sites that treated the tracer
+    # as a lambda (`tracer.call(name, **payload)`) keep working without
+    # change. Turn uses this exclusively.
+    #
+    # Uses `send` because EventTraceable's `trace_event` is a private
+    # method of the including class — the convention is "private inside
+    # the job, but the substrate's Tracer is allowed to dispatch to it
+    # the same way the job's own perform method would."
+    def call(name, **payload)
+      @emitter.send(:trace_event, "#{@prefix}.#{name}", **payload)
+    end
+  end
+end