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