legate 0.1.0

data/lib/legate/tools/calculator.rb

@@ -0,0 +1,89 @@
+# File: lib/legate/tools/calculator.rb
+# frozen_string_literal: true
+
+# Removed require 'logger' - Use Legate.logger
+require_relative '../tool' # Ensure base class is loaded
+
+module Legate
+  module Tools
+    # A simple calculator tool supporting basic arithmetic operations.
+    class Calculator < Tool
+      # --- New DSL Metadata ---
+      # Name :calculator will be inferred
+      tool_description 'Calculates the result of an arithmetic operation. Requires two numbers (operand1, operand2) and the operation name (operation: "add", "subtract", "multiply", "divide", or symbols +, -, *, /).'
+
+      parameter :operand1,
+                type: :numeric,
+                description: 'The first number for the calculation.',
+                required: true
+
+      parameter :operand2,
+                type: :numeric,
+                description: 'The second number for the calculation.',
+                required: true
+
+      parameter :operation,
+                type: :string,
+                description: 'The operation to perform (e.g., "add", "subtract", "multiply", "divide", "+", "-", "*", "/").',
+                required: true
+
+      private
+
+      # @param params [Hash] Contains operand1, operand2, operation.
+      # @param _context [Legate::ToolContext, nil] The execution context (unused here).
+      def perform_execution(params, _context)
+        op1_str = params.fetch('operand1') { params.fetch(:operand1, nil) }
+        op2_str = params.fetch('operand2') { params.fetch(:operand2, nil) }
+        operation = params.fetch('operation') { params.fetch(:operation, nil) }&.to_s&.downcase
+
+        begin
+          # Validate inputs first
+          begin
+            op1 = Float(op1_str)
+            op2 = Float(op2_str)
+          rescue ArgumentError, TypeError
+            err_msg = "Invalid numeric input provided for operands. Op1: '#{op1_str}', Op2: '#{op2_str}'"
+            Legate.logger.error("Calculator Tool Argument Error: #{err_msg}")
+            raise Legate::ToolArgumentError, err_msg
+          end
+
+          valid_ops = %w[add subtract multiply divide + - * /]
+          unless valid_ops.include?(operation)
+            err_msg = "Unsupported operation: '#{operation}'. Use add, subtract, multiply, or divide (or +, -, *, /)."
+            Legate.logger.warn("Calculator Tool Argument Warning: #{err_msg}")
+            raise Legate::ToolArgumentError, err_msg
+          end
+
+          if %w[divide /].include?(operation) && op2.zero?
+            err_msg = 'Division by zero is not allowed.'
+            Legate.logger.error("Calculator Tool Argument Error: #{err_msg}")
+            raise Legate::ToolArgumentError, err_msg
+          end
+
+          # Perform calculation
+          result_val = case operation
+                       when 'add', '+' then op1 + op2
+                       when 'subtract', '-' then op1 - op2
+                       when 'multiply', '*' then op1 * op2
+                       when 'divide', '/' then op1 / op2 # Zero already checked
+                         # No else needed due to validation above
+                       end
+
+          Legate.logger.info("Calculator Tool: #{op1} #{operation} #{op2} = #{result_val}")
+          { status: :success, result: result_val }
+
+        # Catch potential unexpected errors during execution logic itself
+        rescue Legate::ToolArgumentError => e # Re-raise argument errors
+          raise e
+        rescue Legate::ToolError => e # Catch specific Legate tool errors if they occur somehow
+          Legate.logger.error("Calculator Tool Legate::ToolError: #{e.message}")
+          raise e # Re-raise to be handled by the agent
+        rescue StandardError => e
+          # Wrap unexpected errors in a ToolError
+          Legate.logger.error("Calculator Tool: Unexpected internal error during calculation: #{e.class} - #{e.message}")
+          raise Legate::ToolError, "Calculation failed due to an unexpected internal error: #{e.message}"
+        end
+      end # End perform_execution
+    end # End Calculator class
+  end # End Tools module
+end # End Legate module

data/lib/legate/tools/cat_facts.rb

@@ -0,0 +1,81 @@
+# File: lib/legate/tools/cat_facts.rb
+# frozen_string_literal: true
+
+# Removed Faraday and JSON requires, handled by HttpClient
+require_relative '../tool'
+require_relative 'base/http_client' # Include the base module
+
+module Legate
+  module Tools
+    # Tool to fetch a random cat fact from an online API.
+    class CatFacts < Legate::Tool
+      include Legate::Tools::Base::HttpClient # Include the mixin
+
+      # --- New DSL Metadata ---
+      # Name :cat_facts will be inferred
+      tool_description 'Fetches a random cat fact from an online API.'
+      # No parameters needed, so no `parameter` calls.
+      # --- End New DSL Metadata ---
+
+      # The base URL for the Cat Fact API.
+      CAT_FACT_BASE_URL = 'https://catfact.ninja'
+
+      # Initializes the tool instance.
+      # Sets up the HTTP client using the base module.
+      def initialize(**options)
+        super(**options)
+        # Use the base module to set up the client
+        # It handles initialization errors and logging internally.
+        setup_http_client(base_url: CAT_FACT_BASE_URL)
+      end
+
+      private
+
+      # The main execution method required by the Legate::Tool base class.
+      # It delegates the actual work to the fetch_cat_fact helper method.
+      def perform_execution(_params, _context)
+        fetch_cat_fact
+      end
+
+      # Helper method to perform the HTTP request using the HttpClient module
+      # and handle responses/errors.
+      # Returns the standardized result hash.
+      #
+      # @return [Hash] A hash with :status (:success or :error) and :result/:error_message.
+      # @raise [Legate::ToolError] Propagates errors from http_get, parse_json_response, or validation.
+      def fetch_cat_fact
+        Legate.logger.info('Fetching cat fact using HttpClient...')
+
+        # Perform the GET request using the base module helper
+        # Network/HTTP/Timeout errors are automatically handled and raised as Legate::ToolError
+        response = http_get('/fact')
+
+        # Parse the JSON response body directly
+        begin
+          data = JSON.parse(response.body)
+        rescue JSON::ParserError => e
+          raise Legate::ToolError.new("Failed to parse JSON response from Cat Fact API: #{e.message}", cause: e)
+        end
+
+        fact = data['fact'] # Extract the 'fact' field
+
+        # Check if a valid fact was received
+        if fact && !fact.empty?
+          Legate.logger.info('Cat fact fetched successfully.')
+          { status: :success, result: fact }
+        else
+          # Raise an error if the expected field is missing or empty
+          err_msg = "Cat fact API response did not contain a valid 'fact' field."
+          Legate.logger.warn(err_msg)
+          raise Legate::ToolError, err_msg
+        end
+
+        # No need for extensive rescue blocks here anymore.
+        # Legate::ToolError from http_get, parse_json_response, or the validation
+        # will propagate up and be handled by the Legate runtime.
+        # StandardError might still occur in unexpected places, but the base
+        # HttpClient tries to catch most common issues.
+      end # end fetch_cat_fact
+    end # End CatFacts class
+  end # End Tools module
+end # End Legate module

data/lib/legate/tools/check_job_status_tool.rb

@@ -0,0 +1,48 @@
+# File: lib/legate/tools/check_job_status_tool.rb
+# frozen_string_literal: true
+
+require_relative '../tool'
+require_relative '../errors'
+require 'json'
+
+module Legate
+  module Tools
+    # A built-in tool to check the status and retrieve results for a background job
+    # initiated by a Legate async tool.
+    class CheckJobStatusTool < Legate::Tool
+      # --- New DSL Metadata ---
+      # Name :check_job_status_tool will be inferred
+      self.explicit_tool_name = :check_job_status # Keep original name
+
+      tool_description 'Checks the status and retrieves the result of a previously started background job using its ID.'
+
+      parameter :job_id,
+                type: :string,
+                description: 'The ID of the job to check status for',
+                required: true
+      # --- End New DSL Metadata ---
+
+      private
+
+      # @param params [Hash] Must contain :job_id.
+      # @param _context [Legate::ToolContext, nil] The execution context (unused here).
+      # @return [Hash] { status: :success/:error, ... }
+      def perform_execution(params, _context)
+        job_id = params[:job_id]
+        return { status: :error, error_message: 'Missing job_id parameter.' } unless job_id && !job_id.strip.empty?
+
+        result = Legate::Tools::BaseAsyncJobTool.job_results[job_id]
+
+        if result.nil?
+          { status: :success, job_id: job_id, job_status: 'unknown', message: 'Job ID not found.' }
+        else
+          job_status = result['status']
+          response = { status: :success, job_id: job_id, job_status: job_status }
+          response[:result] = result['result'] if result['result']
+          response[:error_message] = result['error_message'] if result['error_message']
+          response
+        end
+      end
+    end
+  end
+end

data/lib/legate/tools/current_time_tool.rb

@@ -0,0 +1,64 @@
+# File: lib/legate/tools/current_time_tool.rb
+# frozen_string_literal: true
+
+require_relative '../tool'
+require 'time'
+
+module Legate
+  module Tools
+    # Returns the current date and time.
+    #
+    # Language models don't know the current time, so this is a common building
+    # block for scheduling, "how long ago", and freshness checks. Returns UTC by
+    # default; accepts "UTC", "local", or a fixed UTC offset (e.g. "+09:00").
+    # Named IANA zones (e.g. "America/New_York") are intentionally not supported
+    # to avoid a timezone-database dependency and process-global TZ mutation.
+    class CurrentTime < Legate::Tool
+      OFFSET_PATTERN = /\A[+-]\d{2}:?\d{2}\z/
+
+      tool_name # inferred: :current_time
+      tool_description 'Returns the current date and time (ISO 8601, epoch, and an optional custom format). ' \
+                       'Accepts a timezone of "UTC" (default), "local", or a fixed UTC offset like "+09:00".'
+
+      parameter :timezone, type: :string, required: false,
+                           description: 'Timezone: "UTC" (default), "local", or a fixed offset such as "+05:30" or "-0800".'
+      parameter :format, type: :string, required: false,
+                         description: 'Optional strftime format (e.g. "%A, %B %-d, %Y"). Defaults to ISO 8601.'
+
+      private
+
+      def perform_execution(params, _context)
+        now = Time.now.utc
+        tz = params[:timezone].to_s.strip
+        base = localize(now, tz)
+        return { status: :error, error_message: unsupported_tz_message(tz) } unless base
+
+        fmt = params[:format].to_s
+        {
+          status: :success,
+          result: {
+            iso8601: base.iso8601,
+            formatted: fmt.empty? ? base.iso8601 : base.strftime(fmt),
+            epoch: now.to_i,
+            timezone: tz.empty? ? 'UTC' : tz
+          }
+        }
+      rescue ArgumentError => e
+        { status: :error, error_message: "Invalid format or timezone: #{e.message}" }
+      end
+
+      def localize(utc_now, zone)
+        case zone.downcase
+        when '', 'utc', 'z' then utc_now
+        when 'local' then utc_now.getlocal
+        else
+          zone.match?(OFFSET_PATTERN) ? utc_now.getlocal(zone) : nil
+        end
+      end
+
+      def unsupported_tz_message(zone)
+        "Unsupported timezone '#{zone}'. Use 'UTC', 'local', or a fixed offset like '+09:00'."
+      end
+    end
+  end
+end

data/lib/legate/tools/echo.rb

@@ -0,0 +1,43 @@
+# File: lib/legate/tools/echo.rb
+# frozen_string_literal: true
+
+require_relative '../tool'
+
+module Legate
+  module Tools
+    class Echo < Tool
+      # --- New DSL Metadata ---
+      # Name :echo will be inferred
+      tool_description 'Echoes back the provided message.'
+
+      parameter :message,
+                type: :string,
+                description: 'The message to echo',
+                required: true
+      # --- End New DSL Metadata ---
+
+      private
+
+      # @param params [Hash] Contains :message.
+      # @param _context [Legate::ToolContext, nil] The execution context (unused here).
+      def perform_execution(params, _context)
+        # Fetch validated parameter
+        message = params.fetch('message') { params.fetch(:message, nil) }
+
+        # This check is belts-and-suspenders; validation should catch missing required params.
+        unless message
+          err_msg = 'Internal Error: Message parameter missing in perform_execution for Echo tool after validation.'
+          Legate.logger.error(err_msg)
+          raise Legate::ToolError, err_msg
+        end
+
+        # Simple success case
+        { status: :success, result: message }
+      rescue StandardError => e # Catch any truly unexpected errors during fetch/processing
+        Legate.logger.error("Echo Tool: Unexpected error: #{e.class} - #{e.message}")
+        # Wrap unexpected errors in a ToolError
+        raise Legate::ToolError, "Unexpected error in Echo tool: #{e.message}"
+      end
+    end # End Echo class
+  end # End Tools module
+end # End Legate module

data/lib/legate/tools/http_request_tool.rb

@@ -0,0 +1,105 @@
+# File: lib/legate/tools/http_request_tool.rb
+# frozen_string_literal: true
+
+require_relative '../tool'
+require_relative 'base/http_client'
+require_relative 'base/safe_url'
+
+module Legate
+  module Tools
+    # General-purpose HTTP client tool.
+    #
+    # Makes a request to a URL and returns the status code, response headers, and
+    # body. It is SSRF-safe (private/loopback/link-local hosts are blocked and the
+    # connection is pinned to the validated IP) and auth-aware (configured auth
+    # URL-mappings are applied automatically; pass `headers` for manual auth).
+    #
+    # A non-2xx response is returned as a normal result (with its status_code) so
+    # an agent can inspect it; only network/SSRF/timeout failures are errors.
+    class HttpRequest < Legate::Tool
+      include Legate::Tools::Base::HttpClient
+
+      # Cap the returned body so a large download can't blow up the context/LLM.
+      MAX_BODY_BYTES = 1_000_000
+      ALLOWED_METHODS = %w[GET POST PUT PATCH DELETE HEAD].freeze
+
+      tool_name # inferred: :http_request
+      tool_description 'Makes an HTTP request to a URL and returns the status code, headers, and body. ' \
+                       'Supports GET (default), POST, PUT, PATCH, DELETE, and HEAD. Blocks private and ' \
+                       'loopback addresses (SSRF-safe) and applies configured authentication for matching URLs.'
+
+      parameter :url, type: :string, required: true,
+                      description: 'The full URL to request (must be http or https).'
+      parameter :method, type: :string, required: false,
+                         description: 'HTTP method: GET (default), POST, PUT, PATCH, DELETE, or HEAD.'
+      parameter :headers, type: :hash, required: false,
+                          description: 'Optional request headers.'
+      parameter :body, type: %i[hash string], required: false,
+                       description: 'Optional request body. A Hash is JSON-encoded with Content-Type: application/json.'
+      parameter :query, type: :hash, required: false,
+                        description: 'Optional query-string parameters.'
+
+      def initialize(**options)
+        super(**options)
+        # Targets are passed absolute per-request; the base URL is only a required placeholder.
+        setup_http_client(base_url: 'https://placeholder.invalid')
+      end
+
+      private
+
+      def perform_execution(params, context)
+        url = params.fetch(:url)
+        method = (params[:method] || 'GET').to_s.upcase
+        return { status: :error, error_message: "Unsupported HTTP method: #{method}" } unless ALLOWED_METHODS.include?(method)
+
+        uri, pinned_ip = Legate::Tools::Base::SafeUrl.resolve!(url)
+        headers = apply_auth(context, method, url, stringify_headers(params[:headers] || {}))
+
+        response = make_request(
+          method.downcase.to_sym, url,
+          body: params[:body],
+          query: params[:query] || {},
+          headers: headers,
+          options: { resolved_ip: pinned_ip, original_host: uri.host }
+        )
+        { status: :success, result: build_result(url, response) }
+      rescue Legate::ToolHttpError => e
+        # A non-2xx response still completed; surface its details rather than erroring.
+        return { status: :success, result: build_result(url, e.response) } if e.response
+
+        { status: :error, error_message: e.message }
+      rescue Legate::ToolError => e
+        { status: :error, error_message: e.message }
+      end
+
+      # Let the execution context apply any configured auth (URL mappings). It is a
+      # no-op when no auth is configured or the context doesn't support it.
+      def apply_auth(context, method, url, headers)
+        return headers unless context.respond_to?(:handle_request_auth)
+
+        request = context.handle_request_auth({ method: method.downcase.to_sym, url: url, headers: headers })
+        request.is_a?(Hash) && request[:headers] ? request[:headers] : headers
+      rescue StandardError => e
+        Legate.logger.warn("HttpRequest: auth application failed, sending unauthenticated: #{e.message}")
+        headers
+      end
+
+      def build_result(url, response)
+        body = response.body.to_s
+        truncated = body.bytesize > MAX_BODY_BYTES
+        body = body.byteslice(0, MAX_BODY_BYTES) if truncated
+        {
+          url: url,
+          status_code: response.status,
+          headers: response.headers,
+          body: body,
+          truncated: truncated
+        }
+      end
+
+      def stringify_headers(hash)
+        hash.transform_keys(&:to_s)
+      end
+    end
+  end
+end

data/lib/legate/tools/random_number_tool.rb

@@ -0,0 +1,64 @@
+# File: lib/legate/tools/random_number_tool.rb
+# frozen_string_literal: true
+
+require_relative '../tool'
+
+module Legate
+  module Tools
+    class RandomNumberTool < Legate::Tool
+      # --- New DSL Metadata ---
+      # Name will be inferred as :random_number_tool
+      self.explicit_tool_name = :random_number # Keep original name
+
+      tool_description 'Generates a random integer between a minimum and maximum value (inclusive). Defaults to 1-100.'
+
+      parameter :min,
+                type: :integer,
+                description: 'The minimum value for the random number (inclusive).',
+                required: false
+
+      parameter :max,
+                type: :integer,
+                description: 'The maximum value for the random number (inclusive).',
+                required: false
+      # --- End New DSL Metadata ---
+
+      private
+
+      # @param params [Hash] Contains min and max.
+      # @param _context [Legate::ToolContext, nil] The execution context (unused here).
+      def perform_execution(params, _context)
+        # Fetch parameters safely, providing defaults
+        min_val_str = params.fetch('min') { params.fetch(:min, '1') }
+        max_val_str = params.fetch('max') { params.fetch(:max, '100') }
+
+        begin
+          min_val = Integer(min_val_str)
+          max_val = Integer(max_val_str)
+        rescue ArgumentError, TypeError
+          err_msg = "Invalid integer input provided for min or max. Min: '#{min_val_str}', Max: '#{max_val_str}'"
+          Legate.logger.error("RandomNumberTool Argument Error: #{err_msg}")
+          raise Legate::ToolArgumentError, err_msg
+        end
+
+        # Check logical constraint
+        if min_val > max_val
+          err_msg = "Min value (#{min_val}) cannot be greater than Max value (#{max_val})."
+          Legate.logger.error("RandomNumberTool Argument Error: #{err_msg}")
+          raise Legate::ToolArgumentError, err_msg
+        end
+
+        # Perform the core logic
+        random_num = rand(min_val..max_val)
+        Legate.logger.info("RandomNumberTool generated: #{random_num} (Range: #{min_val}-#{max_val})")
+        { status: :success, result: random_num }
+      rescue Legate::ToolArgumentError => e # Re-raise specific argument errors
+        raise e
+      rescue StandardError => e # Catch unexpected errors during the process
+        Legate.logger.error("RandomNumberTool: Unexpected error: #{e.class} - #{e.message}")
+        # Wrap unexpected errors in a ToolError
+        raise Legate::ToolError, "Unexpected error in RandomNumber tool: #{e.message}"
+      end
+    end # End RandomNumberTool class
+  end # End Tools module
+end # End Legate module

data/lib/legate/tools/read_webpage_tool.rb

@@ -0,0 +1,92 @@
+# File: lib/legate/tools/read_webpage_tool.rb
+# frozen_string_literal: true
+
+require_relative '../tool'
+require_relative 'base/http_client'
+require_relative 'base/safe_url'
+
+module Legate
+  module Tools
+    # Fetches a web page and returns its readable text content with markup removed.
+    #
+    # This is the backbone of research/RAG agents: give it a URL and it returns
+    # the page title and plain text (script/style stripped, entities decoded,
+    # whitespace collapsed), capped to a sane size. SSRF-safe via {Base::SafeUrl}.
+    class ReadWebpage < Legate::Tool
+      include Legate::Tools::Base::HttpClient
+
+      DEFAULT_MAX_CHARS = 20_000
+      HARD_MAX_CHARS = 200_000
+      ENTITIES = { '&amp;' => '&', '&lt;' => '<', '&gt;' => '>', '&quot;' => '"',
+                   '&#39;' => "'", '&apos;' => "'", '&nbsp;' => ' ' }.freeze
+
+      tool_name # inferred: :read_webpage
+      tool_description 'Fetches a web page and returns its readable text content (HTML markup removed) and title. ' \
+                       'Use this to read articles or documentation. Blocks private/loopback addresses (SSRF-safe).'
+
+      parameter :url, type: :string, required: true,
+                      description: 'The URL of the page to read (http or https).'
+      parameter :max_chars, type: :integer, required: false,
+                            description: "Maximum characters of text to return (default #{DEFAULT_MAX_CHARS})."
+
+      def initialize(**options)
+        super(**options)
+        setup_http_client(base_url: 'https://placeholder.invalid')
+      end
+
+      private
+
+      def perform_execution(params, _context)
+        url = params.fetch(:url)
+        limit = (params[:max_chars] || DEFAULT_MAX_CHARS).to_i.clamp(1, HARD_MAX_CHARS)
+
+        uri, pinned_ip = Legate::Tools::Base::SafeUrl.resolve!(url)
+        response = make_request(
+          :get, url,
+          headers: { 'Accept' => 'text/html,application/xhtml+xml,text/plain;q=0.9,*/*;q=0.8' },
+          options: { resolved_ip: pinned_ip, original_host: uri.host }
+        )
+
+        html = response.body.to_s
+        text = html_to_text(html)
+        truncated = text.length > limit
+        {
+          status: :success,
+          result: {
+            url: url,
+            title: extract_title(html),
+            text: truncated ? text[0, limit] : text,
+            truncated: truncated
+          }
+        }
+      rescue Legate::ToolError => e
+        { status: :error, error_message: e.message }
+      end
+
+      def extract_title(html)
+        match = html.match(%r{<title[^>]*>(.*?)</title>}im)
+        match ? decode_entities(match[1].strip) : nil
+      end
+
+      # Best-effort HTML → plain text without a parser dependency: drop
+      # script/style/comments, turn block boundaries into newlines, strip the
+      # remaining tags, decode common entities, and collapse whitespace.
+      def html_to_text(html)
+        text = html.dup
+        text.gsub!(%r{<head[^>]*>.*?</head>}im, ' ')
+        text.gsub!(%r{<(script|style)[^>]*>.*?</\1>}im, ' ')
+        text.gsub!(/<!--.*?-->/m, ' ')
+        text.gsub!(%r{</?(p|div|br|li|tr|h[1-6]|section|article|header|footer)[^>]*>}i, "\n")
+        text.gsub!(/<[^>]+>/, ' ')
+        text = decode_entities(text)
+        text.gsub(/[ \t]+/, ' ').gsub(/ *\n */, "\n").gsub(/\n{3,}/, "\n\n").strip
+      end
+
+      def decode_entities(str)
+        str = str.gsub(/&#(\d+);/) { [Regexp.last_match(1).to_i].pack('U') }
+        ENTITIES.each { |entity, char| str = str.gsub(entity, char) }
+        str
+      end
+    end
+  end
+end

data/lib/legate/tools/sleepy_tool.rb

@@ -0,0 +1,74 @@
+# File: lib/legate/tools/sleepy_tool.rb
+# frozen_string_literal: true
+
+require_relative 'base_async_job_tool'
+
+module Legate
+  module Tools
+    # An example Legate tool that starts a background job that sleeps for a specified duration.
+    # This tool demonstrates how to implement a BaseAsyncJobTool with a background worker.
+    class SleepyTool < BaseAsyncJobTool
+      # --- New DSL Metadata ---
+      # Name will be inferred as :sleepy_tool
+      self.explicit_tool_name = :start_sleepy_job # Keep original name
+
+      tool_description 'Starts a background job that sleeps for a specified duration and then returns a message.'
+
+      parameter :duration,
+                type: :integer,
+                description: 'How many seconds the job should sleep.',
+                required: true
+
+      parameter :message,
+                type: :string,
+                description: 'A message to include in the final result.',
+                required: true
+      # --- End New DSL Metadata ---
+
+      # Return the worker class to use.
+      def worker_class
+        SleepyWorker
+      end
+
+      # Prepare the arguments for the worker's perform method.
+      # Arguments must be JSON-serializable.
+      def prepare_job_arguments(params, _context)
+        duration = params[:duration].to_i
+        message = params[:message].to_s
+        [duration, message] # Must match SleepyWorker#perform signature (after jid)
+      end
+    end
+
+    # The worker that performs the actual sleep operation.
+    class SleepyWorker
+      # @param jid [String] The Job ID (passed as first argument by BaseAsyncJobTool).
+      # @param duration [Integer] How long to sleep in seconds.
+      # @param message [String] The message to return upon completion.
+      def perform(jid, duration, message)
+        # --- Store initial pending status --- #
+        begin
+          Legate::Tools::BaseAsyncJobTool.store_job_pending(jid)
+        rescue StandardError => e
+          # Log error but try to continue if possible
+          Legate.logger.error("[SleepyWorker JID: #{jid}] Failed to store initial pending status: #{e.message}")
+        end
+        # --- End store initial pending status --- #
+
+        Legate.logger.info("[SleepyWorker JID: #{jid}] Starting job. Sleeping for #{duration} seconds...")
+
+        begin
+          sleep duration.to_i
+          result_message = "Slept for #{duration} seconds. Your message: #{message}"
+          Legate.logger.info("[SleepyWorker JID: #{jid}] Job finished. Storing result.")
+          # Store the successful result using the helper from BaseAsyncJobTool
+          Legate::Tools::BaseAsyncJobTool.store_job_result(jid, result_message)
+        rescue StandardError => e
+          error_message = "Job failed after starting sleep: #{e.message}"
+          Legate.logger.error("[SleepyWorker JID: #{jid}] Job failed! Storing error. Error: #{error_message}")
+          # Store the error using the helper
+          Legate::Tools::BaseAsyncJobTool.store_job_error(jid, error_message, e.class.name)
+        end
+      end
+    end
+  end
+end