opencode-ruby 0.0.1.alpha2

data/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

data/lib/opencode/response_parser.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module Opencode
+  module ResponseParser
+    def self.extract_text(response_body)
+      parts = response_body[:parts] || []
+      parts
+        .select { |p| p[:type] == "text" }
+        .map { |p| p[:text] }
+        .join("\n\n")
+    end
+
+    def self.extract_reasoning(response_body)
+      parts = response_body[:parts] || []
+      reasoning = parts
+        .select { |p| p[:type] == "reasoning" }
+        .map { |p| p[:text] }
+        .join("\n\n")
+      reasoning.presence
+    end
+
+    TERMINAL_STATUSES = %w[completed error].freeze
+
+    # Terminal-only tool list. Returned as canonical string-keyed hashes
+    # (same shape `extract_interleaved_parts` returns) so callers do not
+    # have to know which path produced the data.
+    def self.extract_tool_summary(response_body)
+      parts = response_body[:parts] || []
+      parts
+        .select { |p| p[:type] == "tool" && p.dig(:state, :status).in?(TERMINAL_STATUSES) }
+        .map { |p| build_tool_summary(p) }
+    end
+
+    def self.extract_interleaved_parts(response_body)
+      parts = response_body[:parts] || []
+
+      parts.filter_map do |part|
+        case part[:type]
+        when "text"
+          { "type" => "text", "content" => part[:text] }
+        when "reasoning"
+          { "type" => "reasoning", "content" => part[:text] }
+        when "tool"
+          status = part.dig(:state, :status)
+          next unless status.in?(TERMINAL_STATUSES)
+
+          build_tool_summary(part)
+        else
+          nil
+        end
+      end
+    end
+
+    # Canonical tool-part shape from one OpenCode message part. Delegates
+    # to Opencode::ToolPart so the streaming path (Reply#apply_tool_state)
+    # and recovery path (this method) cannot drift.
+    def self.build_tool_summary(part)
+      Opencode::ToolPart.from_message_part(part)
+    end
+
+    private_class_method :build_tool_summary
+
+    def self.extract_tokens(response_body)
+      response_body.dig(:info, :tokens)
+    end
+
+    def self.extract_cost(response_body)
+      response_body.dig(:info, :cost)
+    end
+
+    def self.extract_cache_tokens(response_body)
+      tokens = response_body.dig(:info, :tokens) || {}
+      {
+        cache_read: tokens.dig(:cache, :read) || 0,
+        cache_write: tokens.dig(:cache, :write) || 0
+      }
+    end
+
+    def self.extract_error(response_body)
+      error = response_body.dig(:info, :error)
+      return nil unless error.is_a?(Hash)
+
+      {
+        name: error[:name],
+        message: error.dig(:data, :message),
+        status_code: error.dig(:data, :statusCode),
+        retryable: error.dig(:data, :isRetryable),
+        url: error.dig(:data, :metadata, :url)
+      }.compact
+    end
+
+    MAX_ARTIFACT_SIZE = 10.megabytes
+    ARTIFACT_TOOLS = %w[write apply_patch].freeze
+
+    def self.extract_artifact_files(response_body)
+      parts = response_body[:parts] || []
+      completed_tools = parts.select do |p|
+        p[:type] == "tool" &&
+          ARTIFACT_TOOLS.include?(p[:tool]) &&
+          p.dig(:state, :status) == "completed"
+      end
+      return [] if completed_tools.empty?
+
+      files = completed_tools.flat_map { |part| extract_files_from_tool_part(part) }
+      files.uniq { |f| f[:filename] }
+    end
+
+    def self.extract_artifacts_from_messages(messages)
+      return [] unless messages.is_a?(Array)
+
+      messages
+        .select { |m| m.dig(:info, :role) == "assistant" }
+        .flat_map { |m| extract_artifact_files(m) }
+        .uniq { |f| f[:filename] }
+    end
+
+    def self.extract_files_from_tool_part(part)
+      case part[:tool]
+      when "write"
+        extract_from_write(part)
+      when "apply_patch"
+        extract_from_apply_patch(part)
+      else
+        []
+      end
+    end
+
+    def self.extract_from_write(part)
+      content = part.dig(:state, :input, :content)
+      file_path = part.dig(:state, :input, :filePath)
+      return [] if content.blank? || file_path.blank?
+      return [] if content.bytesize > MAX_ARTIFACT_SIZE
+
+      filename = File.basename(file_path)
+      content_type = Marcel::MimeType.for(extension: File.extname(filename))
+      [ { filename: filename, content: content, content_type: content_type } ]
+    end
+
+    # apply_patch tool metadata shape changed materially between the early
+    # opencode versions this code originally targeted (which exposed
+    # `before` + `after` post-write file content as inline strings) and
+    # v1.4.0+ (which dropped them and only exposes the diff text in `patch`
+    # plus a `files` array of { filePath, relativePath, type, patch,
+    # additions, deletions, movePath? } descriptors). Source of truth:
+    # https://raw.githubusercontent.com/anomalyco/opencode/v1.15.0/packages/opencode/src/tool/apply_patch.ts
+    #
+    # With no `after` field in the v1.15.0 wire shape, this method previously
+    # silently returned [] for every real apply_patch invocation while still
+    # passing its (now-stale-shape) unit test — the worst kind of bug: a
+    # green test paired with a dead production path.
+    #
+    # Current behavior (intentional, until apply_patch becomes a hot path
+    # for the gem's users): we accept the v1.15.0 shape and return []. Most
+    # agents write whole files via the `write` tool rather than patching,
+    # so the practical impact today is zero. When you do use apply_patch,
+    # opencode-rails' `Opencode::Exchange#tool_artifacts` emits
+    # `opencode.apply_patch.artifacts_dropped` so operators see the silent
+    # drop and can route through the missing sandbox-read path.
+    #
+    # The event emission lives on Exchange (not here) because ResponseParser
+    # is a pure module — every other method takes a hash and returns a hash.
+    # Pure functions stay pure.
+    def self.extract_from_apply_patch(_part)
+      []
+    end
+
+    private_class_method :extract_files_from_tool_part, :extract_from_write, :extract_from_apply_patch
+  end
+end

data/lib/opencode/todo.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Opencode
+  # One todo item the OpenCode `todowrite` tool and `todo.updated` bus
+  # event carry: `content` + `status` + (optional) `priority`.
+  # Source-of-truth canonicalization lives here so Reply, ToolDisplay,
+  # and any future consumer all share one definition of "what does this
+  # todo look like once we've normalized it."
+  #
+  # Status canonicalization: OpenCode bus events have been observed
+  # emitting the hyphenated `"in-progress"` form. The rest of the
+  # codebase (per-product views, todowrite tool input shape per the
+  # v1.15+ openapi spec) uses the underscored `"in_progress"`.
+  # Canonicalize to underscore at every entry point so downstream code
+  # never has to handle both.
+  module Todo
+    HYPHENATED_TO_CANONICAL_STATUS = {
+      "in-progress" => "in_progress"
+    }.freeze
+
+    module_function
+
+    def canonical_status(status)
+      raw = status.to_s
+      HYPHENATED_TO_CANONICAL_STATUS.fetch(raw) { raw.tr("-", "_") }
+    end
+
+    # Canonicalize one todo hash: string-keyed, normalized status.
+    # Returns the input unchanged when it isn't a Hash (the substrate
+    # tolerates wire-shape drift defensively).
+    def canonicalize(todo)
+      return todo unless todo.is_a?(Hash)
+
+      result = todo.deep_stringify_keys
+      result["status"] = canonical_status(result["status"]) if result.key?("status")
+      result
+    end
+
+    def canonicalize_all(todos)
+      Array(todos).map { |t| canonicalize(t) }
+    end
+  end
+end

data/lib/opencode/tool_part.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module Opencode
+  # Canonical shape of a tool part in an assistant reply.
+  #
+  # A tool part starts `pending` and transitions through `running` to a
+  # terminal `completed` or `error`. The complete representation carries
+  # seven fields, all string-keyed so views read consistent keys whether
+  # the part came from a live streaming event or a post-stream message
+  # poll:
+  #
+  #   "type"     => "tool"
+  #   "tool"     => "edit"
+  #   "status"   => "completed"
+  #   "title"    => "Edited /INDEX.md"
+  #   "input"    => { ... }   # full args the agent passed, deep-stringified
+  #   "metadata" => { ... }   # tool-specific output: diff, preview, stdout, etc.
+  #   "output"   => "Edited successfully."
+  #   "error"    => "..."     # only when status == "error", truncated to 200 chars
+  #
+  # The shape is produced two ways:
+  #
+  #   1. Opencode::Reply#apply_tool_state — live, mid-stream, merging
+  #      incoming event state into an in-memory record (previous values
+  #      survive when the new event omits a field).
+  #
+  #   2. Opencode::ResponseParser.build_tool_summary — post-stream, built
+  #      fresh from a complete OpenCode message returned by
+  #      /session/:id/message during recovery / final-exchange polling.
+  #
+  # Existence reason: the two paths used to drift. ResponseParser stripped
+  # `metadata` and whitelisted `input` to a fixed key list, so `parts_json`
+  # saved on finalize had strictly less data than the streaming DOM had
+  # shown. The visible symptom was "I saw the diff while streaming and it
+  # disappeared when the turn finished". This class is the single source of
+  # truth that prevents that drift.
+  module ToolPart
+    MAX_ERROR_LEN = 200
+    INVALID_TOOL = "invalid"
+
+    module_function
+
+    # Build a fresh canonical tool-part hash from one OpenCode message
+    # part (the shape that arrives through /session/:id/message).
+    # Used by ResponseParser for recovery and final-exchange polling.
+    def from_message_part(part)
+      state = state_of(part)
+      build_canonical(
+        tool: part[:tool] || part["tool"],
+        status: state_value(state, :status),
+        title: state_value(state, :title),
+        input: state_value(state, :input),
+        metadata: state_value(state, :metadata),
+        output: state_value(state, :output),
+        error: state_value(state, :error)
+      )
+    end
+
+    # Merge an incoming `message.part.updated` event state into an
+    # existing record. Used by Reply#apply_tool_state during streaming.
+    #
+    # Fields the event omits (or that arrive empty) leave the record's
+    # previous value intact. Mid-tool events are partial by design.
+    #
+    # In addition to the canonical render fields (status, title, input,
+    # metadata, output, error), this also persists `callID` and
+    # `messageID` from the incoming state. Those identifiers are needed
+    # by downstream lookups (e.g. matching an ask-user reply event back
+    # to the originating tool part by callID) and would otherwise be
+    # silently dropped on the way into Reply.parts JSON.
+    #
+    # Returns the (mutated) record for chaining.
+    def merge_streaming_state(record, part)
+      state = state_of(part)
+
+      tool = part[:tool] || part["tool"]
+      # Preserve original tool name if OpenCode later renames to "invalid"
+      # mid-session — we want to keep rendering the original name.
+      record["tool"] = tool if tool.present? && tool != INVALID_TOOL
+
+      status = state_value(state, :status)
+      record["status"] = status if status
+
+      title = state_value(state, :title)
+      record["title"] = title if title.present?
+
+      input = state_value(state, :input)
+      record["input"] = stringify_deep(input) if input.present?
+
+      metadata = state_value(state, :metadata)
+      record["metadata"] = stringify_deep(metadata) if metadata.present?
+
+      output = state_value(state, :output)
+      record["output"] = output if output.present?
+
+      error = state_value(state, :error)
+      record["error"] = error.to_s.truncate(MAX_ERROR_LEN) if error.present?
+
+      # callID and messageID moved from state.* to the part's top level
+      # somewhere in opencode v1.15.x. Read top-level first, fall back
+      # to state.* for any older versions that may still be in flight.
+      # Without this, merge_pending_question_into_existing_tool_part
+      # (which searches @parts by callID) silently no-ops, and the
+      # question form renders with no questions or routing IDs.
+      call_id = part[:callID] || part["callID"] || state_value(state, :callID)
+      record["callID"] = call_id if call_id.present?
+
+      message_id = part[:messageID] || part["messageID"] || state_value(state, :messageID)
+      record["messageID"] = message_id if message_id.present?
+
+      record
+    end
+
+    class << self
+      private
+
+      def state_of(part)
+        part[:state] || part["state"] || {}
+      end
+
+      def state_value(state, key)
+        return nil unless state.is_a?(Hash)
+        state[key] || state[key.to_s]
+      end
+
+      def build_canonical(tool:, status:, title:, input:, metadata:, output:, error:)
+        hash = {
+          "type" => "tool",
+          "tool" => tool.to_s.presence,
+          "status" => status,
+          "title" => title.presence,
+          "input" => stringify_deep(input).presence,
+          "metadata" => stringify_deep(metadata).presence,
+          "output" => output.presence
+        }
+        hash["error"] = error.to_s.truncate(MAX_ERROR_LEN).presence if status == "error"
+        hash.compact
+      end
+
+      def stringify_deep(value)
+        case value
+        when Hash
+          value.each_with_object({}) { |(k, v), h| h[k.to_s] = stringify_deep(v) }
+        when Array
+          value.map { |v| stringify_deep(v) }
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/opencode/tracer.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Opencode
+  # A namespacing trace emitter.
+  #
+  # Opencode::Turn emits unprefixed event names like "response.started"
+  # and "session.recreated". The host product wraps Turn in a Tracer
+  # whose job is to prepend a product prefix and forward to whatever
+  # actually emits trace events (typically the host job's
+  # `EventTraceable#trace_event`).
+  #
+  # Two responsibilities live here, and only here:
+  #
+  #   1. Callable interface: `tracer.call(name, **payload)` — the
+  #      contract Turn relies on.
+  #   2. Namespacing strategy: prepend "<prefix>." to every event name.
+  #
+  # A closure-based alternative that mixes both concerns looks like:
+  #
+  #     tracer: ->(name, **payload) { trace_event("myapp.#{name}", **payload) }
+  #
+  # That closure conflates the two responsibilities; every caller has
+  # to rediscover the prefix-with-period rule, and a typo only shows up
+  # in production trace data. Making it a real role removes that risk
+  # and makes the rule visible in one place.
+  #
+  # Usage:
+  #
+  #   Opencode::Tracer.new(prefix: "myapp", emitter: self)
+  #
+  # `emitter` must respond to `trace_event(name, **payload)`.
+  class Tracer
+    def initialize(prefix:, emitter:)
+      @prefix = prefix
+      @emitter = emitter
+    end
+
+    # Tracer is callable so existing call sites that treated the tracer
+    # as a lambda (`tracer.call(name, **payload)`) keep working without
+    # change. Turn uses this exclusively.
+    #
+    # Uses `send` because EventTraceable's `trace_event` is a private
+    # method of the including class — the convention is "private inside
+    # the job, but the substrate's Tracer is allowed to dispatch to it
+    # the same way the job's own perform method would."
+    def call(name, **payload)
+      @emitter.send(:trace_event, "#{@prefix}.#{name}", **payload)
+    end
+  end
+end

data/lib/opencode/version.rb

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

data/lib/opencode-ruby.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# Minimal ActiveSupport surface — `present?`, `blank?`, `presence`,
+# `truncate`, `duplicable?`. We deliberately load only the core_ext bits
+# we use, not all of activesupport, to keep the boot footprint small in
+# 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/string/filters"    # provides String#truncate
+require "active_support/core_ext/numeric/bytes"     # provides Integer#megabytes
+
+require_relative "opencode/version"
+require_relative "opencode/error"
+require_relative "opencode/instrumentation"
+require_relative "opencode/response_parser"
+require_relative "opencode/part_source"
+require_relative "opencode/tool_part"
+require_relative "opencode/todo"
+require_relative "opencode/prompts"
+require_relative "opencode/reply_observer"
+require_relative "opencode/reply"
+require_relative "opencode/tracer"
+require_relative "opencode/client"
+
+module Opencode
+end

data/opencode-ruby.gemspec

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "lib/opencode/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "opencode-ruby"
+  spec.version       = Opencode::VERSION
+  spec.authors       = ["Ajay Krishnan"]
+  spec.email         = ["opencode-ruby@ajay.to"]
+
+  spec.summary       = "Idiomatic Ruby client for OpenCode (HTTP + SSE)."
+  spec.description   = <<~DESC
+    Hand-rolled, opinionated Ruby SDK for OpenCode's REST + SSE API.
+    Block-form streaming, value-object responses, automatic SSE
+    reconnection. Complement to opencode_client (auto-generated from
+    OpenAPI) — pick this one if you want a small Ruby-idiomatic surface;
+    pick opencode_client if you want every endpoint with generated types.
+  DESC
+  spec.homepage      = "https://github.com/ajaynomics/opencode-ruby"
+  spec.license       = "MIT"
+  spec.required_ruby_version = ">= 3.2.0"
+
+  spec.metadata["homepage_uri"]    = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"]   = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata["bug_tracker_uri"] = "#{spec.homepage}/issues"
+
+  spec.files = Dir.glob("lib/**/*.rb") +
+               Dir.glob("examples/**/*.rb") +
+               %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.
+  spec.add_runtime_dependency "activesupport", ">= 6.1", "< 9.0"
+
+  spec.add_development_dependency "minitest", "~> 5.20"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "webmock", "~> 3.20"
+end