zephira 0.1.0

data/lib/zephira/agent.rb

@@ -0,0 +1,312 @@
+# frozen_string_literal: true
+
+require "readline"
+require "json"
+require "tty-spinner"
+require "tty-screen"
+require "tty-cursor"
+
+module Zephira
+  class Agent
+    COMPACTION_TRIGGER_RATIO = 0.8
+    COMPACTION_TARGET_RATIO = 0.5
+
+    SYSTEM_PROMPT = <<~PROMPT
+      You are a helpful command line agent called Zephira.
+      You can run commands and tools to assist the user.
+      You should make full use of the tools that are available to you.
+      You can use the knowledge you already have to help the user, but if you don't know something, you should:
+        - Use the tools available to you to find the answer
+        - Ask the user for more information
+        - Do not make up answers or pretend to know something you don't.
+
+      Return all responses in a format that is easy to read in a terminal:
+        - Do NOT return responses in Markdown format.
+        - You can use unicode characters to make your output more readable.
+        - You can use emojis to make your output more engaging (but don't overdo it).
+        - You can use colors to highlight important information.
+        - You can use formatting to make your output more readable.
+        - You can return links to documentation or other resources as full URLs.
+
+      You can use the following formatting tokens in your responses:
+        - #{Formatter.available_formats.join("\n  - ")}
+
+      If you are trying to perform operations that don't seem to be working,
+      you should stop what you're doing and tell the user that you are unable
+      to perform the operation, and tell the user why.
+
+      When updating a file using the `update_file` tool, always output the complete file content — never partial content or diffs.
+
+      You should not try to guess what the user is trying to do, or try to
+      perform operations that are not explicitly requested by the user.
+
+      Additional instructions provided by the user. The project-local instructions
+      should overrule the global instructions:
+
+      Global instructions (loaded from ~/.zephira/additional_instructions.md):
+      @@@GLOBAL_ADDITIONAL_INSTRUCTIONS@@@
+
+      Project instructions (loaded from ./.zephira/additional_instructions.md):
+      @@@PROJECT_ADDITIONAL_INSTRUCTIONS@@@
+
+      The user's current `date` is: @@@DATE@@@
+      The user's current `uname -a` is: @@@UNAME@@@
+      The user's current `pwd` is: @@@PWD@@@
+      The user's current `ls -R` is: @@@LSR@@@
+    PROMPT
+
+    LOGO = <<~'LOGO'
+      ░▒▓████████▓▒░░▒▓████████▓▒░░▒▓███████▓▒░ ░▒▓█▓▒░░▒▓█▓▒░░▒▓█▓▒░░▒▓███████▓▒░  ░▒▓██████▓▒░
+           ░▒▓██▓▒░ ░▒▓█▓▒░       ░▒▓█▓▒░░▒▓█▓▒░░▒▓█▓▒░░▒▓█▓▒░░▒▓█▓▒░░▒▓█▓▒░░▒▓█▓▒░░▒▓█▓▒░░▒▓█▓▒░
+         ░▒▓██▓▒░   ░▒▓██████▓▒░  ░▒▓███████▓▒░ ░▒▓████████▓▒░░▒▓█▓▒░░▒▓███████▓▒░ ░▒▓████████▓▒░
+       ░▒▓██▓▒░     ░▒▓█▓▒░       ░▒▓█▓▒░       ░▒▓█▓▒░░▒▓█▓▒░░▒▓█▓▒░░▒▓█▓▒░░▒▓█▓▒░░▒▓█▓▒░░▒▓█▓▒░
+      ░▒▓████████▓▒░░▒▓████████▓▒░░▒▓█▓▒░       ░▒▓█▓▒░░▒▓█▓▒░░▒▓█▓▒░░▒▓█▓▒░░▒▓█▓▒░░▒▓█▓▒░░▒▓█▓▒░
+    LOGO
+
+    attr_reader :history, :tools, :commands, :completions, :logger, :status
+    attr_accessor :model, :verbose
+
+    def initialize
+      @verbose = false
+      log_file_path = File.join(Dir.pwd, ".zephira", "session.log")
+      @logger = Logger.new(file_path: log_file_path)
+      @status = Status.new(self)
+      @spinner = nil
+      @output_mutex = Mutex.new
+
+      tool_dirs = [File.expand_path("tools", __dir__)]
+      command_dirs = [File.expand_path("commands", __dir__)]
+      completion_dirs = [File.expand_path("completions", __dir__)]
+
+      @tools = Tools.load(paths: tool_dirs)
+      @commands = Commands.load(paths: command_dirs)
+      @completions = Completions.load(paths: completion_dirs)
+      @history = History.new
+      @history.compact_tool_messages!
+
+      @uname = `uname -a`.strip
+      @pwd = `pwd`.strip
+
+      @model = resolve_model
+    end
+
+    def thinking(model_class)
+      thinkmojis = %w[🤔 🧠 💭 🤯 🧐 ⏳ 🔄 🌀 🤨 💡 🧩 🔍 📚 ⚙️]
+      token_count = Tokens.estimate(history.messages.to_json)
+      update_status("Thinking... #{thinkmojis.shuffle.first} " + Formatter.color(:grey, "(#{model_class.model_name} - #{token_count} tokens)"))
+    end
+
+    def update_status(msg)
+      @output_mutex.synchronize do
+        @spinner&.spin
+        puts msg
+      end
+    end
+
+    def run_tool(name:, args:)
+      @tools.run(name: name, args: args, agent: self)
+    end
+
+    def run_command(name:, args:)
+      @commands.run(name: name, args: args, agent: self)
+    end
+
+    def compact_history(force: false)
+      current = Tokens.estimate(JSON.dump(@history.messages))
+      threshold = (@model.context_limit * COMPACTION_TRIGGER_RATIO).to_i
+      target = force ? [current / 2, 1].max : (@model.context_limit * COMPACTION_TARGET_RATIO).to_i
+
+      return false if @history.messages.empty?
+      return false if !force && current <= threshold
+
+      puts Formatter.color(:grey, "  ✦ Compacting history (~#{current} tokens)...")
+      @history.compact(
+        response_model: @model,
+        api_key: Config.read("ZEPHIRA_API_KEY"),
+        agent: self,
+        token_limit: target
+      )
+      after = Tokens.estimate(JSON.dump(@history.messages))
+      puts Formatter.color(:grey, "  ✦ History compacted (~#{after} tokens).")
+      true
+    end
+
+    def compact_if_needed
+      compact_history(force: false)
+    end
+
+    def run_loop
+      Readline.completion_proc = proc { |input| @completions.complete_all(input: input, agent: self) }
+      seed_readline_history
+      print_intro
+
+      loop do
+        render_status_bar
+
+        user_input = Readline.readline("> ", true)
+        break if user_input.nil?
+
+        input = user_input.strip
+        next if input.empty?
+
+        TTY::Cursor.hide
+        echo_user_input(input)
+
+        if input.start_with?("/")
+          dispatch_command(input)
+          TTY::Cursor.show
+          next
+        end
+
+        process_user_message(input)
+        TTY::Cursor.show
+
+        history.compact_tool_messages!
+        compact_if_needed
+      rescue Interrupt
+        puts "\n[Interrupted]"
+        break
+      rescue => e
+        puts "\nError: #{e.message}"
+        logger.error("#{e.class}: #{e.message}\n#{e.backtrace.first(5).join("\n")}")
+      end
+    end
+
+    def seed_readline_history
+      return unless history.session_start > 0
+      history.messages[0...history.session_start]
+        .select { |message| message[:role] == "user" }
+        .map { |message| message[:content] }
+        .each { |command| Readline::HISTORY.push(command) }
+    end
+
+    def print_intro
+      logo_width = LOGO.each_line.first.chomp.length
+      logo_indent = [(screen_width - logo_width) / 2, 0].max
+      puts Formatter.format(Formatter.color(:green, LOGO), indent: logo_indent)
+      puts
+      puts "#{Formatter.color(:grey, "System:")}\n Zephira starting... #{Formatter.color(:green, "Ready!")}"
+      puts
+      puts Formatter.color(:grey, "Zephira:")
+      puts "  Hello! I am Zephira, your command line assistant. How can I help you today?"
+      puts "  Type your command or question below. If you're not sure what to ask, you can"
+      puts "  ask me what I can do for you... or type '/help' for a list of commands."
+    end
+
+    def render_status_bar
+      context_used = Tokens.estimate(JSON.dump(@history.messages))
+      context_limit = @model.context_limit
+      # Percent of context window REMAINING (limit - used) / limit, clamped to 0..100.
+      context_pct = ((context_limit - context_used).to_f / context_limit * 100).clamp(0, 100).to_i
+      width = screen_width
+      print TTY::Cursor.move_to(0, screen_height - 3)
+      puts Formatter.color(:grey, "-" * width)
+
+      sandbox_label = ENV["ZEPHIRA_IN_SANDBOX"] == "1" ? "sandboxed" : "⚠ DANGER: NO SANDBOX"
+      sandbox_color = ENV["ZEPHIRA_IN_SANDBOX"] == "1" ? :green : :red
+      right_text = "ctrl+c to exit | '/help' + enter to see commands | #{context_pct}% context left"
+      padding = [width - sandbox_label.length - right_text.length, 1].max
+      puts Formatter.color(sandbox_color, sandbox_label) + " " * padding + Formatter.color(:grey, right_text)
+    end
+
+    def echo_user_input(input)
+      rows = screen_rows
+      puts
+      puts Formatter.color(:grey, "=" * screen_width)
+      puts "\n" * rows
+      print TTY::Cursor.up(rows)
+      puts Formatter.color(:grey, "User:")
+      puts Formatter.format(input, indent: 2)
+      puts
+    end
+
+    def dispatch_command(input)
+      parts = input[1..].strip.split
+      run_command(name: parts.first, args: parts[1..] || [])
+    end
+
+    def process_user_message(input)
+      history.append(role: "user", content: input)
+      messages = [system_prompt] + history.messages.map { |message| message.slice(:role, :content, :tool_call_id, :tool_calls) }
+
+      response = run_inference_with_spinner(messages)
+
+      if response
+        history.append(role: "assistant", content: response)
+        puts Formatter.color(:grey, "\nZephira:")
+        puts Formatter.format(response, indent: 2)
+        puts
+      end
+    end
+
+    def run_inference_with_spinner(messages)
+      response = nil
+      spinner_format_string = Formatter.color(:grey, "[") + Formatter.color(:green, " :spinner ") + Formatter.color(:grey, ":elapsed] ")
+      @spinner = TTY::Spinner.new(spinner_format_string, format: :dots)
+      spinner_started_at = Time.now
+      @spinner.on(:spin) do
+        elapsed = (Time.now - spinner_started_at).to_i
+        @spinner.update(elapsed: sprintf("%03ds", elapsed))
+      end
+
+      @spinner.run(Formatter.color(:green, "Done!")) do
+        response = @model.inference(
+          api_key: Config.read("ZEPHIRA_API_KEY"),
+          base_url: Config.read("ZEPHIRA_BASE_URL"),
+          messages: messages,
+          agent: self
+        )
+      end
+      @spinner = nil
+      response
+    end
+
+    private
+
+    def load_additional_instructions
+      instructions = {}
+      global_file = File.join(Dir.home, ".zephira", "additional_instructions.md")
+      project_file = File.join(Dir.pwd, ".zephira", "additional_instructions.md")
+      instructions[:global] = File.read(global_file).strip if File.exist?(global_file)
+      instructions[:project] = File.read(project_file).strip if File.exist?(project_file)
+      instructions
+    end
+
+    def system_prompt
+      instructions = load_additional_instructions
+      {
+        role: "system",
+        content: SYSTEM_PROMPT
+          .gsub("@@@GLOBAL_ADDITIONAL_INSTRUCTIONS@@@", instructions[:global] || "[NONE FOUND]")
+          .gsub("@@@PROJECT_ADDITIONAL_INSTRUCTIONS@@@", instructions[:project] || "[NONE FOUND]")
+          .gsub("@@@DATE@@@", `date`.strip)
+          .gsub("@@@UNAME@@@", @uname)
+          .gsub("@@@PWD@@@", @pwd)
+          .gsub("@@@LSR@@@", `ls -R`.strip)
+      }
+    end
+
+    def resolve_model
+      name = Config.read("ZEPHIRA_MODEL") || "gpt-5.4"
+      Models.find_by_name(name) || Models::Gpt54
+    end
+
+    def screen_width
+      TTY::Screen.width
+    rescue
+      80
+    end
+
+    def screen_height
+      TTY::Screen.height
+    rescue
+      24
+    end
+
+    def screen_rows
+      TTY::Screen.rows
+    rescue
+      24
+    end
+  end
+end

data/lib/zephira/backends/open_ai_compatible.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "fileutils"
+require "json"
+require "time"
+
+module Zephira
+  module Backends
+    class OpenAiCompatible
+      def self.name
+        "openai_compatible"
+      end
+
+      REQUEST_TIMEOUT = 300
+
+      def initialize(api_key:, base_url: nil)
+        @api_key = api_key
+        @base_url = base_url || "https://api.openai.com/v1"
+      end
+
+      def chat(model_name:, messages:, agent:, tools: nil, options: {})
+        payload = {
+          model: model_name,
+          messages: messages,
+          tools: tools
+        }.merge(options).compact
+
+        debug_log(payload, agent: agent) if Config.read("ZEPHIRA_DEBUG") == "true"
+
+        client = Faraday.new(
+          url: @base_url,
+          headers: {
+            "Authorization" => "Bearer #{@api_key}",
+            "Content-Type" => "application/json"
+          },
+          request: {timeout: REQUEST_TIMEOUT}
+        ) do |faraday|
+          faraday.request :json
+          faraday.response :raise_error
+          faraday.adapter Faraday.default_adapter
+        end
+
+        response = client.post("chat/completions", JSON.generate(payload))
+        raw = JSON.parse(response.body)
+
+        agent&.logger&.info "OpenAI API response: #{raw.inspect}"
+        raw.dig("choices", 0, "message") || {}
+      rescue => exception
+        agent&.logger&.error "OpenAI API request failed: #{exception.class}: #{exception.message}"
+        if exception.respond_to?(:response) && exception.response
+          agent&.logger&.error "Response status: #{exception.response[:status]}"
+          agent&.logger&.error "Response body: #{exception.response[:body]}"
+        end
+        raise
+      end
+
+      private
+
+      def debug_log(parameters, agent:)
+        log_dir = File.join(Dir.pwd, ".zephira", "logs")
+        FileUtils.mkdir_p(log_dir)
+        timestamp = Time.now.utc.strftime("%Y%m%dT%H%M%S%L")
+        filepath = File.join(log_dir, "#{timestamp}_openai_request.log")
+        File.write(filepath, JSON.pretty_generate({
+          timestamp: Time.now.utc.iso8601,
+          base_url: @base_url,
+          parameters: parameters
+        }))
+        agent&.logger&.debug "OpenAI request logged to: #{filepath}"
+      end
+    end
+  end
+end

data/lib/zephira/backends.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Zephira
+  module Backends
+    Dir[File.join(__dir__, "backends", "*.rb")].each { |file| require file }
+
+    def self.available
+      constants(false)
+        .map { |const| const_get(const) }
+        .select { |const| const.respond_to?(:name) && const.name.is_a?(String) }
+    end
+
+    def self.find_by_name(identifier)
+      available.find { |backend| backend.name == identifier }
+    end
+  end
+end

data/lib/zephira/cli.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module Zephira
+  class CLI
+    DANGEROUS_SKIP_SANDBOX_FLAG = "--dangerously-skip-sandbox"
+
+    def initialize(argv)
+      ENV["ZEPHIRA_SANDBOX"] = "false" if argv.include?(DANGEROUS_SKIP_SANDBOX_FLAG)
+      Zephira::Sandbox.exec_if_needed!(argv)
+      option_parser.parse!(argv)
+      Zephira::Agent.new.run_loop
+    rescue OptionParser::InvalidOption
+      puts option_parser
+      exit(1)
+    end
+
+    private
+
+    def option_parser
+      OptionParser.new do |opts|
+        opts.banner = "Usage: zephira [options]"
+
+        opts.on("-v", "--version", "Print the version") do
+          puts Zephira::VERSION
+          exit(0)
+        end
+
+        opts.on("-h", "--help", "Print this help") do
+          puts opts
+          exit(0)
+        end
+
+        opts.on(DANGEROUS_SKIP_SANDBOX_FLAG, "Skip sandbox and run without isolation") do
+          ENV["ZEPHIRA_SANDBOX"] = "false"
+        end
+      end
+    end
+  end
+end

data/lib/zephira/commands/about.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Zephira
+  class Commands
+    class About
+      class << self
+        def name
+          "about"
+        end
+
+        def description
+          "Display information about the agent"
+        end
+
+        def run(agent:, args:)
+          puts [
+            "Zephira: A toy coding agent",
+            "  Version: #{::Zephira::VERSION}",
+            "  https://github.com/aarongough/zephira",
+            "",
+            "Released under the MIT license."
+          ].join("\n")
+        end
+      end
+    end
+  end
+end

data/lib/zephira/commands/bye.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Zephira
+  class Commands
+    class Bye
+      class << self
+        def name
+          "bye"
+        end
+
+        def description
+          "End the session and close the agent"
+        end
+
+        def run(agent:, args:)
+          puts "Bye!"
+          exit(0)
+        end
+      end
+    end
+  end
+end

data/lib/zephira/commands/clear.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Zephira
+  class Commands
+    class Clear
+      USAGE = "Usage: /clear [session|all]"
+
+      class << self
+        def name
+          "clear"
+        end
+
+        def description
+          "Clear history: 'session' clears current session, 'all' clears everything"
+        end
+
+        def run(agent:, args:)
+          case args&.first
+          when "session"
+            agent.history.clear_session
+            puts "Session history cleared."
+          when "all"
+            agent.history.clear
+            puts "History cleared."
+          else
+            puts USAGE
+          end
+        end
+      end
+    end
+  end
+end

data/lib/zephira/commands/compact.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Zephira
+  class Commands
+    class Compact
+      class << self
+        def name
+          "compact"
+        end
+
+        def description
+          "Summarize older history to free up context"
+        end
+
+        def run(agent:, args:)
+          compacted = agent.compact_history(force: true)
+          puts "Nothing to compact." unless compacted
+        end
+      end
+    end
+  end
+end

data/lib/zephira/commands/help.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Zephira
+  class Commands
+    class Help
+      class << self
+        def name
+          "help"
+        end
+
+        def description
+          "Display this help information"
+        end
+
+        def run(agent:, args:)
+          lines = agent.commands.constants.map { |cmd| "  /#{cmd.name}: #{cmd.description}" }
+          puts "Available commands:\n#{lines.join("\n")}\n\n"
+        end
+      end
+    end
+  end
+end

data/lib/zephira/commands/history.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Zephira
+  class Commands
+    class History
+      class << self
+        def name
+          "history"
+        end
+
+        def description
+          "Display the conversation history"
+        end
+
+        def run(agent:, args:)
+          agent.history.messages.each do |message|
+            content = message[:content].to_s
+            content = "#{content.gsub("\n", "\\n").slice(0, 100)}..." if content.length > 100
+            puts "[#{message[:timestamp]}] #{message[:role]}: #{content}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/zephira/commands/model.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Zephira
+  class Commands
+    class Model
+      class << self
+        def name
+          "model"
+        end
+
+        def description
+          "List available models or switch: /model set MODEL_NAME"
+        end
+
+        def run(agent:, args:)
+          model_classes = Zephira::Models.available
+
+          if args.nil? || args.empty?
+            puts "Available models:"
+            model_classes.each do |model|
+              marker = (model == agent.model) ? "*" : " "
+              suffix = (model == agent.model) ? " (current)" : ""
+              puts "  #{marker} #{model.model_name}#{suffix}"
+            end
+            puts
+            return
+          end
+
+          parts = args.dup
+          parts.shift if parts.first.to_s.casecmp("set").zero?
+          model_name = parts.first
+
+          if model_name.nil? || model_name.strip.empty?
+            puts "Usage: /model set MODEL_NAME"
+            return
+          end
+
+          target = Zephira::Models.find_by_name(model_name)
+
+          if target
+            agent.model = target
+            puts "Model changed to #{target.model_name}"
+          else
+            puts "Unknown model '#{model_name}'. Available models:"
+            model_classes.each { |model| puts "    #{model.model_name}" }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/zephira/commands.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Zephira
+  class Commands
+    def self.load(paths:)
+      paths.each do |path|
+        Dir.glob(File.join(path, "**", "*.rb")).each { |file| require file }
+      end
+      new
+    end
+
+    def constants
+      @constants ||= ::Zephira::Commands.constants(false).map do |name|
+        ::Zephira::Commands.const_get(name)
+      end
+    end
+
+    def run(name:, args:, agent:)
+      command_class = constants.find { |command| command.name == name }
+      if command_class.nil?
+        puts "Unknown command '/#{name}'. Type /help for a list of commands."
+      else
+        command_class.run(agent: agent, args: args)
+      end
+    end
+
+    def to_h
+      constants.map { |command| {name: command.name, description: command.description} }
+    end
+  end
+end