rails-agent-stack 0.1.1

data/lib/rails_agents/client.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module RailsAgents
+  class Client
+    class Error < StandardError
+      attr_reader :status, :body
+
+      def initialize(message, status: nil, body: nil)
+        super(message)
+        @status = status
+        @body = body
+      end
+    end
+
+    def initialize(config: RailsAgents.config)
+      @config = config
+    end
+
+    def create_run(agent:, message:, session_id: nil, metadata: {})
+      post("/runs", {
+        agent: agent,
+        message: message,
+        session_id: session_id,
+        project_id: @config.project_id,
+        metadata: metadata
+      }.compact)
+    end
+
+    def stream_run(run_id, &block)
+      get_stream("/runs/#{run_id}/stream", &block)
+    end
+
+    def deploy(agent:, bundle_path: nil)
+      payload = { agent: agent, project_id: @config.project_id }
+      payload[:bundle_path] = bundle_path if bundle_path
+      post("/deploys", payload)
+    end
+
+    def install_channel(kind:, redirect_url: nil)
+      post("/channels/#{kind}/install", {
+        project_id: @config.project_id,
+        redirect_url: redirect_url
+      }.compact)
+    end
+
+    def sync_knowledge(agent:, paths: [])
+      post("/knowledge/sync", {
+        agent: agent,
+        project_id: @config.project_id,
+        paths: paths
+      })
+    end
+
+    def get_agent(agent:)
+      get("/agents/#{agent}")
+    end
+
+    def sync_files(agent:, files:)
+      put("/agents/#{agent}/files", { files: files })
+    end
+
+    def list_files(agent:)
+      get("/agents/#{agent}/files")
+    end
+
+    def handshake(email:, password:, workspace: nil)
+      post("/auth/handshake", {
+        email: email,
+        password: password,
+        workspace: workspace
+      }.compact, auth: false)
+    end
+
+    def claim_connect(code)
+      post("/auth/connect/claim", { code: code }, auth: false)
+    end
+
+    def email_start(email:, purpose:, name: nil, company: nil)
+      post("/auth/email/start", {
+        email: email,
+        purpose: purpose,
+        name: name,
+        company: company
+      }.compact, auth: false)
+    end
+
+    def email_verify(email:, code:, name: nil, company: nil)
+      post("/auth/email/verify", {
+        email: email,
+        code: code,
+        name: name,
+        company: company
+      }.compact, auth: false)
+    end
+
+    def logs(agent: nil, limit: 50)
+      get("/logs", query: { agent: agent, limit: limit, project_id: @config.project_id }.compact)
+    end
+
+    def traces(agent: nil, limit: 50)
+      get("/traces", query: { agent: agent, limit: limit, project_id: @config.project_id }.compact)
+    end
+
+    def evals(agent: nil)
+      get("/evals", query: { agent: agent, project_id: @config.project_id }.compact)
+    end
+
+    def search_packages(query:, registry: "all", limit: 18)
+      get("/packages", query: { q: query, registry: registry, limit: limit }.compact)
+    end
+
+    def install_package(payload)
+      post("/packages", payload)
+    end
+
+    private
+
+    def get(path, query: {})
+      request(:get, path, query: query)
+    end
+
+    def post(path, body, auth: true)
+      request(:post, path, body: body, auth: auth)
+    end
+
+    def put(path, body, auth: true)
+      request(:put, path, body: body, auth: auth)
+    end
+
+    def request(method, path, body: nil, query: {}, auth: true)
+      uri = build_uri(path, query)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = 10
+      http.read_timeout = 120
+
+      request_class =
+        case method
+        when :get then Net::HTTP::Get
+        when :put then Net::HTTP::Put
+        else Net::HTTP::Post
+        end
+
+      req = request_class.new(uri)
+      req["Accept"] = "application/json"
+      req["Content-Type"] = "application/json"
+      req["Authorization"] = "Bearer #{@config.api_key}" if auth && @config.api_key
+      req.body = JSON.generate(body) if body
+
+      response = http.request(req)
+      parse_response(response)
+    end
+
+    def get_stream(path, &block)
+      uri = build_uri(path)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.read_timeout = nil
+
+      req = Net::HTTP::Get.new(uri)
+      req["Accept"] = "text/event-stream"
+      req["Authorization"] = "Bearer #{@config.api_key}" if @config.api_key
+
+      http.request(req) do |response|
+        raise Error.new("Stream failed", status: response.code.to_i, body: response.body) unless response.is_a?(Net::HTTPOK)
+
+        buffer = +""
+        response.read_body do |chunk|
+          buffer << chunk
+          while (line = buffer.slice!(/.*\n/))
+            line = line.strip
+            next if line.empty? || line.start_with?(":")
+
+            if line.start_with?("data: ")
+              data = line.delete_prefix("data: ")
+              block.call(JSON.parse(data)) if block
+            end
+          end
+        end
+      end
+    end
+
+    def build_uri(path, query = {})
+      base = @config.api_v1_base
+      base = "#{base}/" unless base.end_with?("/")
+      uri = URI.join(base, path.delete_prefix("/"))
+      uri.query = URI.encode_www_form(query) unless query.empty?
+      uri
+    end
+
+    def parse_response(response)
+      body = response.body.to_s
+      parsed = body.empty? ? {} : JSON.parse(body)
+
+      return parsed if response.is_a?(Net::HTTPSuccess)
+
+      message =
+        if parsed.is_a?(Hash)
+          error = parsed["error"]
+          error = error["message"] if error.is_a?(Hash)
+          error || parsed["message"] || "Request failed"
+        else
+          "Request failed"
+        end
+      raise Error.new(message, status: response.code.to_i, body: parsed)
+    rescue JSON::ParserError
+      raise Error.new("Invalid JSON response", status: response.code.to_i, body: body) unless response.is_a?(Net::HTTPSuccess)
+
+      {}
+    end
+  end
+end

data/lib/rails_agents/configuration.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module RailsAgents
+  class Configuration
+    # Always Rails Agent Cloud. Not overridable via ENV.
+    DEFAULT_ORIGIN = "https://cloud.rails-agent.com"
+
+    attr_accessor :api_key, :project_id
+    attr_reader :api_base, :dashboard_base
+
+    def initialize
+      @api_key = ENV["RAILS_AGENTS_API_KEY"]
+      @project_id = ENV["RAILS_AGENTS_PROJECT_ID"]
+      @api_base = DEFAULT_ORIGIN
+      @dashboard_base = DEFAULT_ORIGIN
+    end
+
+    # Kept for tests / rare overrides; production apps should not set these.
+    def api_base=(value)
+      stripped = value.to_s.strip
+      @api_base = stripped.empty? ? DEFAULT_ORIGIN : stripped
+    end
+
+    def dashboard_base=(value)
+      stripped = value.to_s.strip
+      @dashboard_base = stripped.empty? ? DEFAULT_ORIGIN : stripped
+    end
+
+    def configured?
+      api_key.to_s.strip != ""
+    end
+
+    def api_v1_base
+      base = api_base.to_s.chomp("/")
+      return base if base.end_with?("/api/v1")
+      return "#{base}/v1" if base.end_with?("/api")
+
+      "#{base}/api/v1"
+    end
+  end
+end

data/lib/rails_agents/creation_agent.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module RailsAgents
+  # Legacy compatibility class. New output-producing agents should use WorkflowAgent.
+  class CreationAgent < Base
+    def self.agent_kind
+      :creation
+    end
+  end
+end

data/lib/rails_agents/credentials_writer.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module RailsAgents
+  module CredentialsWriter
+    module_function
+
+    def write!(api_key:, project_id: nil)
+      path = Rails.root.join("config/rails_agents_credentials.yml")
+      payload = {
+        "api_key" => api_key,
+        "project_id" => project_id
+      }.compact
+      File.write(path, payload.to_yaml)
+
+      env_path = Rails.root.join(".env")
+      lines = {
+        "RAILS_AGENTS_API_KEY" => api_key,
+        "RAILS_AGENTS_PROJECT_ID" => project_id
+      }.compact
+
+      if env_path.exist?
+        existing = File.read(env_path)
+        lines.each do |key, value|
+          if existing.match?(/^#{Regexp.escape(key)}=/)
+            existing = existing.gsub(/^#{Regexp.escape(key)}=.*$/, "#{key}=#{value}")
+          else
+            existing = existing.sub(/\n*\z/, "\n") + "#{key}=#{value}\n"
+          end
+        end
+        File.write(env_path, existing)
+      else
+        File.write(env_path, lines.map { |k, v| "#{k}=#{v}" }.join("\n") + "\n")
+      end
+    end
+  end
+end

data/lib/rails_agents/engine.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "rails/engine"
+
+module RailsAgents
+  class Engine < ::Rails::Engine
+    isolate_namespace RailsAgents
+
+    config.rails_agents = ActiveSupport::OrderedOptions.new
+
+    initializer "rails_agents.assets" do |app|
+      if app.config.respond_to?(:assets) && app.config.assets.respond_to?(:precompile)
+        app.config.assets.precompile += %w[
+          rails_agents/application.css
+        ]
+      end
+    end
+  end
+end

data/lib/rails_agents/knowledge_agent.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module RailsAgents
+  # Answers questions from your database, docs, and knowledge files (RAG).
+  class KnowledgeAgent < Base
+    def self.agent_kind
+      :knowledge
+    end
+  end
+end

data/lib/rails_agents/library_imports.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "yaml"
+
+module RailsAgents
+  # Resolves workspace-shared capabilities declared by an agent's imports.yml.
+  # Sources live under app/agents_library; sync uploads virtual agent-local
+  # copies so the cloud runtime keeps its existing app/agents/<slug>/ contract.
+  class LibraryImports
+    class Error < StandardError; end
+
+    Entry = Struct.new(:kind, :slug, :source, :target, keyword_init: true)
+
+    KINDS = %w[tool skill connector plugin knowledge package].freeze
+    EXTENSIONS = {
+      "tool" => ".rb",
+      "skill" => ".rb",
+      "connector" => ".yml",
+      "plugin" => ".yml",
+      "knowledge" => ".md",
+      "package" => ".yml"
+    }.freeze
+
+    attr_reader :agent_directory, :library_root
+
+    def initialize(agent_directory, library_root: nil)
+      @agent_directory = Pathname.new(agent_directory).expand_path
+      @library_root = library_root ? Pathname.new(library_root).expand_path : default_library_root
+    end
+
+    def entries
+      return [] unless manifest_path.file?
+
+      document = YAML.safe_load(manifest_path.read, permitted_classes: [], aliases: false) || {}
+      imports = document.fetch("imports", [])
+      raise Error, "#{manifest_path} must contain an imports array" unless imports.is_a?(Array)
+
+      imports.map { |raw| build_entry(raw) }
+    rescue Psych::Exception => e
+      raise Error, "Invalid #{manifest_path}: #{e.message}"
+    end
+
+    def virtual_files
+      entries.flat_map do |entry|
+        raise Error, "Missing Library source: #{entry.source}" unless entry.source.exist?
+
+        if entry.kind == "package"
+          package_virtual_files(entry)
+        else
+          raise Error, "Missing Library source: #{entry.source}" unless entry.source.file?
+
+          [{
+            "path" => cloud_path(entry.target),
+            "content" => entry.source.read,
+            "library_source" => entry.source.relative_path_from(library_root).to_s
+          }]
+        end
+      end
+    end
+
+    def knowledge_paths
+      entries.select { |entry| entry.kind == "knowledge" }.map { |entry| entry.target.to_s }
+    end
+
+    private
+
+    def package_virtual_files(entry)
+      root =
+        if entry.source.directory?
+          entry.source
+        elsif entry.source.basename.to_s == "package.yml"
+          entry.source.dirname
+        else
+          entry.source
+        end
+      raise Error, "Missing Library package directory: #{root}" unless root.directory?
+
+      Dir.glob(root.join("**", "*").to_s).select { |path| File.file?(path) }.map do |path|
+        file = Pathname.new(path)
+        relative = file.relative_path_from(root)
+        target = Pathname.new("packages/#{entry.slug}").join(relative)
+        {
+          "path" => cloud_path(target),
+          "content" => file.read,
+          "library_source" => file.relative_path_from(library_root).to_s
+        }
+      end
+    end
+
+    def manifest_path
+      agent_directory.join("imports.yml")
+    end
+
+    def default_library_root
+      agent_directory.parent.parent.join("agents_library")
+    end
+
+    def build_entry(raw)
+      raise Error, "Each import in #{manifest_path} must be a mapping" unless raw.is_a?(Hash)
+
+      kind = raw["kind"].to_s
+      kind = "connector" if kind == "plugin"
+      slug = normalize_slug(raw["slug"])
+      raise Error, "Unsupported Library kind: #{kind.inspect}" unless KINDS.include?(kind)
+      raise Error, "Library import slug is required" if slug.empty?
+
+      from = raw["from"].to_s
+      prefix = "library/"
+      raise Error, "Library import #{slug} must use from: library/..." unless from.start_with?(prefix)
+
+      source_relative = safe_relative(from.delete_prefix(prefix), "source")
+      source = library_root.join(source_relative)
+      if kind == "connector" && !source.exist? && source_relative.to_s.start_with?("connectors/")
+        legacy = source_relative.to_s.sub(/\Aconnectors\//, "plugins/")
+        legacy_source = library_root.join(legacy)
+        source = legacy_source if legacy_source.exist?
+      end
+      target_relative = raw["as"].to_s.strip
+      target_relative = default_target(kind, slug, source) if target_relative.empty?
+      target = safe_relative(target_relative, "target")
+
+      Entry.new(kind: kind, slug: slug, source: source, target: target)
+    end
+
+    def normalize_slug(value)
+      value.to_s.downcase.gsub(/[^a-z0-9_]+/, "_").gsub(/\A_|_\z/, "")[0, 64]
+    end
+
+    def safe_relative(value, label)
+      path = Pathname.new(value)
+      clean = path.cleanpath
+      if path.absolute? || clean.to_s == ".." || clean.to_s.start_with?("../")
+        raise Error, "Library import #{label} must stay inside its root"
+      end
+      clean
+    end
+
+    def default_target(kind, slug, source)
+      extension = source.extname
+      extension = EXTENSIONS.fetch(kind) if extension.empty?
+      case kind
+      when "knowledge"
+        "knowledge/#{slug}#{extension}"
+      when "package"
+        "packages/#{slug}/package.yml"
+      when "connector", "plugin"
+        "connectors/#{slug}#{extension}"
+      else
+        "#{kind}s/#{slug}#{extension}"
+      end
+    end
+
+    def cloud_path(target)
+      root = application_root
+      agent_directory.join(target).relative_path_from(root).to_s
+    end
+
+    def application_root
+      agent_directory.parent.parent.parent
+    end
+  end
+end

data/lib/rails_agents/local_auth.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module RailsAgents
+  module LocalAuth
+    extend ActiveSupport::Concern
+
+    private
+
+    def local_return_url
+      port = (request.port.presence || 3000).to_s
+      return nil unless %w[localhost 127.0.0.1].include?(request.host)
+
+      "http://127.0.0.1:#{port}#{rails_agents.connect_path}"
+    end
+
+    def github_oauth_url
+      cloud = RailsAgents.config.dashboard_base.to_s.chomp("/")
+      cloud = "https://cloud.rails-agent.com" if cloud.blank?
+      return_to = "/dashboard"
+      url = "#{cloud}/api/v1/auth/github?return_to=#{ERB::Util.url_encode(return_to)}"
+      lr = local_return_url
+      url = "#{url}&local_return=#{ERB::Util.url_encode(lr)}" if lr
+      url
+    end
+
+    def complete_cloud_auth!(response)
+      data = response.is_a?(Hash) ? response : {}
+      api_key =
+        data.dig("apiKey", "token") ||
+        (data["apiKey"].is_a?(String) ? data["apiKey"] : nil) ||
+        data["api_key"]
+      project_id = data.dig("project", "id") || data["projectId"] || data["project_id"]
+      embed_token = data["embedToken"] || data["embed_token"]
+
+      raise Client::Error.new("No API key returned from Cloud") if api_key.blank?
+
+      CredentialsWriter.write!(api_key: api_key, project_id: project_id)
+      RailsAgents.configure do |config|
+        config.api_key = api_key
+        config.project_id = project_id if project_id
+      end
+
+      # Keep JWT out of the browser address bar — stash for the next dashboard render.
+      session[:ra_embed_token] = embed_token if embed_token.present?
+      redirect_to rails_agents.dashboard_path, notice: "Connected. Welcome to Rails Agent."
+    end
+
+    def redirect_if_configured!
+      return unless configured?
+
+      redirect_to rails_agents.dashboard_path
+    end
+  end
+end

data/lib/rails_agents/local_sync.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "pathname"
+
+module RailsAgents
+  # Pulls agent files from Rails Agent Cloud and writes them under app/agents/<slug>/.
+  #
+  # @deprecated Cloud-to-local authoring pull. Build agents locally (see AGENTS.md) and use
+  #   `rails-agents sync` to push files to the cloud. This class remains for CLI compatibility.
+  class LocalSync
+    class Error < StandardError; end
+
+    def initialize(client: Client.new, root: nil)
+      @client = client
+      @root = Pathname.new(root || (defined?(Rails) ? Rails.root : Dir.pwd))
+    end
+
+    # agent_id: cloud agent id (agt_…) or slug/name accepted by the API
+    def pull!(agent_id)
+      raise Error, "Not connected — run handshake or set RAILS_AGENTS_API_KEY" unless RailsAgents.config.configured?
+
+      agent = fetch_agent(agent_id)
+      slug = present(agent["slug"]) || slugify(agent["name"]) || slugify(agent_id)
+      raise Error, "Could not resolve agent slug for #{agent_id}" unless present(slug)
+
+      files_payload = @client.list_files(agent: agent["id"] || agent_id)
+      files = normalize_files_list(files_payload)
+      written = []
+      deleted = []
+
+      agent_dir = @root.join("app/agents", slug)
+      FileUtils.mkdir_p(agent_dir)
+
+      files.each do |file|
+        rel = normalize_relative_path(file["path"] || file[:path], slug)
+        abs = @root.join(rel)
+        ensure_inside_agents!(abs, slug)
+
+        content = file["content"] || file[:content]
+        if content.nil?
+          next
+        end
+
+        FileUtils.mkdir_p(abs.dirname)
+        File.write(abs, content)
+        written << rel.to_s
+      end
+
+      {
+        "ok" => true,
+        "agent_id" => agent["id"] || agent_id,
+        "slug" => slug,
+        "written" => written,
+        "deleted" => deleted,
+        "count" => written.size
+      }
+    end
+
+    private
+
+    def fetch_agent(agent_id)
+      response = @client.get_agent(agent: agent_id)
+      data = response.is_a?(Hash) ? (response["data"] || response) : {}
+      data = data["agent"] if data.is_a?(Hash) && data["agent"].is_a?(Hash)
+      raise Error, "Agent not found: #{agent_id}" unless data.is_a?(Hash) && present(data["id"] || data["slug"] || data["name"])
+
+      data
+    end
+
+    def normalize_files_list(payload)
+      return [] if payload.nil?
+
+      if payload.is_a?(Array)
+        payload
+      elsif payload.is_a?(Hash)
+        payload["data"] || payload["files"] || []
+      else
+        []
+      end
+    end
+
+    def normalize_relative_path(path, slug)
+      raw = path.to_s.sub(%r{\A/+}, "")
+      raise Error, "Invalid path" if raw.empty? || raw.include?("..")
+
+      if raw.start_with?("app/agents/")
+        raw
+      elsif raw.start_with?("#{slug}/")
+        "app/agents/#{raw}"
+      else
+        "app/agents/#{slug}/#{raw}"
+      end
+    end
+
+    def ensure_inside_agents!(abs_path, slug)
+      agents_root = @root.join("app/agents", slug).expand_path
+      expanded = abs_path.expand_path
+      return if expanded.to_s.start_with?(agents_root.to_s + File::SEPARATOR) || expanded == agents_root
+
+      raise Error, "Refusing to write outside app/agents/#{slug}: #{abs_path}"
+    end
+
+    def present(value)
+      str = value.to_s.strip
+      str.empty? ? nil : str
+    end
+
+    def slugify(value)
+      present(value.to_s.downcase.gsub(/[^a-z0-9]+/, "_").gsub(/\A_|_\z/, ""))
+    end
+  end
+end

data/lib/rails_agents/monitoring_agent.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module RailsAgents
+  # Watches runs, traces, evals, and alerts on anomalies or SLA breaches.
+  class MonitoringAgent < Base
+    def self.agent_kind
+      :monitoring
+    end
+  end
+end