zephira 0.1.0

data/lib/zephira/sandbox.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+require "tempfile"
+require "io/console"
+
+module Zephira
+  class Sandbox
+    GHCR_IMAGE           = "ghcr.io/aarongough/zephira"
+    DERIVED_IMAGE_PREFIX = "zephira-sandbox"
+
+    FORWARDED_ENV_PATTERNS = [/\AZEPHIRA_/].freeze
+    FORWARDED_ENV_EXCLUDES = %w[ZEPHIRA_IN_SANDBOX ZEPHIRA_SANDBOX].freeze
+
+    OUTER_TL = "╔"
+    OUTER_TR = "╗"
+    OUTER_BL = "╚"
+    OUTER_BR = "╝"
+    OUTER_H  = "═"
+    OUTER_V  = "║"
+
+    INNER_TL = "┌"
+    INNER_TR = "┐"
+    INNER_BL = "└"
+    INNER_BR = "┘"
+    INNER_H  = "─"
+    INNER_V  = "│"
+    INNER_PADDING = 3
+
+    class << self
+      def exec_if_needed!(argv)
+        return if ENV["ZEPHIRA_IN_SANDBOX"] == "1"
+        return if ENV["ZEPHIRA_SANDBOX"] == "false"
+
+        abort_with_sandbox_error unless docker_available?
+
+        target = resolve_image
+        $stderr.puts "[Zephira] Launching in Docker sandbox (#{target})..."
+        Kernel.exec(*build_docker_command(argv, target))
+      end
+
+      private
+
+      def abort_with_sandbox_error
+        width = terminal_width
+
+        warn_lines = [
+          "",
+          "#{Formatter.color(:red, "⚠")}  #{Formatter.color(:red, "WARNING:")} Without the sandbox the agent has direct access to",
+          "your host filesystem. Files it creates, modifies, or deletes",
+          "affect your real system with no isolation or undo. Only skip",
+          "the sandbox if you understand and accept this risk.",
+          ""
+        ]
+
+        instruction_lines = [
+          "",
+          "  #{Formatter.color(:red, "ERROR:")} Zephira requires Docker to run safely in a sandboxed environment.",
+          "",
+          "  Docker was not found or is not currently running. To fix this:",
+          "",
+          "    1. Install Docker Desktop:  https://docs.docker.com/get-docker/",
+          "    2. Start Docker and confirm it is running:  docker info",
+          "",
+          "  To bypass the sandbox (not recommended):",
+          "",
+          "    zephira --dangerously-skip-sandbox",
+          ""
+        ]
+
+        max_warn_width    = warn_lines.map { |line| visible_length(line) }.max
+        max_content_width = instruction_lines.map { |line| visible_length(line) }.max
+        inner_width       = [max_warn_width, max_content_width - 10].max
+
+        inner_box = [
+          "  " + inner_top(inner_width),
+          *warn_lines.map { |line| "  " + inner_row(line, inner_width) },
+          "  " + inner_bottom(inner_width)
+        ]
+
+        content = [*instruction_lines, *inner_box, ""]
+
+        [
+          outer_top(width),
+          *content.map { |line| outer_row(line, width) },
+          outer_bottom(width),
+          ""
+        ].each { |line| $stderr.puts line }
+        exit(1)
+      end
+
+      def outer_top(width)
+        Formatter.color(:red, OUTER_TL + OUTER_H * (width - 2) + OUTER_TR)
+      end
+
+      def outer_bottom(width)
+        Formatter.color(:red, OUTER_BL + OUTER_H * (width - 2) + OUTER_BR)
+      end
+
+      def outer_row(text, width)
+        padding = " " * [width - 2 - visible_length(text), 0].max
+        Formatter.color(:red, OUTER_V) + text + padding + Formatter.color(:red, OUTER_V)
+      end
+
+      def inner_top(max_width)
+        Formatter.color(:red, INNER_TL + INNER_H * (max_width + INNER_PADDING * 2) + INNER_TR)
+      end
+
+      def inner_bottom(max_width)
+        Formatter.color(:red, INNER_BL + INNER_H * (max_width + INNER_PADDING * 2) + INNER_BR)
+      end
+
+      def inner_row(text, max_width)
+        padding = " " * [max_width - visible_length(text), 0].max
+        pad = " " * INNER_PADDING
+        Formatter.color(:red, INNER_V) + pad + text + padding + pad + Formatter.color(:red, INNER_V)
+      end
+
+      def visible_length(str)
+        str.gsub(/\e\[[0-9;]*m/, "").length
+      end
+
+      def terminal_width
+        IO.console&.winsize&.last || 80
+      rescue StandardError
+        80
+      end
+
+      def docker_available?
+        system("docker info > /dev/null 2>&1")
+      end
+
+      def resolve_image
+        base = Config.read("ZEPHIRA_BASE_IMAGE")
+        return "#{GHCR_IMAGE}:#{VERSION}" unless base
+
+        derived = derived_image_name(base)
+        unless image_exists?(derived)
+          $stderr.puts "[Zephira] Building sandbox image from #{base}..."
+          build_derived_image(base, derived)
+        end
+        derived
+      end
+
+      def derived_image_name(base_image)
+        sanitized = base_image.gsub(/[^a-zA-Z0-9._-]/, "-")
+        "#{DERIVED_IMAGE_PREFIX}-#{sanitized}:#{VERSION}"
+      end
+
+      def image_exists?(name)
+        system("docker image inspect #{name} > /dev/null 2>&1")
+      end
+
+      def build_derived_image(base_image, target_name)
+        dockerfile = "FROM #{base_image}\nRUN gem install zephira:#{VERSION} --no-document\n"
+        Tempfile.create(["zephira-sandbox", ".dockerfile"]) do |file|
+          file.write(dockerfile)
+          file.flush
+          system("docker build -t #{target_name} -f #{file.path} .")
+        end
+      end
+
+      def forwarded_env_keys
+        ENV.keys
+          .reject { |key| FORWARDED_ENV_EXCLUDES.include?(key) }
+          .select { |key| FORWARDED_ENV_PATTERNS.any? { |pattern| key.match?(pattern) } }
+          .sort
+      end
+
+      def build_docker_command(argv, image)
+        cmd = ["docker", "run", "--rm", "-i"]
+        cmd << "-t" if $stdout.tty?
+
+        cmd += ["-e", "ZEPHIRA_IN_SANDBOX=1"]
+        cmd += ["-v", "#{Dir.pwd}:/workspace:rw"]
+
+        global_config = File.expand_path("~/.zephira.yml")
+        cmd += ["-v", "#{global_config}:/root/.zephira.yml:ro"] if File.exist?(global_config)
+
+        global_dir = File.expand_path("~/.zephira")
+        cmd += ["-v", "#{global_dir}:/root/.zephira:ro"] if File.exist?(global_dir) && File.directory?(global_dir)
+
+        forwarded_env_keys.each do |key|
+          cmd += ["-e", "#{key}=#{ENV[key]}"]
+        end
+
+        cmd += ["-w", "/workspace"]
+        cmd << image
+        cmd += ["zephira"] + argv
+        cmd
+      end
+    end
+  end
+end

data/lib/zephira/tokens.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Zephira
+  # Approximates token counts for arbitrary text without pulling in a real
+  # tokenizer dependency. Counts word-like runs and standalone punctuation,
+  # which lands within ~20% of real BPE tokenizers (GPT/Claude) for English
+  # text — close enough for context-budget decisions, never trust for billing.
+  module Tokens
+    TOKEN_PATTERN = /\w+|[^\s\w]/.freeze
+
+    def self.estimate(text)
+      return 0 if text.nil? || text.empty?
+      text.to_s.scan(TOKEN_PATTERN).size
+    end
+  end
+end

data/lib/zephira/tools/base_tool.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Zephira
+  class Tools
+    class BaseTool
+      class ToolUseError < StandardError; end
+
+      attr_reader :args, :agent
+
+      def initialize(args:, agent:)
+        @args = args
+        @agent = agent
+      end
+
+      def arg(name)
+        @args[name] || @args[name.to_s]
+      end
+
+      def validate(actual, arg_path:, type:, allow_nil: false, allow_empty: false)
+        if !allow_nil && actual.nil?
+          raise ToolUseError, "argument `#{arg_path}` must be supplied"
+        end
+
+        unless actual.is_a?(type)
+          raise ToolUseError, "argument `#{arg_path}` must be of type #{type} and non-empty"
+        end
+
+        if !allow_empty && type == String && actual.strip.empty?
+          raise ToolUseError, "argument `#{arg_path}` must be of type #{type} and non-empty"
+        end
+
+        if !allow_empty && actual.respond_to?(:empty?) && actual.empty?
+          raise ToolUseError, "argument `#{arg_path}` must be of type #{type} and non-empty"
+        end
+
+        actual
+      end
+
+      def run
+        raise NotImplementedError, "This method should be overridden in a subclass"
+      end
+
+      def error_result(message:)
+        {outcome: "error", error: message, data: nil}
+      end
+
+      def success_result(data)
+        {outcome: "success", error: nil, data: data}
+      end
+
+      class << self
+        def run(args:, agent:)
+          result = begin
+            tool_instance = new(args: args, agent: agent)
+            intent_value = tool_instance.arg(:intent)
+            tool_instance.validate(intent_value, arg_path: "args[:intent]", type: String)
+            agent.update_status(Formatter.color(:green, "→ ") + intent_value) if announces_intent?
+            tool_instance.run
+          rescue => exception
+            log_message = "Tool call `#{name}` with args `#{args.inspect}` returned error: #{exception.message}"
+            agent.logger.warn(log_message)
+            agent.status.warn("ERROR: Tool call `#{name}` returned error: #{exception.message}")
+            return {outcome: "error", error: exception.message, data: nil}
+          end
+
+          if result[:outcome] == "success"
+            agent.logger.info("Tool call `#{name}` with args `#{args.inspect}` completed successfully: #{result[:data]}")
+            agent.status.verbose("Tool call `#{name}` completed successfully")
+          elsif result[:outcome] == "error"
+            agent.logger.warn("Tool call `#{name}` with args `#{args.inspect}` returned error: #{result[:error]}")
+            agent.status.warn("ERROR: Tool call `#{name}` returned error: #{result[:error]}")
+          end
+
+          result
+        end
+
+        def name
+          raise NotImplementedError, "This method should be overridden in a subclass"
+        end
+
+        def description
+          raise NotImplementedError, "This method should be overridden in a subclass"
+        end
+
+        def parameters
+          raise NotImplementedError, "This method should be overridden in a subclass"
+        end
+
+        # Override and return true in read-only tools so the agent can run them
+        # concurrently. Anything that mutates filesystem, network state, memory
+        # store, or agent state must remain false (the default).
+        def read_only?
+          false
+        end
+
+        # Override to false in tools that emit their own per-item status lines
+        # (e.g. one line per query). Suppresses the auto-printed `→ intent`
+        # line that BaseTool.run emits before #run.
+        def announces_intent?
+          true
+        end
+      end
+    end
+  end
+end

data/lib/zephira/tools/code_search.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require "open3"
+require "json"
+
+module Zephira
+  class Tools
+    class CodeSearch < BaseTool
+      class << self
+        def name
+          "code_search"
+        end
+
+        def description
+          "Search codebase for symbols or patterns"
+        end
+
+        def read_only?
+          true
+        end
+
+        def parameters
+          {
+            type: "object",
+            properties: {
+              queries: {
+                type: "array",
+                items: {
+                  type: "object",
+                  properties: {
+                    query: {type: "string", description: "String to search for"},
+                    path: {type: "string", description: "Directory path to search"},
+                    case_sensitive: {type: "boolean", description: "Enable case-sensitive search"},
+                    max_results: {type: "integer", description: "Maximum number of results"}
+                  },
+                  required: ["query", "path"]
+                }
+              },
+              intent: {
+                type: "string",
+                description: "Brief summary of intent of the operation, meant to be used for context compaction and presentation to the user. Use active voice (e.g., 'Reading X to do Y')."
+              }
+            },
+            required: ["queries", "intent"]
+          }
+        end
+      end
+
+      def run
+        queries = arg(:queries)
+        unless queries.is_a?(Array) && !queries.empty?
+          return error_result(message: "argument `queries` must be a non-empty array")
+        end
+
+        results = queries.map { |query_args| run_query(query_args) }
+        success_result(results)
+      end
+
+      private
+
+      def run_query(query_args)
+        query = query_args[:query] || query_args["query"]
+        path = query_args[:path] || query_args["path"]
+        case_sensitive = query_args[:case_sensitive] || query_args["case_sensitive"]
+        max_results = query_args[:max_results] || query_args["max_results"]
+
+        return error_result(message: "Path must be provided") if path.nil? || path.to_s.strip.empty?
+
+        expanded_path = ::File.expand_path(path.to_s)
+        return error_result(message: "Path not found: #{expanded_path}") unless ::Dir.exist?(expanded_path)
+
+        return error_result(message: "Query must be a non-empty string") if query.nil? || !query.is_a?(String) || query.strip.empty?
+        return error_result(message: "ripgrep (rg) not found") unless executable_available?("rg")
+
+        agent.status.verbose(" • Text search for '#{query}' in '#{path}'")
+
+        cmd = ["rg", "--json", "-C", "2", "-n"]
+        cmd << "-i" unless case_sensitive
+        cmd << query
+        cmd << expanded_path
+
+        stdout, stderr, status = Open3.capture3(*cmd)
+        return error_result(message: "ripgrep failed: #{stderr.strip}") unless status.success?
+
+        results = parse_rg_output(stdout, max_results)
+        agent.status.verbose(" • Code search completed: found #{results.size} matches")
+        success_result(results)
+      end
+
+      def parse_rg_output(stdout, max_results)
+        results = []
+        context_buffer = []
+        current_file = nil
+
+        stdout.each_line do |line|
+          data = begin
+            JSON.parse(line)
+          rescue JSON::ParserError
+            next
+          end
+
+          case data["type"]
+          when "begin"
+            current_file = data.dig("data", "path", "text")
+            context_buffer = []
+          when "match"
+            context_buffer << {
+              file: current_file,
+              line: data["data"]["line_number"],
+              content: data["data"]["lines"]["text"],
+              match: true
+            }
+          when "context"
+            context_buffer << {
+              file: current_file,
+              line: data["data"]["line_number"],
+              content: data["data"]["lines"]["text"],
+              match: false
+            }
+          when "end"
+            results << context_buffer.sort_by { |entry| entry[:line] }
+            break if max_results && results.size >= max_results
+          end
+        end
+
+        results
+      end
+
+      def executable_available?(cmd)
+        _, _, status = Open3.capture3("command", "-v", cmd)
+        status.success?
+      end
+    end
+  end
+end

data/lib/zephira/tools/delete_file.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Zephira
+  class Tools
+    class DeleteFile < BaseTool
+      class << self
+        def name
+          "delete_file"
+        end
+
+        def description
+          "Delete a file or directory and its contents."
+        end
+
+        def parameters
+          {
+            type: "object",
+            properties: {
+              intent: {type: "string", description: "Brief summary of intent of the operation, meant to be used for context compaction and presentation to the user. Use active voice (e.g., 'Reading X to do Y')."},
+              file_path: {type: "string", description: "Path to the file or directory to delete"}
+            },
+            required: ["file_path", "intent"]
+          }
+        end
+      end
+
+      def run
+        path = validate(arg(:file_path), arg_path: "file_path", type: String)
+
+        agent.status.verbose(" • Deleting file or directory: '#{path}'")
+
+        expanded = ::File.expand_path(path)
+        begin
+          ::FileUtils.rm_rf(expanded)
+        rescue Errno::EACCES
+          return error_result(message: "Permission denied: #{path}")
+        end
+
+        agent.status.verbose(" • File or dir deleted: '#{path}'")
+        agent.logger.info("File or dir deleted: '#{path}'")
+        success_result("File or dir deleted: '#{path}'")
+      end
+    end
+  end
+end

data/lib/zephira/tools/http_request.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+
+module Zephira
+  class Tools
+    class HttpRequest < BaseTool
+      class << self
+        def name
+          "http_request"
+        end
+
+        def description
+          "Perform HTTP requests: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS"
+        end
+
+        def parameters
+          {
+            type: "object",
+            properties: {
+              intent: {
+                type: "string",
+                description: "Brief summary of intent of the operation, meant to be used for context compaction and presentation to the user. Use active voice (e.g., 'Reading X to do Y')."
+              },
+              method: {
+                type: "string",
+                enum: ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]
+              },
+              url: {
+                type: "string",
+                description: "Request URL"
+              },
+              headers: {
+                type: "object",
+                description: "Request headers as key-value pairs"
+              },
+              query: {
+                type: "object",
+                description: "Query parameters as key-value pairs"
+              },
+              body: {
+                type: ["string", "object"],
+                description: "Request body as string or JSON object"
+              },
+              timeout: {
+                type: "number",
+                description: "Timeout in seconds for open/read"
+              }
+            },
+            required: ["intent", "method", "url"]
+          }
+        end
+      end
+
+      def run
+        http_method = arg(:method)
+        url = arg(:url)
+        headers = arg(:headers) || {}
+        query = arg(:query) || {}
+        body = arg(:body)
+        timeout = arg(:timeout)
+
+        uri = URI.parse(url)
+        uri.query = URI.encode_www_form(query) if query.is_a?(Hash) && !query.empty?
+
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = (uri.scheme == "https")
+        http.open_timeout = timeout if timeout
+        http.read_timeout = timeout if timeout
+
+        request_class =
+          case http_method.to_s.upcase
+          when "GET" then Net::HTTP::Get
+          when "POST" then Net::HTTP::Post
+          when "PUT" then Net::HTTP::Put
+          when "PATCH" then Net::HTTP::Patch
+          when "DELETE" then Net::HTTP::Delete
+          when "HEAD" then Net::HTTP::Head
+          when "OPTIONS" then Net::HTTP::Options
+          else
+            return error_result(message: "Unsupported HTTP method: #{http_method}")
+          end
+
+        req = request_class.new(uri)
+        headers.each { |key, value| req[key] = value.to_s }
+
+        if body
+          if body.is_a?(Hash)
+            req.body = body.to_json
+            req["Content-Type"] ||= "application/json"
+          else
+            req.body = body.to_s
+          end
+        end
+
+        agent.status.verbose(" • #{http_method} #{url}")
+        response = http.request(req)
+        agent.status.verbose(" • Response: #{response.code}")
+        agent.logger.info("#{http_method} #{url} -> #{response.code}")
+
+        charset = response.type_params["charset"] || "UTF-8"
+        body = response.body.to_s.dup.force_encoding(charset)
+        body = body.encode("UTF-8", invalid: :replace, undef: :replace, replace: "?")
+
+        success_result(status: response.code.to_i, headers: response.each_header.to_h, body: body)
+      rescue => error
+        error_result(message: error.message)
+      end
+    end
+  end
+end

data/lib/zephira/tools/list_directory.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Zephira
+  class Tools
+    class ListDirectory < BaseTool
+      class << self
+        def name
+          "list_directory"
+        end
+
+        def description
+          "List the contents of a directory."
+        end
+
+        def read_only?
+          true
+        end
+
+        def parameters
+          {
+            type: "object",
+            properties: {
+              intent: {
+                type: "string",
+                description: "Brief summary of intent of the operation, meant to be used for context compaction and presentation to the user. Use active voice (e.g., 'Reading X to do Y')."
+              },
+              directory_path: {
+                type: "string",
+                description: "Path to the directory to list"
+              }
+            },
+            required: ["directory_path", "intent"]
+          }
+        end
+      end
+
+      def run
+        dir_path = arg(:directory_path)
+        if dir_path.nil? || dir_path.strip.empty?
+          return error_result(message: "`directory_path` was empty or missing")
+        end
+
+        agent.status.verbose(" • Listing directory contents: '#{dir_path}'")
+        expanded_path = ::File.expand_path(dir_path)
+        entries = Dir.children(expanded_path)
+
+        agent.status.verbose(" • Directory contents listed: #{entries.size} entries in '#{dir_path}'")
+        agent.logger.info("Listing directory contents: '#{dir_path}'")
+        success_result(entries)
+      rescue Errno::ENOENT
+        error_result(message: "Directory not found: '#{dir_path}'")
+      rescue Errno::EACCES
+        error_result(message: "Permission denied: #{dir_path}")
+      end
+    end
+  end
+end