llm_gateway 0.6.0 → 0.7.0

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

@@ -0,0 +1,132 @@
+require "securerandom"
+require "tmpdir"
+require_relative "tool_utils"
+
+class BashTool < LlmGateway::Tool
+  # Pi adaptation notes:
+  # - Keep timeout schema as integer: gruv treats integer and number schemas equivalently for seconds.
+  # - Do not add pi's pluggable operations, shell/env hooks, command prefix, AbortSignal handling, partial updates, or UI render details: those are runtime/UI extension concerns outside this tool contract.
+  name "bash"
+  description "Execute a bash command in the current working directory. Returns stdout and stderr. Output is truncated to last #{ToolUtils::DEFAULT_MAX_LINES} lines or #{ToolUtils::DEFAULT_MAX_BYTES / 1024}KB (whichever is hit first). If truncated, full output is saved to a temp file. Optionally provide a timeout in seconds."
+  input_schema({
+    type: "object",
+    properties: {
+      command: { type: "string", description: "Bash command to execute" },
+      timeout: { type: "integer", description: "Timeout in seconds (optional, no default timeout)" }
+    },
+    required: [ "command" ]
+  })
+
+  def execute(input)
+    command = input[:command]
+    timeout = input[:timeout]
+
+    result = run_command(command, timeout)
+    out = format_output(result[:output], empty_text: result[:timed_out] ? "" : "(no output)")
+
+    if result[:timed_out]
+      return append_status(out, "Command timed out after #{timeout} seconds")
+    end
+
+    if result[:exit_status] && result[:exit_status] != 0
+      return append_status(out, "Command exited with code #{result[:exit_status]}")
+    end
+
+    out
+  rescue StandardError => e
+    e.message
+  end
+
+  private
+
+  def run_command(command, timeout)
+    output = +""
+    timed_out = false
+    read_io, write_io = IO.pipe
+    pid = Process.spawn(command, chdir: Dir.pwd, in: File::NULL, out: write_io, err: write_io, pgroup: true)
+    write_io.close
+
+    deadline = timeout && timeout.positive? ? Time.now + timeout : nil
+
+    loop do
+      remaining = deadline ? deadline - Time.now : nil
+      if remaining && remaining <= 0
+        timed_out = true
+        terminate_process_group(pid)
+        break
+      end
+
+      ready = IO.select([ read_io ], nil, nil, remaining)
+      unless ready
+        timed_out = true
+        terminate_process_group(pid)
+        break
+      end
+
+      begin
+        output << read_io.readpartial(16 * 1024)
+      rescue EOFError
+        break
+      end
+    end
+
+    _, status = Process.wait2(pid)
+    drain_available_output(read_io, output)
+    read_io.close
+
+    { output: output, exit_status: status.exitstatus, timed_out: timed_out }
+  ensure
+    write_io.close if write_io && !write_io.closed?
+    read_io.close if read_io && !read_io.closed?
+  end
+
+  def drain_available_output(read_io, output)
+    loop do
+      ready = IO.select([ read_io ], nil, nil, 0.1)
+      break unless ready
+
+      begin
+        output << read_io.readpartial(16 * 1024)
+      rescue EOFError
+        break
+      end
+    end
+  end
+
+  def terminate_process_group(pid)
+    Process.kill("TERM", -pid)
+    sleep 0.1
+    Process.kill("KILL", -pid)
+  rescue Errno::ESRCH, Errno::EPERM
+    nil
+  end
+
+  def format_output(output, empty_text: "(no output)")
+    truncation = ToolUtils.truncate_tail(output)
+    out = truncation[:content]
+    out = empty_text if out.empty?
+
+    return out unless truncation[:truncated]
+
+    temp_path = File.join(Dir.tmpdir, "pi-bash-#{SecureRandom.hex(8)}.log")
+    File.write(temp_path, output)
+
+    start_line = truncation[:total_lines] - truncation[:output_lines] + 1
+    end_line = truncation[:total_lines]
+
+    notice = if truncation[:last_line_partial]
+      last_line = output.split("\n", -1).last
+      "[Showing last #{ToolUtils.format_size(truncation[:output_bytes])} of line #{end_line} (line is #{ToolUtils.format_size(last_line.bytesize)}). Full output: #{temp_path}]"
+    elsif truncation[:truncated_by] == "lines"
+      "[Showing lines #{start_line}-#{end_line} of #{truncation[:total_lines]}. Full output: #{temp_path}]"
+    else
+      "[Showing lines #{start_line}-#{end_line} of #{truncation[:total_lines]} (#{ToolUtils.format_size(ToolUtils::DEFAULT_MAX_BYTES)} limit). Full output: #{temp_path}]"
+    end
+
+    "#{out}\n\n#{notice}"
+  end
+
+  def append_status(text, status)
+    text.empty? ? status : "#{text}\n\n#{status}"
+  end
+end

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

@@ -0,0 +1,215 @@
+require "json"
+require_relative "tool_utils"
+
+class EditTool < LlmGateway::Tool
+  # Pi adaptation notes:
+  # - Legacy single-edit input: pi accepts oldText/newText and converts to edits,
+  #   but this tool intentionally exposes/supports only the edits array to keep the LLM contract unambiguous.
+  # - Do not add pi's diff/patch details, preview rendering, pluggable operations, or AbortSignal handling: those are UI/runtime extension concerns outside this tool contract.
+  name "edit"
+
+  class EditError < StandardError; end
+  description "Edit a single file using exact text replacement. Every edits[].oldText must match a unique, non-overlapping region of the original file. If two changes affect the same block or nearby lines, merge them into one edit instead of emitting overlapping edits."
+  input_schema({
+    type: "object",
+    properties: {
+      path: { type: "string", description: "Path to the file to edit (relative or absolute)" },
+      edits: {
+        type: "array",
+        description: "One or more targeted replacements. Each edit is matched against the original file, not incrementally. Do not include overlapping or nested edits.",
+        items: {
+          type: "object",
+          properties: {
+            oldText: { type: "string", description: "Exact text for one targeted replacement. It must be unique in the original file and must not overlap with any other edits[].oldText in the same call." },
+            newText: { type: "string", description: "Replacement text for this targeted edit." }
+          },
+          required: [ "oldText", "newText" ]
+        }
+      }
+    },
+    required: [ "path", "edits" ]
+  })
+
+  def execute(input)
+    path = input[:path]
+    edits = prepare_edits(input[:edits])
+
+    return "Edit tool input is invalid. edits must contain at least one replacement." if !edits.is_a?(Array) || edits.empty?
+
+    absolute_path = ToolUtils.resolve_to_cwd(path)
+
+    ToolUtils.with_file_mutation_lock(absolute_path) do
+      begin
+        File.open(absolute_path, File::RDWR) { }
+      rescue SystemCallError => e
+        return "Could not edit file: #{path}. Error code: #{e.class.name.split("::").last}."
+      end
+
+      raw_content = File.binread(absolute_path)
+
+      bom = raw_content.start_with?("\xEF\xBB\xBF".b) ? "\xEF\xBB\xBF".b : "".b
+      content_without_bom = bom.empty? ? raw_content : raw_content.byteslice(3..)
+      content_utf8 = content_without_bom.force_encoding("UTF-8")
+
+      original_ending = detect_line_ending(content_utf8)
+      normalized_content = normalize_to_lf(content_utf8)
+      base_content, new_content = apply_edits_to_normalized_content(normalized_content, edits, path)
+
+      restored = restore_line_endings(new_content, original_ending)
+      final_bytes = bom + restored.encode("UTF-8").b
+
+      File.binwrite(absolute_path, final_bytes)
+      "Successfully replaced #{edits.length} block(s) in #{path}."
+    end
+  rescue EditError => e
+    e.message
+  rescue StandardError => e
+    "Error editing file: #{e.message}"
+  end
+
+  private
+
+  def prepare_edits(edits)
+    return JSON.parse(edits, symbolize_names: true) if edits.is_a?(String)
+
+    edits
+  end
+
+  def detect_line_ending(content)
+    crlf_index = content.index("\r\n")
+    lf_index = content.index("\n")
+    return "\n" unless lf_index
+    return "\n" unless crlf_index
+
+    crlf_index < lf_index ? "\r\n" : "\n"
+  end
+
+  def normalize_to_lf(text)
+    text.gsub("\r\n", "\n").gsub("\r", "\n")
+  end
+
+  def restore_line_endings(text, ending)
+    ending == "\r\n" ? text.gsub("\n", "\r\n") : text
+  end
+
+  def normalize_for_fuzzy_match(text)
+    text
+      .unicode_normalize(:nfkc)
+      .split("\n", -1)
+      .map(&:rstrip)
+      .join("\n")
+      .gsub(/[\u2018\u2019\u201A\u201B]/, "'")
+      .gsub(/[\u201C\u201D\u201E\u201F]/, '"')
+      .gsub(/[\u2010\u2011\u2012\u2013\u2014\u2015\u2212]/, "-")
+      .gsub(/[\u00A0\u2002-\u200A\u202F\u205F\u3000]/, " ")
+  end
+
+  def fuzzy_find_text(content, old_text)
+    exact_index = content.index(old_text)
+    if exact_index
+      return {
+        found: true,
+        index: exact_index,
+        match_length: old_text.length,
+        used_fuzzy_match: false,
+        content_for_replacement: content
+      }
+    end
+
+    fuzzy_content = normalize_for_fuzzy_match(content)
+    fuzzy_old_text = normalize_for_fuzzy_match(old_text)
+    fuzzy_index = fuzzy_content.index(fuzzy_old_text)
+
+    return { found: false, index: -1, match_length: 0, used_fuzzy_match: false, content_for_replacement: content } unless fuzzy_index
+
+    {
+      found: true,
+      index: fuzzy_index,
+      match_length: fuzzy_old_text.length,
+      used_fuzzy_match: true,
+      content_for_replacement: fuzzy_content
+    }
+  end
+
+  def count_occurrences(content, old_text)
+    fuzzy_content = normalize_for_fuzzy_match(content)
+    fuzzy_old_text = normalize_for_fuzzy_match(old_text)
+    fuzzy_content.split(fuzzy_old_text, -1).length - 1
+  end
+
+  def apply_edits_to_normalized_content(normalized_content, edits, path)
+    normalized_edits = edits.map do |edit|
+      {
+        oldText: normalize_to_lf(edit[:oldText]),
+        newText: normalize_to_lf(edit[:newText])
+      }
+    end
+
+    normalized_edits.each_with_index do |edit, index|
+      raise EditError, empty_old_text_error(path, index, normalized_edits.length) if edit[:oldText].empty?
+    end
+
+    initial_matches = normalized_edits.map { |edit| fuzzy_find_text(normalized_content, edit[:oldText]) }
+    base_content = initial_matches.any? { |match| match[:used_fuzzy_match] } ? normalize_for_fuzzy_match(normalized_content) : normalized_content
+
+    matched_edits = []
+    normalized_edits.each_with_index do |edit, index|
+      match = fuzzy_find_text(base_content, edit[:oldText])
+      raise EditError, not_found_error(path, index, normalized_edits.length) unless match[:found]
+
+      occurrences = count_occurrences(base_content, edit[:oldText])
+      raise EditError, duplicate_error(path, index, normalized_edits.length, occurrences) if occurrences > 1
+
+      matched_edits << {
+        edit_index: index,
+        match_index: match[:index],
+        match_length: match[:match_length],
+        new_text: edit[:newText]
+      }
+    end
+
+    matched_edits.sort_by! { |edit| edit[:match_index] }
+    matched_edits.each_cons(2) do |previous, current|
+      next unless previous[:match_index] + previous[:match_length] > current[:match_index]
+
+      raise EditError, "edits[#{previous[:edit_index]}] and edits[#{current[:edit_index]}] overlap in #{path}. Merge them into one edit or target disjoint regions."
+    end
+
+    new_content = base_content.dup
+    matched_edits.reverse_each do |edit|
+      new_content = new_content[0...edit[:match_index]] + edit[:new_text] + new_content[(edit[:match_index] + edit[:match_length])..]
+    end
+
+    raise EditError, no_change_error(path, normalized_edits.length) if base_content == new_content
+
+    [ base_content, new_content ]
+  end
+
+  def not_found_error(path, edit_index, total_edits)
+    return "Could not find the exact text in #{path}. The old text must match exactly including all whitespace and newlines." if total_edits == 1
+
+    "Could not find edits[#{edit_index}] in #{path}. The oldText must match exactly including all whitespace and newlines."
+  end
+
+  def duplicate_error(path, edit_index, total_edits, occurrences)
+    if total_edits == 1
+      return "Found #{occurrences} occurrences of the text in #{path}. The text must be unique. Please provide more context to make it unique."
+    end
+
+    "Found #{occurrences} occurrences of edits[#{edit_index}] in #{path}. Each oldText must be unique. Please provide more context to make it unique."
+  end
+
+  def empty_old_text_error(path, edit_index, total_edits)
+    return "oldText must not be empty in #{path}." if total_edits == 1
+
+    "edits[#{edit_index}].oldText must not be empty in #{path}."
+  end
+
+  def no_change_error(path, total_edits)
+    if total_edits == 1
+      return "No changes made to #{path}. The replacement produced identical content. This might indicate an issue with special characters or the text not existing as expected."
+    end
+
+    "No changes made to #{path}. The replacements produced identical content."
+  end
+end

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