samagotchi 0.2.0

data/lib/samagotchi/tools/builtins.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require_relative "registry"
+require_relative "../tool_declarations"
+require_relative "execute"
+require_relative "read"
+require_relative "write"
+require_relative "memory"
+require_relative "edit"
+require_relative "task_create"
+require_relative "task_get"
+require_relative "task_list"
+require_relative "task_stop"
+require_relative "task_wait"
+require_relative "web_fetch"
+require_relative "register_reminder"
+require_relative "cancel_reminder"
+require_relative "list_reminders"
+require_relative "list_sessions"
+require_relative "send_note"
+require_relative "delegate"
+require_relative "delegate_result"
+require_relative "ask_user_question"
+
+module Samagotchi
+  module Tools
+    # chi's own tools as Registry entries: each schema from
+    # ToolDeclarations::TOOL_SCHEMAS, with a handler (call, kctx) that runs
+    # its class. kctx (KernelLoop::ToolContext) gives what some need from the
+    # kernel: the reminder store, the peers, the model key, the muted memory
+    # read and the ask-user flow.
+    module Builtins
+      CLASSES = [
+        Execute,
+        Read,
+        Write,
+        MemoryRead,
+        MemoryWrite,
+        Edit,
+        TaskCreate,
+        TaskGet,
+        TaskList,
+        TaskStop,
+        TaskWait,
+        WebFetch,
+        RegisterReminder,
+        CancelReminder,
+        ListReminders,
+        ListSessions,
+        SendNote,
+        Delegate,
+        DelegateResult,
+        AskUserQuestion
+      ].freeze
+
+      # The handlers that pass more than the call's content.
+      HANDLERS = {
+        MemoryRead::NAME => ->(call, kctx) { kctx.muted_memory_read(call) },
+        MemoryWrite::NAME => lambda do |call, kctx|
+          MemoryWrite.call(call[:content], path: call[:path], scope: call[:scope], description: call[:description],
+                                           current_model_only: truthy?(call[:current_model_only]),
+                                           model_key: kctx.model_key)
+        end,
+        Write::NAME => ->(call, _kctx) { Write.call(call[:content], path: call[:path]) },
+        Read::NAME => lambda do |call, _kctx|
+          Read.call(call[:content], start_line: call[:start_line], end_line: call[:end_line])
+        end,
+        Edit::NAME => lambda do |call, _kctx|
+          Edit.call(call[:content], path: call[:path], start_line: call[:start_line], end_line: call[:end_line])
+        end,
+        TaskCreate::NAME => ->(call, _kctx) { TaskCreate.call(call[:content], cwd: call[:cwd], env: call[:env]) },
+        TaskWait::NAME => lambda do |call, _kctx|
+          TaskWait.call(call[:content], timeout: call[:timeout], tail_lines: call[:tail_lines],
+                                        done_pattern: call[:done_pattern])
+        end,
+        Execute::NAME => ->(call, _kctx) { Execute.call(call[:content], cwd: call[:cwd]) },
+        RegisterReminder::NAME => lambda do |call, kctx|
+          RegisterReminder.call(call[:content], reminder_store: kctx.reminder_store, description: call[:description],
+                                                interval_minutes: call[:interval_minutes])
+        end,
+        CancelReminder::NAME => ->(call, kctx) { CancelReminder.call(call[:content], reminder_store: kctx.reminder_store) },
+        ListReminders::NAME => ->(call, kctx) { ListReminders.call(call[:content], reminder_store: kctx.reminder_store) },
+        ListSessions::NAME => ->(call, kctx) { ListSessions.call(call[:content], peers: kctx.peers, cwd: call[:cwd]) },
+        SendNote::NAME => ->(call, kctx) { SendNote.call(call[:content], session: call[:session], peers: kctx.peers) },
+        Delegate::NAME => lambda do |call, kctx|
+          Delegate.call(call[:content], model: call[:model], session: call[:session], wait: call[:wait],
+                                        timeout: call[:timeout], peers: kctx.peers)
+        end,
+        DelegateResult::NAME => lambda do |call, kctx|
+          DelegateResult.call(call[:content], session: call[:session], timeout: call[:timeout], peers: kctx.peers)
+        end,
+        AskUserQuestion::NAME => ->(call, kctx) { kctx.ask_user_question(call) }
+      }.freeze
+
+      module_function
+
+      # @return [Registry] a new registry with the built-ins, in
+      #   TOOL_SCHEMAS order (an Engine's own, which bundles add to)
+      def registry
+        by_name = CLASSES.to_h { |klass| [klass::NAME, klass] }
+        ToolDeclarations::TOOL_SCHEMAS.each_with_object(Registry.new) do |schema, registry|
+          klass = by_name.fetch(schema[:name])
+          handler = HANDLERS.fetch(klass::NAME) { ->(call, _kctx) { klass.call(call[:content]) } }
+          registry.register(klass::NAME, schema: schema, handler: handler)
+        end
+      end
+
+      # @return [Registry] the built-ins alone, frozen: a KernelLoop or a
+      #   ChatLoop without an Engine's registry uses it
+      def default
+        @default ||= registry.freeze
+      end
+
+      def truthy?(val)
+        return true if val == true
+        return false if val == false || val.nil?
+
+        val.to_s.strip.downcase == "true"
+      end
+    end
+  end
+end

data/lib/samagotchi/tools/cancel_reminder.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative "../reminder_store"
+
+module Samagotchi
+  module Tools
+    # Cancels a previously registered reminder by name.
+    class CancelReminder
+      NAME        = "cancel_reminder"
+
+      def self.name        = NAME
+
+      def self.call(content, reminder_store: nil)
+        return "Error: reminder_store not configured" unless reminder_store
+
+        name = content.to_s.strip
+        reminder_store.cancel(name)
+      end
+    end
+  end
+end

data/lib/samagotchi/tools/delegate.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require_relative "../session"
+require_relative "../config"
+require_relative "../model_profile"
+require_relative "peers"
+require_relative "delegate_wait"
+
+module Samagotchi
+  # Loaded on first use: session_manager requires terminal_ui, which
+  # requires KernelLoop and so these tools (a require cycle otherwise).
+  autoload :SessionManager, File.expand_path("../session_manager", __dir__)
+
+  module Tools
+    # Hand a task to a child session: an ordinary chi session in its own
+    # worker, started in this session's folder with the task as its first
+    # user message and the `delegated` system memory preloaded. It shows in
+    # every list as a child of this one and the user can attach to it. With
+    # session:, a follow-up to a child that exists. Only the child's final
+    # reply comes back (DelegateWait), never its trace.
+    class Delegate
+      NAME = "delegate"
+      CLIENT_PREFIX = "delegate"
+      MAX_CHILDREN_KEY = "session.max_children"
+      MAX_CHILDREN_DEFAULT = 4
+      # A child spawned this many seconds ago counts as running even before
+      # its worker holds the owner lock: two delegate calls in one model
+      # message come milliseconds apart, and the first child's worker is
+      # still starting when the second call counts.
+      STARTING_GRACE_SECONDS = 15
+      # The memory every child starts with, scoped so a project memory of
+      # the same name cannot shadow it.
+      CHILD_MEMORIES = ["system/delegated"].freeze
+
+      def self.name = NAME
+
+      # @param content [String] the task (the child's user message, verbatim)
+      # @param model [String, nil] the child's model (an alias works); the parent's by default
+      # @param session [String, nil] a child's id or prefix: send the task there instead
+      # @param wait [Boolean, String, nil] wait for the reply (default true)
+      # @param timeout [Integer, String, nil] seconds to wait (default DelegateWait::TIMEOUT_DEFAULT)
+      # @param peers [Peers, nil]
+      def self.call(content, model: nil, session: nil, wait: nil, timeout: nil, peers: nil)
+        return "Error: this session's id is not known here" unless peers&.session_id
+
+        task = content.to_s.strip
+        return "Error: give the task, the child's first message" if task.empty?
+
+        sd = peers.state_dir || Session.default_state_dir
+        parent = Session.load(peers.session_id, state_dir: sd)
+        wait = parse_wait(wait)
+        timeout = parse_timeout(timeout)
+
+        child_id = if session.to_s.strip.empty?
+                     start_child(task, parent: parent, model: model, state_dir: sd)
+                   else
+                     follow_up(task, session: session.to_s.strip, parent: parent, state_dir: sd)
+                   end
+        return child_id if child_id.start_with?("Error:")
+        return DelegateWait.call(child_id, peers: peers, timeout: timeout) if wait
+
+        started = session.to_s.strip.empty? ? "Started a delegate session" : "Sent the follow-up to delegate #{child_id[0, 8]}"
+        "session: #{child_id}\nstatus: running\n#{started}; delegate_result waits for its reply. " \
+          "It shows in chi sessions list and the web as a child of this session; the user can attach to it."
+      rescue ArgumentError => e
+        "Error: #{e.message}"
+      end
+
+      # @return [String] the new child's id, or an Error: line
+      def self.start_child(task, parent:, model:, state_dir:)
+        if parent.parent_id
+          return "Error: this session is a delegate of #{parent.parent_id}; delegated sessions don't delegate further"
+        end
+
+        running = running_children(parent.id, state_dir: state_dir)
+        max = max_children
+        if running.size >= max
+          ids = running.map { |s| s[:short_id] }.join(", ")
+          return "Error: #{running.size} delegate#{"s" if running.size != 1} of this session #{running.size == 1 ? "is" : "are"} running " \
+                 "(the most is #{max}, #{MAX_CHILDREN_KEY}): #{ids}. delegate_result waits for one; `chi sessions stop ID` stops one."
+        end
+
+        child = SessionManager.spawn_session(prompt: task, working_directory: parent.working_directory,
+                                             model_name: child_model(model, parent), memories: CHILD_MEMORIES,
+                                             parent_id: parent.id, state_dir: state_dir)
+        child.id
+      end
+      private_class_method :start_child
+
+      # @return [String] the child's id, or an Error: line
+      def self.follow_up(task, session:, parent:, state_dir:)
+        id = Session.resolve_id(session, state_dir: state_dir)
+        child = begin
+          Session.load(id, state_dir: state_dir)
+        rescue ArgumentError
+          return "Error: no session #{session} (list_sessions shows them)"
+        end
+        unless child.parent_id == parent.id
+          return "Error: #{id[0, 8]} is not a delegate of this session; send_note reaches any session"
+        end
+
+        # Only a reply after this delivery counts as the follow-up's.
+        DelegateWait.mark_seen(parent.id, id, state_dir: state_dir)
+        delivered = SessionManager.deliver_turn(id, prompt: task, client_id: "#{CLIENT_PREFIX}:#{parent.id[0, 8]}",
+                                                    state_dir: state_dir)
+        case delivered[:status]
+        when :accepted then id
+        when :refused then "Error: session #{id[0, 8]} refused the message (#{delivered.dig(:ack, "error")})"
+        when :timeout then "Error: the worker of session #{id[0, 8]} did not answer in time, so the message was not sent"
+        else "Error: the message to session #{id[0, 8]} could not be written"
+        end
+      rescue SessionManager::OwnedByTUI
+        "Error: session #{id[0, 8]} is open in a chi REPL, which can't take a delegated message"
+      rescue Session::AmbiguousId => e
+        "Error: #{e.message}"
+      end
+      private_class_method :follow_up
+
+      # --model as the REPL reads it: an alias resolved, a host prefix kept.
+      # No existence check: an unknown model fails the child's first turn.
+      def self.child_model(model, parent)
+        return parent.model_name if model.to_s.strip.empty?
+
+        ModelProfile.required_model_name(ConfigFile.resolve_model_alias(model.to_s.strip))
+      end
+      private_class_method :child_model
+
+      # The children of +parent_id+ that count against session.max_children
+      # (a plugin's ctx.sessions.fork counts them too).
+      # @return [Array<Hash>] SessionManager.children_of rows
+      def self.running_children(parent_id, state_dir:)
+        SessionManager.children_of(parent_id, state_dir: state_dir).select { |s| running?(s) }
+      end
+
+      # busy (a worker runs its turn), or running with a worker on its way.
+      def self.running?(summary)
+        return true if summary[:busy]
+        return false unless summary[:status] == Session::STATUS_RUNNING && !summary[:live]
+
+        Time.now - Time.iso8601(summary[:updated_at].to_s) < STARTING_GRACE_SECONDS
+      rescue ArgumentError
+        false
+      end
+      private_class_method :running?
+
+      def self.max_children
+        value = Integer(Config.get(MAX_CHILDREN_KEY), exception: false)
+        value&.positive? ? value : MAX_CHILDREN_DEFAULT
+      rescue StandardError
+        MAX_CHILDREN_DEFAULT
+      end
+
+      # true unless told otherwise; text-based parsers hand strings over.
+      def self.parse_wait(value)
+        return true if value.nil? || value.to_s.strip.empty?
+        return value if value == true || value == false
+
+        !%w[false 0 no off].include?(value.to_s.strip.downcase)
+      end
+
+      def self.parse_timeout(value)
+        parsed = Integer(value.to_s.strip, exception: false)
+        parsed&.positive? ? parsed : DelegateWait::TIMEOUT_DEFAULT
+      end
+    end
+  end
+end

data/lib/samagotchi/tools/delegate_result.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative "../session"
+require_relative "peers"
+require_relative "delegate"
+require_relative "delegate_wait"
+
+module Samagotchi
+  # Loaded on first use: session_manager requires terminal_ui, which
+  # requires KernelLoop and so these tools (a require cycle otherwise).
+  autoload :SessionManager, File.expand_path("../session_manager", __dir__)
+
+  module Tools
+    # Wait for a delegated session's next reply: the one named, or this
+    # session's newest running child.
+    class DelegateResult
+      NAME = "delegate_result"
+
+      def self.name = NAME
+
+      # @param session [String, nil] a child's id or prefix
+      # @param timeout [Integer, String, nil] seconds (default DelegateWait::TIMEOUT_DEFAULT)
+      # @param peers [Peers, nil]
+      def self.call(_content = nil, session: nil, timeout: nil, peers: nil)
+        return "Error: this session's id is not known here" unless peers&.session_id
+
+        sd = peers.state_dir || Session.default_state_dir
+        child_id = if session.to_s.strip.empty?
+                     newest_running_child(peers.session_id, state_dir: sd) ||
+                       (return "No running delegate; list_sessions shows finished ones.")
+                   else
+                     id = Session.resolve_id(session.to_s.strip, state_dir: sd)
+                     child = Session.load(id, state_dir: sd)
+                     unless child.parent_id == peers.session_id
+                       return "Error: #{id[0, 8]} is not a delegate of this session (list_sessions marks them child)"
+                     end
+
+                     id
+                   end
+        DelegateWait.call(child_id, peers: peers, timeout: Delegate.parse_timeout(timeout))
+      rescue Session::AmbiguousId => e
+        "Error: #{e.message}"
+      rescue ArgumentError
+        "Error: no session #{session.to_s.strip} (list_sessions shows them)"
+      end
+
+      def self.newest_running_child(parent_id, state_dir:)
+        SessionManager.children_of(parent_id, state_dir: state_dir).find { |s| s[:busy] }&.fetch(:id)
+      end
+      private_class_method :newest_running_child
+    end
+  end
+end

data/lib/samagotchi/tools/delegate_wait.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require_relative "../session"
+require_relative "output_guardrails"
+require_relative "peers"
+
+module Samagotchi
+  # Loaded on first use: session_manager requires terminal_ui, which
+  # requires KernelLoop and so these tools (a require cycle otherwise).
+  autoload :SessionManager, File.expand_path("../session_manager", __dir__)
+
+  module Tools
+    # Waiting for a delegated session's next reply, shared by delegate and
+    # delegate_result. A reply is the child's output/<timestamp>.txt file
+    # (the worker writes one per turn that ended with visible text, just
+    # before its idle save), so "new" means a filename past the cursor: the
+    # newest one this parent was already given. The cursors live in this
+    # process (a worker runs one session), keyed by parent and child; a
+    # worker respawn loses them, which only repeats the newest reply once.
+    module DelegateWait
+      TIMEOUT_DEFAULT = 600
+      POLL_INTERVAL = 0.5
+      # Cut like an execute result: full up to TRUNCATE_AT bytes, else a
+      # head-and-tail preview of PREVIEW bytes.
+      TRUNCATE_AT_BYTES = OutputGuardrails::DEFAULT_TRUNCATE_AT_BYTES
+      PREVIEW_BYTES = OutputGuardrails::DEFAULT_PREVIEW_BYTES
+
+      module_function
+
+      # @return [Hash{Array(String, String) => String}] [parent id, child id] → newest reply filename given
+      def seen
+        @seen ||= {}
+      end
+
+      # @param child_id [String] the child's full id
+      # @param peers [Peers] the parent (session_id, state_dir, cancelled?)
+      # @param timeout [Integer] seconds
+      # @param poll_interval [Float]
+      # @return [String] the tool result
+      def call(child_id, peers:, timeout: TIMEOUT_DEFAULT, poll_interval: POLL_INTERVAL)
+        sd = peers.state_dir || Session.default_state_dir
+        key = [peers.session_id, child_id]
+        cursor = seen[key]
+        deadline = monotonic + timeout.to_i
+        seen_running = false
+
+        loop do
+          session = Session.load(child_id, state_dir: sd)
+
+          if (file = newest_reply(child_id, state_dir: sd)) && newer?(file, cursor)
+            seen[key] = file
+            return reply_result(child_id, File.read(File.join(reply_dir(child_id, state_dir: sd), file)))
+          end
+
+          case session.status
+          when Session::STATUS_ERROR
+            return result(child_id, "error", "the child's worker failed: #{session.last_prompt.to_s.strip}; its session shows what happened")
+          when Session::STATUS_STOPPED
+            return result(child_id, "stopped", "the child was stopped (chi sessions stop); delegate with session: #{child_id} starts it again with a message")
+          end
+
+          if (pending = session.pending_question)
+            return result(child_id, "waiting_for_answer", waiting_text(child_id, pending))
+          end
+
+          if peers.respond_to?(:cancelled?) && peers.cancelled?
+            return result(child_id, "canceled", "wait canceled; the child keeps running; delegate_result #{child_id} waits again")
+          end
+
+          if session.status == Session::STATUS_RUNNING
+            seen_running = true
+          elsif seen_running
+            # It ran and is idle again with no new reply: canceled, failed or
+            # empty. Before it was ever seen running, idle means a
+            # file-delivered follow-up its worker has not picked up yet.
+            return result(child_id, "no_reply", "the child's turn ended without a reply (canceled, failed or empty); its session shows what happened")
+          end
+
+          return timeout_result(child_id, timeout) if monotonic > deadline
+
+          sleep(poll_interval)
+        end
+      rescue ArgumentError => e
+        "Error: #{e.message}"
+      end
+
+      # @return [String, nil] the newest reply filename (sortable timestamps)
+      def newest_reply(child_id, state_dir:)
+        dir = reply_dir(child_id, state_dir: state_dir)
+        return nil unless Dir.exist?(dir)
+
+        Dir.children(dir).select { |f| f.end_with?(".txt") }.max
+      end
+
+      # Point the cursor at the newest reply now, so only a later one counts
+      # (a follow-up sent to a child that already answered).
+      def mark_seen(parent_id, child_id, state_dir:)
+        seen[[parent_id, child_id]] = newest_reply(child_id, state_dir: state_dir)
+      end
+
+      def reply_dir(child_id, state_dir:)
+        File.join(Session.session_dir(child_id, state_dir: state_dir), SessionManager::OUTPUT_DIR)
+      end
+
+      def newer?(file, cursor)
+        cursor.nil? || file > cursor
+      end
+
+      def reply_result(child_id, text)
+        "session: #{child_id}\nstatus: done\n---\n#{cut(text)}"
+      end
+
+      def result(child_id, status, text)
+        "session: #{child_id}\nstatus: #{status}\n#{text}"
+      end
+
+      def timeout_result(child_id, timeout)
+        result(child_id, "running",
+               "no reply yet after #{timeout.to_i} s; the child keeps running. delegate_result #{child_id} waits again; " \
+               "chi --attach #{child_id} shows it.")
+      end
+
+      def waiting_text(child_id, pending)
+        what = pending[:kind].to_s == "approval" ? "an approval" : "a question"
+        "Child #{child_id} is waiting for an answer (#{what}); attach with chi --attach #{child_id} or answer it in the web. " \
+          "delegate_result #{child_id} waits again once it is answered."
+      end
+
+      def cut(text)
+        text = OutputGuardrails.safe_utf8(text)
+        return text if text.bytesize <= TRUNCATE_AT_BYTES
+
+        preview = OutputGuardrails.head_tail_from_string(content: text, preview_bytes: PREVIEW_BYTES)
+        [
+          "truncated=true",
+          "preview_strategy=head_tail",
+          "reply_bytes=#{text.bytesize}",
+          "returned_preview_bytes=#{preview[:returned_preview_bytes]}",
+          "omitted_bytes=#{preview[:omitted_bytes]}",
+          "[TRUNCATED_PREVIEW_HEAD]",
+          preview[:head],
+          "[... omitted #{preview[:omitted_bytes]} bytes ...]",
+          "[TRUNCATED_PREVIEW_TAIL]",
+          preview[:tail]
+        ].join("\n")
+      end
+
+      def monotonic
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/samagotchi/tools/edit.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require_relative "output_guardrails"
+require_relative "tool_path"
+
+module Samagotchi
+  module Tools
+    # Replaces an exact block of text in an existing file.
+    #
+    # XML syntax (used by the model):
+    #   <tool name="edit" path="path/to/file">
+    #     <old>exact text to replace</old>
+    #     <new>replacement text</new>
+    #   </tool>
+    #
+    # The <old> block must match exactly once in the file.  The tool returns an
+    # error if the text is not found or appears more than once.
+    class Edit
+      NAME        = "edit"
+
+      def self.name        = NAME
+
+      def self.call(content, path:, start_line: nil, end_line: nil)
+        path = ToolPath.normalize(path)
+
+        if range_requested?(start_line, end_line)
+          return call_range_mode(content, path: path, start_line: start_line, end_line: end_line)
+        end
+
+        old_text = extract_tag(content, "old")
+        new_text = extract_tag(content, "new")
+
+        return "Error: missing <old>...</old> block" if old_text.nil?
+        return "Error: missing <new>...</new> block" if new_text.nil?
+        return "Error: <old> block is empty" if old_text.empty?
+        return "Error: file not found: #{path}" unless File.exist?(path)
+
+        source = File.read(path)
+        count  = count_occurrences(source, old_text)
+
+        return "Error: old text not found in #{path}" if count == 0
+        return "Error: old text matches #{count} times in #{path}; make it unique" if count > 1
+
+        idx     = source.index(old_text)
+        updated = source[0, idx] + new_text + source[idx + old_text.length..]
+        File.write(path, updated)
+        "Edited #{path}: replaced #{old_text.bytesize} bytes with #{new_text.bytesize} bytes"
+      rescue => e
+        "Error: #{e.message}"
+      end
+
+      def self.call_range_mode(content, path:, start_line:, end_line:)
+        return "Error: file not found: #{path}" unless File.exist?(path)
+
+        new_text = extract_tag(content, "new")
+        return "Error: missing <new>...</new> block" if new_text.nil?
+
+        start_num = parse_positive_line_number(start_line, "start_line")
+        return start_num if start_num.is_a?(String)
+        return "Error: start_line must be provided for range edits" if start_num.nil?
+
+        source = File.read(path)
+        lines = source.lines
+        total_lines = lines.length
+
+        # Option C: end_line is optional and means "to EOF" when omitted
+        # (unless SAMAGOTCHI_EDIT_END_OPTIONAL=false).
+        end_provided = !blank?(end_line)
+        end_num = end_provided ? parse_positive_line_number(end_line, "end_line") : nil
+        return end_num if end_num.is_a?(String)
+
+        # Option B: an end_line that overshoots EOF is clamped here and flagged
+        # in the result so the agent never mutates a different span silently.
+        # Set SAMAGOTCHI_EDIT_ALLOW_OOR_END=false to keep the hard error instead.
+        clamp_note = ""
+        end_value = nil
+        if end_provided
+          if end_num > total_lines
+            if OutputGuardrails.env_bool("SAMAGOTCHI_EDIT_ALLOW_OOR_END", default: true)
+              clamp_note = " (end_line #{end_num} exceeds #{total_lines} lines; clamped to line #{total_lines})"
+              end_value = total_lines
+            else
+              return "Error: range out of bounds for #{path}: file has #{total_lines} lines"
+            end
+          else
+            end_value = end_num
+          end
+        else
+          unless OutputGuardrails.env_bool("SAMAGOTCHI_EDIT_END_OPTIONAL", default: true)
+            return "Error: start_line and end_line must both be provided for range edits"
+          end
+          end_value = total_lines
+        end
+
+        # start past EOF is genuinely unusable -> keep a hard error.
+        return "Error: start_line #{start_num} out of bounds for #{path}: file has #{total_lines} lines" if start_num > total_lines
+        return "Error: start_line must be <= end_line" if start_num > end_value
+
+        prefix = lines[0, start_num - 1].join
+        suffix = lines[end_value..]&.join.to_s
+        # Ensure new_text ends with a newline when a suffix follows so that the
+        # first suffix line isn't concatenated onto the last replacement line.
+        normalized = (!new_text.empty? && !suffix.empty? && !new_text.end_with?("\n")) ? new_text + "\n" : new_text
+        updated = prefix + normalized + suffix
+        File.write(path, updated)
+
+        replaced_lines = (end_value - start_num) + 1
+        new_line_count = new_text.lines.length
+        "Edited #{path}: replaced lines #{start_num}-#{end_value} (#{replaced_lines} lines) with #{new_line_count} lines#{clamp_note}"
+      rescue => e
+        "Error: #{e.message}"
+      end
+      private_class_method :call_range_mode
+
+      # Count non-overlapping literal occurrences of +needle+ in +haystack+.
+      def self.count_occurrences(haystack, needle)
+        count = 0
+        pos   = 0
+        while (i = haystack.index(needle, pos))
+          count += 1
+          break if count > 1  # early exit — we only care whether it's 0, 1, or >1
+          pos = i + needle.length
+        end
+        count
+      end
+      private_class_method :count_occurrences
+
+      def self.extract_tag(content, tag)
+        m = content.match(/<#{tag}>(.*?)<\/#{tag}>/m)
+        m ? m[1] : nil
+      end
+      private_class_method :extract_tag
+
+      def self.range_requested?(start_line, end_line)
+        !blank?(start_line) || !blank?(end_line)
+      end
+      private_class_method :range_requested?
+
+      def self.parse_positive_line_number(value, key)
+        return nil if blank?(value)
+
+        integer = Integer(value.to_s.strip, exception: false)
+        return "Error: #{key} must be a positive integer" unless integer&.positive?
+
+        integer
+      end
+      private_class_method :parse_positive_line_number
+
+      def self.blank?(value)
+        value.nil? || value.to_s.strip.empty?
+      end
+      private_class_method :blank?
+    end
+  end
+end