xeno 0.0.1

data/lib/xeno/agent_definition.rb

@@ -0,0 +1,286 @@
+module Xeno
+  # The resolved agent: everything discovered under the app's agent/
+  # directory, plus diagnostics for anything misplaced or broken.
+  # Discovery never raises — a broken agent directory yields a definition
+  # whose diagnostics say exactly what is wrong (surfaced by `rake xeno:info`).
+  class AgentDefinition
+    SLOT_DIRS = %w[tools skills channels schedules hooks lib].freeze
+    TOOL_SLUG = /\A[a-z][a-z0-9_]*\z/
+
+    Diagnostic = Struct.new(:level, :message) do
+      def error? = level == :error
+    end
+
+    Schedule = Struct.new(:name, :cron, :prompt, keyword_init: true)
+
+    # What agent/instructions.rb's block receives.
+    InstructionContext = Struct.new(:session, :principal, keyword_init: true)
+
+    attr_reader :root, :name, :config, :instructions, :dynamic_instructions,
+                :tools, :schedules, :channels, :hooks, :diagnostics
+
+    # Builds the definition for the app's agent root. `resolver` maps a tool
+    # file's camelized basename to its constant; the default asks Zeitwerk
+    # (via const_get on Xeno::Tools) and is only overridden in tests.
+    def self.load(root, name:, resolver: nil)
+      new(root: root, name: name, resolver: resolver).tap(&:discover)
+    end
+
+    def initialize(root:, name:, resolver: nil)
+      @root = Pathname(root)
+      @name = name
+      @resolver = resolver || method(:resolve_tool_constant)
+      @config = AgentConfig.new
+      @instructions = nil
+      @dynamic_instructions = nil
+      @tools = {}
+      @schedules = {}
+      @channels = {}
+      @hooks = {}
+      @diagnostics = []
+    end
+
+    def discover
+      unless root.directory?
+        error "no agent/ directory at #{root} — run `rails g xeno:install`"
+        return self
+      end
+
+      load_agent_config
+      load_instructions
+      discover_tools
+      discover_schedules
+      discover_channels
+      discover_hooks
+      report_misplaced_files
+      self
+    end
+
+    def tool_classes
+      tools.values
+    end
+
+    def dynamic_instructions? = !@dynamic_instructions.nil?
+
+    # The system prompt for one turn: static markdown first, the dynamic
+    # block's return appended (resolved fresh at every turn stage with the
+    # session context — the current_user use case). A raising block never
+    # bricks the session: the turn proceeds on the static instructions and
+    # the failure is logged.
+    def instructions_for(session: nil)
+      parts = [ instructions ]
+      if @dynamic_instructions
+        context = InstructionContext.new(session: session, principal: session&.principal)
+        begin
+          parts << @dynamic_instructions.call(context).to_s
+        rescue StandardError => e
+          Rails.logger.warn(
+            "xeno: agent/instructions.rb raised #{e.class}: #{e.message} — using static instructions only"
+          )
+        end
+      end
+      combined = parts.compact.map(&:strip).reject(&:empty?).join("\n\n")
+      combined.empty? ? nil : combined
+    end
+
+    def errors? = diagnostics.any?(&:error?)
+
+    private
+
+    def load_agent_config
+      file = root.join("agent.rb")
+      return unless file.file?
+
+      Xeno.capture_agent_config { load file.to_s }
+      captured = Xeno.captured_agent_config
+      if captured
+        @config = captured
+      else
+        warn_diag "agent.rb loaded but never called Xeno.agent — using defaults"
+      end
+    rescue StandardError, SyntaxError => e
+      error "agent.rb failed to load: #{e.class}: #{e.message}"
+    end
+
+    def load_instructions
+      file = root.join("instructions.md")
+      if file.file?
+        @instructions = file.read
+        error "instructions.md is empty" if @instructions.strip.empty?
+      end
+
+      load_dynamic_instructions
+
+      if @instructions.nil? && @dynamic_instructions.nil?
+        error "instructions are missing (instructions.md and/or instructions.rb — the agent's always-on system prompt)"
+      end
+    end
+
+    # agent/instructions.rb — `Xeno.instructions do |context| ... end`,
+    # resolved at turn-stage time (context: session, principal) and appended
+    # to the static markdown.
+    def load_dynamic_instructions
+      file = root.join("instructions.rb")
+      return unless file.file?
+
+      Xeno.capture_instructions { load file.to_s }
+      captured = Xeno.captured_instructions
+      if captured
+        @dynamic_instructions = captured
+      else
+        warn_diag "instructions.rb loaded but never called Xeno.instructions — ignored"
+      end
+    rescue StandardError, SyntaxError => e
+      error "instructions.rb failed to load: #{e.class}: #{e.message}"
+    end
+
+    def discover_tools
+      dir = root.join("tools")
+      return unless dir.directory?
+
+      dir.glob("*.rb").sort.each do |file|
+        slug = file.basename(".rb").to_s
+
+        unless slug.match?(TOOL_SLUG)
+          error "tools/#{file.basename}: invalid tool name #{slug.inspect} (want snake_case: get_weather.rb)"
+          next
+        end
+
+        klass = begin
+          @resolver.call(slug)
+        rescue NameError => e
+          error "tools/#{file.basename}: expected it to define Xeno::Tools::#{slug.camelize} (#{e.message})"
+          next
+        end
+
+        # Xeno::Tool required, not just RubyLLM::Tool: a plain RubyLLM
+        # subclass leaks a namespaced wire name (`xeno--tools--foo`) that
+        # misses the slug-keyed lookup, and it has no approval API — the
+        # gate would silently fail open.
+        unless klass.is_a?(Class) && klass < Xeno::Tool
+          error "tools/#{file.basename}: Xeno::Tools::#{slug.camelize} must subclass Xeno::Tool " \
+                "(naming and the approval gate depend on it)"
+          next
+        end
+
+        tools[slug] = klass
+      end
+    end
+
+    def resolve_tool_constant(slug)
+      Xeno::Tools.const_get(slug.camelize)
+    end
+
+    # agent/schedules/*.md — YAML frontmatter with a cron: line, body is the
+    # task prompt. Compiled to Solid Queue recurring entries by
+    # `rake xeno:schedules:sync`; never fired on cadence in development.
+    def discover_schedules
+      dir = root.join("schedules")
+      return unless dir.directory?
+
+      dir.glob("*.md").sort.each do |file|
+        slug = file.basename(".md").to_s
+
+        unless slug.match?(TOOL_SLUG)
+          error "schedules/#{file.basename}: invalid schedule name #{slug.inspect} (want snake_case)"
+          next
+        end
+
+        frontmatter, prompt = parse_frontmatter(file.read)
+        cron = frontmatter["cron"].presence
+
+        unless cron
+          error "schedules/#{file.basename}: missing `cron:` in the frontmatter"
+          next
+        end
+        if prompt.blank?
+          error "schedules/#{file.basename}: no prompt body after the frontmatter"
+          next
+        end
+
+        schedules[slug] = Schedule.new(name: slug, cron: cron, prompt: prompt)
+      end
+    end
+
+    # agent/channels/*.rb — DSL files (`Xeno.channel :slack do ... end`).
+    # Loading registers the channel globally; the definition records what
+    # each file declared for diagnostics and xeno:info.
+    def discover_channels
+      dir = root.join("channels")
+      return unless dir.directory?
+
+      dir.glob("*.rb").sort.each do |file|
+        slug = file.basename(".rb").to_s
+
+        channel = begin
+          load file.to_s
+          Xeno::Channels.registry[slug.to_sym]
+        rescue StandardError, SyntaxError => e
+          error "channels/#{file.basename}: failed to load: #{e.class}: #{e.message}"
+          next
+        end
+
+        if channel
+          channels[slug] = channel
+        else
+          error "channels/#{file.basename}: expected it to call Xeno.channel :#{slug}"
+        end
+      end
+    end
+
+    # agent/hooks/*.rb — observe-only handlers (`Xeno.hook "type" do … end`).
+    # One file may declare several; they merge across files. Handlers for
+    # unknown event types get a warning (typos never fire).
+    def discover_hooks
+      dir = root.join("hooks")
+      return unless dir.directory?
+
+      dir.glob("*.rb").sort.each do |file|
+        captured = begin
+          Xeno.capture_hooks { load file.to_s }
+        rescue StandardError, SyntaxError => e
+          error "hooks/#{file.basename}: failed to load: #{e.class}: #{e.message}"
+          next
+        end
+
+        if captured.empty?
+          warn_diag "hooks/#{file.basename}: loaded but never called Xeno.hook — ignored"
+          next
+        end
+
+        captured.each do |event_type, handlers|
+          unless event_type == "*" || Event::TYPES.include?(event_type)
+            warn_diag "hooks/#{file.basename}: #{event_type.inspect} is not in the event vocabulary (typo?) — it will never fire"
+          end
+          (hooks[event_type] ||= []).concat(handlers)
+        end
+      end
+    end
+
+    def parse_frontmatter(content)
+      if content =~ /\A---\s*\n(.*?)\n---\s*\n?(.*)\z/m
+        [ YAML.safe_load(Regexp.last_match(1)) || {}, Regexp.last_match(2).strip ]
+      else
+        [ {}, content.strip ]
+      end
+    rescue Psych::SyntaxError
+      [ {}, content.strip ]
+    end
+
+    def report_misplaced_files
+      root.glob("*.rb").each do |file|
+        next if %w[agent.rb instructions.rb].include?(file.basename.to_s)
+
+        warn_diag "#{file.basename}: ruby files at the agent root are not loaded — did you mean tools/#{file.basename}?"
+      end
+
+      root.children.select(&:directory?).each do |dir|
+        slot = dir.basename.to_s
+        warn_diag "#{slot}/: not a known slot (#{SLOT_DIRS.join(', ')})" unless SLOT_DIRS.include?(slot)
+      end
+    end
+
+    def error(message) = diagnostics << Diagnostic.new(:error, message)
+    def warn_diag(message) = diagnostics << Diagnostic.new(:warning, message)
+  end
+end

data/lib/xeno/approval_context.rb

@@ -0,0 +1,4 @@
+module Xeno
+  # What an approval lambda gets to look at.
+  ApprovalContext = Struct.new(:session, :turn, :tool_name, :arguments, :principal, keyword_init: true)
+end

data/lib/xeno/arguments.rb

@@ -0,0 +1,62 @@
+module Xeno
+  # Models send JSON-typed arguments loosely — the first field run had
+  # llama sending "4200" (String) for an integer-typed parameter, which
+  # flowed into execute unchecked. Casts each argument per the tool's
+  # declared parameter type; anything uncoercible becomes a validation
+  # error the runner turns into an error tool result (the model retries
+  # with fixed arguments) — never an exception into execute.
+  module Arguments
+    module_function
+
+    # Returns [coerced_arguments, errors]. Undeclared keys pass through
+    # untouched (schema-based tools declare nothing here).
+    def coerce(tool_class, arguments)
+      declared = tool_class.respond_to?(:declared_parameters) ? tool_class.declared_parameters : {}
+      return [ arguments, [] ] if declared.empty? || !arguments.is_a?(Hash)
+
+      coerced = {}
+      errors = []
+      arguments.each do |key, value|
+        parameter = declared[key.to_sym]
+        if parameter.nil? || value.nil?
+          coerced[key] = value
+          next
+        end
+
+        begin
+          coerced[key] = cast(value, parameter.type.to_s)
+        rescue ArgumentError, TypeError
+          errors << "#{key}: expected #{parameter.type}, got #{value.inspect}"
+        end
+      end
+      [ coerced, errors ]
+    end
+
+    def cast(value, type)
+      case type
+      when "integer" then value.is_a?(Integer) ? value : Integer(value, exception: true)
+      when "number"  then value.is_a?(Numeric) ? value : Float(value)
+      when "boolean" then boolean(value)
+      when "string"  then value.is_a?(String) ? value : scalar_to_string(value)
+      when "array"   then value.is_a?(Array) ? value : raise(TypeError)
+      when "object"  then value.is_a?(Hash) ? value : raise(TypeError)
+      else value
+      end
+    end
+
+    def boolean(value)
+      case value
+      when true, false then value
+      when "true", "1", 1 then true
+      when "false", "0", 0 then false
+      else raise TypeError
+      end
+    end
+
+    def scalar_to_string(value)
+      raise TypeError if value.is_a?(Array) || value.is_a?(Hash)
+
+      value.to_s
+    end
+  end
+end

data/lib/xeno/ask_question.rb

@@ -0,0 +1,18 @@
+module Xeno
+  # The one framework tool in v0.1. It has no executable body: the model
+  # calling it parks the turn with an input.requested event, and a human's
+  # answer is injected as the tool result on resume — the same mechanics as
+  # approvals. Registered on every chat (outside the Xeno::Tools namespace,
+  # which belongs to the app's agent/tools/).
+  class AskQuestion < Tool
+    description "Ask the human a question and wait for their answer. " \
+                "Use when you need information or a decision only they can provide."
+    parameter :question, description: "The question to ask"
+    parameter :choices, type: :array, required: false,
+                        description: "Optional list of suggested answers"
+
+    def execute(question:, choices: nil)
+      raise "ask_question is never executed — the runtime parks the turn instead"
+    end
+  end
+end

data/lib/xeno/channels/slack.rb

@@ -0,0 +1,311 @@
+require "openssl"
+require "net/http"
+
+module Xeno
+  module Channels
+    # The Slack channel: Events API webhook with constant-time signature
+    # verification, thread-scoped sessions (continuation token =
+    # "slack:<channel>:<thread_ts>"), replies posted at turn completion,
+    # and plain-text approvals ("approve"/"deny"/an answer) in the thread.
+    #
+    # v0.1 scope: mentions and DMs start sessions; thread replies continue
+    # them. Post-then-edit streaming and Block Kit buttons are v0.2.
+    class Slack
+      SIGNATURE_VERSION = "v0".freeze
+      TIMESTAMP_TOLERANCE = 300 # seconds; replayed webhooks are rejected
+
+      APPROVE_WORDS = %w[approve approved yes y ok 👍].freeze
+      DENY_WORDS = %w[deny denied no n reject rejected 👎].freeze
+
+      def initialize(&block)
+        @api_base = "https://slack.com/api"
+        instance_eval(&block) if block
+      end
+
+      # --- the config DSL (setter-and-reader hybrids, like AgentConfig) ---
+
+      def signing_secret(value = nil)
+        @signing_secret = value if value
+        @signing_secret
+      end
+
+      def bot_token(value = nil)
+        @bot_token = value if value
+        @bot_token
+      end
+
+      # Overridable for offline tests (the fake Slack API).
+      def api_base(value = nil)
+        @api_base = value if value
+        @api_base
+      end
+
+      # Opt-in post-then-edit streaming: the reply posts on the first model
+      # delta and is edited (~1s cadence, rate-limit aware) until the final
+      # text lands. Off by default — replies post once at completion.
+      def stream_replies(value = nil)
+        @stream_replies = value unless value.nil?
+        @stream_replies
+      end
+
+      # --- inbound: webhook verification + event handling ---
+
+      def verify_signature(timestamp, signature, raw_body)
+        return false if signing_secret.blank? || timestamp.blank? || signature.blank?
+        return false if (Time.now.to_i - timestamp.to_i).abs > TIMESTAMP_TOLERANCE
+
+        base = "#{SIGNATURE_VERSION}:#{timestamp}:#{raw_body}"
+        digest = OpenSSL::HMAC.hexdigest("sha256", signing_secret, base)
+        expected = "#{SIGNATURE_VERSION}=#{digest}"
+        ActiveSupport::SecurityUtils.secure_compare(expected, signature.to_s)
+      end
+
+      def handle_event(payload)
+        event = payload["event"] || {}
+        return if event["bot_id"].present? # never talk to ourselves
+
+        case event["type"]
+        when "app_mention"
+          handle_message(event)
+        when "message"
+          # DMs only; edits/joins/etc. carry a subtype and are ignored.
+          handle_message(event) if event["channel_type"] == "im" && event["subtype"].blank?
+        end
+      end
+
+      # --- outbound: delivery ---
+
+      def deliver_completion(session, content)
+        channel_id, thread_ts = thread_for(session)
+        return unless channel_id
+
+        post_message(channel: channel_id, thread_ts: thread_ts, text: content.to_s)
+      end
+
+      # One per content-bearing model reply when stream_replies is on: the
+      # runner pushes deltas, we post-then-edit in the thread.
+      def streamer_for(session)
+        return nil unless stream_replies
+
+        channel_id, thread_ts = thread_for(session)
+        return nil unless channel_id
+
+        Streamer.new(self, channel: channel_id, thread_ts: thread_ts)
+      end
+
+      def deliver_input_request(session, actions)
+        channel_id, thread_ts = thread_for(session)
+        return unless channel_id
+
+        prompts = actions.map do |action|
+          if action.kind == "question"
+            question = action.input&.dig("question")
+            choices = Array(action.input&.dig("choices"))
+            choices.any? ? "❓ #{question} (#{choices.join(' / ')})" : "❓ #{question}"
+          else
+            "⏸ Approval needed: `#{action.tool_name}(#{action.input.to_json})` — reply *approve* or *deny*."
+          end
+        end
+        post_message(channel: channel_id, thread_ts: thread_ts, text: prompts.join("\n"))
+      end
+
+      # Raised by api_post on HTTP 429; carries Slack's Retry-After.
+      class RateLimited < Xeno::Error
+        attr_reader :retry_after
+
+        def initialize(retry_after:)
+          @retry_after = [ retry_after.to_f, 1.0 ].max
+          super("slack rate limited (retry after #{@retry_after}s)")
+        end
+      end
+
+      # Post-then-edit delivery for ONE streaming model reply. The first
+      # content delta posts the thread message; later deltas edit it at most
+      # once per EDIT_INTERVAL; finish writes the durable final text. Rate
+      # limits defer the next edit (Retry-After); any hard failure turns
+      # streaming off for this reply — the completion post is the fallback,
+      # and the durable truth is rows either way.
+      class Streamer
+        EDIT_INTERVAL = 1.0 # seconds — comfortably under chat.update's tier
+
+        def initialize(slack, channel:, thread_ts:)
+          @slack = slack
+          @channel = channel
+          @thread_ts = thread_ts
+          @buffer = +""
+          @ts = nil
+          @posted_text = nil
+          @next_edit_at = 0.0
+          @dead = false
+        end
+
+        def push(chunk)
+          content = chunk.respond_to?(:content) ? chunk.content : nil
+          return if @dead || content.to_s.empty?
+
+          @buffer << content
+          @ts.nil? ? start_message : edit_message(@buffer.dup)
+        end
+
+        # Returns true when this streamer delivered the reply (the runner
+        # then skips the completion post); false hands delivery back.
+        def finish(final_text)
+          return false if @ts.nil?
+
+          text = final_text.to_s
+          return true if @posted_text == text
+
+          wait = @next_edit_at - now
+          sleep([ wait, 3.0 ].min) if wait.positive? # respect a pending rate-limit window
+          @slack.api_post("chat.update", channel: @channel, ts: @ts, text: text)
+          @posted_text = text
+          true
+        rescue StandardError => e
+          Rails.logger.warn("xeno: slack streaming final edit failed: #{e.class}: #{e.message}")
+          false
+        end
+
+        private
+
+        def start_message
+          payload = @slack.api_post("chat.postMessage",
+                                    channel: @channel, thread_ts: @thread_ts, text: @buffer.dup)
+          @ts = payload["ts"]
+          @posted_text = @buffer.dup
+          @next_edit_at = now + EDIT_INTERVAL
+        rescue StandardError => e
+          @dead = true
+          Rails.logger.warn("xeno: slack streaming post failed: #{e.class}: #{e.message}")
+        end
+
+        def edit_message(text)
+          return if now < @next_edit_at
+
+          @slack.api_post("chat.update", channel: @channel, ts: @ts, text: text)
+          @posted_text = text
+          @next_edit_at = now + EDIT_INTERVAL
+        rescue RateLimited => e
+          @next_edit_at = now + e.retry_after
+        rescue StandardError => e
+          @dead = true
+          Rails.logger.warn("xeno: slack streaming edit failed: #{e.class}: #{e.message}")
+        end
+
+        def now
+          Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        end
+      end
+
+      # One JSON POST to the Slack Web API; 429 becomes RateLimited (with
+      # Retry-After), any other failure raises Xeno::Error.
+      def api_post(method, payload)
+        uri = URI("#{api_base}/#{method}")
+        request = Net::HTTP::Post.new(uri)
+        request["Authorization"] = "Bearer #{bot_token}"
+        request["Content-Type"] = "application/json; charset=utf-8"
+        request.body = JSON.generate(payload)
+
+        response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", read_timeout: 10) do |http|
+          http.request(request)
+        end
+        parsed = JSON.parse(response.body) rescue {}
+
+        raise RateLimited.new(retry_after: response["Retry-After"]) if response.code.to_i == 429
+        unless response.is_a?(Net::HTTPSuccess) && parsed["ok"]
+          raise Xeno::Error, "slack #{method} failed: #{response.code} #{parsed['error']}"
+        end
+
+        parsed
+      end
+
+      private
+
+      def handle_message(event)
+        text = strip_mention(event["text"].to_s).strip
+        return if text.empty?
+
+        channel_id = event["channel"]
+        thread_ts = event["thread_ts"] || event["ts"]
+        token = "slack:#{channel_id}:#{thread_ts}"
+        principal = {
+          "type" => "slack",
+          "user_id" => event["user"],
+          "team_id" => event["team"],
+          "channel_id" => channel_id
+        }
+
+        session = Session.find_by(continuation_token: token)
+        if session&.active?
+          continue_session(session, text, principal)
+        else
+          Session.start!(message: text, channel: "slack", principal: principal, continuation_token: token)
+        end
+      end
+
+      # A reply into a waiting thread resolves the FIRST pending input; an
+      # unrelated reply is HELD as the next message (never auto-deny, never
+      # a forced answer):
+      # - approvals: approve/deny words resolve; anything else holds.
+      # - questions with choices: match by 1-based index ("2"), by label
+      #   (case-insensitive), or by exact option text; no match holds and
+      #   the question stays pending.
+      # - free-form questions (no choices): any text is the answer.
+      def continue_session(session, text, principal)
+        pending = Action.joins(:turn)
+                        .where(xeno_turns: { session_id: session.id }, status: "pending_approval")
+                        .order(:id)
+                        .first
+
+        if pending && session.status == "waiting"
+          if pending.kind == "question"
+            answer = match_answer(pending, text)
+            if answer
+              Inputs.answer!(pending, answer, principal: principal)
+            else
+              session.receive_message!(text) # held; the question stays pending
+            end
+          elsif APPROVE_WORDS.include?(text.downcase)
+            Inputs.approve!(pending, principal: principal)
+          elsif DENY_WORDS.include?(text.downcase)
+            Inputs.deny!(pending, principal: principal)
+          else
+            session.receive_message!(text) # held; the approval stays pending
+          end
+        else
+          session.receive_message!(text)
+        end
+      end
+
+      # The resolved answer for a question, or nil to hold the reply.
+      def match_answer(action, text)
+        choices = Array(action.input&.dig("choices")).map(&:to_s)
+        return text if choices.empty? # free-form: any text answers
+
+        normalized = text.strip
+        if normalized.match?(/\A\d+\z/)
+          index = normalized.to_i
+          return choices[index - 1] if index.between?(1, choices.size)
+        end
+
+        choices.find { |choice| choice.casecmp?(normalized) }
+      end
+
+      def strip_mention(text)
+        text.gsub(/<@[A-Z0-9]+>/, " ")
+      end
+
+      def thread_for(session)
+        token = session.continuation_token ||
+                session.metadata&.dig("released_continuation_token")
+        return nil unless token&.start_with?("slack:")
+
+        _prefix, channel_id, thread_ts = token.split(":", 3)
+        [ channel_id, thread_ts ]
+      end
+
+      def post_message(channel:, thread_ts:, text:)
+        api_post("chat.postMessage", channel: channel, thread_ts: thread_ts, text: text)
+      end
+    end
+  end
+end