opencode-rails/README.md

opencode-rails

Production-grade OpenCode integration for Rails apps. Layers an ActiveRecord-aware session lifecycle, a turn orchestrator, an artifact pipeline, and a sandbox model on top of the wire-level client in opencode-ruby.

Alpha software. API will change before 1.0. Pin to a specific version.

Why this gem exists

opencode-ruby gives you a clean Net::HTTP + SSE client. To turn it into something a Rails app can ship, you need:

1. Session lifecycle — idempotent create-or-resolve with row-level locking so concurrent jobs don't double-mint sessions; recreation for stale-session recovery; best-effort upstream abort on teardown.
2. Turn orchestration — drive send_message_async, stream events into Opencode::Reply, recover from SessionNotFoundError / StaleSessionError by recreating + retrying, fetch the final exchange for cost/artifact extraction, finalize the persisted message via CAS against :pending.
3. Mid-stream snapshot — update_columns writes to bypass AR callbacks so app-level Turbo broadcasts fire on rate-limited intervals, not every SSE event.
4. Artifact pipeline — extract files written by the agent (via the write tool's metadata, or by reading from a sandbox path), attach them to the assistant message via ActiveStorage, transform host-rendered artifacts (flight results HTML, etc.) before persisting.

opencode-rails ships these as named, single-responsibility objects so you wire them up instead of re-implementing them.

Install

After both alpha9 gems are confirmed on RubyGems, pin the lockstep tuple:

# Gemfile
gem "opencode-ruby", "= 0.0.1.alpha9" # wire client + Reply state machine
gem "opencode-rails", "= 0.0.1.alpha9"

Until publication is verified, validate this candidate checkout against the exact opencode-ruby source it was tested with:

# Gemfile
gem "opencode-ruby",
  git: "https://github.com/ajaynomics/opencode-ruby.git",
  ref: "65a44ca1502926d533e6b4b6692779fa39740218"

gem "opencode-rails",
  path: "../opencode-rails"

bundle install

Runtime deps: activerecord, activestorage, activesupport (>= 7.1), and marcel. Depends on opencode-ruby for the underlying HTTP/SSE primitives.

UploadedFilesPrompt anchors upload writes through /proc/self/fd or /dev/fd to prevent sandbox-root path swaps. Hosts using upload copying must provide one of those traversable descriptor filesystems; unsupported platforms fail closed before writing.

During the alpha series both gems are pinned in lockstep. Version 0.0.1.alpha9 retains the subscribe-ready-before-prompt transport contract and reconnects an accepted turn without posting its prompt again, while hardening SSE framing.

The unrepaired opencode-ruby 0.0.1.alpha8 package was yanked, and opencode-rails alpha8 was never published. opencode-rails 0.0.1.alpha9 is a release candidate and is not yet confirmed published on RubyGems. The release.yml workflow is prepared for RubyGems trusted publishing, but the gem's trusted publisher must be registered and verified for that workflow and its release environment. Until the registry result is verified, pushing a v* tag does not guarantee publication. Trusted publishing does not require a long-lived RubyGems API key.

Quickstart

# config/initializers/opencode.rb
Opencode::Instrumentation.adapter = ->(name, payload, &blk) {
  ActiveSupport::Notifications.instrument(name, payload, &blk)
}
Opencode::ErrorReporter.adapter = ->(error, **opts) {
  Rails.error.report(error, **opts) if Rails.respond_to?(:error)
}

# app/services/noop_reply_observer.rb
#
# Turn requires an observer factory even when the app does not need live
# partial rendering. For a streaming UI, replace this with an observer that
# persists/broadcasts selected ReplyObserver callbacks (and throttle writes).
class NoopReplyObserver
  include Opencode::ReplyObserver

  def watch(reply)
    reply.add_observer(self)
    self
  end
end

# app/jobs/generate_response_job.rb
class GenerateResponseJob < ApplicationJob
  def perform(assistant_message, user_message)
    conversation = assistant_message.conversation
    unless user_message.conversation_id == conversation.id
      raise ArgumentError, "User and assistant messages must belong to the same conversation"
    end
    sandbox_directory = sandbox_directory_for(conversation)
    client = Opencode::Client.new(
      base_url: ENV.fetch("OPENCODE_URL"),
      directory: sandbox_directory.to_s
    )

    session = Opencode::Session.new(
      conversation,
      permissions_for: ->(record) { permission_rules_for(record) },
      on_error:        ->(e, **opts) { Opencode::ErrorReporter.report(e, **opts) }
    )

    Opencode::Turn.new(
      message:        assistant_message,
      subject:        conversation,
      query_text:     user_message.content,
      client:         client,
      session_for:    session,
      observer_factory: ->(_message) { NoopReplyObserver.new },
      system_context: ->(record) { "You are assisting with #{record.title}." },
      agent_name:     ->(_record) { ENV.fetch("OPENCODE_AGENT", "build") },
      tracer:         ->(name, **payload) {
        ActiveSupport::Notifications.instrument("assistant.#{name}", payload)
      },
      on_turn_finished: ->(result) {
        # result.status   #=> :completed | :cancelled | :error | :failed
        # result.message  #=> the AR row (reloaded)
        # result.duration_ms
      }
    ).call
  end

  private

  def permission_rules_for(_conversation)
    [
      { permission: "*", pattern: "*", action: "deny" }
    ]
  end

  def sandbox_directory_for(conversation)
    identifier = conversation.id.to_s
    unless identifier.match?(/\A[0-9A-Za-z_-]+\z/)
      raise ArgumentError, "Conversation id is not safe for a directory name"
    end

    root = Pathname.new(ENV.fetch("OPENCODE_SANDBOX_ROOT")).expand_path
    root.mkpath
    root = root.realpath
    if root.ascend.any? { |directory| directory.join(".git").exist? }
      raise ArgumentError, "OPENCODE_SANDBOX_ROOT must be outside every Git worktree"
    end

    directory = root.join(identifier)
    directory.mkpath
    stat = directory.lstat
    unless stat.directory? && !stat.symlink?
      raise ArgumentError, "Conversation sandbox must be a real directory"
    end

    resolved = directory.realpath
    unless resolved.to_s.start_with?("#{root}#{File::SEPARATOR}")
      raise ArgumentError, "Conversation sandbox escapes its root"
    end
    resolved
  end
end

OPENCODE_SANDBOX_ROOT must be outside every Git worktree and mounted at the same absolute path in the OpenCode server. OpenCode treats an entire detected worktree as internal, so a directory inside the application repository is not an external_directory boundary. This quickstart intentionally grants no filesystem tools: OpenCode permissions alone are not an OS sandbox. Add product-specific allows only when the OpenCode process also has an independent container or operating-system boundary around the conversation directory.

Opencode::Session applies permissions only when it creates a session. Before deploying a directory or permission-policy change, recreate persisted sessions with a client scoped to the new directory; an existing session ID does not prove that the new policy was applied.

The host record (here conversation) must respond to #title, #opencode_session_id, #opencode_session_id=, #with_lock(&block), #update!, #reload, and #id. The assistant message must respond to #id, #reload, #cancelled?, #finalize!(**attrs), #update!(**attrs), and #error!(content). A non-no-op observer may impose additional record methods for its own live snapshots.

Opencode::Turn is an internal, alpha-stage composition seam. Its keyword constructor is intentionally explicit and may change before 1.0, so keep this wiring in one host service/job and keep the gem source pinned exactly.

What you get

Constant	Role
Opencode::Session	Idempotent ensure!/recreate!/abort! with row-level locking
Opencode::Turn	End-to-end orchestrator: ensure session → send → stream → recover → finalize
Opencode::Exchange	Domain object over a turn's message array; owns artifact extraction
Opencode::Artifact	Value object: filename + bytes + content_type + trust metadata
Opencode::MessageArtifacts	Idempotent attachment pipeline (ActiveStorage-aware, transform-applying)
Opencode::Sandbox	Reads written files from disk, returns Artifact list
Opencode::SandboxFile	Single-file value: pathname → bytes/content-type/identity Artifact
Opencode::Transform	Base class for content-rewriting transforms (e.g. host-rendered HTML)
Opencode::Impostor	ActiveStorage download/upload helper that round-trips bytes
Opencode::UploadedFilesPrompt	Builds the user-prompt prefix listing uploaded files
Opencode::ToolDisplay	View-model converting tool-call hashes to Turbo-friendly props
Opencode::ErrorReporter	Pluggable adapter for routing swallowed errors

Plus everything from opencode-ruby: Client, Reply, ReplyObserver, Tracer, Prompts, ResponseParser, ToolPart, PartSource, Todo, Instrumentation, the error hierarchy.

Instrumentation + error reporting

The wire client emits opencode.request and artifact extraction emits opencode.apply_patch.artifacts_dropped through Opencode::Instrumentation. Turn events flow through the injected tracer; with the Quickstart's assistant. prefix they include:

• assistant.response.started, assistant.turn.finished
• assistant.stream.completed, assistant.stream.interrupted
• assistant.session.created, assistant.session.recreated_with_resend
• assistant.response.upstream_error

Swallowed errors flow through Opencode::ErrorReporter.report(error, **opts). Instrumentation and error reporting are no-ops until the host wires adapters.

Position

opencode-rails is for Rails apps that want production-grade OpenCode streaming without reimplementing the orchestration boilerplate. If you want only the wire client, use opencode-ruby directly. If you want every endpoint with generated types, use opencode_client (Eric Guo's auto-generated gem).

License

MIT. See LICENSE.