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

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Opencode
+  # The canonical observer protocol for Opencode::Reply — every event
+  # Reply dispatches, documented in one place, with safe no-op defaults.
+  #
+  # Include this module in a reply-stream class to get two things:
+  #
+  # 1. **Compile-time checklist.** Override only the callbacks you care
+  #    about; the rest inherit a no-op. Forgetting to handle a new event
+  #    never crashes the stream.
+  # 2. **Protocol documentation that can't rot.** The signatures here are
+  #    the contract. If Reply's dispatch shape ever drifts, every observer
+  #    using this module updates in lockstep.
+  #
+  # Callbacks are duck-typed in Reply — features may choose not to
+  # include this module and implement the methods directly, but then
+  # they lose the two benefits above.
+  #
+  # Every callback takes keyword arguments, so adding a new keyword later
+  # only requires existing observers to add `**_` if they want to opt out
+  # of breakage.
+  module ReplyObserver
+    # A new part was appended to the reply's parts list.
+    def part_added(part:, index:)
+    end
+
+    # An existing part's content grew by a delta (streaming text or
+    # reasoning).
+    def part_changed(part:, index:, delta:)
+    end
+
+    # An existing part's content was rewritten to the authoritative
+    # value from part.updated. Fires unconditionally when a part closes
+    # so throttled observers can flush, regardless of whether content
+    # actually diverged from what deltas accumulated.
+    def part_finalized(part:, index:)
+    end
+
+    # A tool part transitioned status (pending → running → completed/error),
+    # or its state payload (title/input/error) changed.
+    def tool_progressed(part:, index:, status:, raw:)
+    end
+
+    # A step boundary with usage info. `tokens` is the raw tokens hash
+    # from the step-finish part (keys: :input, :output, :reasoning, :cache).
+    def step_finished(cost:, tokens:)
+    end
+
+    # The upstream session is retrying an LLM call (e.g., provider
+    # rate-limit backoff). Attempt is nullable; message is a short
+    # reason string.
+    def session_retried(attempt:, message:)
+    end
+
+    # A session-level error surfaced. Text is a human-readable summary
+    # ("ErrorName: details"); raw is the full error hash.
+    def session_errored(text:, raw:)
+    end
+
+    # The authoritative message.info was updated (cost, tokens, provider
+    # error metadata). Fires late in the stream after the agent closes.
+    def message_updated(info:)
+    end
+
+    # Agent's internal todo list changed. Todos are whatever shape the
+    # agent's task tool uses.
+    def todos_changed(todos:)
+    end
+
+    # opencode emitted a question.asked event — the agent's `question`
+    # tool is suspended waiting for the user's reply. `request` is the
+    # full QuestionRequest hash ({id, sessionID, questions, tool?}).
+    def question_asked(request:, raw:)
+    end
+
+    # opencode emitted a question.replied event — the user submitted
+    # answers (Array<Array<String>>, one inner array per question).
+    # `asked_at` is the monotonic clock value when question.asked was
+    # observed, for latency telemetry; nil if asked never arrived.
+    def question_replied(request_id:, answers:, raw:, asked_at:)
+    end
+
+    # opencode emitted a question.rejected event — the user dismissed
+    # the prompt, or it was cancelled (e.g., container shutdown).
+    def question_rejected(request_id:, raw:, asked_at:)
+    end
+
+    # opencode emitted a permission.asked event — a tool is requesting
+    # user permission to proceed. `request` is the PermissionRequest
+    # hash ({id, sessionID, permission, patterns, metadata, always, tool?}).
+    def permission_asked(request:, raw:)
+    end
+
+    # opencode emitted a permission.replied event — the user chose
+    # once/always/reject. `reply` is the string. `asked_at` per
+    # question_replied semantics.
+    def permission_replied(request_id:, reply:, raw:, asked_at:)
+    end
+  end
+end