xeno 0.0.1

data/lib/xeno/schedules.rb

@@ -0,0 +1,49 @@
+require "yaml"
+
+module Xeno
+  # Compiles agent/schedules/*.md into Solid Queue recurring entries —
+  # compile-to-the-queue's-native-scheduler, not a dispatcher. No polling
+  # dispatcher: the queue's own recurring machinery fires ScheduleJob.
+  #
+  # Only keys under the managed prefix are touched; hand-written recurring
+  # entries survive a sync. Dev servers never fire user schedules on
+  # cadence — those are written for every environment section EXCEPT
+  # development, where the dispatch endpoint triggers by name. The REAPER
+  # entry is different: it's runtime infrastructure (turns with no live
+  # owner), so it goes into every section including development.
+  module Schedules
+    MANAGED_PREFIX = "xeno_".freeze
+    REAPER_KEY = "#{MANAGED_PREFIX}runtime_reaper".freeze
+
+    module_function
+
+    def sync!(definition: Xeno.definition, path: Rails.root.join("config", "recurring.yml"))
+      existing = File.exist?(path) ? (YAML.safe_load_file(path) || {}) : {}
+      environments = (existing.keys.presence || %w[production]) | %w[development]
+
+      environments.each do |env|
+        section = (existing[env] ||= {})
+        section.delete_if { |key, _| key.start_with?(MANAGED_PREFIX) }
+
+        unless env == "development"
+          definition.schedules.each do |name, schedule|
+            section["#{MANAGED_PREFIX}#{name}"] = {
+              "class" => "Xeno::ScheduleJob",
+              "args" => [ name ],
+              "schedule" => schedule.cron
+            }
+          end
+        end
+
+        section[REAPER_KEY] = reaper_entry
+      end
+
+      File.write(path, YAML.dump(existing))
+      existing
+    end
+
+    def reaper_entry
+      { "class" => "Xeno::ReaperJob", "schedule" => "every minute" }
+    end
+  end
+end

data/lib/xeno/session_state.rb

@@ -0,0 +1,57 @@
+module Xeno
+  # The per-session KV store: working state for
+  # ONE conversation. JSON-typed — values round-trip through JSON, so
+  # symbols become strings and anything unserializable is rejected up
+  # front. Reads always hit the database (a tool in a fresh worker sees
+  # what the last worker wrote); writes take the session row lock, so
+  # read-modify-write merges never lose entries. Cleared by `reset`; it is
+  # NOT long-term memory — durable knowledge belongs in your own models.
+  class SessionState
+    def initialize(session)
+      @session = session
+    end
+
+    def get(key)
+      current[key.to_s]
+    end
+    alias [] get
+
+    def to_h
+      current
+    end
+
+    # Merges the entries in one locked write. Keys stringify; values must
+    # be JSON-serializable (Xeno::Error otherwise).
+    def update(entries)
+      normalized = normalize(entries)
+      @session.with_lock do
+        @session.update!(state: (@session[:state] || {}).merge(normalized))
+      end
+      self
+    end
+
+    def set(key, value)
+      update(key => value)
+    end
+    alias []= set
+
+    def delete(key)
+      @session.with_lock do
+        @session.update!(state: (@session[:state] || {}).except(key.to_s))
+      end
+      self
+    end
+
+    private
+
+    def current
+      Session.where(id: @session.id).pick(:state) || {}
+    end
+
+    def normalize(entries)
+      JSON.parse(JSON.generate(entries.to_h))
+    rescue TypeError, JSON::GeneratorError, NoMethodError => e
+      raise Xeno::Error, "session state values must be JSON-serializable: #{e.message}"
+    end
+  end
+end

data/lib/xeno/standalone/local_secret.rb

@@ -0,0 +1,26 @@
+require "securerandom"
+require "fileutils"
+
+module Xeno
+  module Standalone
+    module_function
+
+    # A persisted local secret so sessions survive restarts without asking
+    # anyone to manage SECRET_KEY_BASE for a dev-grade standalone app.
+    # Owner-only (0600) — it signs cookies/sessions (S6); pre-existing
+    # looser files are tightened on read.
+    #
+    # Lives apart from xeno/standalone so tests can exercise it without
+    # defining the Rails::Application (which self-registers on inheritance).
+    def local_secret(root)
+      path = root.join("storage", ".local_secret")
+      FileUtils.mkdir_p(path.dirname)
+      if path.file?
+        File.chmod(0o600, path)
+        return path.read.strip
+      end
+
+      SecureRandom.hex(64).tap { |secret| File.write(path, secret, perm: 0o600) }
+    end
+  end
+end

data/lib/xeno/standalone/model_refresh.rb

@@ -0,0 +1,26 @@
+module Xeno
+  module Standalone
+    module_function
+
+    # First boot only (the registry table is empty): pull the live model
+    # catalog from the configured providers so current model ids resolve
+    # without a manual RubyLLM.models.refresh!. Loading the definition first
+    # runs agent.rb's RubyLLM.configure — the refresh needs those provider
+    # keys. Never fatal, never repeated once the table has rows; skippable
+    # with XENO_SKIP_MODEL_REFRESH=1 (deterministic scripts, offline boots).
+    def refresh_models!
+      return if ENV["XENO_SKIP_MODEL_REFRESH"]
+
+      Xeno.definition
+      store = RubyLLM.config.model_registry_store
+      return unless store.respond_to?(:none?) && store.none?
+
+      Rails.logger.info "xeno: first boot — refreshing the model registry"
+      RubyLLM.models.refresh!
+      Rails.logger.info "xeno: model registry ready (#{store.count} models)"
+    rescue StandardError => error
+      Rails.logger.warn "xeno: model registry refresh failed (#{error.class}: #{error.message}). " \
+                        "Continuing; run RubyLLM.models.refresh! manually if a model fails to resolve."
+    end
+  end
+end

data/lib/xeno/standalone/puma.rb

@@ -0,0 +1,17 @@
+# Gem-owned puma config for standalone mode (`xeno server`): the whole
+# stack — web + Solid Queue supervisor — inside one Puma process.
+threads_count = ENV.fetch("RAILS_MAX_THREADS", 5).to_i
+threads threads_count, threads_count
+
+# Loopback by default: development runs with the dev auth bypass, and an
+# unauthenticated dev UI must not be exposed to the LAN. Opt out with
+# HOST=0.0.0.0 for containers/proxies that need it.
+bind "tcp://#{ENV.fetch("HOST", "127.0.0.1")}:#{ENV.fetch("PORT", 3000)}"
+
+plugin :solid_queue if ENV.fetch("SOLID_QUEUE_IN_PUMA", "1") != "0"
+
+# Ctrl-C must win. Live SSE streams (the dev UI's EventSource) are in-flight
+# requests, and Puma's default is to wait for in-flight requests :forever —
+# an open browser tab made shutdown hang (found by the first manual run).
+# Hard-stop leftover streams after 5s; xeno's state is rows, nothing is lost.
+force_shutdown_after ENV.fetch("XENO_FORCE_SHUTDOWN_AFTER", 5).to_i

data/lib/xeno/standalone.rb

@@ -0,0 +1,136 @@
+# Standalone mode: Rails as an implementation detail. A scaffolded app is
+# a handful of visible files (agent/, Gemfile, config.ru, .gitignore); the
+# entire Rails::Application lives HERE, inside the gem.
+#
+#   # config.ru
+#   require "xeno/standalone"
+#   run Xeno.rails_app
+#
+# SQLite + Solid Queue inside Puma (`xeno server`) make it one process with
+# zero external services; migrations run at boot.
+require "rails"
+require "active_model/railtie"
+require "active_record/railtie"
+require "active_job/railtie"
+require "action_controller/railtie"
+require "action_view/railtie"
+
+# A config.ru-only app has no Bundler.require(*Rails.groups); pull in what
+# the scaffolded Gemfile provides.
+require "solid_queue"
+require "sqlite3"
+
+require "xeno"
+require "xeno/schedules"
+require "xeno/standalone/local_secret"
+require "xeno/standalone/model_refresh"
+require "yaml"
+
+module Xeno
+  class StandaloneApplication < Rails::Application
+    APP_ROOT = Pathname(Dir.pwd)
+
+    config.root = APP_ROOT
+    config.load_defaults Rails::VERSION::STRING.to_f
+    config.eager_load = ENV["RAILS_ENV"] == "production"
+    config.consider_all_requests_local = ENV["RAILS_ENV"] != "production"
+    config.api_only = false
+    config.logger = ActiveSupport::TaggedLogging.logger($stdout)
+    config.log_level = ENV.fetch("LOG_LEVEL", "info")
+
+    config.active_record.dump_schema_after_migration = false
+    config.active_job.queue_adapter = :solid_queue
+
+    # One durable file under storage/ for everything: app rows + queue.
+    config.paths["db/migrate"] = [ Xeno::Engine.root.join("db", "migrate").to_s ]
+
+    def config.database_configuration
+      {
+        Rails.env => {
+          "primary" => {
+            "adapter" => "sqlite3",
+            "database" => ENV.fetch("XENO_DATABASE", "storage/xeno_#{Rails.env}.sqlite3"),
+            "pool" => ENV.fetch("RAILS_MAX_THREADS", 10).to_i,
+            # Busy handler: web + Solid Queue's forked dispatcher/worker share this
+            # one file; without a timeout the sqlite3 adapter does NOT wait for
+            # locks ("default: no wait") and every collision raises
+            # SQLite3::BusyException. Same 5s default rails new generates.
+            "timeout" => ENV.fetch("XENO_DATABASE_TIMEOUT", 5000).to_i
+          }
+        }
+      }
+    end
+
+    config.secret_key_base = ENV["SECRET_KEY_BASE"] || Xeno::Standalone.local_secret(APP_ROOT)
+  end
+
+  module Standalone
+    module_function
+
+    # Boot: initialize the app, then bring the database up to date — the
+    # engine's migrations plus Solid Queue's tables (loaded straight from
+    # the solid_queue gem's install template).
+    def boot!
+      ENV["RAILS_ENV"] ||= "development"
+      FileUtils.mkdir_p(StandaloneApplication::APP_ROOT.join("storage"))
+
+      app = Rails.application || StandaloneApplication.instance
+      unless app.initialized?
+        app.initialize!
+        app.routes.draw do
+          mount Xeno::Engine => "/agent"
+          root to: redirect("/agent/dev")
+        end
+      end
+
+      migrate!
+      refresh_models!
+      write_recurring_config!
+      Rails.application
+    end
+
+    # Solid Queue's recurring machinery is how the reaper (always) and the
+    # compiled schedules (outside development) fire in standalone mode. The
+    # file lives under storage/ (gitignored) so the scaffold stays four
+    # visible files; the env var — read by Solid Queue's supervisor, which
+    # starts after config.ru has loaded — points the scheduler at it.
+    def write_recurring_config!
+      section = { Xeno::Schedules::REAPER_KEY => Xeno::Schedules.reaper_entry }
+      unless Rails.env.development?
+        Xeno.definition.schedules.each do |name, schedule|
+          section["#{Xeno::Schedules::MANAGED_PREFIX}#{name}"] = {
+            "class" => "Xeno::ScheduleJob", "args" => [ name ], "schedule" => schedule.cron
+          }
+        end
+      end
+
+      path = StandaloneApplication::APP_ROOT.join("storage", "recurring.yml")
+      File.write(path, YAML.dump({ Rails.env.to_s => section }))
+      ENV["SOLID_QUEUE_RECURRING_SCHEDULE"] ||= File.join("storage", "recurring.yml")
+    end
+
+    def migrate!
+      ActiveRecord::MigrationContext.new([ Xeno::Engine.root.join("db", "migrate").to_s ]).migrate
+
+      connection = ActiveRecord::Base.lease_connection
+      unless connection.table_exists?("solid_queue_jobs")
+        load queue_schema_path
+      end
+    end
+
+    def queue_schema_path
+      spec = Gem::Specification.find_by_name("solid_queue")
+      File.join(spec.gem_dir, "lib", "generators", "solid_queue", "install", "templates", "db", "queue_schema.rb")
+    end
+
+    # The gem-owned puma config used by `xeno server` — Solid Queue runs
+    # inside Puma (SOLID_QUEUE_IN_PUMA), one process total.
+    def puma_config_path
+      File.expand_path("standalone/puma.rb", __dir__)
+    end
+  end
+
+  def self.rails_app
+    Standalone.boot!
+  end
+end

data/lib/xeno/tool.rb

@@ -0,0 +1,73 @@
+module Xeno
+  # Base class for agent tools. Anyone who knows RubyLLM already knows how
+  # to write these; xeno adds discovery and (later) the approval macro and
+  # session context.
+  #
+  #   # agent/tools/get_weather.rb
+  #   class Xeno::Tools::GetWeather < Xeno::Tool
+  #     description "Return current weather for a city."
+  #     parameter :city, description: "City name"
+  #
+  #     def execute(city:)
+  #       { city: city, condition: "Sunny" }
+  #     end
+  #   end
+  #
+  class Tool < RubyLLM::Tool
+    class << self
+      # The runtime name the model calls this tool by. The path supplies the
+      # name: Zeitwerk guarantees agent/tools/get_weather.rb
+      # defines Xeno::Tools::GetWeather, so the demodulized class name and
+      # the file basename are the same thing. No suffix-stripping: a
+      # `charge_card_tool.rb` must be callable as `charge_card_tool`, or the
+      # runtime's slug-keyed lookup misses and the approval gate is skipped.
+      def tool_name
+        name.demodulize.underscore
+      end
+
+      # The human-in-the-loop gate. Anything irreversible or externally
+      # visible should be gated — approvals are the guardrail in an
+      # in-app-tools trust model.
+      #
+      #   approval :never    # default: runs without asking
+      #   approval :once     # asks the first time in a session, then remembered
+      #   approval :always   # asks on every call
+      #   approval ->(ctx) { ctx.principal&.dig("role") != "admin" }
+      #
+      # The lambda receives an ApprovalContext (session, turn, tool_name,
+      # arguments, principal); truthy means approval is required.
+      def approval(policy = nil)
+        @approval = policy unless policy.nil?
+        return @approval if defined?(@approval) && @approval
+
+        superclass.respond_to?(:approval) ? superclass.approval : :never
+      end
+    end
+
+    # RubyLLM derives the wire name from the full class name, which would
+    # leak the namespace (xeno/tools/get_weather). Use the path-derived name.
+    def name
+      self.class.tool_name
+    end
+
+    # The session this call is running in — set by the runner before
+    # `call`. nil when the tool is exercised outside a session (unit tests
+    # calling `Tool.new.call` directly).
+    attr_accessor :session
+
+    # The session-scoped KV store: JSON-typed values that survive restarts,
+    # never cross sessions, and are cleared by reset. Working state, not
+    # long-term memory.
+    #
+    #   def execute(city:)
+    #     searches = state.get("searches").to_i + 1
+    #     state.update("searches" => searches, "last_city" => city)
+    #     ...
+    #   end
+    def state
+      raise Xeno::Error, "session state is only available while running inside a session" unless session
+
+      session.state
+    end
+  end
+end