Merge pull request #3 from ajaynomics/docs/certified-opencode-compatibility

Document evidence-based OpenCode compatibility

CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.0.1.alpha7 - 2026-07-18
+
+### Fixed
+
+- Add an at-most-once `on_subscribed` hook to the lower-level
+  `Opencode::Client#stream_events` API. Higher-level orchestrators can now
+  wait for `server.connected` before submitting `prompt_async` without
+  abandoning their own Reply observers, persistence, or recovery pipeline.
+- Propagate subscription-hook failures directly and never invoke the hook
+  again on SSE reconnect. Ambiguous prompt transport failures therefore
+  cannot silently become duplicate turns.
+
 ## 0.0.1.alpha6 - 2026-07-18
 
 ### Fixed
@@ -88,5 +100,7 @@ First public alpha. HTTP + SSE client for OpenCode REST API.
 ### Compatibility
 
 - Ruby ≥ 3.2
-- OpenCode server ≥ 1.15 (tested against the message bus schema in `packages/opencode/src/session/message-v2.ts`)
+- OpenCode targeted the then-current 1.15 message-bus shape. This historical
+  target was not a blanket SemVer compatibility guarantee; use the README's
+  current compatibility evidence for deployment decisions.
 - Runtime dependency: `activesupport (>= 6.1)` for `blank?`/`present?`/`presence`/`truncate`/`duplicable?`/`megabytes`. ActiveSupport is *not* Rails — it's a standalone helpers gem.

README.md

@@ -67,7 +67,9 @@ child = client.create_session(
 
 Model strings use OpenCode's `provider/model` form; a preformatted model hash
 with `providerID` and `id` keys is also accepted. These configured-session
-fields require OpenCode 1.16.1 or newer.
+fields first appeared in OpenCode 1.16.1. That is an API-introduction note,
+not evidence that every later server is compatible; use the
+[certified compatibility evidence](#compatibility) for deployment choices.
 
 ### Streaming (the headline)
 
@@ -106,8 +108,9 @@ client.update_session(session_id, permissions: permission_rules)
 
 OpenCode appends PATCHed permission rules and evaluates the last matching
 rule. Hosts should send a complete ordered policy and fingerprint it so the
-same policy is not appended on every turn. This endpoint requires OpenCode
-1.16.1 or newer; the rest of the client remains compatible with 1.15.
+same policy is not appended on every turn. This endpoint first appeared in
+OpenCode 1.16.1; that version floor describes endpoint availability, not
+compatibility with every later server.
 
 ### Lower-level event firehose
 
@@ -119,6 +122,23 @@ client.stream_events(session_id: session_id) do |event|
 end
 ```
 
+Orchestrators that submit their own async prompt must do so through
+`on_subscribed`; the callback runs only after the first `server.connected`
+frame and at most once across automatic reconnects:
+
+```ruby
+client.stream_events(
+  session_id: session_id,
+  on_subscribed: -> { client.send_message_async(session_id, prompt) }
+) do |event|
+  reply.apply(event)
+end
+```
+
+If the callback raises, `stream_events` propagates that error and does not
+retry it. This is intentional: a timed-out prompt response is ambiguous, so
+reposting could duplicate the model turn and its cost.
+
 ### Interactive prompts
 
 When the agent uses the `question` or `permission` tools, opencode emits `question.asked` / `permission.asked` events. Answer them via:
@@ -182,9 +202,29 @@ Want every OpenCode endpoint auto-generated from the OpenAPI spec? Use [`opencod
 ## Compatibility
 
 - Ruby ≥ 3.2
-- OpenCode server ≥ 1.15
 - Runtime dependency: `activesupport (>= 6.1)` — *not* Rails. ActiveSupport is a standalone helpers gem (`blank?`, `present?`, `presence`, `truncate`, etc.).
 
+OpenCode server compatibility is evidence-based, not an open-ended SemVer
+promise. OpenCode's HTTP, SSE, and runtime behavior can change independently
+of a numeric version floor, so this gem does not infer compatibility from a
+constraint such as `>= 1.15`.
+
+Use the [OpenCode compatibility corpus](https://github.com/ajaynomics/opencode-compat)
+as the source of current evidence. Its
+[image matrix](https://github.com/ajaynomics/opencode-compat/blob/main/manifests/image-matrix.json)
+records the exact gem commit and immutable OpenCode OCI digest exercised by
+the `ruby-rest-sse` profile. Its
+[runtime tuples](https://github.com/ajaynomics/opencode-compat/blob/main/manifests/runtime-tuples.json)
+add the exact consumer commit and canary evidence needed for promotion and
+rollback. A version label or image tag is provenance only, never the execution
+coordinate.
+
+A combination absent from passing evidence is **unverified**, not necessarily
+incompatible. Run the corpus against the exact gem, image digest, and consumer
+commit before adopting or promoting it. See the
+[certification policy](https://github.com/ajaynomics/opencode-compat/blob/main/docs/certification.md)
+for the full process.
+
 ## Development
 
 ```sh
@@ -196,10 +236,13 @@ The smoke suite covers Client end-to-end against WebMock-stubbed OpenCode
 endpoints, including subscription-before-prompt ordering and
 reconnect-without-repost.
 
-Releases use RubyGems trusted publishing. After the repository's
-`release.yml` workflow is registered as a trusted publisher with the `release`
-environment, pushing a `v*` tag builds, attests, and publishes the gem without
-a long-lived RubyGems API key.
+The repository contains a tag-triggered `release.yml` workflow intended for
+RubyGems trusted publishing, but its RubyGems trusted-publisher registration is
+not configured as of `0.0.1.alpha7`; that release was published manually. A
+`v*` tag push therefore does not currently guarantee publication. Before a
+future release, verify the RubyGems registry result explicitly. Once the
+workflow is registered as a trusted publisher for the `release` environment,
+it can build, attest, and publish without a long-lived RubyGems API key.
 
 ## License
 

lib/opencode/client.rb

@@ -285,6 +285,13 @@ module Opencode
     # without nuking real reasoning. Callers that know their agent is
     # short-prompt + fast can pass a lower value.
     #
+    # on_subscribed: optional callable invoked at most once, after the first
+    # `server.connected` frame proves the SSE response body is flowing. This
+    # is the safe place for higher-level orchestrators to submit prompt_async;
+    # reconnects wait for their own connected frame but never invoke it again.
+    # A raised callback error is propagated directly and is never treated as
+    # a reconnectable SSE transport failure.
+    #
     # idle_stream_timeout: seconds to wait BETWEEN meaningful events once
     # the session has started producing them. Default nil = no check
     # (preserves the overall `timeout` ceiling behavior). Opt-in heartbeat
@@ -298,7 +305,7 @@ module Opencode
     # translate into a user-visible error / retry affordance.
     def stream_events(session_id:, timeout: 600, first_event_timeout: 120,
                        idle_stream_timeout: nil,
-                       reply: nil, on_activity_tick: nil, &block)
+                       reply: nil, on_activity_tick: nil, on_subscribed: nil, &block)
       consume_event_stream(
         session_id: session_id,
         timeout: timeout,
@@ -306,6 +313,7 @@ module Opencode
         idle_stream_timeout: idle_stream_timeout,
         reply: reply,
         on_activity_tick: on_activity_tick,
+        on_subscribed: on_subscribed,
         &block
       )
     end
@@ -318,6 +326,7 @@ module Opencode
       first_event_deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + first_event_timeout
       received_session_event = false
       last_meaningful_event_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      subscription_callback_attempted = on_subscribed.nil?
 
       loop do
         now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
@@ -390,14 +399,22 @@ module Opencode
                   # available readiness handshake before prompting.
                   next unless event[:type] == "server.connected"
 
-                  begin
-                    turn_started = on_subscribed.call
-                  rescue StandardError => error
-                    # Prompt submission happens inside the open SSE response.
-                    # Do not mistake its transport failure for an SSE disconnect
-                    # and hide it behind a reconnect/first-event timeout.
-                    subscription_callback_error = error
-                    raise
+                  turn_started = false
+                  unless subscription_callback_attempted
+                    # Mark the attempt before invoking the callback. A timeout
+                    # can mean the prompt reached OpenCode even though its HTTP
+                    # response did not reach us; retrying would duplicate the
+                    # turn. The caller receives the original error instead.
+                    subscription_callback_attempted = true
+                    begin
+                      turn_started = on_subscribed.call
+                    rescue StandardError => error
+                      # Prompt submission happens inside the open SSE response.
+                      # Do not mistake its transport failure for an SSE disconnect
+                      # and hide it behind a reconnect/first-event timeout.
+                      subscription_callback_error = error
+                      raise
+                    end
                   end
                   if turn_started
                     # Before this fix stream_events began only after the prompt

lib/opencode/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Opencode
-  VERSION = "0.0.1.alpha6"
+  VERSION = "0.0.1.alpha7"
 end

test/opencode/smoke_test.rb

@@ -271,6 +271,70 @@ class SmokeTest < Minitest::Test
     assert_requested prompt, times: 1
   end
 
+  def test_stream_events_invokes_on_subscribed_once_after_connected_across_reconnects
+    order = []
+    connections = [
+      [ CONNECTED_EVENT, { type: "server.heartbeat", properties: {} } ],
+      [
+        CONNECTED_EVENT,
+        {
+          type: "session.status",
+          properties: { sessionID: SESSION_ID, status: { type: "idle" } }
+        }
+      ]
+    ]
+
+    event_stream = stub_request(:get, %r{#{Regexp.escape(BASE)}/event(\?.*)?\z})
+      .to_return do
+        events = connections.shift or raise "unexpected third SSE connection"
+        order << :sse_accepted
+        {
+          status: 200,
+          body: events.map { |event| "data: #{event.to_json}\n\n" }.join,
+          headers: { "Content-Type" => "text/event-stream" }
+        }
+      end
+
+    subscribed_calls = 0
+    @client.stream_events(
+      session_id: SESSION_ID,
+      timeout: 1,
+      first_event_timeout: 1,
+      on_subscribed: -> {
+        subscribed_calls += 1
+        order << :prompt
+        true
+      }
+    ) { |_event| }
+
+    assert_equal 1, subscribed_calls
+    assert_equal [ :sse_accepted, :prompt, :sse_accepted ], order
+    assert_requested event_stream, times: 2
+  end
+
+  def test_stream_events_surfaces_on_subscribed_timeout_without_reconnecting
+    event_stream = stub_request(:get, %r{#{Regexp.escape(BASE)}/event(\?.*)?\z})
+      .to_return(status: 200, body: "data: #{CONNECTED_EVENT.to_json}\n\n",
+                 headers: { "Content-Type" => "text/event-stream" })
+
+    calls = 0
+    error = assert_raises(Net::ReadTimeout) do
+      @client.stream_events(
+        session_id: SESSION_ID,
+        timeout: 1,
+        first_event_timeout: 1,
+        on_subscribed: -> {
+          calls += 1
+          raise Net::ReadTimeout, "ambiguous prompt response"
+        }
+      ) { |_event| }
+    end
+
+    assert_equal "Net::ReadTimeout with \"ambiguous prompt response\"", error.message
+    assert_equal 1, calls
+    assert_requested event_stream, times: 1
+  end
+
   def test_stream_events_preserves_question_and_permission_wait_state
     events = [
       {

test/readme_contract_test.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+class ReadmeContractTest < Minitest::Test
+  README = File.read(File.expand_path("../README.md", __dir__))
+
+  def test_server_compatibility_points_to_exact_certification_evidence
+    assert_includes README, "https://github.com/ajaynomics/opencode-compat"
+    assert_includes README, "manifests/image-matrix.json"
+    assert_includes README, "manifests/runtime-tuples.json"
+    refute_match(/OpenCode server\s*(?:>=|≥)\s*\d/, README)
+  end
+
+  def test_release_guidance_does_not_claim_trusted_publishing_is_configured
+    assert_includes README, "not configured as of `0.0.1.alpha7`"
+    assert_includes README, "does not currently guarantee publication"
+  end
+end