samagotchi 0.2.0

data/lib/samagotchi/tools/read.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+require_relative "output_guardrails"
+require_relative "tool_path"
+require_relative "../image_store"
+
+module Samagotchi
+  module Tools
+    # Reads a file from disk and returns its contents as a string.
+    class Read
+      NAME        = "read"
+
+      DEFAULT_HARD_MAX_BYTES = 2 * 1024 * 1024
+
+      def self.name        = NAME
+
+      # An image the tool found (by its magic bytes, whatever its name): the
+      # line the model reads, and the file the loop attaches (ToolRunner).
+      # It is that line as a String.
+      class ImageResult < String
+        attr_reader :image_path, :description
+
+        def initialize(image_path, description)
+          @image_path = image_path
+          @description = description
+          super("Image #{description} attached.")
+        end
+
+        def images = [{ path: image_path, description: description }]
+
+        # The text only says the image is attached: when it can't be, the
+        # line saying why replaces it.
+        def image_only? = true
+      end
+
+      # How far into a file its size is looked for (a JPEG's frame header
+      # can follow a large EXIF block).
+      IMAGE_HEADER_BYTES = 256 * 1024
+
+      def self.call(path, start_line: nil, end_line: nil)
+        path = ToolPath.normalize(path)
+
+        if ImageStore.image_file?(path)
+          return "Error: #{path} is an image; read it without start_line/end_line" if range_requested?(start_line, end_line)
+
+          return image_result(path)
+        end
+
+        if range_requested?(start_line, end_line)
+          return read_range(path, start_line: start_line, end_line: end_line)
+        end
+
+        size = File.size(path)
+
+        hard_max_bytes = OutputGuardrails.env_positive_int("SAMAGOTCHI_READ_HARD_MAX_BYTES", DEFAULT_HARD_MAX_BYTES)
+        truncate_at_bytes = OutputGuardrails.env_positive_int("SAMAGOTCHI_READ_TRUNCATE_AT_BYTES", OutputGuardrails::DEFAULT_TRUNCATE_AT_BYTES)
+        preview_bytes = OutputGuardrails.env_positive_int("SAMAGOTCHI_READ_PREVIEW_BYTES", OutputGuardrails::DEFAULT_PREVIEW_BYTES)
+
+        if size > hard_max_bytes
+          return "Error: file too large: #{path} (#{size} bytes, hard limit #{hard_max_bytes} bytes)."
+        end
+
+        return File.read(path) if size <= truncate_at_bytes
+
+        build_truncated_preview(path: path, file_size: size, preview_bytes: preview_bytes)
+      rescue Errno::ENOENT
+        "Error: file not found: #{path}"
+      rescue => e
+        "Error: #{e.message}"
+      end
+
+      def self.image_result(path)
+        info = ImageHeader.read(File.binread(path, IMAGE_HEADER_BYTES))
+        size = info.width && info.height ? "#{info.width}×#{info.height} " : ""
+        ImageResult.new(path, "#{File.basename(path)} (#{size}#{info.format.to_s.upcase})")
+      end
+      private_class_method :image_result
+
+      def self.build_truncated_preview(path:, file_size:, preview_bytes:)
+        preview = OutputGuardrails.head_tail_from_file(path: path, file_size: file_size, preview_bytes: preview_bytes)
+
+        preview_block = [
+          "[TRUNCATED_PREVIEW_HEAD]",
+          preview[:head],
+          "[... omitted #{preview[:omitted_bytes]} bytes ...]",
+          "[TRUNCATED_PREVIEW_TAIL]",
+          preview[:tail]
+        ].join("\n")
+
+        metadata_lines = [
+          "truncated=true",
+          "path=#{path}",
+          "preview_strategy=head_tail",
+          "file_bytes=#{file_size}",
+          "returned_preview_bytes=#{preview[:returned_preview_bytes]}",
+          "omitted_bytes=#{preview[:omitted_bytes]}"
+        ]
+
+        telemetry = telemetry_lines_for(preview_block)
+        metadata_lines.concat(telemetry) unless telemetry.empty?
+
+        [metadata_lines.join("\n"), "", preview_block].join("\n")
+      end
+
+      def self.telemetry_lines_for(content)
+        OutputGuardrails.telemetry_lines_for(
+          content: content,
+          threshold_env: "SAMAGOTCHI_READ_TELEMETRY_THRESHOLD_PCT",
+          threshold_default: OutputGuardrails::DEFAULT_TELEMETRY_THRESHOLD_PCT,
+          token_key: "estimated_tokens_for_preview",
+          pct_key: "estimated_window_pct_for_preview"
+        )
+      end
+
+      def self.range_requested?(start_line, end_line)
+        !blank?(start_line) || !blank?(end_line)
+      end
+      private_class_method :range_requested?
+
+      def self.read_range(path, start_line:, end_line:)
+        lines = File.readlines(path, chomp: false)
+        total_lines = lines.length
+        return "Error: range out of bounds for #{path}: file is empty (0 lines)" if total_lines.zero?
+
+        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 reads" if start_num.nil?
+
+        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 C: end_line is optional and means "to EOF" when omitted
+        # (unless SAMAGOTCHI_READ_END_OPTIONAL=false).
+        unless end_provided
+          return "Error: start_line and end_line must both be provided for range reads" unless OutputGuardrails.env_bool("SAMAGOTCHI_READ_END_OPTIONAL", default: true)
+
+          end_num = total_lines
+        end
+
+        # Option B: an end_line that overshoots EOF is clamped silently by
+        # Ruby's slice; when it also exceeds the file we trim here so the agent
+        # sees the real span.  Set SAMAGOTCHI_READ_ALLOW_OOR_END=false to keep
+        # the historical hard error instead.
+        clamp_note = ""
+        if end_provided && end_num > total_lines
+          if OutputGuardrails.env_bool("SAMAGOTCHI_READ_ALLOW_OOR_END", default: true)
+            clamp_note = "\n[read: end_line #{end_num} exceeds #{total_lines} lines; returning lines #{start_num}-#{total_lines}]"
+            end_num = total_lines
+          else
+            return "Error: range out of bounds for #{path}: file has #{total_lines} lines"
+          end
+        end
+
+        # A start past EOF is genuinely unusable -> keep a hard error.  A slice
+        # whose start is within the file never yields nil, so this also guards
+        # against the previous ".join on nil" crash.
+        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_num
+
+        content = lines[(start_num - 1)..(end_num - 1)].join
+        clamp_note.empty? ? content : content + clamp_note
+      end
+      private_class_method :read_range
+
+      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

data/lib/samagotchi/tools/register_reminder.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative "../reminder_store"
+
+module Samagotchi
+  module Tools
+    # Registers a periodic reminder. The harness will inject a [SYSTEM:] message
+    # into the next idle turn's conversation.
+    #
+    # The agent can use this to schedule checks (API health, file changes, etc.)
+    # without blocking the main turn. The reminder fires when the agent is idle
+    # and a new turn is about to start.
+    class RegisterReminder
+      NAME        = "register_reminder"
+
+      def self.name        = NAME
+
+      def self.call(content, reminder_store: nil, description: nil, interval_minutes: nil)
+        return "Error: reminder_store not configured" unless reminder_store
+
+        # Parse params from content string (JSON-like)
+        params = parse_params(content)
+        # Merge explicit params from kernel normalizer (overrides parsed content)
+        unless content.to_s.strip.empty?
+          params[:name] ||= content.to_s.strip
+        end
+        params[:description] ||= description if description
+        params[:interval_minutes] ||= interval_minutes if interval_minutes
+        reminder_store.register(params)
+      end
+
+      def self.parse_params(content)
+        return {} if content.to_s.strip.empty?
+
+        # Try JSON first
+        begin
+          parsed = JSON.parse(content.to_s)
+          return parsed if parsed.is_a?(Hash)
+        rescue JSON::ParserError
+          # fall through to key=value parsing
+        end
+
+        # Fallback: key=value pairs
+        params = {}
+        content.to_s.split(",").each do |pair|
+          key, value = pair.split(":", 2).map(&:strip)
+          params[key] = value if key && !value.nil?
+        end
+        params
+      end
+    end
+  end
+end

data/lib/samagotchi/tools/registry.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  module Tools
+    # The tools a session offers the model, in declaration order: the
+    # built-ins (Tools::Builtins), and later the ones bundles add. The
+    # native prompts and the chat path's tools: are rendered from #schemas,
+    # and KernelLoop#dispatch runs a call through its entry's handler.
+    class Registry
+      # @!attribute name [String]
+      # @!attribute schema [Hash] {name:, description:, parameters:}, as in
+      #   ToolDeclarations::TOOL_SCHEMAS
+      # @!attribute handler [#call] (call, kctx) → the result (a String;
+      #   "Error: …" marks a failure); kctx is the KernelLoop's ToolContext
+      # @!attribute label [String, nil] the activity line's action ("calling
+      #   tool" when nil); ToolActivity knows the built-ins' own
+      # @!attribute preview [#call, nil] call → the activity line's params
+      # @!attribute targets [#call, nil] call → what guardrail rules match
+      # @!attribute source [String] "core", or the bundle that added it
+      Entry = Struct.new(:name, :schema, :handler, :label, :preview, :targets, :source, keyword_init: true) do
+        def core? = source == "core"
+      end
+
+      def initialize
+        @entries = {}
+      end
+
+      # @return [Entry]
+      def register(name, schema:, handler:, label: nil, preview: nil, targets: nil, source: "core")
+        raise ArgumentError, "tool #{name} is already registered" if @entries.key?(name)
+
+        @entries[name] = Entry.new(name: name, schema: schema, handler: handler, label: label, preview: preview,
+                                   targets: targets, source: source)
+      end
+
+      # Remove a tool (a plugin's tool set changed after load).
+      # @return [Entry, nil] the removed entry
+      def unregister(name) = @entries.delete(name.to_s)
+
+      # @return [Entry, nil]
+      def [](name) = @entries[name.to_s]
+
+      def key?(name) = @entries.key?(name.to_s)
+
+      # @return [Array<String>] in declaration order
+      def names = @entries.keys
+
+      # @return [Array<Entry>] in declaration order
+      def entries = @entries.values
+
+      # @return [Array<Hash>] the schemas, in declaration order
+      def schemas = @entries.values.map(&:schema)
+
+      def freeze
+        @entries.freeze
+        super
+      end
+    end
+  end
+end

data/lib/samagotchi/tools/send_note.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative "../session"
+require_relative "../context_note"
+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
+    # Tell another chi session something: a context note it sees on its next
+    # turn as background from this session. It never starts a turn there.
+    class SendNote
+      NAME = "send_note"
+
+      def self.name = NAME
+
+      # @param content [String] the note
+      # @param session [String] the target's id or a unique prefix
+      # @param peers [Peers, nil]
+      def self.call(content, session: nil, peers: nil)
+        return "Error: this session's id is not known here" unless peers&.session_id
+        return "Error: give the target session's id (list_sessions shows them)" if session.to_s.strip.empty?
+
+        id = Session.resolve_id(session.to_s.strip, state_dir: peers.state_dir)
+        Session.load(id, state_dir: peers.state_dir)
+        return "Error: #{id[0, 8]} is this session; send_note is for other sessions" if id == peers.session_id
+
+        owner = SessionManager.session_owner(id, state_dir: peers.state_dir)
+        if owner && owner["kind"] == "tui"
+          return "Error: session #{id[0, 8]} is open in a chi REPL, which can't take notes"
+        end
+
+        SessionManager.write_note(id, text: content, source: "session", from_session: peers.session_id,
+                                      from_cwd: peers.cwd, state_dir: peers.state_dir)
+        where = owner ? "its worker adds it before its next turn" : "it has no worker now, so it waits for its next start"
+        "Queued a note for session #{id[0, 8]}: #{where}. It does not start a turn there."
+      rescue Session::AmbiguousId => e
+        "Error: #{e.message}"
+      rescue SessionManager::NoteRejected => e
+        "Error: #{e.message}"
+      rescue ArgumentError
+        "Error: no session #{session.to_s.strip} (list_sessions shows them)"
+      end
+    end
+  end
+end

data/lib/samagotchi/tools/task_create.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "task_runtime"
+
+module Samagotchi
+  module Tools
+    class TaskCreate
+      NAME = "task_create"
+
+      def self.name = NAME
+
+      def self.call(command, cwd: nil, env: nil)
+        record, error = TaskRuntime.create_task(command, cwd: cwd, env: env)
+        return error if error
+
+        [
+          "task_id: #{record.fetch("id")}",
+          "status: #{record.fetch("status")}",
+          "pid: #{record.fetch("pid")}",
+          "created_at: #{record.fetch("created_at")}",
+          "output_path: #{record.fetch("output_path")}",
+          "cwd: #{record.fetch("cwd")}"
+        ].join("\n")
+      rescue => e
+        "Error: #{e.message}"
+      end
+    end
+  end
+end

data/lib/samagotchi/tools/task_get.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "task_runtime"
+
+module Samagotchi
+  module Tools
+    class TaskGet
+      NAME = "task_get"
+
+      def self.name = NAME
+
+      def self.call(task_id)
+        record, error = TaskRuntime.get_record(task_id.to_s.strip)
+        return error if error
+
+        format_record(record)
+      rescue => e
+        "Error: #{e.message}"
+      end
+
+      def self.format_record(record)
+        [
+          "task_id: #{record.fetch("id")}",
+          "status: #{record.fetch("status")}",
+          "command: #{record.fetch("command")}",
+          "cwd: #{record.fetch("cwd")}",
+          "pid: #{record.fetch("pid")}",
+          "created_at: #{record.fetch("created_at")}",
+          "started_at: #{record.fetch("started_at")}",
+          "finished_at: #{record["finished_at"]}",
+          "exit_code: #{record["exit_code"]}",
+          "stop_reason: #{record["stop_reason"]}",
+          "output_path: #{record.fetch("output_path")}"
+        ].join("\n")
+      end
+      private_class_method :format_record
+    end
+  end
+end

data/lib/samagotchi/tools/task_list.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "task_runtime"
+
+module Samagotchi
+  module Tools
+    class TaskList
+      NAME = "task_list"
+      COMMAND_PREVIEW_LIMIT = 80
+
+      def self.name = NAME
+
+      def self.call(_content = nil)
+        records = TaskRuntime.list_records
+        return "No tasks found." if records.empty?
+
+        records.map { |record| format_entry(record) }.join("\n\n")
+      rescue => e
+        "Error: #{e.message}"
+      end
+
+      def self.format_entry(record)
+        [
+          "task_id: #{record.fetch("id")}",
+          "status: #{record.fetch("status")}",
+          "pid: #{record.fetch("pid")}",
+          "created_at: #{record.fetch("created_at")}",
+          "command: #{preview(record.fetch("command"))}",
+          "output_path: #{record.fetch("output_path")}"
+        ].join("\n")
+      end
+      private_class_method :format_entry
+
+      def self.preview(value)
+        text = value.to_s.gsub(/\s+/, " ").strip
+        return "" if text.length <= COMMAND_PREVIEW_LIMIT
+
+        text[0, COMMAND_PREVIEW_LIMIT - 1] + "…"
+      end
+      private_class_method :preview
+    end
+  end
+end