llm_gateway 0.6.0 → 0.8.0

data/lib/llm_gateway/agents/tools/read_tool.rb

@@ -0,0 +1,143 @@
+require "base64"
+require_relative "tool_utils"
+
+class ReadTool < LlmGateway::Tool
+  # Pi adaptation notes:
+  # - Keep offset/limit schema as integer: gruv treats integer and number schemas equivalently for line counts.
+  # - Do not add pi's image resize/model-omission behavior: current LLMs allow larger images than pi's conservative limit, and gruv tools do not receive model capability context.
+  # - Do not add pi's compact read UI, pluggable operations, AbortSignal handling, or details metadata: those are UI/runtime extension concerns outside this tool contract.
+  name "read"
+  description "Read the contents of a file. Supports text files and images (jpg, png, gif, webp). Images are sent as attachments. For text files, output is truncated to #{ToolUtils::DEFAULT_MAX_LINES} lines or #{ToolUtils::DEFAULT_MAX_BYTES / 1024}KB (whichever is hit first). Use offset/limit for large files. When you need the full file, continue with offset until complete."
+  input_schema({
+    type: "object",
+    properties: {
+      path: { type: "string", description: "Path to the file to read (relative or absolute)" },
+      offset: { type: "integer", description: "Line number to start reading from (1-indexed)" },
+      limit: { type: "integer", description: "Maximum number of lines to read" }
+    },
+    required: [ "path" ]
+  })
+
+  IMAGE_TYPE_SNIFF_BYTES = 4100
+  PNG_SIGNATURE = [ 0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a ].freeze
+
+  def execute(input)
+    path = input[:path] || input["path"]
+    offset = input[:offset] || input["offset"]
+    limit = input[:limit] || input["limit"]
+
+    absolute_path = ToolUtils.resolve_read_path(path)
+
+    return "File not found: #{path}" unless File.exist?(absolute_path)
+    return "Cannot read directory: #{path}" if File.directory?(absolute_path)
+    return "File is not readable: #{path}" unless File.readable?(absolute_path)
+
+    mime_type = detect_supported_image_mime_type_from_file(absolute_path)
+    if mime_type
+      data = Base64.strict_encode64(File.binread(absolute_path))
+      return [
+        { type: "text", text: "Read image file [#{mime_type}]" },
+        { type: "image", data: data, media_type: mime_type }
+      ]
+    end
+
+    content = File.read(absolute_path, mode: "r:bom|utf-8")
+    all_lines = content.split("\n", -1)
+    total_file_lines = all_lines.length
+
+    start_line = [ 0, (offset || 1).to_i - 1 ].max
+    return "Offset #{offset} is beyond end of file (#{all_lines.length} lines total)" if start_line >= all_lines.length
+
+    selected_content = if limit
+      end_line = [ start_line + limit.to_i, all_lines.length ].min
+      all_lines[start_line...end_line].join("\n")
+    else
+      all_lines[start_line..].join("\n")
+    end
+
+    truncation = ToolUtils.truncate_head(selected_content)
+    start_display = start_line + 1
+
+    if truncation[:first_line_exceeds_limit]
+      first_line_size = ToolUtils.format_size(all_lines[start_line].to_s.bytesize)
+      return "[Line #{start_display} is #{first_line_size}, exceeds #{ToolUtils.format_size(ToolUtils::DEFAULT_MAX_BYTES)} limit. Use bash: sed -n '#{start_display}p' #{path} | head -c #{ToolUtils::DEFAULT_MAX_BYTES}]"
+    end
+
+    output = truncation[:content]
+
+    if truncation[:truncated]
+      end_display = start_display + truncation[:output_lines] - 1
+      next_offset = end_display + 1
+      suffix = if truncation[:truncated_by] == "lines"
+        "[Showing lines #{start_display}-#{end_display} of #{total_file_lines}. Use offset=#{next_offset} to continue.]"
+      else
+        "[Showing lines #{start_display}-#{end_display} of #{total_file_lines} (#{ToolUtils.format_size(ToolUtils::DEFAULT_MAX_BYTES)} limit). Use offset=#{next_offset} to continue.]"
+      end
+      output = "#{output}\n\n#{suffix}"
+    elsif limit && (start_line + limit.to_i) < all_lines.length
+      next_offset = start_line + limit.to_i + 1
+      remaining = all_lines.length - (start_line + limit.to_i)
+      output = "#{output}\n\n[#{remaining} more lines in file. Use offset=#{next_offset} to continue.]"
+    end
+
+    output
+  rescue StandardError => e
+    "Error reading file: #{e.message}"
+  end
+
+  private
+
+  def detect_supported_image_mime_type_from_file(path)
+    detect_supported_image_mime_type(File.binread(path, IMAGE_TYPE_SNIFF_BYTES))
+  end
+
+  def detect_supported_image_mime_type(buffer)
+    bytes = buffer.bytes
+    return "image/jpeg" if jpeg?(bytes)
+    return "image/png" if png?(bytes) && !animated_png?(bytes)
+    return "image/gif" if ascii_at?(bytes, 0, "GIF")
+    return "image/webp" if ascii_at?(bytes, 0, "RIFF") && ascii_at?(bytes, 8, "WEBP")
+
+    nil
+  end
+
+  def jpeg?(bytes)
+    bytes.length >= 4 && bytes[0] == 0xff && bytes[1] == 0xd8 && bytes[2] == 0xff && bytes[3] != 0xf7
+  end
+
+  def png?(bytes)
+    starts_with?(bytes, PNG_SIGNATURE) && bytes.length >= 16 && read_uint32_be(bytes, PNG_SIGNATURE.length) == 13 && ascii_at?(bytes, 12, "IHDR")
+  end
+
+  def animated_png?(bytes)
+    offset = PNG_SIGNATURE.length
+    while offset + 8 <= bytes.length
+      chunk_length = read_uint32_be(bytes, offset)
+      chunk_type_offset = offset + 4
+      return true if ascii_at?(bytes, chunk_type_offset, "acTL")
+      return false if ascii_at?(bytes, chunk_type_offset, "IDAT")
+
+      next_offset = offset + 8 + chunk_length + 4
+      return false if next_offset <= offset || next_offset > bytes.length
+
+      offset = next_offset
+    end
+    false
+  end
+
+  def read_uint32_be(bytes, offset)
+    ((bytes[offset] || 0) << 24) + ((bytes[offset + 1] || 0) << 16) + ((bytes[offset + 2] || 0) << 8) + (bytes[offset + 3] || 0)
+  end
+
+  def starts_with?(bytes, prefix)
+    return false if bytes.length < prefix.length
+
+    prefix.each_with_index.all? { |byte, index| bytes[index] == byte }
+  end
+
+  def ascii_at?(bytes, offset, text)
+    return false if bytes.length < offset + text.length
+
+    text.bytes.each_with_index.all? { |byte, index| bytes[offset + index] == byte }
+  end
+end

data/lib/llm_gateway/agents/tools/tool_utils.rb

@@ -0,0 +1,164 @@
+require "pathname"
+require "thread"
+
+module ToolUtils
+  DEFAULT_MAX_LINES = 2000
+  DEFAULT_MAX_BYTES = 50 * 1024
+
+  @file_mutation_locks = Hash.new { |hash, key| hash[key] = Mutex.new }
+  @file_mutation_locks_mutex = Mutex.new
+
+  module_function
+
+  def with_file_mutation_lock(path)
+    lock = @file_mutation_locks_mutex.synchronize { @file_mutation_locks[path] }
+    lock.synchronize { yield }
+  end
+
+  def format_size(bytes)
+    return "#{bytes}B" if bytes < 1024
+    return format("%.1fKB", bytes / 1024.0) if bytes < 1024 * 1024
+
+    format("%.1fMB", bytes / (1024.0 * 1024.0))
+  end
+
+  def expand_path(file_path)
+    normalized = file_path.to_s.sub(/^@/, "").gsub(/[\u00A0\u2000-\u200A\u202F\u205F\u3000]/, " ")
+    return Dir.home if normalized == "~"
+    return File.join(Dir.home, normalized[2..]) if normalized.start_with?("~/")
+
+    normalized
+  end
+
+  def resolve_to_cwd(file_path, cwd = Dir.pwd)
+    expanded = expand_path(file_path)
+    Pathname.new(expanded).absolute? ? expanded : File.expand_path(expanded, cwd)
+  end
+
+  def resolve_read_path(file_path, cwd = Dir.pwd)
+    resolved = resolve_to_cwd(file_path, cwd)
+    return resolved if File.exist?(resolved)
+
+    am_pm_variant = resolved.gsub(/ (AM|PM)\./i) { "\u202F#{Regexp.last_match(1)}." }
+    return am_pm_variant if File.exist?(am_pm_variant)
+
+    nfd_variant = resolved.unicode_normalize(:nfd)
+    return nfd_variant if File.exist?(nfd_variant)
+
+    curly_variant = resolved.tr("'", "\u2019")
+    return curly_variant if File.exist?(curly_variant)
+
+    nfd_curly_variant = nfd_variant.tr("'", "\u2019")
+    return nfd_curly_variant if File.exist?(nfd_curly_variant)
+
+    resolved
+  end
+
+  def truncate_head(content, max_lines: DEFAULT_MAX_LINES, max_bytes: DEFAULT_MAX_BYTES)
+    lines = split_lines_for_counting(content)
+    total_lines = lines.length
+    total_bytes = content.bytesize
+
+    if total_lines <= max_lines && total_bytes <= max_bytes
+      return truncation_result(content, false, nil, total_lines, total_bytes, total_lines, total_bytes, false, false, max_lines, max_bytes)
+    end
+
+    first_line_bytes = lines.first.to_s.bytesize
+    if first_line_bytes > max_bytes
+      return truncation_result("", true, "bytes", total_lines, total_bytes, 0, 0, false, true, max_lines, max_bytes)
+    end
+
+    out_lines = []
+    out_bytes = 0
+    truncated_by = "lines"
+
+    lines.each_with_index do |line, index|
+      break if index >= max_lines
+
+      line_bytes = line.bytesize + (index.positive? ? 1 : 0)
+      if out_bytes + line_bytes > max_bytes
+        truncated_by = "bytes"
+        break
+      end
+
+      out_lines << line
+      out_bytes += line_bytes
+    end
+
+    output = out_lines.join("\n")
+    truncation_result(output, true, truncated_by, total_lines, total_bytes, out_lines.length, output.bytesize, false, false, max_lines, max_bytes)
+  end
+
+  def truncate_tail(content, max_lines: DEFAULT_MAX_LINES, max_bytes: DEFAULT_MAX_BYTES)
+    lines = split_lines_for_counting(content)
+    total_lines = lines.length
+    total_bytes = content.bytesize
+
+    if total_lines <= max_lines && total_bytes <= max_bytes
+      return truncation_result(content, false, nil, total_lines, total_bytes, total_lines, total_bytes, false, false, max_lines, max_bytes)
+    end
+
+    out_lines = []
+    out_bytes = 0
+    truncated_by = "lines"
+    last_line_partial = false
+
+    (lines.length - 1).downto(0) do |i|
+      break if out_lines.length >= max_lines
+
+      line = lines[i]
+      line_bytes = line.bytesize + (out_lines.empty? ? 0 : 1)
+
+      if out_bytes + line_bytes > max_bytes
+        truncated_by = "bytes"
+        if out_lines.empty?
+          out_lines.unshift(truncate_string_to_bytes_from_end(line, max_bytes))
+          out_bytes = out_lines.first.bytesize
+          last_line_partial = true
+        end
+        break
+      end
+
+      out_lines.unshift(line)
+      out_bytes += line_bytes
+    end
+
+    output = out_lines.join("\n")
+    truncation_result(output, true, truncated_by, total_lines, total_bytes, out_lines.length, output.bytesize, last_line_partial, false, max_lines, max_bytes)
+  end
+
+  def split_lines_for_counting(content)
+    return [] if content.empty?
+
+    lines = content.split("\n", -1)
+    lines.pop if content.end_with?("\n")
+    lines
+  end
+
+  def truncation_result(content, truncated, truncated_by, total_lines, total_bytes, output_lines, output_bytes, last_line_partial, first_line_exceeds_limit, max_lines, max_bytes)
+    {
+      content: content,
+      truncated: truncated,
+      truncated_by: truncated_by,
+      total_lines: total_lines,
+      total_bytes: total_bytes,
+      output_lines: output_lines,
+      output_bytes: output_bytes,
+      last_line_partial: last_line_partial,
+      first_line_exceeds_limit: first_line_exceeds_limit,
+      max_lines: max_lines,
+      max_bytes: max_bytes
+    }
+  end
+
+  def truncate_string_to_bytes_from_end(str, max_bytes)
+    bytes = str.dup.force_encoding("UTF-8").bytes
+    return str if bytes.length <= max_bytes
+
+    tail = bytes.last(max_bytes).pack("C*")
+    until tail.valid_encoding?
+      tail = tail.bytes.drop(1).pack("C*")
+    end
+    tail
+  end
+end

data/lib/llm_gateway/agents/tools/write_tool.rb

@@ -0,0 +1,34 @@
+require "fileutils"
+require_relative "tool_utils"
+
+class WriteTool < LlmGateway::Tool
+  # Pi adaptation notes:
+  # - Keep Ruby bytesize in the success message rather than pi's JS string length; the byte count is more accurate for UTF-8 content.
+  # - Do not add pi's pluggable operations, AbortSignal handling, render previews, or details metadata: those are UI/runtime extension concerns outside this tool contract.
+  name "write"
+  description "Write content to a file. Creates the file if it doesn't exist, overwrites if it does. Automatically creates parent directories."
+  input_schema({
+    type: "object",
+    properties: {
+      path: { type: "string", description: "Path to the file to write (relative or absolute)" },
+      content: { type: "string", description: "Content to write to the file" }
+    },
+    required: [ "path", "content" ]
+  })
+
+  def execute(input)
+    path = input[:path] || input["path"]
+    content = input[:content] || input["content"]
+
+    absolute_path = ToolUtils.resolve_to_cwd(path)
+
+    ToolUtils.with_file_mutation_lock(absolute_path) do
+      FileUtils.mkdir_p(File.dirname(absolute_path))
+      File.write(absolute_path, content)
+    end
+
+    "Successfully wrote #{content.bytesize} bytes to #{path}"
+  rescue StandardError => e
+    e.message
+  end
+end

data/lib/llm_gateway/base_client.rb

@@ -41,7 +41,7 @@ module LlmGateway
       request.set_form(form_data, "multipart/form-data")
 
       # Headers (excluding Content-Type because set_form already sets it)
-      multipart_headers = build_headers.reject { |k, _| k.downcase == "content-type" }
+      multipart_headers = build_headers.except("content-type", "Content-Type")
       multipart_headers.each { |key, value| request[key] = value }
 
       response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
@@ -112,7 +112,7 @@ module LlmGateway
           next if data_str == "[DONE]"
 
           data = begin
-            LlmGateway::Utils.deep_symbolize_keys(JSON.parse(data_str))
+            JSON.parse(data_str).deep_symbolize_keys
           rescue JSON::ParserError
             { raw: data_str }
           end
@@ -141,7 +141,7 @@ module LlmGateway
       when 200
         content_type = response["content-type"]
         if content_type&.include?("application/json")
-          LlmGateway::Utils.deep_symbolize_keys(JSON.parse(response.body))
+          JSON.parse(response.body).deep_symbolize_keys
         else
           response.body
         end

data/lib/llm_gateway/clients/anthropic.rb

@@ -54,19 +54,19 @@ module LlmGateway
         }
 
         tools = apply_tools_cache_control(tools, cache_retention)
-        body.merge!(tools: tools) if LlmGateway::Utils.present?(tools)
+        body.merge!(tools: tools) if tools.present?
 
         system = prepend_claude_code_identity(system) if claude_code_oauth_api_key?
         system = apply_system_cache_control(system, cache_retention)
 
-        body.merge!(system: system) if LlmGateway::Utils.present?(system)
+        body.merge!(system: system) if system.present?
         body.merge!(cache_control: cache_control) unless cache_control.nil?
         body.merge!(options)
         body
       end
 
       def apply_system_cache_control(system, cache_retention)
-        return system if system.nil? || system.empty? || !system.is_a?(Array)
+        return system if system.blank? || !system.is_a?(Array)
 
         cache_control = anthropic_cache_control_for(cache_retention)
         return system if cache_control.nil?
@@ -84,7 +84,7 @@ module LlmGateway
       end
 
       def apply_tools_cache_control(tools, cache_retention)
-        return tools if tools.nil? || tools.empty? || !tools.is_a?(Array)
+        return tools if tools.blank? || !tools.is_a?(Array)
 
         cache_control = anthropic_cache_control_for(cache_retention)
         return tools if cache_control.nil?
@@ -149,7 +149,7 @@ module LlmGateway
           text: "You are Claude Code, Anthropic's official CLI for Claude."
         }
 
-        if system.nil? || system.empty?
+        if system.blank?
           [ identity ]
         else
           [ identity ] + system

data/lib/llm_gateway/clients/claude_code/oauth_flow.rb

@@ -105,7 +105,7 @@ module LlmGateway
           code = uri.query && URI.decode_www_form(uri.query).to_h["code"]
           state = uri.query && URI.decode_www_form(uri.query).to_h["state"]
 
-          raise ArgumentError, "Callback URL is missing code parameter" if code.nil? || code.empty?
+          raise ArgumentError, "Callback URL is missing code parameter" if code.blank?
 
           { code: code, state: state }
         rescue URI::InvalidURIError => e
@@ -116,7 +116,7 @@ module LlmGateway
 
         def extract_code_and_state(auth_code_or_callback, state)
           value = auth_code_or_callback.to_s.strip
-          raise ArgumentError, "Authorization code is required" if value.empty?
+          raise ArgumentError, "Authorization code is required" if value.blank?
 
           if looks_like_url?(value)
             callback = parse_callback(value)

data/lib/llm_gateway/clients/openai.rb

@@ -114,7 +114,7 @@ module LlmGateway
 
       def build_codex_body(messages, system, tools, model:, **options)
         instructions = Array(system).filter_map { |s| s.is_a?(Hash) ? s[:content] : s }.join("\n")
-        instructions = "You are a helpful assistant." if instructions.empty?
+        instructions = instructions.presence || "You are a helpful assistant."
 
         body = {
           model: model,
@@ -196,7 +196,7 @@ module LlmGateway
         end
         # If we get here, we didn't handle it specifically
         fallback_body = response.body.to_s.strip
-        fallback_message = if fallback_body.empty?
+        fallback_message = if fallback_body.blank?
           "OpenAI request failed with status #{response.code}"
         else
           "OpenAI request failed with status #{response.code}: #{fallback_body}"

data/lib/llm_gateway/clients/openai_codex/oauth_flow.rb

@@ -96,7 +96,7 @@ module LlmGateway
           uri    = URI.parse(callback_url)
           params = URI.decode_www_form(uri.query.to_s).to_h
           code   = params["code"]
-          raise ArgumentError, "Callback URL is missing code parameter" if code.nil? || code.empty?
+          raise ArgumentError, "Callback URL is missing code parameter" if code.blank?
 
           { code: code, state: params["state"] }
         rescue URI::InvalidURIError => e
@@ -120,7 +120,7 @@ module LlmGateway
           input = tty.gets&.strip
           tty.close
 
-          raise "No authorization code provided" if input.nil? || input.empty?
+          raise "No authorization code provided" if input.blank?
 
           exchange_code(input, flow[:code_verifier], expected_state: flow[:state])
         end
@@ -183,7 +183,7 @@ module LlmGateway
           auth       = payload[JWT_CLAIM_PATH]
           account_id = auth&.dig("chatgpt_account_id")
 
-          account_id.is_a?(String) && !account_id.empty? ? account_id : nil
+          account_id.is_a?(String) ? account_id.presence : nil
         rescue StandardError
           nil
         end
@@ -214,7 +214,7 @@ module LlmGateway
         end
 
         def parse_authorization_input(input, expected_state = nil)
-          return nil if input.nil? || input.empty?
+          return nil if input.blank?
 
           value = input.to_s.strip