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

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Opencode
+  # Per-Reply registry of interactive prompts (questions + permissions)
+  # opencode has asked the user but not yet resolved. Lives on
+  # Opencode::Reply for the lifetime of one streaming turn.
+  #
+  # Two access patterns:
+  #
+  #   * by request id ("que_..." or "per_...") — for the controller
+  #     posting a user's answer back.
+  #   * by {message_id, call_id} — for the order-race fix where
+  #     `question.asked` may arrive before the matching tool part.
+  #
+  # The registry also exposes a `prompt_blocked?` predicate that
+  # Opencode::Client uses to suspend the SSE deadline check while
+  # a healthy wait is in progress.
+  class Prompts
+    Entry = Struct.new(:kind, :request, :asked_at, keyword_init: true)
+
+    def initialize
+      @entries = {}
+      @by_call = {}
+    end
+
+    def record_question(request)
+      record(:question, request)
+    end
+
+    def record_permission(request)
+      record(:permission, request)
+    end
+
+    # Returns the raw request hash (not the Entry wrapper) so callers
+    # don't depend on internal bookkeeping shape.
+    def find(request_id)
+      @entries[request_id]&.request
+    end
+
+    # Returns the raw request hash, same shape as #find.
+    def find_by_call(message_id:, call_id:)
+      key = call_key(message_id, call_id)
+      @by_call[key]&.request
+    end
+
+    def resolve(request_id)
+      entry = @entries.delete(request_id)
+      return unless entry
+
+      tool = entry.request[:tool]
+      return unless tool
+
+      @by_call.delete(call_key(tool[:messageID], tool[:callID]))
+    end
+
+    def each_pending
+      @entries.each_value { |entry| yield(entry.kind, entry.request) }
+    end
+
+    def any_pending?
+      @entries.any?
+    end
+    alias_method :prompt_blocked?, :any_pending?
+
+    def asked_at(request_id)
+      @entries[request_id]&.asked_at
+    end
+
+    private
+
+    def record(kind, request)
+      entry = Entry.new(
+        kind: kind,
+        request: request,
+        asked_at: Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      )
+      @entries[request[:id]] = entry
+
+      tool = request[:tool]
+      @by_call[call_key(tool[:messageID], tool[:callID])] = entry if tool
+    end
+
+    def call_key(message_id, call_id)
+      [ message_id, call_id ].join(":")
+    end
+  end
+end