Same pattern as opencode-ruby's CI. Workflow runs test suite + gem
build + post-install smoke load on Ruby 3.2 / 3.3 / 3.4.
Note: the 'Verify gem loads after install' step depends on
opencode-ruby being resolvable. Once both gems are on rubygems.org
the runtime_dependency resolves automatically; until then, contributors
who want to run the full workflow locally need to either install
opencode-ruby first or rely on the existing 'bundle exec rake test'
step (which uses the Gemfile-resolved dep, not the gem-spec-resolved
one).
Tobi T6: the README quickstart is too thin to be the only example.
A real integration touches initializer wiring, the job orchestrator,
the ReplyObserver implementation, and the permission rules builder.
Single file, ~180 lines including comments, four labeled sections:
1. config/initializers/opencode.rb adapters for both gems
2. app/jobs/generate_response_job.rb the orchestrator job
3. app/services/reply_stream.rb ReplyObserver -> Turbo Stream
4. permissions_for / build_system_context per-product overrides
NOT loaded by the gem at runtime (the gemspec includes it via Dir.glob
but lib/opencode-rails.rb doesn't require it). Pure reference. Drop in,
adapt to your domain, ship.
Pattern extracted from a production multi-product Rails app
(ajent-rails) running Blackline / Raven / AIGL. Every line maps to
code that runs in production today.
Paired-release commit that completes the .notify migration started in
opencode-ruby v0.0.1.alpha2.
Changes:
- lib/opencode/exchange.rb: drops the empty '{ }' block from the
apply_patch.artifacts_dropped emission, switching from
.instrument(...) { } to .notify(...). Identical wire semantics,
cleaner read at the call site.
- opencode-rails.gemspec: pins opencode-ruby runtime dep to
'= 0.0.1.alpha2' (was alpha1). Lockstep versions during alpha.
- lib/opencode/rails_version.rb: 0.0.1.alpha1 -> 0.0.1.alpha2.
- CHANGELOG: documents the Exchange call-site change and the
opencode-ruby pin bump.
53 tests pass, 134 assertions, 0 failures.
Sandi S2 (smoke coverage was 4/12) + Tobi T7 (adapter exception path
untested) consensus actions. 38 new tests across 9 files take total
from 15 -> 53 tests, 50 -> 134 assertions.
Per-class breakdown:
session_test.rb (2 tests)
Contract on initialize parameters (positional record + keyword
callables) and public surface (ensure!/recreate!/abort!/just_created?).
AR fixtures stay in the host suite.
turn_test.rb (4 tests)
Required + optional keyword arg contracts (locks the 9 required
+ 8 optional keys against drift). Public surface = [:call] only.
Result struct exercised as a value object with status predicates
and cost/token delegation.
message_artifacts_test.rb (2 tests)
Contract on initialize parameters; public surface = [:attach_from].
impostor_test.rb (3 tests)
Initialize keyword contract; delegation to ActiveStorage attachment
via a Struct double on #filename.
sandbox_test.rb (5 tests)
Real tmpdir instantiation: #path / #exists? / #files (Enumerator
when block-less, yields SandboxFile values when files present) /
#file lookup-by-basename returns nil for missing.
sandbox_file_test.rb (4 tests)
Real tmpdir + file: basic readers, marcel-backed content_type
detection, #safe? size-cap rejection, #as_artifact identity
conversion returns Opencode::Artifact.
transform_test.rb (8 tests)
Documents the abstract contract (source_filename / destination_filename /
render all raise NotImplementedError). A trivial concrete subclass
inside the test exercises the default implementations of
#applies_to?, #trusted?, #owned_filenames, and #purge_impostors?
that delegate to the two abstract filename methods.
tool_display_test.rb (5 tests)
Known tool canonicalization, status predicates (running/completed/
errored/in_flight/terminal), unknown-tool fallback, nil-part
tolerance (callers sometimes pass non-tool parts_json entries).
uploaded_files_prompt_test.rb (3 tests)
Initialize keyword contract; #text returns raw content + empty
sandbox_file_names map when no files attached; public surface check.
Plus 2 new tests in error_reporter_test.rb (C4):
- test_adapter_exceptions_propagate: adapter that raises must
propagate, not silently swallow — operators need to know the
error tracker is broken.
- test_report_returns_adapter_return_value: report passes through
the adapter's return value verbatim (Rails.error.report returns
the error itself; callers can chain).
Faithful to actual implementations: every test was first written from
the API I expected, then corrected against the class internals when
errors surfaced. The corrections themselves document the contract:
SandboxFile expects a String sandbox_prefix with trailing separator
(not a Pathname), Transform's filename methods are abstract not
nil-defaulting, etc.
Three tightly-coupled cleanups from the Tobi+Sandi review:
1. Rename lib/opencode/rails/version.rb -> lib/opencode/rails_version.rb
(Sandi S1: file path was lying about its contents — the file defines
Opencode::RAILS_VERSION, NOT Opencode::Rails::VERSION). Updated the
require_relative in opencode-rails.gemspec and lib/opencode-rails.rb
to match. Removed the now-empty lib/opencode/rails/ directory.
2. Drop the 'if File.exist?(...) gem opencode-ruby, path: ...' Gemfile
conditional (Tobi T2 / Sandi S4: Bundler behavior must not depend on
filesystem state). The dev-time sibling-repo override is now
documented in CONTRIBUTING.md as the standard 'bundle config
local.opencode-ruby <path>' pattern, which is what Bundler ships
for this use case.
3. Tighten opencode-ruby runtime dep from '~> 0.0.1.alpha1' to
'= 0.0.1.alpha1' (Tobi T1: ~> during alpha is aspirational; pin
exactly until the public API stabilizes).
Same commit also switches all forward-looking URLs (gemspec homepage,
metadata, README link to opencode-ruby) from Gitea to GitHub since the
gems will eventually publish there. Functional 'git:' URL in
ajent-rails' Gemfile stays on Gitea — that's where the gems actually
are right now; ajent-rails Gemfile flips to GitHub when the user does
the actual remote setup.
Test assertion in loading_test was tightened to match either an
installed-gem path ('gems/opencode-X-VERSION/') or a sibling-repo
checkout ('/opencode-X/'), via a small GEM_PATH_PATTERN helper.
15 tests, 50 assertions, 0 failures.
Critical fix: defining Opencode::Rails as a module shadowed ::Rails
under Ruby's constant lookup whenever host code referenced top-level
Rails.something from inside the Opencode:: namespace.
Caught when host code in lib/opencode/containers/container.rb failed
to boot:
/workspaces/app/lib/opencode/containers/container.rb:433:
undefined method 'root' for module Opencode::Rails (NoMethodError)
"notes.md" => Rails.root.join(...)
Ruby resolved 'Rails' to 'Opencode::Rails' first (the gem's version
namespace) before falling back to ::Rails. The fix removes the
intermediate module entirely:
module Opencode
RAILS_VERSION = "0.0.1.alpha1"
end
Added a regression test (test_no_opencode_rails_module) so the
shadowing never sneaks back in. opencode-ruby uses Opencode::VERSION
for its own gem version; we can't double-up on that constant, so this
gem uses RAILS_VERSION as a sibling on the same Opencode module.
README (~140 LOC):
- Why this gem exists (4 production needs opencode-ruby alone doesn't cover)
- Install + quickstart (showing GenerateResponseJob wiring Session + Turn)
- 12-constant API table with one-line role descriptions
- Instrumentation + error-reporting adapter setup snippets
- Position against opencode-ruby and Eric Guo's opencode_client
CHANGELOG documents what shipped, runtime deps, and known limitations
(apply_patch artifact drop, gem-side behavioral tests TBD, no Rails
generator yet). LICENSE was auto-generated by Gitea (MIT, 2026
ajaynomics) and is unchanged.
Eleven source files moved from ajent-rails:lib/opencode/rails/ to
opencode-rails:lib/opencode/ (flat layout — modules are Opencode::*, not
Opencode::Rails::*; matches opencode-ruby).
artifact.rb 63 LOC
exchange.rb 77 LOC
impostor.rb 48 LOC
message_artifacts.rb 133 LOC
sandbox_file.rb 81 LOC
sandbox.rb 71 LOC
session.rb 168 LOC
tool_display.rb 423 LOC
transform.rb 77 LOC
turn.rb 642 LOC
uploaded_files_prompt.rb 85 LOC
----
total 1,868 LOC
Surgical Rails strips:
exchange.rb:
Rails.event.notify(name, payload)
-> Opencode::Instrumentation.instrument(name, payload) { }
message_artifacts.rb (1 call), turn.rb (6 calls):
Rails.error.report(error, **opts)
-> Opencode::ErrorReporter.report(error, **opts)
Comments/docstrings referencing Rails.error.report / Rails.event left
in place — they document how to wire the host adapter.
ActiveSupport core_ext requires expanded in lib/opencode-rails.rb to
cover Numeric#seconds, Hash#deep_stringify_keys, String#squish/truncate,
String#demodulize. Bundle install + smoke load confirms all 12
gem-provided constants resolve cleanly.
Per the same pattern as Opencode::Instrumentation in opencode-ruby:
zero-dependency default (no-op), host plugs an adapter in to route
errors to Rails.error / Honeybadger / Sentry / etc.
Used by Session, Turn, MessageArtifacts (ported in the next commit) to
report swallowed exceptions and degraded paths without coupling the
gem to any specific error-tracking library.
# config/initializers/opencode.rb
Opencode::ErrorReporter.adapter = ->(error, **opts) {
Rails.error.report(error, **opts)
}
- opencode-rails.gemspec (Ruby >= 3.2, MIT)
- runtime: opencode-ruby ~> 0.0.1.alpha1
- runtime: activerecord/activestorage/activesupport >= 7.1, < 9.0
Per-sublibrary deps (not the rails umbrella) so host apps don't
pull in ActionMailer/ActionCable/ActionView just to use this gem.
- lib/opencode-rails.rb (umbrella; requires opencode-ruby then leaves
then session/turn)
- lib/opencode/rails/version.rb (Opencode::Rails::VERSION = 0.0.1.alpha1)
- Gemfile (sibling-path pull of opencode-ruby for local dev)
- Rakefile, .gitignore
Source files will be ported in the next commit.
