opencode-ruby 0.0.1.alpha2 → 0.0.1.alpha7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5c85499ae01e9b85854d1738508f079c8e4b41d00d926f7c81cd537db2a30474
-  data.tar.gz: 9034a4c5697390f12f2c1d4c0566de11f1e44321c9f2497bc9b8c54d514e43fb
+  metadata.gz: 7a4ddecebacda21e25ac50bd14d6d36c8ad61b35d23dee985b620d82a2b94b36
+  data.tar.gz: 3aa46267d464d9f95ddc96cb0a7d59cff04a9559c1dffb8d5c6d99c84f46b7b5
 SHA512:
-  metadata.gz: 8a73ddf71df4c272aa3676cdddd5deb9d0db71a10466f4f355df6f9e63ada55a9231773df56f74cf7c44544069bdfc5fa0be82ea5dc8c89732192f87d4bc980d
-  data.tar.gz: e8015d9f32e8f3e1712e1cdf21824eacb7f26f3244831d20c8bfdff513ebb8d692afa2360aaa90450625cf935a0eb744fed16a62c7e3ed2b8b5f421819fd288f
+  metadata.gz: 2b7a4ef58b44d2d179c3dd389a0b3a2593557188fe03e62d8e63fa19b766de22f75cef35309f2155d3eb6af80bb79c4f44f3251448602aade9fc928761561a4e
+  data.tar.gz: 141450c28378875563cb27742eea0ae60d08ef325c37b40923bb0b4103e26f9ce82dd603dc5db313578a12e8a7a160bbbea5aefdeed7e5f87751acb364410cd6

data/CHANGELOG.md

@@ -1,5 +1,58 @@
 # 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
+
+- Make `Opencode::Client#stream` wait for OpenCode's initial
+  `server.connected` SSE readiness frame before submitting `prompt_async`,
+  closing the fast-response window where a turn could emit events before the
+  client was listening.
+- Keep prompt submission at-most-once across automatic SSE reconnects. A
+  reconnect now reopens only the event stream; it never posts the user prompt
+  again, and prompt transport failures remain visible to the caller.
+
+## 0.0.1.alpha5 - 2026-07-15
+
+### Added
+
+- Extend `Opencode::Client#create_session` with OpenCode's native parent,
+  agent, model, metadata, and workspace fields while preserving the existing
+  title and permission call shape. Session model strings are encoded with the
+  session endpoint's `{ providerID, id }` shape rather than the message
+  endpoint's `{ providerID, modelID }` shape.
+
+## 0.0.1.alpha4 - 2026-07-12
+
+### Fixed
+
+- End SSE streams on current OpenCode `session.status` idle events while
+  retaining compatibility with legacy `session.idle` events.
+- Reconcile every assistant message in the current user turn after multi-step
+  tool loops, preserving stream-only parts without duplicating final text.
+- Parse terminal tool parts in standalone Ruby clients without relying on the
+  Rails-loaded `Object#in?` extension.
+
+## 0.0.1.alpha3 - 2026-07-10
+
+### Added
+
+- `Opencode::Client#update_session` for applying permission rules through
+  OpenCode's session PATCH endpoint. OpenCode appends these rules, so hosts
+  should fingerprint their ordered policy and call this only when it changes.
+
 ## 0.0.1.alpha2 — 2026-05-20
 
 ### Added

data/README.md

@@ -48,6 +48,27 @@ Multi-tenant apps construct multiple clients with different `base_url`s — each
 
 ## Core API
 
+### Configured and parent-linked sessions
+
+OpenCode can create a session under an existing parent and select its agent,
+model, metadata, workspace, and permission policy in the same request:
+
+```ruby
+child = client.create_session(
+  title: "Destination curator",
+  parent_id: parent_session_id,
+  agent: "destination-list-curator",
+  model: "openai/gpt-5.5",
+  metadata: { run_id: "9" },
+  workspace_id: workspace_id,
+  permissions: permission_rules
+)
+```
+
+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.
+
 ### Streaming (the headline)
 
 ```ruby
@@ -65,6 +86,11 @@ reply.reasoning_text  # => the model's hidden reasoning, if any
 reply.parts_json      # => the full ordered parts array, ready for persistence
 ```
 
+`stream` waits for OpenCode's initial `server.connected` SSE readiness frame
+before it submits the asynchronous prompt. If the event connection drops
+afterward, the client reconnects only the subscription; it never reposts the
+prompt. This prevents both missed fast responses and duplicate turns.
+
 ### Synchronous send (no streaming)
 
 ```ruby
@@ -72,16 +98,44 @@ result = client.send_message(session_id, "Quick yes/no: is Ruby fun?")
 # result is the OpenCode response hash; see API docs for fields.
 ```
 
+### Updating session permissions
+
+```ruby
+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.
+
 ### Lower-level event firehose
 
 If you need raw SSE events (every server tick, todo update, prompt asked/replied), use `stream_events` directly:
 
 ```ruby
 client.stream_events(session_id: session_id) do |event|
-  puts event[:type] # "message.part.delta", "todo.updated", "session.idle", ...
+  puts event[:type] # "message.part.delta", "todo.updated", "session.status", ...
+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:
@@ -101,7 +155,7 @@ begin
 rescue Opencode::ConnectionError      # server unreachable
 rescue Opencode::TimeoutError         # client-side timeout
 rescue Opencode::SessionNotFoundError # 404 on a session
-rescue Opencode::StaleSessionError    # session.idle never arrived
+rescue Opencode::StaleSessionError    # no session event arrived after the prompt
 rescue Opencode::IdleStreamError      # mid-turn SSE wedge
 rescue Opencode::ServerError          # 5xx
 rescue Opencode::BadRequestError      # 4xx other than 404
@@ -155,7 +209,14 @@ bundle install
 bundle exec rake test
 ```
 
-12-test smoke covers Client end-to-end against WebMock-stubbed OpenCode endpoints.
+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.
 
 ## License
 

data/lib/opencode/client.rb

@@ -25,8 +25,24 @@ module Opencode
       @workspace = workspace
     end
 
-    def create_session(title: nil, permissions: nil)
-      body = { title: title, permission: permissions }.compact
+    def create_session(
+      title: nil,
+      permissions: nil,
+      parent_id: nil,
+      agent: nil,
+      model: nil,
+      metadata: nil,
+      workspace_id: nil
+    )
+      body = {
+        title: title,
+        permission: permissions,
+        parentID: parent_id,
+        agent: agent,
+        model: format_session_model(model),
+        metadata: metadata,
+        workspaceID: workspace_id
+      }.compact
       post("/session", body)
     end
 
@@ -115,21 +131,35 @@ module Opencode
       on_activity_tick: nil,
       &block
     )
-      send_message_async(
-        session_id, text,
-        model: model, agent: agent, system: system, message_id: message_id
-      )
-
       reply = Opencode::Reply.new
       reply.add_observer(StreamBlockObserver.new(&block)) if block_given?
 
-      stream_events(
+      # Opening the event stream after prompt_async leaves a race where a fast
+      # turn can emit (and finish) before the client is subscribed. Wait for
+      # OpenCode's initial server.connected SSE frame, then submit the prompt
+      # exactly once. Reconnects invoke on_subscribed again, so mark the attempt
+      # before the POST: an ambiguous prompt response must never cause the same
+      # turn to be submitted twice.
+      prompt_attempted = false
+      on_subscribed = lambda do
+        next false if prompt_attempted
+
+        prompt_attempted = true
+        send_message_async(
+          session_id, text,
+          model: model, agent: agent, system: system, message_id: message_id
+        )
+        true
+      end
+
+      consume_event_stream(
         session_id: session_id,
         timeout: stream_timeout,
         first_event_timeout: first_event_timeout,
         idle_stream_timeout: idle_stream_timeout,
         reply: reply,
-        on_activity_tick: on_activity_tick
+        on_activity_tick: on_activity_tick,
+        on_subscribed: on_subscribed
       ) do |event|
         reply.apply(event)
       end
@@ -144,6 +174,10 @@ module Opencode
       execute(request)
     end
 
+    def update_session(session_id, permissions:)
+      patch("/session/#{session_id}", { permission: permissions })
+    end
+
     def children(session_id)
       uri = build_uri("/session/#{session_id}/children")
       request = Net::HTTP::Get.new(uri)
@@ -233,8 +267,10 @@ module Opencode
     ].freeze
 
     # Opens SSE connection to GET /event, yields parsed events filtered by session_id.
-    # Blocks until session goes idle or timeout, reconnecting across dropped
-    # event-stream connections.
+    # Blocks until the session reports idle or timeout, reconnecting across
+    # dropped event-stream connections. Current OpenCode emits
+    # `session.status` with `status.type == "idle"`; older versions emitted the
+    # standalone `session.idle` event, so both remain terminal.
     #
     # first_event_timeout: seconds to wait for a session-specific event before
     # declaring the session stale. Server heartbeats don't count — they're global
@@ -249,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
@@ -262,12 +305,28 @@ 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,
+        first_event_timeout: first_event_timeout,
+        idle_stream_timeout: idle_stream_timeout,
+        reply: reply,
+        on_activity_tick: on_activity_tick,
+        on_subscribed: on_subscribed,
+        &block
+      )
+    end
+
+    private def consume_event_stream(session_id:, timeout:, first_event_timeout:,
+                                     idle_stream_timeout:, reply:, on_activity_tick:,
+                                     on_subscribed: nil, &block)
       uri = build_uri("/event")
       deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
       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)
@@ -297,6 +356,8 @@ module Opencode
         http.open_timeout = 10
         http.read_timeout = 30
 
+        subscription_callback_error = nil
+        subscription_ready = on_subscribed.nil?
         begin
           buffer = String.new
 
@@ -330,6 +391,44 @@ module Opencode
                 event = parse_sse_event(raw_event, session_id)
                 next unless event
 
+                unless subscription_ready
+                  # Every supported OpenCode server starts /event with this
+                  # frame. Receiving it proves the stream body is flowing; on
+                  # current servers the bus listener is registered eagerly,
+                  # and on older lazy-stream servers it is the strongest
+                  # available readiness handshake before prompting.
+                  next unless event[:type] == "server.connected"
+
+                  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
+                    # POST returned. Preserve those timeout semantics: the turn
+                    # and first-session-event windows begin after prompt_async
+                    # succeeds, not while establishing the readiness handshake.
+                    started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+                    deadline = started_at + timeout
+                    first_event_deadline = started_at + first_event_timeout
+                    last_meaningful_event_at = started_at
+                  end
+                  subscription_ready = true
+                end
+
                 unless event[:type]&.start_with?("server.")
                   received_session_event = true
                   last_meaningful_event_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
@@ -341,13 +440,16 @@ module Opencode
                 # the reaper doesn't kill it mid-wait.
                 on_activity_tick&.call(event)
                 block.call(event)
-                return if event[:type] == "session.idle"
+                return if terminal_session_event?(event)
               end
             end
           end
         rescue *TRANSIENT_SSE_ERRORS
+          raise if subscription_callback_error
+
           # Treat transport-level SSE disconnects like clean EOF: reconnect
-          # until session.idle, the overall timeout, or first-event timeout.
+          # until an idle session event, the overall timeout, or first-event
+          # timeout.
         ensure
           begin
             http&.finish if http&.started?
@@ -381,13 +483,16 @@ module Opencode
     # the caller's reply is still a usable Result either way.
     def merge_final_exchange(session_id, reply)
       exchange = get_messages(session_id)
-      last_assistant = Array(exchange).reverse_each.find do |message|
-        message.dig(:info, :role) == "assistant"
-      end
-      return unless last_assistant
-
-      polled = Opencode::ResponseParser.extract_interleaved_parts(last_assistant)
-      reply.sync_recovered_parts(polled) if polled.any?
+      polled = current_turn_parts(exchange)
+      return if polled.empty?
+
+      merged = merge_stream_only_parts(reply.result.parts_json, polled)
+      reply.sync_recovered_parts(merged)
+      # sync_recovered_parts intentionally never deletes live parts because it
+      # is also used during mid-stream recovery. This is the terminal poll, so
+      # the wire snapshot is authoritative: remove any replayed trailing wire
+      # part after observers have seen recovered additions/updates.
+      reply.replace_parts(merged) unless reply.result.parts_json == merged
     rescue Opencode::Error
       # Stream's result is still complete; the merge was a polish, not a
       # requirement.
@@ -404,6 +509,45 @@ module Opencode
       deadline
     end
 
+    def terminal_session_event?(event)
+      return true if event[:type] == "session.idle"
+      return false unless event[:type] == "session.status"
+
+      status = event.dig(:properties, :status)
+      status = status[:type] || status["type"] if status.is_a?(Hash)
+      status == "idle"
+    end
+
+    # OpenCode persists one assistant message per model step. A tool loop can
+    # therefore produce several assistant messages for one user turn (for
+    # example skill -> task -> final text). Reconcile the complete current turn
+    # instead of aligning the live parts array with only the last assistant
+    # message, which corrupts tool parts and duplicates final text.
+    def current_turn_parts(exchange)
+      messages = Array(exchange)
+      last_user_index = messages.rindex { |message| message.dig(:info, :role) == "user" }
+      current_turn = last_user_index ? messages.drop(last_user_index + 1) : messages
+
+      current_turn
+        .select { |message| message.dig(:info, :role) == "assistant" }
+        .flat_map { |message| Opencode::ResponseParser.extract_interleaved_parts(message) }
+    end
+
+    def merge_stream_only_parts(stream_parts, wire_parts)
+      remaining_wire = Array(wire_parts).dup
+      merged = []
+
+      Array(stream_parts).each do |part|
+        if Opencode::PartSource.stream_only?(part)
+          merged << part
+        elsif remaining_wire.any?
+          merged << remaining_wire.shift
+        end
+      end
+
+      merged.concat(remaining_wire)
+    end
+
     def prompt_payload(text, parts:, model:, agent:, system:, message_id:, no_reply:, tools:, format:, variant:)
       message_parts = parts || [ { type: "text", text: text } ]
       {
@@ -427,6 +571,14 @@ module Opencode
       { providerID: provider, modelID: model_id }
     end
 
+    def format_session_model(model)
+      return nil unless model
+      return model if model.is_a?(Hash)
+
+      provider, model_id = model.split("/", 2)
+      { providerID: provider, id: model_id }
+    end
+
     def post(path, body)
       uri = build_uri(path)
       request = Net::HTTP::Post.new(uri)
@@ -434,6 +586,13 @@ module Opencode
       execute(request)
     end
 
+    def patch(path, body)
+      uri = build_uri(path)
+      request = Net::HTTP::Patch.new(uri)
+      request.body = body.to_json
+      execute(request)
+    end
+
     def build_uri(path, scoped: true)
       uri = @uri.dup
       uri.path = path

data/lib/opencode/response_parser.rb

@@ -27,7 +27,7 @@ module Opencode
     def self.extract_tool_summary(response_body)
       parts = response_body[:parts] || []
       parts
-        .select { |p| p[:type] == "tool" && p.dig(:state, :status).in?(TERMINAL_STATUSES) }
+        .select { |p| p[:type] == "tool" && TERMINAL_STATUSES.include?(p.dig(:state, :status)) }
         .map { |p| build_tool_summary(p) }
     end
 
@@ -42,7 +42,7 @@ module Opencode
           { "type" => "reasoning", "content" => part[:text] }
         when "tool"
           status = part.dig(:state, :status)
-          next unless status.in?(TERMINAL_STATUSES)
+          next unless TERMINAL_STATUSES.include?(status)
 
           build_tool_summary(part)
         else

data/lib/opencode/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: opencode-ruby
 version: !ruby/object:Gem::Version
-  version: 0.0.1.alpha2
+  version: 0.0.1.alpha7
 platform: ruby
 authors:
 - Ajay Krishnan