opencode-ruby 0.0.1.alpha6 → 0.0.1.alpha9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ebac8d73ce010347ee830b23a1280b45a6ff71effd1109aad787743ec60fae45
-  data.tar.gz: c815940b8e87bcd5724535e987833e360ee9a725081f753cd451f5ae6938f70d
+  metadata.gz: d0723db2b0d77a65c6718f0dcc49b67d298a62c33996169a697eb47c9436980a
+  data.tar.gz: c0446dbb4539a3432e6d0b71f4790b6c16377ac8aad32406c6f178b04c1dbf54
 SHA512:
-  metadata.gz: 902785c4c78de0f30affcb638bec979844f2e1481cabbb4ce3a2a0fc23ca8d384ed6e2cdbd1e49da7050599728dfb619b1eb7b7c3f011e7b18a793a00e00ca40
-  data.tar.gz: 7e7cc7a596386dd3846dbe1baa91f3cbeba049e46bc8748e05823375ddd07b145849a217ef249d97ff732d3e9f90c3e3e2de1ee7b6ba2021ef30e8cd04bf362d
+  metadata.gz: 73205b52ce2f279b8daee9f7274f52d3ff2382cba757f8af2cfce0d2addb0e67c1bf7b684f6575b9161af53678bccfd0ff40c154afe2336b4202fff5f2085f7a
+  data.tar.gz: 98d7e60949dcad273ab8533c4652902084f0df117cb52ec522ee7a9cdf8bf35906093479634350b395ea1159d9d881e1b683c70a53fd7be5f5815d4d96cb0d84

data/CHANGELOG.md

@@ -1,5 +1,49 @@
 # Changelog
 
+## 0.0.1.alpha9 - 2026-07-20
+
+### Fixed
+
+- Parse SSE events with CRLF, CR-only, or LF framing; accept `data:` fields
+  with or without the optional leading space; join multiple `data:` fields;
+  ignore the stream's optional leading UTF-8 BOM and comment fields; and decode
+  correctly when a transport chunk splits any byte of the event framing.
+- Keep request instrumentation free of query credentials and private workspace
+  paths.
+- Load non-empty todo events and written-file artifacts in standalone Ruby
+  clients.
+- Bound reconnects after an interactive prompt loses its event stream, handle
+  DNS failures as transient stream errors, and map non-404 4xx responses to
+  `BadRequestError` consistently.
+- Retry the Rails recovery recipe with its replacement session and keep
+  exception details out of user-facing message content.
+
+### Changed
+
+- Test Ruby 3.2, 3.3, 3.4, and 4.0; pin every third-party CI and release
+  action to an exact reviewed commit; and use Ruby 4.0 for release builds.
+- Fail the trusted-publishing job before release when the pushed tag does not
+  match `Opencode::VERSION`.
+
+## 0.0.1.alpha8 - 2026-07-20
+
+### Yanked
+
+- Published from the unrepaired alpha8 source by mistake and yanked the same
+  day. Use alpha9, which contains the intended alpha8 fixes and release gates.
+
+## 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 +132,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.

data/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,8 +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.).
+- Runtime dependency: `activesupport (>= 6.1, < 9.0)` — *not* Rails. ActiveSupport is a standalone helpers gem (`blank?`, `present?`, `presence`, `truncate`, etc.).
+- Runtime dependency: `marcel (~> 1.0)` for artifact MIME type detection.
+
+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
 
@@ -196,10 +237,14 @@ 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 mistakenly published `0.0.1.alpha8` package contained unrepaired source and
+was yanked; use `0.0.1.alpha9` or later. The repository contains a tag-triggered
+`release.yml` workflow intended for RubyGems trusted publishing, but its
+trusted-publisher registration is not confirmed for alpha9. 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
 

data/examples/conversation_recipe.rb

@@ -128,12 +128,13 @@ class GenerateAssistantReplyJob < ApplicationJob
       end
     rescue Opencode::SessionNotFoundError, Opencode::StaleSessionError
       raise if attempted_recreate
-      message.conversation.recreate_opencode_session!(client)
+      session_id = message.conversation.recreate_opencode_session!(client)
       attempted_recreate = true
       retry
     end
   rescue StandardError => e
-    message&.update!(status: :errored, content: "An error occurred: #{e.message.truncate(200)}")
+    Rails.logger.error(e.full_message)
+    message&.update!(status: :errored, content: "An error occurred. Please try again.")
   end
 
   private

data/lib/opencode/client.rb

@@ -230,18 +230,12 @@ module Opencode
       request = Net::HTTP::Get.new(uri)
       add_auth_header(request)
 
-      response = Opencode::Instrumentation.instrument("opencode.request", method: request.method, path: request.path) do
+      response = Opencode::Instrumentation.instrument("opencode.request", method: request.method, path: uri.path) do
         http_client.request(request)
       end
 
-      unless response.code.to_i.between?(200, 299)
-        raise ServerError, "list_questions failed: HTTP #{response.code} — #{response.body.to_s[0, 200]}"
-      end
-
-      return [] if response.body.blank?
-      JSON.parse(response.body, symbolize_names: true)
-    rescue JSON::ParserError => e
-      raise ServerError, "list_questions returned invalid JSON: #{e.message}"
+      body = handle_response(response)
+      body.is_a?(Array) ? body : []
     rescue Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout => e
       raise TimeoutError, "OpenCode timeout after #{@timeout}s: #{e.message}"
     rescue Errno::ECONNREFUSED, SocketError => e
@@ -255,6 +249,10 @@ module Opencode
     end
 
     MAX_SSE_BUFFER = 1_048_576 # 1 MB — safety valve against pathological server responses
+    # Keep CRLF atomic so it cannot backtrack into CR + LF and look like a
+    # blank line. SSE also permits bare CR and LF line endings.
+    SSE_EVENT_BOUNDARY = /(?>\r\n|[\r\n]){2}/
+    UTF8_BOM = "\xEF\xBB\xBF".b.freeze
     SSE_RECONNECT_DELAY = 0.1
     TRANSIENT_SSE_ERRORS = [
       EOFError,
@@ -263,7 +261,8 @@ module Opencode
       Net::ReadTimeout,
       Errno::ECONNREFUSED,
       Errno::ECONNRESET,
-      Errno::EPIPE
+      Errno::EPIPE,
+      SocketError
     ].freeze
 
     # Opens SSE connection to GET /event, yields parsed events filtered by session_id.
@@ -285,6 +284,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 +304,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 +312,7 @@ module Opencode
         idle_stream_timeout: idle_stream_timeout,
         reply: reply,
         on_activity_tick: on_activity_tick,
+        on_subscribed: on_subscribed,
         &block
       )
     end
@@ -318,10 +325,11 @@ 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)
-        deadline = check_deadline_or_suspend(now, deadline, timeout, reply)
+        deadline = check_deadline(now, deadline, timeout)
 
         # NOTE: first_event_deadline is *not* suspension-eligible. If the agent
         # never gets started we want to fail fast — a session that's blocked on
@@ -348,9 +356,11 @@ module Opencode
         http.read_timeout = 30
 
         subscription_callback_error = nil
+        event_callback_error = nil
         subscription_ready = on_subscribed.nil?
         begin
           buffer = String.new
+          first_sse_event = true
 
           http.request(request) do |response|
             unless response.is_a?(Net::HTTPSuccess)
@@ -377,9 +387,14 @@ module Opencode
                 raise ServerError, "SSE buffer exceeded #{MAX_SSE_BUFFER} bytes"
               end
 
-              while (idx = buffer.index("\n\n"))
-                raw_event = buffer.slice!(0, idx + 2)
-                event = parse_sse_event(raw_event, session_id)
+              while (boundary = buffer.match(SSE_EVENT_BOUNDARY))
+                raw_event = buffer.slice!(0, boundary.end(0))
+                event = parse_sse_event(
+                  raw_event,
+                  session_id,
+                  allow_bom: first_sse_event
+                )
+                first_sse_event = false
                 next unless event
 
                 unless subscription_ready
@@ -390,14 +405,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
@@ -421,14 +444,19 @@ module Opencode
                 # that's the whole point: a healthy long wait (user thinking
                 # for 30 minutes) keeps the container warm via heartbeats so
                 # the reaper doesn't kill it mid-wait.
-                on_activity_tick&.call(event)
-                block.call(event)
+                begin
+                  on_activity_tick&.call(event)
+                  block.call(event)
+                rescue StandardError => error
+                  event_callback_error = error
+                  raise
+                end
                 return if terminal_session_event?(event)
               end
             end
           end
         rescue *TRANSIENT_SSE_ERRORS
-          raise if subscription_callback_error
+          raise if subscription_callback_error || event_callback_error
 
           # Treat transport-level SSE disconnects like clean EOF: reconnect
           # until an idle session event, the overall timeout, or first-event
@@ -487,6 +515,11 @@ module Opencode
     # the prompt resolves. Otherwise apply the normal deadline check.
     def check_deadline_or_suspend(now, deadline, timeout, reply)
       return now + timeout if reply&.prompt_blocked?
+
+      check_deadline(now, deadline, timeout)
+    end
+
+    def check_deadline(now, deadline, timeout)
       raise TimeoutError, "SSE stream timed out after #{timeout}s" if now > deadline
 
       deadline
@@ -601,7 +634,7 @@ module Opencode
       add_auth_header(request)
 
       response = nil
-      result = Opencode::Instrumentation.instrument("opencode.request", method: request.method, path: request.path) do
+      result = Opencode::Instrumentation.instrument("opencode.request", method: request.method, path: request.uri.path) do
         response = http_client.request(request)
         handle_response(response)
       end
@@ -622,11 +655,22 @@ module Opencode
       end
     end
 
-    def parse_sse_event(raw, session_id)
-      data_line = raw.lines.find { |l| l.start_with?("data: ") }
-      return nil unless data_line
+    def parse_sse_event(raw, session_id, allow_bom: false)
+      if allow_bom && raw.b.start_with?(UTF8_BOM)
+        raw = raw.byteslice(UTF8_BOM.bytesize..)
+      end
 
-      json = JSON.parse(data_line.sub("data: ", "").strip, symbolize_names: true)
+      data = raw.split(/\r\n|\r|\n/, -1).filter_map do |line|
+        next if line.start_with?(":")
+
+        field, value = line.split(":", 2)
+        next unless field == "data"
+
+        (value || "").delete_prefix(" ")
+      end
+      return nil if data.empty?
+
+      json = JSON.parse(data.join("\n"), symbolize_names: true)
 
       event_session = json.dig(:properties, :sessionID) ||
                       json.dig(:properties, :info, :sessionID) ||
@@ -642,23 +686,30 @@ module Opencode
     end
 
     def handle_response(response)
-      return {} if response.code.to_i == 204
+      status = response.code.to_i
+      return {} if status == 204
 
-      body = if response.body.present?
-        JSON.parse(response.body, symbolize_names: true)
-      else
-        {}
-      end
+      body = parse_response_body(response, status)
 
-      case response.code.to_i
+      case status
       when 200..299 then body
-      when 400 then raise BadRequestError.new(error_message(body, "Bad request"), response: body)
       when 404 then raise SessionNotFoundError.new(error_message(body, "Session not found"), response: body)
+      when 400..499 then raise BadRequestError.new(error_message(body, "Bad request"), response: body)
       when 500..599 then raise ServerError.new(error_message(body, "Server error"), response: body)
       else raise Error.new("Unexpected response: #{response.code}", response: body)
       end
+    end
+
+    def parse_response_body(response, status)
+      return {} if response.body.blank?
+
+      JSON.parse(response.body, symbolize_names: true)
     rescue JSON::ParserError
-      raise ServerError.new("Invalid JSON from OpenCode (HTTP #{response.code}): #{response.body&.truncate(200)}")
+      if status.between?(200, 299)
+        raise ServerError.new("Invalid JSON from OpenCode (HTTP #{response.code}): #{response.body&.truncate(200)}")
+      end
+
+      { message: response.body.to_s.truncate(200) }
     end
 
     # OpenCode HTTP error bodies use a wrapped shape: { name:, data: { message:, kind?: } }.
@@ -666,6 +717,9 @@ module Opencode
     # `body[:message]` is no longer populated for errors — only `body[:data][:message]`.
     # We read both to keep older mock servers working in tests.
     def error_message(body, fallback)
+      return body.truncate(200) if body.is_a?(String) && body.present?
+      return fallback unless body.is_a?(Hash)
+
       body.dig(:data, :message) || body[:message] || fallback
     end
   end

data/lib/opencode/version.rb

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

data/lib/opencode-ruby.rb

@@ -6,8 +6,10 @@
 # non-Rails apps.
 require "active_support/core_ext/object/blank"      # provides blank?, present?, presence
 require "active_support/core_ext/object/duplicable"
+require "active_support/core_ext/hash/keys"         # provides Hash#deep_stringify_keys
 require "active_support/core_ext/string/filters"    # provides String#truncate
 require "active_support/core_ext/numeric/bytes"     # provides Integer#megabytes
+require "marcel"
 
 require_relative "opencode/version"
 require_relative "opencode/error"

data/opencode-ruby.gemspec

@@ -30,14 +30,10 @@ Gem::Specification.new do |spec|
                %w[README.md LICENSE CHANGELOG.md opencode-ruby.gemspec]
   spec.require_paths = ["lib"]
 
-  # The only runtime dependency is ActiveSupport (NOT Rails). ActiveSupport
-  # is a standalone gem providing the `present?`/`blank?`/`presence`/
-  # `truncate`/`duplicable?` helpers used in this gem's code. It does NOT
-  # pull in ActiveRecord, ActionView, ActionController, Turbo, or any other
-  # Rails-only piece. Most Ruby apps in the wild already have ActiveSupport
-  # transitively via another gem; in the rare case yours doesn't, ~250 LOC
-  # of core_ext is added when this gem installs.
+  # ActiveSupport supplies the small set of core extensions used by the
+  # client without pulling in Rails. Marcel identifies artifact content types.
   spec.add_runtime_dependency "activesupport", ">= 6.1", "< 9.0"
+  spec.add_runtime_dependency "marcel", "~> 1.0"
 
   spec.add_development_dependency "minitest", "~> 5.20"
   spec.add_development_dependency "rake", "~> 13.0"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: opencode-ruby
 version: !ruby/object:Gem::Version
-  version: 0.0.1.alpha6
+  version: 0.0.1.alpha9
 platform: ruby
 authors:
 - Ajay Krishnan
@@ -29,6 +29,20 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: marcel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement