rails-agent-stack 0.1.1

data/lib/rails_agents/base.rb

@@ -0,0 +1,294 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "active_support/core_ext/string/inflections"
+
+module RailsAgents
+  # Prefer product-facing typed subclasses: KnowledgeAgent, WorkflowAgent,
+  # OperationsAgent, or MonitoringAgent.
+  class Base
+    class << self
+      attr_reader :agent_name, :model_setting, :model_provider, :model_credential,
+                  :memory_setting, :memory_provider, :memory_recall, :knowledge_glob,
+                  :tool_definitions, :skill_definitions, :channel_definitions
+
+      def agent_kind
+        :base
+      end
+
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@tool_definitions, {})
+        subclass.instance_variable_set(:@skill_definitions, {})
+        subclass.instance_variable_set(:@channel_definitions, [])
+        subclass.instance_variable_set(:@channel_via, {})
+        subclass.instance_variable_set(:@channel_message_handler, nil)
+      end
+
+      # model :gpt_5_mini, provider: :openai, credential: :company_openai
+      # model :auto  # legacy cloud-routed default (still supported)
+      def model(value, provider: nil, credential: nil)
+        @model_setting = value
+        @model_provider = provider
+        @model_credential = credential
+      end
+
+      # memory :conversation, provider: :mem0, recall: 5
+      def memory(value, provider: nil, recall: nil)
+        @memory_setting = value
+        @memory_provider = provider
+        @memory_recall = recall
+      end
+
+      def knowledge_from(glob)
+        @knowledge_glob = glob
+      end
+
+      def tool(name, &block)
+        @tool_definitions ||= {}
+        @tool_definitions[name.to_sym] = block
+      end
+
+      def skill(name, from:)
+        @skill_definitions ||= {}
+        @skill_definitions[name.to_sym] = from
+      end
+
+      # Declares a SaaS connector (manifest lives under connectors/).
+      # `plugin` remains as a deprecated alias.
+      def connector(name, **opts)
+        @connector_definitions ||= {}
+        @connector_definitions[name.to_sym] = opts
+      end
+      alias_method :plugin, :connector
+
+      def channel(kind, via: nil)
+        @channel_definitions ||= []
+        @channel_definitions << kind.to_sym
+        @channel_via ||= {}
+        @channel_via[kind.to_sym] = via.to_sym if via
+      end
+
+      def channel_via(kind)
+        (@channel_via || {})[kind.to_sym]
+      end
+
+      # Callback for Open-Wire (and future channel) inbound messages.
+      #   on_channel_message { |msg| … }
+      def on_channel_message(&block)
+        @channel_message_handler = block
+      end
+
+      def channel_message_handler
+        @channel_message_handler
+      end
+
+      def agent_directory
+        @agent_directory ||= resolve_agent_directory
+      end
+
+      def run(message = nil, session_id: nil, client: nil, **inputs)
+        text = coerce_run_message(message, inputs)
+        new(client: client).run(text, session_id: session_id)
+      end
+
+      def deploy(client: nil)
+        new(client: client).deploy
+      end
+
+      def sync_knowledge(client: nil)
+        new(client: client).sync_knowledge
+      end
+
+      def coerce_run_message(message, inputs)
+        if inputs.any?
+          if !message.nil?
+            raise ArgumentError, "pass either a message string or keyword inputs, not both"
+          end
+
+          inputs.map { |key, value| "#{key}: #{value}" }.join("\n")
+        elsif message.nil?
+          raise ArgumentError, "message is required (or pass keyword inputs like order_id:)"
+        else
+          message.to_s
+        end
+      end
+      private :coerce_run_message
+
+      def resolve_agent_directory
+        caller_path = Pathname.new(caller_locations(1, 1).first.absolute_path)
+        caller_path.dirname
+      end
+      private :resolve_agent_directory
+    end
+
+    def initialize(client: nil)
+      @client = client || Client.new
+    end
+
+    def run(message = nil, session_id: nil, **inputs)
+      text = self.class.send(:coerce_run_message, message, inputs)
+      response = @client.create_run(
+        agent: agent_identifier,
+        message: text,
+        session_id: session_id,
+        metadata: agent_metadata
+      )
+
+      RunResult.new(response, client: @client)
+    end
+
+    def deploy
+      @client.deploy(agent: agent_identifier, bundle_path: self.class.agent_directory.to_s)
+    end
+
+    def sync_knowledge
+      paths = knowledge_paths
+      @client.sync_knowledge(agent: agent_identifier, paths: paths)
+    end
+
+    def agent_metadata
+      {
+        kind: self.class.agent_kind,
+        model: model_metadata,
+        memory: memory_metadata,
+        tools: self.class.tool_definitions&.keys || [],
+        skills: self.class.skill_definitions || {},
+        channels: self.class.channel_definitions || []
+      }
+    end
+
+    def model_metadata
+      setting = self.class.model_setting
+      provider = self.class.model_provider
+      credential = self.class.model_credential
+
+      if provider.nil? && credential.nil?
+        setting
+      else
+        {
+          name: setting,
+          provider: provider,
+          credential: credential
+        }.compact
+      end
+    end
+
+    def memory_metadata
+      setting = self.class.memory_setting
+      provider = self.class.memory_provider
+      recall = self.class.memory_recall
+
+      if provider.nil? && recall.nil?
+        setting
+      else
+        {
+          type: setting,
+          provider: provider,
+          recall: recall
+        }.compact
+      end
+    end
+
+    def agent_identifier
+      if self.class.name && !self.class.name.empty?
+        self.class.name.underscore
+      else
+        self.class.agent_directory.basename.to_s
+      end
+    end
+
+    def knowledge_paths
+      glob = self.class.knowledge_glob
+      return [] unless glob
+
+      dir = self.class.agent_directory
+      local = Dir.glob(dir.join(glob).to_s).map do |path|
+        Pathname.new(path).relative_path_from(dir).to_s
+      end
+      (local + LibraryImports.new(dir).knowledge_paths).uniq
+    end
+
+    class RunResult
+      attr_reader :response, :client
+
+      def initialize(response, client:)
+        @response = response
+        @client = client
+      end
+
+      def run_id
+        response["id"] ||
+          response["run_id"] ||
+          dig_data("id")
+      end
+
+      def stream(&block)
+        client.stream_run(run_id, &block)
+      end
+
+      # Prefer the sync create_run body; otherwise drain the SSE stream.
+      # Legacy alias for output_text (Markdown final answer).
+      def output
+        text = output_text
+        return text if text.is_a?(String) && !text.empty?
+
+        final = nil
+        chunks = []
+        stream do |event|
+          # Prefer terminal / normalized payloads (done / output events).
+          if event["output_text"].is_a?(String) && !event["output_text"].empty?
+            final = event["output_text"]
+          elsif event["output"].is_a?(String) && !event["output"].empty? &&
+                (event.key?("items") || event.key?("format") || event.key?("status"))
+            final = event["output"]
+          else
+            piece = event["content"] || event["text"]
+            chunks << piece if piece.is_a?(String) && !piece.empty?
+          end
+        end
+        final || chunks.join
+      end
+
+      # Eve-aligned: final assistant Markdown (provider-agnostic).
+      def output_text
+        response["output_text"] ||
+          dig_data("output_text") ||
+          response["output"] ||
+          dig_data("output")
+      end
+
+      # Optional structured final payload (when a schema/result was requested).
+      def output_data
+        response["output_data"] || dig_data("output_data")
+      end
+
+      # Typed turn items: message (+ optional result). Tool trail lives on #trace.
+      def items
+        response["items"] || dig_data("items") || []
+      end
+
+      def format
+        response["format"] || dig_data("format") || "markdown"
+      end
+
+      def status
+        response["status"] || dig_data("status")
+      end
+
+      def trace
+        response["trace"] || dig_data("trace")
+      end
+
+      private
+
+      def dig_data(key)
+        data = response["data"]
+        data.is_a?(Hash) ? data[key] : nil
+      end
+    end
+  end
+
+  # Alias for PRD compatibility
+  RailsAgent = RailsAgents unless defined?(RailsAgent)
+end

data/lib/rails_agents/chat_agent.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module RailsAgents
+  # @deprecated Use {KnowledgeAgent} for conversational / Q&A agents.
+  class ChatAgent < KnowledgeAgent
+    def self.inherited(subclass)
+      super
+      warn "[RailsAgents] ChatAgent is deprecated; use KnowledgeAgent instead.", uplevel: 1
+    end
+
+    def self.agent_kind
+      :knowledge
+    end
+  end
+end

data/lib/rails_agents/cli.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+require "thor"
+require "io/console"
+
+module RailsAgents
+  class CLI < Thor
+    package_name "rails-agents"
+
+    desc "install", "Mount the engine and write the initializer"
+    def install
+      exec_rails_generator("rails_agents:install")
+    end
+
+    desc "new NAME", "Scaffold a new agent directory"
+    def new(name)
+      exec_rails_generator("rails_agents:agent", name)
+    end
+
+    desc "login", "Sign in to Rails Agent Cloud and print export lines for your API key"
+    method_option :email, type: :string, aliases: "-e"
+    method_option :workspace, type: :string, aliases: "-w"
+    def login
+      email = options[:email] || ask("Email:")
+      password = $stdin.tty? ? $stdin.getpass("Password: ") : ask("Password:")
+      workspace = options[:workspace]
+
+      response = Client.new.handshake(
+        email: email,
+        password: password,
+        workspace: workspace
+      )
+      data = response["data"] || response
+      api_key = data["api_key"] || data["apiKey"]
+      api_key = api_key["token"] if api_key.is_a?(Hash)
+      project_id = data["project_id"] || data["projectId"] || data.dig("project", "id")
+      dashboard_url = data["dashboard_url"] || data["dashboardUrl"]
+
+      say ""
+      say "Signed in to Rails Agent Cloud."
+      say "Cloud host is fixed — only these belong in .env (or production env):"
+      say ""
+      say "export RAILS_AGENTS_API_KEY=#{api_key}" if api_key.present?
+      say "export RAILS_AGENTS_PROJECT_ID=#{project_id}" if project_id.present?
+      say ""
+      say "Get or rotate keys anytime: https://cloud.rails-agent.com/dashboard/keys"
+      say "Then visit /agents in your Rails app."
+      if dashboard_url.present?
+        say "Dashboard: #{dashboard_url.to_s.split("?").first}"
+      end
+    rescue Client::Error => e
+      say_error e.message
+      exit 1
+    end
+
+    map "run" => :execute
+
+    desc "execute NAME [MESSAGE]", "Run an agent against the cloud runtime"
+    method_option :session, type: :string, desc: "Session ID for conversation memory"
+    def execute(name, message = nil)
+      agent_class = load_agent_class(name)
+      message ||= $stdin.tty? ? Thor::Shell::Basic.new.ask("Message:") : $stdin.read
+
+      result = agent_class.run(message, session_id: options[:session])
+      say result.output
+    rescue LoadError, NameError => e
+      say_error "Could not load agent #{name}: #{e.message}"
+      exit 1
+    rescue Client::Error => e
+      say_error e.message
+      exit 1
+    end
+
+    desc "deploy [NAME]", "Deploy agent bundle(s) to Rails Agent Cloud"
+    def deploy(name = nil)
+      agents = name ? [name] : discover_agent_names
+      agents.each do |agent_name|
+        agent_class = load_agent_class(agent_name)
+        response = agent_class.deploy
+        say "Deployed #{agent_name}: #{response["id"] || response["status"] || "ok"}"
+      end
+    rescue Client::Error => e
+      say_error e.message
+      exit 1
+    end
+
+    desc "sync NAME", "Push local agent files to the cloud"
+    def sync(name)
+      agent_class = load_agent_class(name)
+      dir = agent_class.agent_directory
+      root = defined?(Rails) ? Rails.root.to_s : Dir.pwd
+      files = Dir[File.join(dir, "**", "*")].select { |p| File.file?(p) }.map do |path|
+        rel = path.sub(%r{\A#{Regexp.escape(root)}/?}, "")
+        rel = rel.sub(%r{\A.*?app/agents/}, "app/agents/") if rel.include?("app/agents/")
+        { "path" => rel, "content" => File.read(path) }
+      end
+      imported = LibraryImports.new(dir).virtual_files
+      local_paths = files.to_h { |file| [file["path"], true] }
+      conflicts = imported.filter_map do |file|
+        file["path"] if local_paths[file["path"]]
+      end
+      unless conflicts.empty?
+        raise LibraryImports::Error,
+          "Library imports conflict with agent-local files: #{conflicts.join(", ")}"
+      end
+      files.concat(
+        imported.map { |file| { "path" => file["path"], "content" => file["content"] } }
+      )
+
+      Client.new.sync_files(agent: name, files: files)
+      suffix = imported.empty? ? "" : " (#{imported.size} from app/agents_library)"
+      say "Synced #{files.size} files for #{name}#{suffix}"
+    rescue LibraryImports::Error => e
+      say_error e.message
+      exit 1
+    rescue Client::Error => e
+      say_error e.message
+      exit 1
+    end
+
+    desc "pull AGENT_ID_OR_SLUG", "[deprecated] Pull agent files from cloud into app/agents/<slug>/"
+    def pull(agent_id)
+      warn "[RailsAgents] `rails-agents pull` is deprecated; scaffold locally and use `rails-agents sync`."
+      result = LocalSync.new.pull!(agent_id)
+      say "Pulled #{result["count"]} files into app/agents/#{result["slug"]}/"
+      Array(result["written"]).each { |path| say "  #{path}" }
+    rescue LocalSync::Error, Client::Error => e
+      say_error e.message
+      exit 1
+    end
+
+    desc "packages QUERY", "Search Skills.sh / APM / Smithery packages"
+    method_option :registry, type: :string, default: "all",
+      desc: "all | skills_sh | apm | smithery"
+    method_option :limit, type: :numeric, default: 12
+    def packages(query)
+      response = Client.new.search_packages(
+        query: query,
+        registry: options[:registry],
+        limit: options[:limit]
+      )
+      rows = response["data"] || []
+      if rows.empty?
+        say "No packages found for #{query.inspect}"
+        return
+      end
+      rows.each do |row|
+        installs = row["installs"] ? " (#{row["installs"]} installs)" : ""
+        say "#{row["registry"]}  #{row["name"]}#{installs}"
+        say "  #{row["id"]}"
+        say "  #{row["description"]}"
+        say ""
+      end
+    rescue Client::Error => e
+      say_error e.message
+      exit 1
+    end
+
+    desc "add-package ID", "Install a registry package onto an agent (and Library)"
+    method_option :agent, type: :string, required: true, aliases: "-a"
+    method_option :registry, type: :string, required: true,
+      desc: "skills_sh | apm | smithery"
+    method_option :name, type: :string
+    method_option :source, type: :string
+    method_option :description, type: :string
+    def add_package(id)
+      payload = {
+        registry: options[:registry],
+        id: id,
+        name: options[:name] || id.split("/").last,
+        source: options[:source] || id.sub(/\A(skills_sh|apm|smithery):/, ""),
+        description: options[:description],
+        agent_id: options[:agent],
+        save_to_library: true
+      }.compact
+      response = Client.new.install_package(payload)
+      data = response["data"] || {}
+      pkg = data["package"] || {}
+      say "Installed #{pkg["name"] || id}"
+      Array(data["paths"]).each { |path| say "  #{path}" }
+      say "Then run: bundle exec rails-agents sync #{options[:agent]}"
+    rescue Client::Error => e
+      say_error e.message
+      exit 1
+    end
+
+    desc "logs [NAME]", "Fetch recent run logs from the cloud"
+    method_option :limit, type: :numeric, default: 50
+    def logs(name = nil)
+      print_json Client.new.logs(agent: name, limit: options[:limit])
+    end
+
+    desc "traces [NAME]", "Fetch recent traces from the cloud"
+    method_option :limit, type: :numeric, default: 50
+    def traces(name = nil)
+      print_json Client.new.traces(agent: name, limit: options[:limit])
+    end
+
+    desc "evals [NAME]", "Fetch eval results from the cloud"
+    def evals(name = nil)
+      print_json Client.new.evals(agent: name)
+    end
+
+    default_task :help
+
+    private
+
+    def exec_rails_generator(generator, *args)
+      if File.exist?("bin/rails")
+        exec "bin/rails", "generate", generator, *args
+      else
+        say_error "Run this command from your Rails app root (bin/rails not found)."
+        exit 1
+      end
+    end
+
+    def load_agent_class(name)
+      path = Rails.root.join("app/agents/#{name}/agent.rb") if defined?(Rails)
+      path ||= File.expand_path("app/agents/#{name}/agent.rb", Dir.pwd)
+
+      require path
+      classify(name).constantize
+    end
+
+    def discover_agent_names
+      base = defined?(Rails) ? Rails.root.join("app/agents") : Pathname.new(Dir.pwd).join("app/agents")
+      return [] unless base.directory?
+
+      base.children.select(&:directory?).map { |d| d.basename.to_s }
+    end
+
+    def classify(name)
+      name.to_s.split(%r{[_\-/]}).map(&:capitalize).join
+    end
+
+    def print_json(data)
+      require "json"
+      say JSON.pretty_generate(data)
+    end
+
+    def say_error(message)
+      say message, :red
+    end
+  end
+end