rixie 0.1.0

data/lib/rixie/strategy/plan_execute.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Rixie
+  module Strategy
+    class PlanExecute
+      Plan = Data.define(:steps)
+
+      def run(task:, listener:)
+        plan = plan_phase(task:, listener:)
+        execute_phase(plan:, task:, listener:)
+        task.runs.last.output
+      end
+
+      private
+
+      def plan_phase(task:, listener:)
+        run = Run.new(
+          user_input: task.user_input,
+          agent: Agent::Plan.new(base_agent: task.agent),
+          context: task.context
+        )
+        task.runs << run
+        run.execute(listener:)
+        extract_plan(run)
+      end
+
+      def execute_phase(plan:, task:, listener:)
+        completed_histories = []
+
+        plan.steps.each do |step|
+          run = Run.new(
+            user_input: task.user_input,
+            agent: task.agent,
+            context: task.context + completed_histories + [
+              Context::Plan.new(steps: plan.steps, current_step: step)
+            ]
+          )
+          task.runs << run
+          run.execute(listener:)
+          completed_histories << run.to_history if run.completed?
+        end
+      end
+
+      def extract_plan(run)
+        plan_call = run.find_tool_call("plan_done")
+
+        raise AgentError, "plan_done tool call not found in run steps" if plan_call.nil?
+
+        raw_steps = plan_call.arguments[:steps] || plan_call.arguments["steps"]
+        if raw_steps.is_a?(String)
+          begin
+            raw_steps = JSON.parse(raw_steps)
+          rescue JSON::ParserError => e
+            raise AgentError, "plan_done returned invalid JSON for steps: #{e.message}"
+          end
+        end
+        steps = raw_steps.map do |s|
+          {title: s[:title] || s["title"], description: s[:description] || s["description"]}
+        end
+
+        Plan.new(steps: steps)
+      end
+    end
+  end
+end

data/lib/rixie/strategy/re_act.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Rixie
+  module Strategy
+    class ReAct
+      def run(task:, listener:)
+        agent = Agent::ReAct.new(base_agent: task.agent)
+        run = Run.new(user_input: task.user_input, agent: agent, context: task.context)
+        task.runs << run
+        run.execute(listener:)
+        run.output
+      end
+    end
+  end
+end

data/lib/rixie/strategy/simple.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Rixie
+  module Strategy
+    class Simple
+      def run(task:, listener:)
+        run = Run.new(user_input: task.user_input, agent: task.agent, context: task.context)
+        task.runs << run
+        run.execute(listener:)
+        run.output
+      end
+    end
+  end
+end

data/lib/rixie/subscriber.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Rixie
+  class Subscriber
+    # Registers event handlers on the given listener.
+    # Called once per Task execution (new EventListener each time).
+    # Implement by calling listener.on(EventClass) { |e| ... } for each event of interest.
+    def subscribe(listener)
+      raise NotImplementedError, "#{self.class}#subscribe must be implemented"
+    end
+  end
+end

data/lib/rixie/subscribers/event_severity.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Rixie
+  module Subscribers
+    # Maps an Event::* instance to the log severity (:debug, :info, :warn)
+    # at which subscribers should emit it. Shared by Subscribers::Logger and
+    # Subscribers::JsonLogger so the mapping does not drift between them.
+    module EventSeverity
+      def self.for(event)
+        case event
+        when Event::LlmCallStart, Event::ToolCallStart
+          :debug
+        when Event::ToolCallEnd
+          event.result.error? ? :warn : :debug
+        when Event::CompressionEnd
+          (event.status == "completed") ? :info : :warn
+        else
+          :info
+        end
+      end
+    end
+  end
+end

data/lib/rixie/subscribers/json_logger.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Rixie
+  module Subscribers
+    class JsonLogger < Rixie::Subscriber
+      def initialize(logger:)
+        @logger = logger
+      end
+
+      def subscribe(listener)
+        listener.on(Event::TaskStart) { |envelope|
+          e = envelope.event
+          emit(envelope, "task_start", user_input: e.user_input, strategy: e.strategy.class.name)
+        }
+        listener.on(Event::TaskEnd) { |envelope|
+          emit(envelope, "task_end", status: envelope.event.status)
+        }
+        listener.on(Event::RunStart) { |envelope|
+          emit(envelope, "run_start", user_input: envelope.event.user_input)
+        }
+        listener.on(Event::RunEnd) { |envelope|
+          emit(envelope, "run_end", status: envelope.event.status)
+        }
+        listener.on(Event::CompressionStart) { |envelope|
+          e = envelope.event
+          emit(envelope, "compression_start", entry_count: e.entry_count, keep_recent: e.keep_recent)
+        }
+        listener.on(Event::CompressionEnd) { |envelope|
+          e = envelope.event
+          emit(envelope, "compression_end", status: e.status, entry_count: e.entry_count)
+        }
+        listener.on(Event::LlmCallStart) { |envelope|
+          emit(envelope, "llm_call_start", step_count: envelope.event.step_count)
+        }
+        listener.on(Event::ToolCallStart) { |envelope|
+          tc = envelope.event.tool_call
+          emit(envelope, "tool_call_start", tool_call: {id: tc.id, name: tc.name, arguments: tc.arguments})
+        }
+        listener.on(Event::ToolCallEnd) { |envelope|
+          tc = envelope.event.tool_call
+          r = envelope.event.result
+          emit(envelope, "tool_call_end",
+            tool_call: {id: tc.id, name: tc.name},
+            result: {content: r.content, error: r.error&.message})
+        }
+        listener.on(Event::Finished) { |envelope|
+          emit(envelope, "finished", content: envelope.event.content)
+        }
+      end
+
+      private
+
+      def emit(envelope, type, **payload)
+        record = {
+          type: type,
+          occurred_at: envelope.occurred_at.iso8601,
+          session_id: envelope.session_id,
+          task_id: envelope.task_id,
+          run_id: envelope.run_id,
+          seq: envelope.sequence_number,
+          event_id: envelope.event_id,
+          payload: payload
+        }
+        @logger.public_send(EventSeverity.for(envelope.event)) { JSON.generate(record) }
+      end
+    end
+  end
+end

data/lib/rixie/subscribers/logger.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Rixie
+  module Subscribers
+    class Logger < Rixie::Subscriber
+      def initialize(logger:)
+        @logger = logger
+      end
+
+      def subscribe(listener)
+        listener.on(Event::TaskStart) { |envelope|
+          e = envelope.event
+          log(envelope) { "[Task] started: #{e.user_input.inspect} strategy=#{e.strategy.class.name} #{meta(envelope)}" }
+        }
+        listener.on(Event::TaskEnd) { |envelope|
+          log(envelope) { "[Task] #{envelope.event.status} #{meta(envelope)}" }
+        }
+        listener.on(Event::RunStart) { |envelope|
+          log(envelope) { "[Run] started: #{envelope.event.user_input.inspect} #{meta(envelope)}" }
+        }
+        listener.on(Event::RunEnd) { |envelope|
+          log(envelope) { "[Run] #{envelope.event.status} #{meta(envelope)}" }
+        }
+        listener.on(Event::CompressionStart) { |envelope|
+          e = envelope.event
+          log(envelope) { "[Session] compression started: #{e.entry_count} entries (keep_recent: #{e.keep_recent}) #{meta(envelope)}" }
+        }
+        listener.on(Event::CompressionEnd) { |envelope|
+          e = envelope.event
+          msg = (e.status == "completed") ? "compression completed: #{e.entry_count} entries after" : "compression failed"
+          log(envelope) { "[Session] #{msg} #{meta(envelope)}" }
+        }
+        listener.on(Event::LlmCallStart) { |envelope|
+          log(envelope) { "[Agent] llm_call ##{envelope.event.step_count} #{meta(envelope)}" }
+        }
+        listener.on(Event::ToolCallStart) { |envelope|
+          e = envelope.event
+          log(envelope) { "[Agent] tool_call: #{e.tool_call.name}(#{e.tool_call.arguments}) #{meta(envelope)}" }
+        }
+        listener.on(Event::ToolCallEnd) { |envelope|
+          log(envelope) { "[Agent] tool_result: #{envelope.event.result.content.inspect} #{meta(envelope)}" }
+        }
+        listener.on(Event::Finished) { |envelope|
+          log(envelope) { "[Agent] finish: #{envelope.event.content.inspect} #{meta(envelope)}" }
+        }
+      end
+
+      private
+
+      def log(envelope, &block)
+        @logger.public_send(EventSeverity.for(envelope.event), &block)
+      end
+
+      def meta(envelope)
+        parts = []
+        parts << "session_id=#{envelope.session_id}" if envelope.session_id
+        parts << "task_id=#{envelope.task_id}" if envelope.task_id
+        parts << "run_id=#{envelope.run_id}" if envelope.run_id
+        parts << "seq=#{envelope.sequence_number}"
+        parts << "event_id=#{envelope.event_id}"
+        "[#{parts.join(" ")}]"
+      end
+    end
+  end
+end

data/lib/rixie/task.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Rixie
+  class Task
+    attr_reader :id, :user_input, :agent, :context, :strategy, :runs, :status, :output
+
+    def initialize(user_input:, agent:, context:, strategy:, subscribers: [], session_id: nil)
+      @id = SecureRandom.uuid
+      @session_id = session_id
+      @user_input = user_input
+      @agent = agent
+      @context = context
+      @strategy = strategy
+      @subscribers = subscribers
+      @runs = []
+      @status = "running"
+      @output = nil
+    end
+
+    def execute
+      listener = EventListener.new(session_id: @session_id, task_id: @id)
+      listener.on(Event::ToolCallsCompleted) { |envelope|
+        e = envelope.event
+        runs.last.add_step(tool_calls: e.tool_calls, tool_results: e.tool_results)
+      }
+      @subscribers.each { |s| s.subscribe(listener) }
+      listener.emit(Event::TaskStart.new(user_input: @user_input, strategy: @strategy))
+
+      result = @strategy.run(task: self, listener:)
+      @output = result
+      @status = "completed"
+      listener.emit(Event::TaskEnd.new(output: @output, status: @status))
+    rescue
+      @status = "failed"
+      listener&.emit(Event::TaskEnd.new(output: nil, status: @status))
+      raise
+    end
+
+    def completed?
+      @status == "completed"
+    end
+
+    def failed?
+      @status == "failed"
+    end
+
+    def to_history
+      @runs.select(&:completed?).map(&:to_history)
+    end
+  end
+end

data/lib/rixie/token_counter.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Rixie
+  module TokenCounter
+    # Approximate token count using character length (1 token ≈ 4 characters).
+    # Replace via Rixie.configure { |c| c.token_counter = your_callable }
+    # to use an exact counter such as tiktoken.
+    DEFAULT = ->(messages) { messages.sum { |m| m.content.to_s.length } / 4 }
+  end
+end

data/lib/rixie/tool/calculator.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require "strscan"
+
+module Rixie
+  class Tool
+    # Recursive-descent parser for arithmetic expressions.
+    # Supports: + - * / % ^ ** (), unary minus/plus, ints / floats / scientific notation.
+    class CalculatorParser
+      class Error < StandardError; end
+
+      ADDITIVE = ["+", "-"].freeze
+      MULTIPLICATIVE = ["*", "/", "%"].freeze
+      POWER = ["**", "^"].freeze
+
+      def self.evaluate(expression)
+        new(expression).parse
+      end
+
+      def initialize(expression)
+        @tokens = tokenize(expression)
+        @pos = 0
+      end
+
+      def parse
+        result = expression
+        raise Error, "Unexpected token: #{peek.inspect}" if peek
+        result
+      end
+
+      private
+
+      def tokenize(input)
+        scanner = StringScanner.new(input.to_s)
+        tokens = []
+        until scanner.eos?
+          scanner.skip(/\s+/)
+          break if scanner.eos?
+
+          if (num = scanner.scan(/\d+(?:\.\d+)?(?:[eE][+-]?\d+)?/))
+            tokens << (num.match?(/[.eE]/) ? num.to_f : num.to_i)
+          elsif (op = scanner.scan(/\*\*|[+\-*\/%^()]/))
+            tokens << op
+          else
+            raise Error, "Invalid character at position #{scanner.pos}: #{scanner.peek(1).inspect}"
+          end
+        end
+        tokens
+      end
+
+      def peek = @tokens[@pos]
+
+      def consume
+        token = @tokens[@pos]
+        @pos += 1
+        token
+      end
+
+      def expression
+        left = term
+        while ADDITIVE.include?(peek)
+          op = consume
+          right = term
+          left = (op == "+") ? left + right : left - right
+        end
+        left
+      end
+
+      def term
+        left = power
+        while MULTIPLICATIVE.include?(peek)
+          op = consume
+          right = power
+          left = apply_multiplicative(op, left, right)
+        end
+        left
+      end
+
+      def apply_multiplicative(op, left, right)
+        case op
+        when "*" then left * right
+        when "/"
+          raise Error, "Division by zero" if right.zero?
+          # Promote integer division to float to avoid surprising truncation.
+          (left.is_a?(Integer) && right.is_a?(Integer)) ? left.fdiv(right) : left / right
+        when "%"
+          raise Error, "Modulo by zero" if right.zero?
+          left % right
+        end
+      end
+
+      def power
+        left = unary
+        if POWER.include?(peek)
+          consume
+          right = power # right-associative
+          left **= right
+        end
+        left
+      end
+
+      def unary
+        case peek
+        when "-" then consume
+                      -unary
+        when "+" then consume
+                      unary
+        else primary
+        end
+      end
+
+      def primary
+        token = consume
+        return parse_parenthesized if token == "("
+        return token if token.is_a?(Numeric)
+
+        raise Error, "Unexpected token: #{token.inspect}"
+      end
+
+      def parse_parenthesized
+        value = expression
+        raise Error, "Expected ')'" unless consume == ")"
+        value
+      end
+    end
+    private_constant :CalculatorParser
+
+    Calculator = Tool.new(
+      name: "calculator",
+      description: "Evaluate an arithmetic expression and return the result. " \
+                   "Supports + - * / % and ^ (or **) for exponentiation, plus parentheses. " \
+                   "Use this for any non-trivial arithmetic — LLMs are unreliable at calculation.",
+      input_schema: {
+        type: "object",
+        properties: {
+          expression: {
+            type: "string",
+            description: "An arithmetic expression, e.g. '(2 + 3) * 4 ^ 2'"
+          }
+        },
+        required: ["expression"]
+      },
+      call: ->(args) {
+        begin
+          expr = args["expression"] || args[:expression]
+          result = CalculatorParser.evaluate(expr)
+          result.to_s
+        rescue CalculatorParser::Error => e
+          "Error: #{e.message}"
+        end
+      }
+    )
+  end
+end

data/lib/rixie/tool/current_time.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Rixie
+  class Tool
+    CurrentTime = Tool.new(
+      name: "current_time",
+      description: "Get the current date and time as an ISO 8601 string. " \
+                   "LLMs do not know the current time on their own — call this " \
+                   "when the user asks about \"now\", \"today\", relative dates, " \
+                   "or anything time-sensitive.",
+      input_schema: {
+        type: "object",
+        properties: {
+          timezone: {
+            type: "string",
+            description: "Either 'local' (system local time) or 'utc'. Defaults to 'local'.",
+            enum: ["local", "utc"]
+          }
+        }
+      },
+      call: ->(args) {
+        tz = (args["timezone"] || args[:timezone] || "local").to_s.downcase
+        time = (tz == "utc") ? Time.now.utc : Time.now
+        time.iso8601
+      }
+    )
+  end
+end

data/lib/rixie/tool/fetch.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Rixie
+  class Tool
+    Fetch = Tool.new(
+      name: "fetch",
+      description: "Fetch the content of a URL and return the readable text. Useful for reading web pages found via web_search.",
+      input_schema: {
+        type: "object",
+        properties: {
+          url: {
+            type: "string",
+            description: "The URL to fetch"
+          }
+        },
+        required: ["url"]
+      },
+      call: ->(args) {
+        begin
+          require "nokogiri"
+        rescue LoadError
+          raise Rixie::ConfigurationError, "nokogiri gem is required for Tool::Fetch. Add `gem 'nokogiri'` to your Gemfile."
+        end
+
+        url = args["url"] || args[:url]
+        response = Rixie::Http::Client.new.get(url)
+        content_type = response[:headers]["content-type"]&.first.to_s
+
+        next response[:body] unless content_type.include?("text/html")
+
+        doc = Nokogiri::HTML(response[:body].to_s)
+        doc.css("nav, script, style, footer, header, aside, img, link, figure, blockquote, button, noscript, iframe").remove
+        doc.css("pre").each { |pre| pre.replace("[code block omitted]") }
+        doc.css("body").text
+          .gsub(/[^\S\n]+/, " ")
+          .gsub(/^ +| +$/, "")
+          .gsub(/\n{3,}/, "\n\n")
+          .strip
+      }
+    )
+  end
+end

data/lib/rixie/tool/file_list.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "file_sandbox"
+
+module Rixie
+  class Tool
+    build = ->(root_dir: nil) {
+      Tool.new(
+        name: "file_list",
+        description: "List files matching a glob pattern within the configured root directory. " \
+                     "Patterns are relative to root_dir; matches that escape root_dir are filtered out.",
+        input_schema: {
+          type: "object",
+          properties: {
+            pattern: {
+              type: "string",
+              description: "Glob pattern, e.g. '**/*.rb', 'src/*.js', 'lib/**/*'"
+            }
+          },
+          required: ["pattern"]
+        },
+        call: ->(args) {
+          base = FileSandbox.root(root_dir)
+          pattern = (args["pattern"] || args[:pattern]).to_s
+          matches = Dir.glob(pattern, base: base).select do |rel|
+            FileSandbox.resolve(base, rel)
+            true
+          rescue FileSandbox::PathError
+            false
+          end
+          matches.sort!
+          matches.empty? ? "No files matched." : matches.join("\n")
+        }
+      )
+    }
+    FileList = build.call
+    FileList.define_singleton_method(:with, &build)
+  end
+end

data/lib/rixie/tool/file_read.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative "file_sandbox"
+
+module Rixie
+  class Tool
+    DEFAULT_FILE_READ_LIMIT = 2000
+    private_constant :DEFAULT_FILE_READ_LIMIT
+
+    build = ->(root_dir: nil) {
+      Tool.new(
+        name: "file_read",
+        description: "Read a text file from the configured root directory. " \
+                     "Paths are relative to root_dir; absolute or '..' paths that " \
+                     "escape root_dir are rejected. Binary files are not returned.",
+        input_schema: {
+          type: "object",
+          properties: {
+            path: {
+              type: "string",
+              description: "Path to the file, relative to root_dir"
+            },
+            offset: {
+              type: "integer",
+              description: "Line number to start reading from (1-indexed). Defaults to 1."
+            },
+            limit: {
+              type: "integer",
+              description: "Maximum number of lines to read. Defaults to #{DEFAULT_FILE_READ_LIMIT}."
+            }
+          },
+          required: ["path"]
+        },
+        call: ->(args) {
+          begin
+            rel_path = args["path"] || args[:path]
+            target = FileSandbox.resolve(root_dir, rel_path)
+            next "Error: File not found: #{rel_path}" unless File.file?(target)
+            next "Error: Binary file not supported: #{rel_path}" if FileSandbox.binary?(target)
+
+            offset = (args["offset"] || args[:offset] || 1).to_i
+            limit = (args["limit"] || args[:limit] || DEFAULT_FILE_READ_LIMIT).to_i
+            File.foreach(target).drop(offset - 1).take(limit).join
+          rescue FileSandbox::PathError => e
+            "Error: #{e.message}"
+          end
+        }
+      )
+    }
+    FileRead = build.call
+    FileRead.define_singleton_method(:with, &build)
+  end
+end

data/lib/rixie/tool/file_sandbox.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Rixie
+  class Tool
+    # Shared path resolution + safety check for file_read / file_list / file_search.
+    # Rejects paths that escape the configured root directory after expansion.
+    module FileSandbox
+      class PathError < StandardError; end
+
+      def self.root(root_dir)
+        File.expand_path(root_dir || Dir.pwd)
+      end
+
+      def self.resolve(root_dir, relative_path)
+        segments = relative_path.to_s.split(%r{[/\\]})
+        raise PathError, "Path '#{relative_path}' contains '..' segment" if segments.include?("..")
+
+        base = root(root_dir)
+        target = File.expand_path(relative_path.to_s, base)
+        return target if target == base || target.start_with?(base + File::SEPARATOR)
+
+        raise PathError, "Path '#{relative_path}' is outside root_dir"
+      end
+
+      BINARY_PROBE_BYTES = 8192
+      private_constant :BINARY_PROBE_BYTES
+
+      def self.binary?(path)
+        File.open(path, "rb") { |f| f.read(BINARY_PROBE_BYTES).to_s.include?("\0") }
+      end
+    end
+  end
+end