rails-agent-stack 0.1.1

data/lib/rails_agents/open_wire_adapter.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "open_wire"
+
+module RailsAgents
+  # Open-Wire channel adapter — thin wrapper so agents don't talk HTTP directly.
+  module OpenWireAdapter
+    module_function
+
+    def client(base_url: nil, api_key: nil)
+      ::OpenWire::Client.new(base_url: base_url, api_key: api_key)
+    end
+
+    def verify_inbound!(secret:, body:, headers:)
+      ::OpenWire::Webhook.verify_and_parse!(
+        secret: secret,
+        body: body,
+        headers: headers
+      )
+    end
+
+    def reply!(installation_id:, to:, text:, thread_id: nil, client: nil)
+      (client || self.client).send_message(
+        installation_id: installation_id,
+        to: to,
+        text: text,
+        thread_id: thread_id
+      )
+    end
+  end
+end

data/lib/rails_agents/operations_agent.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module RailsAgents
+  # Coordinates unpredictable real-world work across people, tools, and changing conditions.
+  class OperationsAgent < Base
+    def self.agent_kind
+      :operations
+    end
+  end
+end

data/lib/rails_agents/railtie.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module RailsAgents
+  class Railtie < Rails::Railtie
+    rake_tasks do
+      load "rails_agents/tasks.rake"
+    end
+
+    generators do
+      require "generators/rails_agents/install/install_generator"
+      require "generators/rails_agents/agent/agent_generator"
+    end
+  end
+end

data/lib/rails_agents/tasks.rake

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+namespace :rails_agents do
+  desc "Install Rails Agents (alias for rails g rails_agents:install)"
+  task install: :environment do
+    sh "bin/rails generate rails_agents:install"
+  end
+end

data/lib/rails_agents/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RailsAgents
+  VERSION = "0.1.1"
+end

data/lib/rails_agents/workflow_agent.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module RailsAgents
+  # Multi-step orchestration agents (onboarding, lead qualification, pipelines).
+  # Prefer a stable +session_id+ so each step continues the same run context.
+  class WorkflowAgent < Base
+    def self.agent_kind
+      :workflow
+    end
+  end
+end

data/lib/rails_agents.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "rails_agents/version"
+require "rails_agents/configuration"
+require "rails_agents/client"
+require "rails_agents/credentials_writer"
+require "rails_agents/local_auth"
+require "rails_agents/local_sync"
+require "rails_agents/library_imports"
+require "rails_agents/base"
+require "rails_agents/knowledge_agent"
+require "rails_agents/creation_agent"
+require "rails_agents/workflow_agent"
+require "rails_agents/operations_agent"
+require "rails_agents/monitoring_agent"
+require "rails_agents/chat_agent"
+require "rails_agents/background_agent"
+require "rails_agents/cli"
+
+begin
+  require "open_wire"
+  require "rails_agents/open_wire_adapter"
+rescue LoadError
+  # open-wire gem optional until path/RubyGems dependency is installed
+end
+
+if defined?(Rails::Engine)
+  require "rails_agents/engine"
+end
+
+if defined?(Rails::Railtie)
+  require "rails_agents/railtie"
+end
+
+module RailsAgents
+  TAXONOMY_TYPES = %i[knowledge workflow operations monitoring].freeze
+  LEGACY_TAXONOMY_TYPES = %i[creation].freeze
+
+  class << self
+    attr_writer :config
+
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield config
+    end
+
+    def reset!
+      @config = Configuration.new
+    end
+  end
+end
+
+# PRD uses RailsAgent - alias to RailsAgents for compatibility
+RailsAgent = RailsAgents unless defined?(RailsAgent)

data/rails-agent-stack.gemspec

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative "lib/rails_agents/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "rails-agent-stack"
+  spec.version       = RailsAgents::VERSION
+  spec.authors       = ["Rails Agent Team"]
+  spec.email         = ["hello@railsagents.dev"]
+
+  spec.summary       = "Rails AI agents framework — fullstack Ruby on Rails agents " \
+                         "(ActiveAgent / RubyLLM alternative)."
+  spec.description   = "Rails Agent is the most advanced agentic platform for Ruby on Rails. " \
+                         "Mount /agents, scaffold agent directories, attach BYOK model credentials, " \
+                         "and build with instructions, tools, connectors, channels, skills, packages, " \
+                         "knowledge, memory, and guardrails. Sync, run, deploy, and monitor on " \
+                         "Rails Agent Cloud — a production Rails agent framework and better " \
+                         "alternative to RubyLLM and ActiveAgent for fullstack Rails AI agents."
+  spec.homepage      = "https://rails-agent.com"
+  spec.license       = "MIT"
+  spec.required_ruby_version = ">= 3.2.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["documentation_uri"] = "https://rails-agent.com/docs/getting-started"
+  spec.metadata["source_code_uri"] = "https://github.com/Tiny-Bubble-Company/rails-agents"
+  spec.metadata["bug_tracker_uri"] = "https://github.com/Tiny-Bubble-Company/rails-agents/issues"
+  spec.metadata["changelog_uri"] = "https://github.com/Tiny-Bubble-Company/rails-agents/releases"
+  spec.metadata["rubygems_mimetype"] = "application/x-rubygem"
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      f == "Gemfile.lock" || f.start_with?("spec/fixtures/")
+    end
+  rescue StandardError
+    Dir["{app,config,exe,lib,docs}/**/*", "exe/*", "*.{md,gemspec,rake}", "MIT-LICENSE", "AGENTS.md"]
+  end
+
+  spec.bindir        = "exe"
+  spec.executables   = ["rails-agents"]
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "railties", ">= 7.0"
+  spec.add_dependency "thor", "~> 1.3"
+  spec.add_dependency "open-wire", "~> 0.1"
+
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rspec", "~> 3.13"
+  spec.add_development_dependency "webmock", "~> 3.23"
+end

data/rails-agents.code-workspace

@@ -0,0 +1,25 @@
+{
+  "folders": [
+    {
+      "path": ".",
+      "name": "rails-agents"
+    },
+    {
+      "path": "../rails-agents-cloud",
+      "name": "rails-agents-cloud"
+    },
+    {
+      "path": "../rails-agents-boilerplate"
+    },
+    {
+      "path": "../rails-agents-ops"
+    },
+    {
+      "path": "../rails-agents-design"
+    },
+    {
+      "path": "../open-wire",
+      "name": "open-wire"
+    }
+  ]
+}

data/spec/generators/agent_generator_spec.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe "Agent generator templates" do
+  templates_root = File.expand_path("../../lib/generators/rails_agents/agent/templates", __dir__)
+
+  it "default agent template uses BYOK model DSL and taxonomy base class" do
+    content = File.read(File.join(templates_root, "agent.rb.tt"))
+    expect(content).to include("<%= agent_base_class %>")
+    expect(content).to include("credential: :company_openai")
+    expect(content).not_to include("model :auto")
+  end
+
+  it "database template scaffolds KnowledgeAgent with order and product tools" do
+    content = File.read(File.join(templates_root, "agent_database.rb.tt"))
+    expect(content).to include("KnowledgeAgent")
+    expect(content).to include("lookup_order")
+    expect(content).to include("search_products")
+    expect(content).to include("Order.find_by")
+    expect(content).to include("Product.where")
+  end
+
+  it "database prompt documents demo orders and BYOK" do
+    content = File.read(File.join(templates_root, "prompt_database.md.tt"))
+    expect(content).to include("ORD-DEMO-1001")
+    expect(content).to include("BYOK")
+  end
+
+  it "scaffolds an explicit workspace Library imports manifest" do
+    content = File.read(File.join(templates_root, "imports.yml.tt"))
+
+    expect(content).to include("imports: []")
+    expect(content).to include("library/skills/triage.rb")
+  end
+end

data/spec/rails_agents/base_spec.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "fileutils"
+require "pathname"
+require "tmpdir"
+
+RSpec.describe RailsAgents::Base do
+  let(:agent_dir) { Pathname.new(Dir.mktmpdir("agent")) }
+
+  after do
+    FileUtils.rm_rf(agent_dir)
+  end
+
+  let(:support_agent) do
+    Class.new(described_class) do
+      model :gpt_5_mini, provider: :openai, credential: :company_openai
+      memory :conversation, provider: :mem0, recall: 5
+      knowledge_from "knowledge/**/*"
+
+      tool :lookup_order do |order_id:|
+        { id: order_id, status: "shipped" }
+      end
+
+      skill :triage, from: "skills/triage.rb"
+      channel :slack
+    end.tap do |klass|
+      klass.instance_variable_set(:@agent_directory, agent_dir)
+    end
+  end
+
+  let(:client) { instance_double(RailsAgents::Client) }
+
+  before do
+    FileUtils.mkdir_p(agent_dir.join("knowledge"))
+    File.write(agent_dir.join("knowledge/faq.md"), "# FAQ")
+  end
+
+  it "stores DSL configuration on the class" do
+    expect(support_agent.model_setting).to eq(:gpt_5_mini)
+    expect(support_agent.model_provider).to eq(:openai)
+    expect(support_agent.model_credential).to eq(:company_openai)
+    expect(support_agent.memory_setting).to eq(:conversation)
+    expect(support_agent.memory_provider).to eq(:mem0)
+    expect(support_agent.memory_recall).to eq(5)
+    expect(support_agent.knowledge_glob).to eq("knowledge/**/*")
+    expect(support_agent.tool_definitions.keys).to include(:lookup_order)
+    expect(support_agent.skill_definitions[:triage]).to eq("skills/triage.rb")
+    expect(support_agent.channel_definitions).to include(:slack)
+  end
+
+  it "supports legacy model :auto without provider metadata" do
+    legacy = Class.new(described_class) { model :auto }
+    instance = legacy.new(client: client)
+    allow(client).to receive(:create_run).and_return({ "id" => "run_1" })
+
+    legacy.new(client: client).run("Hi")
+
+    expect(client).to have_received(:create_run).with(
+      hash_including(metadata: hash_including(model: :auto, kind: :base))
+    )
+  end
+
+  it "supports keyword trigger inputs like order_id:" do
+    allow(client).to receive(:create_run).and_return({ "id" => "run_kw" })
+
+    support_agent.run(order_id: 1, client: client)
+
+    expect(client).to have_received(:create_run).with(
+      hash_including(message: "order_id: 1")
+    )
+  end
+
+  it "rejects mixing a message string with keyword inputs" do
+    expect {
+      support_agent.run("hello", order_id: 1, client: client)
+    }.to raise_error(ArgumentError, /either a message string or keyword/)
+  end
+
+  it "executes tool blocks" do
+    result = support_agent.tool_definitions[:lookup_order].call(order_id: 42)
+    expect(result[:status]).to eq("shipped")
+  end
+
+  it "collects knowledge paths relative to agent directory" do
+    agent = support_agent.new(client: client)
+    expect(agent.knowledge_paths).to eq(["knowledge/faq.md"])
+  end
+
+  it "includes kind and structured model in run metadata" do
+    allow(client).to receive(:create_run).and_return({ "id" => "run_abc" })
+
+    support_agent.new(client: client).run("Hello", session_id: "sess_1")
+
+    expect(client).to have_received(:create_run).with(
+      hash_including(
+        agent: agent_dir.basename.to_s,
+        message: "Hello",
+        session_id: "sess_1",
+        metadata: hash_including(
+          kind: :base,
+          model: {
+            name: :gpt_5_mini,
+            provider: :openai,
+            credential: :company_openai
+          },
+          memory: {
+            type: :conversation,
+            provider: :mem0,
+            recall: 5
+          }
+        )
+      )
+    )
+  end
+
+  it "creates a run via the cloud client" do
+    allow(client).to receive(:create_run).and_return({ "id" => "run_abc" })
+
+    result = support_agent.new(client: client).run("Hello", session_id: "sess_1")
+
+    expect(result.run_id).to eq("run_abc")
+  end
+
+  it "deploys via the cloud client" do
+    allow(client).to receive(:deploy).and_return({ "id" => "dep_1" })
+
+    response = support_agent.new(client: client).deploy
+
+    expect(client).to have_received(:deploy).with(
+      agent: agent_dir.basename.to_s,
+      bundle_path: agent_dir.to_s
+    )
+    expect(response["id"]).to eq("dep_1")
+  end
+
+  it "syncs knowledge via the cloud client" do
+    allow(client).to receive(:sync_knowledge).and_return({ "synced" => 1 })
+
+    support_agent.new(client: client).sync_knowledge
+
+    expect(client).to have_received(:sync_knowledge).with(
+      agent: agent_dir.basename.to_s,
+      paths: ["knowledge/faq.md"]
+    )
+  end
+
+  it "streams run output" do
+    allow(client).to receive(:create_run).and_return({ "id" => "run_1" })
+    allow(client).to receive(:stream_run).and_yield({ "content" => "Hi" }).and_yield({ "content" => " there" })
+
+    result = support_agent.run("Hello", client: client)
+    expect(result.output).to eq("Hi there")
+  end
+
+  it "prefers done output_text over token chunks when draining stream" do
+    allow(client).to receive(:create_run).and_return({ "id" => "run_3" })
+    allow(client).to receive(:stream_run)
+      .and_yield({ "content" => "partial" })
+      .and_yield({
+        "output_text" => "Final markdown",
+        "output" => "Final markdown",
+        "format" => "markdown",
+        "items" => [],
+        "status" => "succeeded"
+      })
+
+    result = support_agent.run("Hello", client: client)
+    expect(result.output).to eq("Final markdown")
+  end
+
+  it "exposes Eve-aligned output_text / items from sync create_run" do
+    allow(client).to receive(:create_run).and_return({
+      "object" => "run",
+      "data" => {
+        "id" => "run_2",
+        "output" => "| Name | Qty |\n| --- | --- |\n| Tee | 2 |",
+        "output_text" => "| Name | Qty |\n| --- | --- |\n| Tee | 2 |",
+        "output_data" => nil,
+        "items" => [
+          {
+            "type" => "message",
+            "role" => "assistant",
+            "content" => "| Name | Qty |\n| --- | --- |\n| Tee | 2 |",
+            "format" => "markdown"
+          }
+        ],
+        "format" => "markdown",
+        "status" => "succeeded"
+      }
+    })
+
+    result = support_agent.run("List products", client: client)
+    expect(result.run_id).to eq("run_2")
+    expect(result.output_text).to include("Tee")
+    expect(result.output).to eq(result.output_text)
+    expect(result.format).to eq("markdown")
+    expect(result.items.first["type"]).to eq("message")
+    expect(result.output_data).to be_nil
+    expect(result.status).to eq("succeeded")
+  end
+end

data/spec/rails_agents/client_spec.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe RailsAgents::Client do
+  let(:config) do
+    RailsAgents.config.tap do |c|
+      c.api_key = "test-key"
+      c.api_base = "https://cloud.rails-agent.com"
+      c.project_id = "proj_123"
+    end
+  end
+
+  subject(:client) { described_class.new(config: config) }
+
+  describe "#create_run" do
+    it "POSTs to /api/v1/runs with auth" do
+      stub_request(:post, "https://cloud.rails-agent.com/api/v1/runs")
+        .with(
+          headers: { "Authorization" => "Bearer test-key" },
+          body: hash_including("agent" => "support", "message" => "Hello")
+        )
+        .to_return(status: 200, body: { id: "run_1" }.to_json, headers: { "Content-Type" => "application/json" })
+
+      response = client.create_run(agent: "support", message: "Hello")
+      expect(response["id"]).to eq("run_1")
+    end
+
+    it "extracts nested API error messages" do
+      stub_request(:post, "https://cloud.rails-agent.com/api/v1/runs")
+        .to_return(
+          status: 401,
+          body: { error: { message: "Invalid API key" } }.to_json,
+          headers: { "Content-Type" => "application/json" }
+        )
+
+      expect do
+        client.create_run(agent: "support", message: "Hello")
+      end.to raise_error(RailsAgents::Client::Error, "Invalid API key")
+    end
+  end
+
+  describe "#deploy" do
+    it "POSTs to /api/v1/deploys" do
+      stub_request(:post, "https://cloud.rails-agent.com/api/v1/deploys")
+        .to_return(status: 200, body: { id: "dep_1", status: "queued" }.to_json)
+
+      response = client.deploy(agent: "support")
+      expect(response["status"]).to eq("queued")
+    end
+  end
+
+  describe "#install_channel" do
+    it "POSTs to /api/v1/channels/:kind/install" do
+      stub_request(:post, "https://cloud.rails-agent.com/api/v1/channels/slack/install")
+        .to_return(status: 200, body: { url: "https://oauth.example" }.to_json)
+
+      response = client.install_channel(kind: "slack")
+      expect(response["url"]).to include("oauth")
+    end
+  end
+
+  describe "#sync_knowledge" do
+    it "POSTs to /api/v1/knowledge/sync" do
+      stub_request(:post, "https://cloud.rails-agent.com/api/v1/knowledge/sync")
+        .to_return(status: 200, body: { synced: 2 }.to_json)
+
+      response = client.sync_knowledge(agent: "support", paths: %w[faq.md])
+      expect(response["synced"]).to eq(2)
+    end
+  end
+
+  describe "#sync_files" do
+    it "PUTs to /api/v1/agents/:id/files" do
+      stub_request(:put, "https://cloud.rails-agent.com/api/v1/agents/support/files")
+        .with(body: hash_including("files" => kind_of(Array)))
+        .to_return(status: 200, body: { data: [] }.to_json)
+
+      response = client.sync_files(agent: "support", files: [{ "path" => "app/agents/support/agent.rb", "content" => "class Support; end" }])
+      expect(response["data"]).to eq([])
+    end
+  end
+
+  describe "#handshake" do
+    it "POSTs to /api/v1/auth/handshake without bearer" do
+      stub_request(:post, "https://cloud.rails-agent.com/api/v1/auth/handshake")
+        .with { |req| !req.headers["Authorization"] }
+        .to_return(status: 201, body: { data: { api_key: "ra_x" } }.to_json)
+
+      response = client.handshake(email: "a@b.com", password: "password1")
+      expect(response.dig("data", "api_key")).to eq("ra_x")
+    end
+  end
+
+  describe "#logs" do
+    it "GETs /api/v1/logs" do
+      stub_request(:get, %r{https://cloud.rails-agent.com/api/v1/logs})
+        .to_return(status: 200, body: { entries: [] }.to_json)
+
+      expect(client.logs(agent: "support")["entries"]).to eq([])
+    end
+  end
+
+  describe "#traces" do
+    it "GETs /api/v1/traces" do
+      stub_request(:get, %r{https://cloud.rails-agent.com/api/v1/traces})
+        .to_return(status: 200, body: { traces: [] }.to_json)
+
+      expect(client.traces["traces"]).to eq([])
+    end
+  end
+
+  describe "#evals" do
+    it "GETs /api/v1/evals" do
+      stub_request(:get, %r{https://cloud.rails-agent.com/api/v1/evals})
+        .to_return(status: 200, body: { evals: [] }.to_json)
+
+      expect(client.evals["evals"]).to eq([])
+    end
+  end
+end

data/spec/rails_agents/configuration_spec.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe RailsAgents::Configuration do
+  subject(:config) { described_class.new }
+
+  it "defaults api_base to cloud.rails-agent.com" do
+    expect(config.api_base).to eq("https://cloud.rails-agent.com")
+  end
+
+  it "defaults dashboard_base to cloud.rails-agent.com" do
+    expect(config.dashboard_base).to eq("https://cloud.rails-agent.com")
+  end
+
+  it "builds api_v1_base under /api/v1" do
+    expect(config.api_v1_base).to eq("https://cloud.rails-agent.com/api/v1")
+  end
+
+  it "reads api_key from ENV" do
+    with_env("RAILS_AGENTS_API_KEY" => "test-key") do
+      expect(described_class.new.api_key).to eq("test-key")
+    end
+  end
+
+  it "reads project_id from ENV" do
+    with_env("RAILS_AGENTS_PROJECT_ID" => "prj_test") do
+      expect(described_class.new.project_id).to eq("prj_test")
+    end
+  end
+
+  it "ignores RAILS_AGENTS_API_BASE env (cloud host is fixed)" do
+    with_env("RAILS_AGENTS_API_BASE" => "https://example.invalid") do
+      expect(described_class.new.api_base).to eq("https://cloud.rails-agent.com")
+    end
+  end
+
+  it "reports configured when api_key is present" do
+    config.api_key = "abc"
+    expect(config).to be_configured
+  end
+
+  it "reports not configured when api_key is blank" do
+    config.api_key = ""
+    expect(config).not_to be_configured
+  end
+
+  def with_env(vars)
+    old = vars.keys.to_h { |k| [k, ENV[k]] }
+    vars.each { |k, v| ENV[k] = v }
+    yield
+  ensure
+    old.each { |k, v| v.nil? ? ENV.delete(k) : ENV[k] = v }
+  end
+end