Initial public release v0.0.1.alpha2

opencode-rails — production-grade Rails integration for OpenCode.

Rails companion to opencode-ruby. ActiveRecord-aware session lifecycle
(idempotent ensure!/recreate!/abort! with row-level locks), a Turn
orchestrator driving the Reply state machine and recovering from
session-not-found, an artifact pipeline backed by ActiveStorage,
sandbox seeding, and tool-display value objects for Turbo Stream
broadcasts. Drop into any Rails 7.1+ app that wants production-grade
OpenCode streaming without rolling boilerplate.

What this version ships:
  - Opencode::Session (AR-coupled lifecycle, row-level locks)
  - Opencode::Turn (Reply state machine, session-not-found recovery)
  - Opencode::Exchange (one turn = one request/response unit)
  - Opencode::Impostor (deterministic mock for tests)
  - Opencode::Sandbox / SandboxFile (per-session FS scratch space)
  - Opencode::Transform (host-rendered artifact pipeline)
  - Opencode::Artifact / MessageArtifacts (ActiveStorage-backed)
  - Opencode::UploadedFilesPrompt (system-prompt builder)
  - Opencode::ToolDisplay (Turbo Stream value objects)
  - Opencode::ErrorReporter (pluggable adapter — Honeybadger/Sentry/etc.)
  - examples/rails_integration.rb — canonical wiring blueprint

53 smoke tests. CI on Ruby 3.2/3.3/3.4.

Ruby >= 3.2. Runtime deps: opencode-ruby = 0.0.1.alpha2,
activerecord/activestorage/activesupport >= 7.1, < 9.0.

See CHANGELOG.md for the alpha1 -> alpha2 delta.

lib/opencode/message_artifacts.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module Opencode
+  # The collection of new artifacts attached to an assistant message as
+  # a result of one turn. The orchestrator that used to live in
+  # Opencode::ArtifactCollector now lives on this collection — instead
+  # of a "Collector" verb-class, the collection knows how to populate
+  # itself from sources (tool exchange, sandbox) and how to attach.
+  #
+  # Two-line usage:
+  #
+  #   Opencode::MessageArtifacts.new(message: m, feature: "chat", transforms: [])
+  #     .attach_from(exchange: exchange, sandbox: sandbox)
+  #
+  # All four phases (tool extract, transform routing, impostor purge,
+  # default sandbox attach) live as small named methods. The substrate
+  # never special-cases a product — `:feature` is only for error-report
+  # context, and `:transforms` (default []) is per-product policy.
+  #
+  # Idempotent under retry: `Opencode::Artifact#attach_to` already
+  # skips when the filename is present on the message, and the
+  # tool-extracted phase excludes filenames the transforms own.
+  class MessageArtifacts
+    MAX_SANDBOX_ARTIFACTS = 20
+
+    # default_attach values:
+    #   :all  — every safe sandbox file that no transform claims falls
+    #           through to identity attach. Use when the agent's `write`
+    #           outputs are final document bytes the host serves back
+    #           unchanged.
+    #   :none — only transform-claimed files attach; everything else stays
+    #           agent-internal. Use when the agent's sandbox is full of
+    #           working scratch the user shouldn't see, and only specific
+    #           filenames (claimed by transforms) become artifacts.
+    def initialize(message:, feature:, transforms: [], default_attach: :all,
+                   max_sandbox_files: MAX_SANDBOX_ARTIFACTS)
+      @message           = message
+      @feature           = feature
+      @transforms        = transforms
+      @default_attach    = default_attach
+      @max_sandbox_files = max_sandbox_files
+    end
+
+    # Drains both sources and attaches. Returns self so callers can
+    # chain off it if they want to count what landed.
+    def attach_from(exchange: nil, sandbox: nil, cutoff: nil, upload_echo: [])
+      attach_from_exchange(exchange) if exchange
+      attach_from_sandbox(sandbox, cutoff: cutoff, upload_echo: upload_echo) if sandbox
+      self
+    rescue StandardError => e
+      report(e, action: "attach_artifacts")
+      self
+    end
+
+    private
+
+    attr_reader :message, :feature, :transforms, :max_sandbox_files, :default_attach
+
+    # Tool-produced artifacts (write tool's input content). Skip any
+    # filename a transform owns — those land via the sandbox path so the
+    # transform's trust pipeline (render + metadata stamp) is the only
+    # way the bytes reach the user.
+    def attach_from_exchange(exchange)
+      exchange.tool_artifacts(exclude: transform_owned_filenames).each do |artifact|
+        artifact.attach_to(message)
+      end
+    rescue StandardError => e
+      report(e, action: "attach_from_exchange")
+    end
+
+    def attach_from_sandbox(sandbox, cutoff:, upload_echo:)
+      return unless sandbox.exists?
+
+      uploaded = Set.new(upload_echo)
+      attached = 0
+
+      sandbox.files(after: cutoff).each do |file|
+        break if attached >= max_sandbox_files
+        next if uploaded.include?(file.basename)
+
+        if (transform = transforms.find { |t| t.applies_to?(file) })
+          attached += 1 if apply_transform(transform, file)
+        elsif default_attach == :all
+          # Default identity path: every safe sandbox file that no
+          # transform claims attaches as-is. Callers that want the
+          # opposite (only transform-claimed files attach) construct
+          # MessageArtifacts with default_attach: :none.
+          attached += 1 if file.as_artifact.attach_to(message)
+        end
+      end
+    rescue StandardError => e
+      report(e, action: "attach_from_sandbox")
+    end
+
+    # Returns true if a fresh trusted artifact was attached. Falsy on
+    # already-trusted-attached, transform-raised, or duplicate-filename.
+    def apply_transform(transform, file)
+      if transform.purge_impostors?
+        purged = Impostor.for(message: message, transform: transform)
+        if purged.any?
+          purged.each(&:purge!)
+          # ActiveStorage purges the attachment + blob, but `message.artifacts`
+          # holds the pre-purge collection in memory. Without resetting,
+          # Artifact#already_attached_to? still sees the (just-purged) row
+          # and shortcuts the trusted attach below.
+          message.artifacts.reset
+        end
+      end
+      return false if trusted_present?(transform)
+
+      artifact = transform.render(file)
+      artifact.attach_to(message)
+    rescue Transform::Error => e
+      report(e, action: "transform_#{transform.class.name.demodulize}")
+      false
+    end
+
+    def trusted_present?(transform)
+      message.artifacts.any? { |a| transform.trusted?(a) }
+    end
+
+    def transform_owned_filenames
+      transforms.flat_map(&:owned_filenames)
+    end
+
+    def report(error, action:)
+      Opencode::ErrorReporter.report(error, handled: true, severity: :warning,
+        context: { feature: feature, action: action, message_id: message.id })
+    end
+  end
+end