zephira 0.1.0

data/lib/zephira/tools/memory_delete.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Zephira
+  class Tools
+    class MemoryDelete < BaseTool
+      class << self
+        def name
+          "memory_delete"
+        end
+
+        def description
+          "Delete a named key from persistent memory."
+        end
+
+        def parameters
+          {
+            type: "object",
+            properties: {
+              key: {type: "string", description: "Memory key to delete"},
+              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: ["key", "intent"]
+          }
+        end
+      end
+
+      def run
+        key = validate(arg(:key), arg_path: "key", type: String)
+
+        unless MemoryStore.delete(key)
+          return error_result(message: "Key not found: #{key}")
+        end
+
+        agent.status.verbose(" • Memory deleted: '#{key}'")
+        success_result("Memory deleted: '#{key}'")
+      end
+    end
+  end
+end

data/lib/zephira/tools/memory_list.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Zephira
+  class Tools
+    class MemoryList < BaseTool
+      class << self
+        def name
+          "memory_list"
+        end
+
+        def description
+          "List all stored memory keys."
+        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')."}
+            },
+            required: ["intent"]
+          }
+        end
+      end
+
+      def run
+        keys = MemoryStore.keys
+        agent.status.verbose(" • Memory list: #{keys.size} keys")
+        success_result(keys)
+      end
+    end
+  end
+end

data/lib/zephira/tools/memory_read.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Zephira
+  class Tools
+    class MemoryRead < BaseTool
+      class << self
+        def name
+          "memory_read"
+        end
+
+        def description
+          "Read a named value from persistent memory."
+        end
+
+        def read_only?
+          true
+        end
+
+        def parameters
+          {
+            type: "object",
+            properties: {
+              key: {type: "string", description: "Memory key to read"},
+              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: ["key", "intent"]
+          }
+        end
+      end
+
+      def run
+        key = validate(arg(:key), arg_path: "key", type: String)
+
+        unless MemoryStore.key?(key)
+          return error_result(message: "Key not found: #{key}")
+        end
+
+        agent.status.verbose(" • Memory read: '#{key}'")
+        success_result(MemoryStore.read(key))
+      end
+    end
+  end
+end

data/lib/zephira/tools/memory_store.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "yaml"
+
+module Zephira
+  class Tools
+    # Shared YAML-backed key/value store used by the memory_* tools. Values are
+    # always strings; loaded with safe_load to refuse arbitrary object
+    # deserialization since memory is agent/user-supplied content.
+    class MemoryStore
+      PATH = ".zephira/memory.yml"
+
+      def self.load
+        return {} unless ::File.exist?(PATH)
+        YAML.safe_load_file(PATH) || {}
+      end
+
+      def self.save(memory)
+        ::FileUtils.mkdir_p(::File.dirname(PATH))
+        ::File.write(PATH, memory.to_yaml)
+      end
+
+      def self.read(key)
+        load[key]
+      end
+
+      def self.write(key, value)
+        memory = load
+        memory[key] = value
+        save(memory)
+      end
+
+      def self.delete(key)
+        memory = load
+        return false unless memory.key?(key)
+        memory.delete(key)
+        save(memory)
+        true
+      end
+
+      def self.key?(key)
+        load.key?(key)
+      end
+
+      def self.keys
+        load.keys
+      end
+    end
+  end
+end

data/lib/zephira/tools/memory_write.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Zephira
+  class Tools
+    class MemoryWrite < BaseTool
+      class << self
+        def name
+          "memory_write"
+        end
+
+        def description
+          "Write a named value to persistent memory."
+        end
+
+        def parameters
+          {
+            type: "object",
+            properties: {
+              key: {type: "string", description: "Memory key"},
+              value: {type: "string", description: "Value to store"},
+              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: ["key", "value", "intent"]
+          }
+        end
+      end
+
+      def run
+        key = validate(arg(:key), arg_path: "key", type: String)
+        value = validate(arg(:value), arg_path: "value", type: String, allow_empty: true)
+
+        MemoryStore.write(key, value)
+
+        agent.status.verbose(" • Memory written: '#{key}'")
+        success_result("Memory written: '#{key}'")
+      end
+    end
+  end
+end

data/lib/zephira/tools/read_file.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Zephira
+  class Tools
+    class ReadFile < BaseTool
+      DEFAULT_MAX_BYTES = 20 * 1024
+
+      class << self
+        def name
+          "read_file"
+        end
+
+        def description
+          "Read the contents of one or more files (up to a size threshold)."
+        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')."
+              },
+              file_paths: {
+                type: "array",
+                items: {type: "string"},
+                description: "Paths to the files to read"
+              }
+            },
+            required: ["file_paths", "intent"]
+          }
+        end
+      end
+
+      def run
+        paths = validate(arg(:file_paths), arg_path: "file_paths", type: Array, allow_empty: false)
+
+        results = paths.map do |file_path|
+          if file_path.nil? || file_path.strip.empty?
+            agent.status.warn("`file_path` was empty or missing for entry")
+            {"path" => file_path, "content" => "", "error" => "`file_path` was empty or missing"}
+          else
+            expanded_path = ::File.expand_path(file_path)
+            begin
+              size = ::File.size(expanded_path)
+              agent.status.verbose(" • Reading file: '#{file_path}' (max #{DEFAULT_MAX_BYTES} bytes)")
+
+              data = if size > DEFAULT_MAX_BYTES
+                agent.status.verbose(" • File size #{size} bytes exceeds limit of #{DEFAULT_MAX_BYTES} bytes, truncating content")
+                ::File.open(expanded_path, "rb") { |file| file.read(DEFAULT_MAX_BYTES) }
+              else
+                ::File.binread(expanded_path)
+              end
+
+              content = normalize_content(data)
+              agent.status.verbose(" • Read file: '#{file_path}'")
+              agent.logger.info("Read file: '#{file_path}'")
+              {"path" => file_path, "content" => content}
+            rescue Errno::ENOENT
+              agent.status.warn(" • File not found: '#{file_path}'")
+              agent.logger.error("File not found: '#{file_path}'")
+              {"path" => file_path, "content" => "", "error" => "No such file or directory: #{file_path}"}
+            rescue Errno::EACCES
+              agent.status.warn(" • Permission denied: '#{file_path}'")
+              agent.logger.error("Permission denied: '#{file_path}'")
+              {"path" => file_path, "content" => "", "error" => "Permission denied: #{file_path}"}
+            rescue Errno::EISDIR
+              agent.status.warn(" • Is a directory: '#{file_path}'")
+              agent.logger.error("Is a directory: '#{file_path}'")
+              {"path" => file_path, "content" => "", "error" => "Is a directory: #{file_path}"}
+            end
+          end
+        end
+
+        success_result(results)
+      end
+
+      private
+
+      def normalize_content(data)
+        data.force_encoding(Encoding::UTF_8).scrub("?")
+      end
+    end
+  end
+end

data/lib/zephira/tools/shell.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Zephira
+  class Tools
+    class Shell < BaseTool
+      OUTPUT_TRUNCATION_WIDTH = 200
+      TRUNCATION_OVERHEAD = 23
+
+      class << self
+        def name
+          "shell"
+        end
+
+        def description
+          "Run a shell command"
+        end
+
+        def parameters
+          {
+            type: "object",
+            properties: {
+              command: {type: "string", description: "Command to run"},
+              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: ["command", "intent"]
+          }
+        end
+      end
+
+      def run
+        cmd = validate(arg(:command), arg_path: "command", type: String, allow_empty: false)
+
+        agent.status.verbose(" • Running shell command: '#{cmd}'")
+        stdout_str, stderr_str, status_obj = Open3.capture3(cmd, chdir: Dir.pwd)
+
+        unless stdout_str.to_s.empty?
+          message = truncate_string_to_fit(
+            prefix: " • Shell command stdout: ",
+            text_array: stdout_str.lines,
+            max_characters: OUTPUT_TRUNCATION_WIDTH
+          )
+          agent.status.verbose(message)
+        end
+
+        unless stderr_str.to_s.empty?
+          message = truncate_string_to_fit(
+            prefix: " • \e[91mShell command stderr:\e[0m ",
+            text_array: stderr_str.lines,
+            max_characters: OUTPUT_TRUNCATION_WIDTH
+          )
+          agent.status.verbose(message)
+        end
+
+        agent.status.verbose(" • Shell command completed with exit status: #{status_obj.exitstatus}")
+        success_result(status: status_obj.exitstatus, stdout: stdout_str, stderr: stderr_str)
+      rescue Errno::ENOENT
+        error_result(message: "Command not found: #{arg(:command)}")
+      end
+
+      private
+
+      def truncate_string_to_fit(prefix:, text_array:, max_characters:)
+        postfix = " ... (~#{text_array.size - 1} more lines)"
+        overhead = prefix.length + postfix.length + TRUNCATION_OVERHEAD
+        available_length = max_characters - overhead
+
+        sanitized = text_array.join
+          .gsub(/\e\[[\d;?]*[@-~]/, "")
+          .delete("\e")
+          .gsub(/\r?\n/, " ")
+
+        full = prefix + sanitized
+        return full if full.length <= max_characters
+
+        truncated = sanitized[0, available_length]
+        prefix + truncated + postfix
+      end
+    end
+  end
+end

data/lib/zephira/tools/update_file.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Zephira
+  class Tools
+    class UpdateFile < BaseTool
+      class << self
+        def name
+          "update_file"
+        end
+
+        def description
+          "Update or create a file by providing the full replacement content."
+        end
+
+        def parameters
+          {
+            type: "object",
+            properties: {
+              content: {type: "string", description: "Full replacement file text"},
+              file_path: {type: "string", description: "Path to the file to be updated or created"},
+              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: ["content", "file_path", "intent"]
+          }
+        end
+      end
+
+      def run
+        content = validate(arg(:content), arg_path: "content", type: String, allow_empty: true)
+        file_path = validate(arg(:file_path), arg_path: "file_path", type: String)
+
+        agent.status.verbose(" • Updating file: '#{file_path}'")
+
+        ::FileUtils.mkdir_p(::File.dirname(file_path))
+        ::File.write(file_path, content)
+
+        msg = "Updated file: '#{file_path}'"
+        agent.status.verbose(" • #{msg}")
+        agent.logger.info(msg)
+        success_result(msg)
+      end
+    end
+  end
+end

data/lib/zephira/tools/web_search.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "uri"
+require "net/http"
+require "json"
+
+module Zephira
+  class Tools
+    class WebSearch < BaseTool
+      class << self
+        def name
+          "web_search"
+        end
+
+        def description
+          "Performs a web search using the Brave Search API."
+        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')."
+              },
+              queries: {
+                type: "array",
+                description: "An array of search query instructions",
+                items: {
+                  type: "object",
+                  properties: {
+                    query: {
+                      type: "string",
+                      description: "The string to search for"
+                    },
+                    num_results: {
+                      type: "integer",
+                      description: "Maximum number of results to return (1-50)",
+                      minimum: 1,
+                      maximum: 50
+                    }
+                  },
+                  required: ["query", "num_results"],
+                  additionalProperties: false
+                }
+              }
+            },
+            required: ["intent", "queries"]
+          }
+        end
+      end
+
+      def run
+        queries = validate(arg(:queries), arg_path: "queries", type: Array, allow_empty: false)
+
+        api_key = Config.read("ZEPHIRA_BRAVE_SEARCH_API_KEY").to_s
+        if api_key.strip.empty?
+          return error_result(message: "ZEPHIRA_BRAVE_SEARCH_API_KEY not set (env var or .zephira.yml)")
+        end
+
+        results = queries.map { |query| run_query(query, api_key) }
+        success_result(results)
+      end
+
+      private
+
+      def run_query(query_args, api_key)
+        query = query_args["query"] || query_args[:query]
+        num_results = query_args["num_results"] || query_args[:num_results]
+
+        unless query.is_a?(String) && !query.strip.empty?
+          return error_result(message: "`query` must be a non-empty string")
+        end
+
+        if num_results && (!num_results.is_a?(Integer) || !(1..50).include?(num_results))
+          return error_result(message: "`num_results` must be an integer between 1 and 50")
+        end
+
+        agent.update_status("    Web search: '#{query}'")
+
+        uri = URI("https://api.search.brave.com/res/v1/web/search")
+        params = {"q" => query}
+        params["count"] = num_results if num_results
+        uri.query = URI.encode_www_form(params)
+
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = true
+        response = http.get(uri.request_uri, {"Accept" => "application/json", "X-Subscription-Token" => api_key})
+
+        if response.code.to_i >= 300
+          agent.status.warn(" • ERROR: '#{query}' search failed (#{response.code})")
+          agent.logger.error("Search failed: '#{query}' (#{response.code})")
+          return error_result(message: "Search failed with status #{response.code}")
+        end
+
+        begin
+          data = JSON.parse(response.body)
+          agent.status.verbose(" • Search complete: '#{query}'")
+          agent.logger.info("Search complete: '#{query}'")
+          success_result(data)
+        rescue JSON::ParserError => error
+          agent.status.warn(" • ERROR: Invalid JSON for '#{query}'")
+          error_result(message: "Invalid JSON: #{error.message}")
+        end
+      end
+    end
+  end
+end

data/lib/zephira/tools.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Zephira
+  class Tools
+    class ToolNotFoundError < StandardError; end
+    class ToolExecutionError < StandardError; end
+    class ToolResultError < StandardError; end
+
+    def self.load(paths:)
+      paths.each do |path|
+        Dir.glob(File.join(path, "**", "*.rb")).each do |file|
+          require File.expand_path(file)
+        end
+      end
+      new
+    end
+
+    def constants
+      @constants ||= ::Zephira::Tools.constants(false)
+        .map { |const_sym| ::Zephira::Tools.const_get(const_sym) }
+        .select { |const| const.is_a?(Class) && const < ::Zephira::Tools::BaseTool }
+    end
+
+    def to_h
+      constants.map do |tool|
+        {
+          name: tool.name,
+          description: tool.description,
+          parameters: tool.parameters
+        }
+      end
+    end
+
+    def run(name:, args:, agent:)
+      tool = find!(name)
+
+      result = begin
+        tool.run(args: args, agent: agent)
+      rescue => exception
+        raise ToolExecutionError, "Encountered an error when executing tool #{name}: #{exception.message}"
+      end
+
+      validate_result(result)
+      result
+    end
+
+    def read_only?(name)
+      tool = constants.find { |candidate| candidate.name == name }
+      tool && tool.respond_to?(:read_only?) && tool.read_only?
+    end
+
+    def find!(name)
+      tool = constants.find { |candidate| candidate.name == name }
+      raise ToolNotFoundError, "Tool not found: #{name}" if tool.nil?
+      tool
+    end
+
+    private
+
+    def validate_result(result)
+      unless result.is_a?(Hash) && result.key?(:outcome) && result.key?(:error) && result.key?(:data)
+        raise ToolResultError, "Tool result must be a hash with keys :outcome, :error, and :data. Got: #{result.inspect}"
+      end
+
+      unless %w[success error].include?(result[:outcome])
+        raise ToolResultError, "Tool result :outcome must be 'success' or 'error'. Got: #{result[:outcome].inspect}"
+      end
+    end
+  end
+end

data/lib/zephira/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Zephira
+  VERSION = "0.1.0"
+end

data/lib/zephira.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative "zephira/version"
+require_relative "zephira/config"
+require_relative "zephira/sandbox"
+require_relative "zephira/formatter"
+require_relative "zephira/tokens"
+require_relative "zephira/logger"
+require_relative "zephira/backends"
+require_relative "zephira/models"
+require_relative "zephira/tools"
+require_relative "zephira/tools/base_tool"
+Dir[File.join(__dir__, "zephira/tools/*.rb")].each { |file| require file }
+require_relative "zephira/history"
+require_relative "zephira/commands"
+Dir[File.join(__dir__, "zephira/commands/*.rb")].each { |file| require file }
+require_relative "zephira/completions"
+Dir[File.join(__dir__, "zephira/completions/*.rb")].each { |file| require file }
+require_relative "zephira/agent"
+require_relative "zephira/agent/status"
+require_relative "zephira/cli"
+
+module Zephira
+end

data/license.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Aaron Gough
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/standard.yml

@@ -0,0 +1,3 @@
+# For available configuration options, see:
+#   https://github.com/testdouble/standard
+ruby_version: 3.4