legate 0.1.0

data/examples/advanced/mcp/mcp_server_legate_agent.rb

@@ -0,0 +1,95 @@
+# File: examples/advanced/mcp/mcp_server_legate_agent.rb
+# frozen_string_literal: true
+
+# --- Example: Exposing an Legate::Agent via MCP using fast-mcp ---
+#
+# This script demonstrates how to wrap an existing Legate::Agent definition
+# and expose it as a single tool on an MCP server
+# run over STDIO using the fast-mcp gem and LegateAgentAdapter.
+#
+# Prerequisites:
+#   - Run `bundle install` in the legate directory.
+#   - Ensure the `fast-mcp` gem is available (e.g., via Gemfile path).
+#   - An agent definition registered in GlobalDefinitionRegistry.
+#     Replace `MY_AGENT_NAME` below with the actual name.
+#
+# Usage:
+#   1. Replace `MY_AGENT_NAME` with your agent's name.
+#   2. Run this script from the legate root directory:
+#      `bundle exec ruby examples/advanced/mcp/mcp_server_legate_agent.rb`
+#   3. The script will start and wait for MCP JSON-RPC messages on STDIN.
+#   4. Use an MCP client connected to this script's STDIO to interact.
+#
+# Example Interaction (using a generic client):
+#   -> {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"capabilities":{}}}
+#   <- {"jsonrpc":"2.0","id":1,"result":{"capabilities":{},"serverInfo":{"name":"Legate Agent Server","version":"x.y.z"}}}
+#   -> {"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
+#   <- {"jsonrpc":"2.0","id":2,"result":{"tools":[{"name":"run_agent_MY_AGENT_NAME","description":"Runs the Legate Agent 'MY_AGENT_NAME' with the given prompt.","inputSchema":{"type":"object","properties":{"prompt":{"type":"string","description":"The user input/prompt for the agent"}},"required":["prompt"]}}]}}
+#   -> {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"run_agent_MY_AGENT_NAME","arguments":{"prompt":"Hello agent!"}}}
+#   <- {"jsonrpc":"2.0","id":3,"result":"Hello from the agent!"} // (or whatever the agent returns)
+#
+# -------------------------------------------------------------
+
+$LOAD_PATH.unshift File.expand_path('../../lib', __dir__)
+require 'legate'
+Legate.load_environment # Handle Bundler, Dotenv, etc.
+require 'legate/mcp'
+require 'legate/mcp/server/legate_agent_adapter' # Load the Agent adapter
+require 'legate/session_service/in_memory' # Using in-memory for temporary sessions
+require 'fast_mcp'
+
+# --- ** Configuration: Replace with your agent name ** ---
+AGENT_NAME = 'my_agent' # <<< CHANGE THIS
+# ---------------------------------------------------------
+
+Legate.configure do |config|
+  # config.log_level = :debug
+end
+
+# --- 1. Create Session Service Instance ---
+# LegateAgentAdapter needs this to create temporary sessions for each call.
+# Using InMemory for simplicity, but RedisSessionService would also work.
+session_service = Legate::SessionService::InMemory.new
+Legate.logger.info("Using session service: #{session_service.class}")
+
+# --- 2. Wrap the Legate Agent Definition ---
+begin
+  AdaptedAgent = Legate::Mcp::Server::LegateAgentAdapter.wrap(AGENT_NAME, session_service)
+  Legate.logger.info("Successfully wrapped Legate Agent definition '#{AGENT_NAME}' for MCP.")
+rescue Legate::Mcp::Error => e
+  Legate.logger.fatal("Failed to wrap Legate Agent: #{e.message}")
+  Legate.logger.fatal("Please ensure the agent '#{AGENT_NAME}' is defined.")
+  exit(1)
+rescue StandardError => e
+  Legate.logger.fatal("Unexpected error during agent wrap: #{e.message}")
+  Legate.logger.fatal(e.backtrace.join("\n"))
+  exit(1)
+end
+
+# --- 3. Create fast-mcp Server Instance ---
+mcp_server = FastMcp::Server::Stdio.new(
+  server_info: {
+    name: 'Legate Agent Server',
+    version: Legate::VERSION
+  },
+  logger: Legate.logger
+)
+Legate.logger.info('Initialized FastMcp::Server::Stdio.')
+
+# --- 4. Register the Wrapped Agent Tool ---
+mcp_server.register_tool(AdaptedAgent)
+Legate.logger.info("Registered adapted agent tool '#{AdaptedAgent.tool_name}' with fast-mcp server.")
+
+# --- 5. Start the Server ---
+Legate.logger.info("Starting MCP server on STDIO for agent '#{AGENT_NAME}'. Waiting for requests...")
+puts "--- Legate MCP Agent Server (#{AGENT_NAME}) Ready --- "
+begin
+  mcp_server.start
+rescue Interrupt
+  Legate.logger.info('Received interrupt, shutting down server.')
+rescue StandardError => e
+  Legate.logger.fatal("MCP server crashed: #{e.class} - #{e.message}")
+  Legate.logger.fatal(e.backtrace.join("\n"))
+ensure
+  Legate.logger.info('MCP server stopped.')
+end

data/examples/advanced/mcp/mcp_server_rack.rb

@@ -0,0 +1,89 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example: Exposing Legate Tools via MCP using Rack Middleware
+#
+# This example demonstrates how to wrap an Legate tool (CalculatorTool)
+# using LegateToolAdapter and expose it via MCP using fast-mcp's
+# Rack middleware integration.
+#
+# Requires:
+#   - legate gem with MCP support installed
+#   - fast-mcp gem installed
+#   - rack and puma gems installed (`bundle add rack puma`)
+#
+# To Run:
+#   1. Execute this script: `bundle exec ruby examples/advanced/mcp/mcp_server_rack.rb`
+#   2. The server will start on http://localhost:9292.
+#   3. In another terminal, use mcp-inspector (select SSE transport):
+#      `npx @modelcontextprotocol/inspector`
+#      Connect to: `http://localhost:9292/mcp/sse`
+#   4. In the inspector:
+#      - Call the 'my_calculator' tool with parameters like:
+#        { "a": 10, "b": 5, "op": "*" }
+#      - Observe the result.
+
+$LOAD_PATH.unshift File.expand_path('../../lib', __dir__)
+require 'legate'
+Legate.load_environment # Handle Bundler, Dotenv, etc.
+
+require 'fast_mcp'
+require 'legate/mcp/server/legate_tool_adapter'
+require 'legate/tools/calculator' # The Legate tool we want to expose
+require 'rack'
+require 'rack/handler/puma'
+
+ENV['LEGATE_LOG_LEVEL'] = 'FATAL'
+
+# Configure Legate logger
+# Legate.configure { |c| c.log_level = Logger::INFO }
+
+# --- Define a simple base Rack app ---
+# This is the app that runs alongside the MCP middleware.
+# You could replace this with your Rails/Sinatra app.
+base_app = lambda do |env|
+  if env['PATH_INFO'] == '/'
+    [200, { 'Content-Type' => 'text/html' }, [
+      '<html><body>',
+      '<h1>Legate MCP Rack Server Example</h1>',
+      '<p>MCP endpoints are active at /mcp/sse and /mcp/messages.</p>',
+      '</body></html>'
+    ]]
+  else
+    [404, { 'Content-Type' => 'text/plain' }, ['Not Found']]
+  end
+end
+
+# --- Wrap the Legate Tool ---
+begin
+  AdaptedCalculator = Legate::Mcp::Server::LegateToolAdapter.wrap(Legate::Tools::Calculator)
+  Legate.logger.info("Wrapped CalculatorTool as: #{AdaptedCalculator.tool_name}")
+rescue ArgumentError => e
+  Legate.logger.fatal("Failed to wrap CalculatorTool: #{e.message}")
+  exit(1)
+end
+
+# --- Create the MCP Middleware ---
+# This adds the /mcp/sse and /mcp/messages endpoints to the base_app.
+mcp_middleware = FastMcp.rack_middleware(
+  base_app,
+  name: 'legate-rack-server',
+  version: '1.0.0',
+  logger: Legate.logger,
+  allowed_origins: ['localhost', '127.0.0.1'] # Optional: Customize allowed origins
+) do |server|
+  # Register the wrapped tool with the server instance managed by the middleware
+  server.register_tool(AdaptedCalculator)
+  Legate.logger.info('Registered adapted tools with fast-mcp middleware server.')
+end
+
+# --- Run the Rack Application with Puma ---
+puts 'Starting Rack application with MCP middleware on http://localhost:9292'
+puts 'MCP endpoints:'
+puts '  - http://localhost:9292/mcp/sse (SSE endpoint)'
+puts '  - http://localhost:9292/mcp/messages (JSON-RPC endpoint)'
+puts 'Press Ctrl+C to stop'
+
+Rack::Handler::Puma.run mcp_middleware, Port: 9292
+
+Legate.logger.info('Server finished.')

data/examples/advanced/random_calculator.rb

@@ -0,0 +1,104 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# If running from project root: bundle exec ruby examples/advanced/random_calculator.rb
+require_relative '../../lib/legate'
+
+# random_number is a demo tool — shipped but not registered by default — so this
+# example opts into it explicitly. (calculator is a registered built-in.)
+Legate::GlobalToolManager.register_tool(Legate::Tools::RandomNumberTool)
+
+puts '--- Random Calculator Agent Example (Multi-Step Planner w/ Hash Results) ---'
+
+# 1. --- Agent Definition ---
+random_calculator_definition = Legate::AgentDefinition.new.define do |a|
+  a.name :random_calculator_agent # Changed from multi_step_hash_agent_001 for clarity
+  a.description 'An agent that uses random number and calculator tools.'
+  a.instruction 'Your goal is to follow multi-step instructions involving random numbers and calculations. Use the random_number tool first, then the calculator tool with the result.'
+  a.use_tool :random_number # Provided by Legate::Tools::RandomNumberTool
+  a.use_tool :calculator    # Provided by Legate::Tools::Calculator
+end
+
+# 2. --- Agent Instantiation ---
+agent = Legate::Agent.new(definition: random_calculator_definition)
+
+puts "\nAgent '#{agent.name}' created."
+puts "Agent tools loaded: #{agent.tools.map(&:name).join(', ')}"
+
+# 3. --- Start Agent ---
+agent.start
+puts "\nAgent '#{agent.name}' started. Running: #{agent.running?}"
+
+# 4. --- Session Setup ---
+# Create a session service and session
+session_service = Legate::SessionService::InMemory.new
+session = session_service.create_session(app_name: agent.name, user_id: 'example_user')
+session_id = session.id
+puts "\nCreated session: #{session_id}"
+
+# 5. --- Task Execution ---
+task = 'Get a random number between 10 and 20, then multiply it by 3.'
+puts "\nRunning high-level task via agent.run_task: '#{task}'"
+
+# Set log level to DEBUG to see planner details if needed
+# ENV['LEGATE_LOG_LEVEL'] = 'DEBUG'
+# Legate.instance_variable_set(:@logger, nil) # Force logger re-init
+
+begin
+  result_event = agent.run_task(
+    session_id: session_id,
+    user_input: task,
+    session_service: session_service
+  )
+  puts "Raw result event: #{result_event.inspect}" # Show the structure
+
+  # --- Updated Result Handling ---
+  puts "\nInterpreted Result:"
+  if result_event.is_a?(Legate::Event)
+    puts ' Status: Event Received'
+    puts " Role: #{result_event.role}"
+
+    content = result_event.content
+    if content.is_a?(Array)
+      puts ' Content Type: Multi-Step Plan Results'
+      any_errors = false
+      content.each_with_index do |step_hash, index|
+        print "  Step #{index + 1}: "
+        if step_hash.is_a?(Hash) && step_hash[:status] == :success
+          puts "Success | Result: #{step_hash[:result]}"
+        elsif step_hash.is_a?(Hash) && step_hash[:status] == :error
+          puts "Error   | Message: #{step_hash[:error_message]}"
+          any_errors = true
+        else
+          puts "Unknown Format | Data: #{step_hash.inspect}"
+          any_errors = true # Treat unexpected format as problematic
+        end
+      end
+      puts " Overall Plan Status: #{any_errors ? 'Completed with errors' : 'Completed successfully'}"
+    elsif content.is_a?(Hash) && content.key?(:status)
+      # Single step plan or a planning error
+      if content[:status] == :success
+        puts ' Content Type: Single Step Success'
+        puts " Result: #{content[:result]}"
+      else # status == :error or other
+        puts ' Content Type: Error (or Single Step Error)'
+        puts " Message: #{content[:error_message]}"
+      end
+    else
+      puts ' Content Type: String or Other Format'
+      puts " Content: #{content}"
+    end
+  else
+    puts ' Status: Unknown (Unexpected Format)'
+    puts " Raw Data: #{result_event.inspect}"
+  end
+  # --- End Updated Result Handling ---
+rescue StandardError => e
+  puts "Error executing task: #{e.class} - #{e.message}"
+  puts e.backtrace.first(5).join("\n")
+end
+
+# 6. --- Stop Agent ---
+agent.stop
+puts "\nAgent '#{agent.name}' stopped. Running: #{agent.running?}"
+puts "\n--- Example Complete ---"

data/examples/advanced/sleep_agent.rb

@@ -0,0 +1,153 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../../lib/legate'
+# Require the specific tool class if not automatically loaded. SleepyTool provides :start_sleepy_job.
+require_relative '../tools/sleepy_tool'
+# Legate::Tools::CheckJobStatusTool (providing :check_job_status) is loaded by Legate core.
+
+puts '--- Async Job Agent Example (Polling Status) ---'
+
+# 1. --- Agent Definition ---
+async_job_demo_definition = Legate::AgentDefinition.new.define do |a|
+  a.name :async_job_demo_agent
+  a.description 'An agent that starts a background job and can check its status.'
+  a.instruction 'You can start sleepy jobs and check their status. Use start_sleepy_job to initiate, and the system might use check_job_status for monitoring.'
+  a.use_tool :start_sleepy_job # Provided by Legate::Tools::SleepyTool
+  a.use_tool :check_job_status # Provided by Legate::Tools::CheckJobStatusTool
+end
+
+# 2. --- Agent Instantiation ---
+agent = Legate::Agent.new(definition: async_job_demo_definition)
+
+# Get an instance of the status checker tool directly (needed for manual polling in this example script)
+status_checker_tool = Legate::GlobalToolManager.create_instance(:check_job_status)
+unless status_checker_tool
+  puts 'Error: Status checker tool (:check_job_status) not found in GlobalToolManager.'
+  exit 1
+end
+
+puts "\nAgent '#{agent.name}' created with tools: #{agent.tools.map(&:name).join(', ')}"
+puts "Status checker tool for manual polling: #{status_checker_tool.name}"
+
+# 3. --- Start Agent (Needed for the initial task) ---
+agent.start
+puts 'Agent started.'
+
+# 4. --- Session Setup ---
+# We use a session service to store the conversation history, including tool results.
+session_service = Legate::SessionService::InMemory.new
+session = session_service.create_session(app_name: agent.name, user_id: 'demo_user')
+session_id = session.id
+puts "\nCreated session: #{session_id}"
+
+# 5. --- Task Execution & Polling ---
+# The task asks the agent to use the async tool.
+job_duration = rand(3..8) # Random duration for the job
+task = "Start a sleepy job for #{job_duration} seconds with message 'Demo complete'"
+puts "\nExecuting task: '#{task}'"
+
+job_id = nil
+final_job_status = nil
+
+begin
+  # --- Run the task that starts the job ---
+  agent.run_task(
+    session_id: session_id,
+    user_input: task,
+    session_service: session_service
+  )
+
+  # --- Check Session History for the Job ID ---
+  puts "\nTask finished. Checking session history for the job ID..."
+  current_session = session_service.get_session(session_id: session_id)
+  # Find the result event from the tool that starts the job
+  start_job_event = current_session&.events&.reverse&.find do |event|
+    event.role == :tool_result && event.tool_name == :start_sleepy_job
+  end
+
+  # --- Polling for Job Completion ---
+  if start_job_event&.content&.is_a?(Hash) && start_job_event.content[:status] == :pending
+    job_id = start_job_event.content[:job_id]
+    puts "Found pending job: #{job_id}. Starting polling using #{status_checker_tool.name}..."
+
+    # Add a small initial delay to give the worker time to start processing
+    sleep 0.5
+
+    max_attempts = 30
+    attempt = 0
+    start_time = Time.now
+    polling_context = Legate::ToolContext.new(session_id: session_id, app_name: 'polling_script', user_id: 'demo_user')
+
+    while attempt < max_attempts
+      attempt += 1
+
+      # Execute the status checker tool directly
+      status_result = status_checker_tool.execute({ job_id: job_id }, polling_context)
+
+      if status_result.is_a?(Hash)
+        final_job_status = status_result[:status]&.to_sym # Ensure symbol
+
+        case final_job_status
+        when :success
+          elapsed = Time.now - start_time
+          puts "\nJob completed successfully! (took #{elapsed.round(1)} seconds)"
+          puts "Result: #{status_result[:result]}"
+          break
+        when :error
+          elapsed = Time.now - start_time
+          puts "\nJob failed! (after #{elapsed.round(1)} seconds)"
+          puts "Error: #{status_result[:error_message]}"
+          break
+        when :pending
+          print '.' # Progress indicator
+          $stdout.flush
+        else
+          elapsed = Time.now - start_time
+          puts "\nUnexpected job status '#{final_job_status}' received after #{elapsed.round(1)}s. Stopping poll."
+          puts "Raw status content: #{status_result.inspect}"
+          break
+        end
+      else
+        elapsed = Time.now - start_time
+        puts "\nUnexpected result format from status checker tool after #{elapsed.round(1)}s: #{status_result.inspect}. Stopping poll."
+        final_job_status = :error # Treat unexpected format as an error
+        break
+      end
+
+      sleep 1 # Wait before next poll
+    end
+
+    if attempt >= max_attempts && final_job_status == :pending
+      elapsed = Time.now - start_time
+      puts "\nPolling timed out after #{max_attempts} attempts (#{elapsed.round(1)} seconds). Job status still pending."
+    end
+
+  elsif start_job_event
+    puts "Job start step did not return a pending status. Status: #{start_job_event.content[:status]}"
+    final_job_status = start_job_event.content[:status]
+  else
+    puts "Could not find the result event for '#{sleepy_tool.name}' in the session history."
+    final_job_status = :error # Indicate failure if job start wasn't found
+  end
+rescue StandardError => e
+  puts "\nError during task execution or polling: #{e.class} - #{e.message}"
+  puts e.backtrace.first(5).join("\n")
+  final_job_status = :error # Indicate failure on exception
+end
+
+# 6. --- Stop Agent ---
+puts "\nStopping agent..."
+agent.stop
+puts 'Agent stopped.'
+
+# 7. --- Final Summary ---
+puts "\n--- Example Summary ---"
+if job_id
+  puts "Job ID: #{job_id}"
+  puts "Final Status: #{final_job_status || 'Unknown'}"
+else
+  puts 'Job ID: Not found'
+  puts "Final Status: #{final_job_status || 'Error'}"
+end
+puts '--- Example Complete ---'

data/examples/advanced/webhooks/webhook_e2e_runner.rb

@@ -0,0 +1,110 @@
+# File: examples/advanced/webhooks/webhook_e2e_runner.rb
+# frozen_string_literal: true
+
+# Add lib to load path
+$LOAD_PATH.unshift(File.expand_path('../../lib', __dir__))
+
+require 'legate'
+require_relative 'webhook_receiver_agent' # Ensure agent definition is loaded
+require 'openssl'
+require 'json'
+
+# --- Configuration ---
+
+# Ensure the secret is set (same as used in webhook_receiver_agent.rb)
+# Set this environment variable before running the script:
+# export WEBHOOK_RECEIVER_SECRET='a-very-secret-key'
+webhook_secret = ENV['WEBHOOK_RECEIVER_SECRET']
+unless webhook_secret
+  puts 'Error: WEBHOOK_RECEIVER_SECRET environment variable must be set.'
+  exit(1)
+end
+
+# Configure Legate for the E2E test
+Legate.configure do |config|
+  # 1. Webhook Listener Settings
+  config.webhooks.listener_enabled = true
+  config.webhooks.listen_address = 'localhost' # Bind to localhost for this test
+  config.webhooks.listen_port = 9293 # Use a non-default port
+  config.webhooks.base_path = '/webhooks' # Default base path
+
+  # 2. Enable Dynamic Agent Handler
+  config.webhooks.enable_dynamic_agent_handler = true
+  # Keep default route pattern: /agents/:agent_name/trigger
+
+  # 3. Session service uses in-memory storage
+  config.session_service = Legate::SessionService::InMemory.new
+end
+
+# --- Verify Agent Definition Was Loaded and Registered Globally ---
+# The `require_relative 'webhook_receiver_agent'` should have defined and globally registered the definition.
+begin
+  retrieved_def_obj = Legate::GlobalDefinitionRegistry.find(:webhook_receiver)
+  raise 'Failed to retrieve :webhook_receiver definition object from Legate::GlobalDefinitionRegistry after loading.' unless retrieved_def_obj && retrieved_def_obj.is_a?(Legate::AgentDefinition) && retrieved_def_obj.name == :webhook_receiver
+
+  puts 'Verified :webhook_receiver definition object exists in GlobalDefinitionRegistry.'
+rescue StandardError => e
+  puts "Error verifying agent definition in GlobalDefinitionRegistry: #{e.message}"
+  exit(1)
+end
+
+# --- Process Management ---
+web_server_pid = nil
+
+begin
+  puts "Starting Legate Web Server (with Webhook Listener) on port #{Legate.config.webhooks.listen_port}..."
+  puts '--- Legate Web Server Output START ---'
+  # Use rackup with the new config.ru
+  port = Legate.config.webhooks.listen_port
+  web_server_pid = Process.spawn("bundle exec rackup config.ru -p #{port}")
+  # Wait briefly for server to start
+  sleep 2
+
+  puts "\nProcess started: Web=#{web_server_pid}"
+  puts "Sending webhook trigger using webhook-example.rb...\n---"
+
+  # Execute the sender script
+  # Pass listener port/path via ENV vars so sender script knows where to send
+  sender_env = {
+    'LEGATE_WEBHOOK_PORT' => Legate.config.webhooks.listen_port.to_s,
+    'LEGATE_WEBHOOK_BASE_PATH' => Legate.config.webhooks.base_path,
+    'WEBHOOK_RECEIVER_SECRET' => webhook_secret # Ensure sender uses the same secret
+  }
+  sender_success = system(sender_env, 'bundle exec ruby examples/webhook-example.rb')
+  puts '---'
+
+  unless sender_success
+    puts "\nWebhook sender script failed! Check output above."
+    # Don't exit immediately, try to clean up processes
+  end
+
+  puts "\nWaiting 5 seconds for job processing..."
+  sleep 5
+
+  # --- Verification (Basic Log Check) ---
+  puts "\nVerification:"
+  puts 'Please check the console output where the web server is running.'
+  puts 'You should see log messages indicating the webhook was received and processed.'
+rescue Interrupt
+  puts "\nInterrupted. Cleaning up..."
+rescue StandardError => e
+  puts "\nAn error occurred in the runner: #{e.message}"
+  puts e.backtrace.join("\n")
+ensure
+  # --- Cleanup Background Processes ---
+  puts "\nCleaning up background processes..."
+  if web_server_pid
+    puts "Stopping Web server (PID: #{web_server_pid})..."
+    begin
+      Process.kill('TERM', web_server_pid)
+    rescue StandardError
+      nil
+    end
+    begin
+      Process.wait(web_server_pid)
+    rescue StandardError
+      nil
+    end # Wait briefly
+  end
+  puts 'Cleanup complete.'
+end

data/examples/advanced/webhooks/webhook_receiver_agent.rb

@@ -0,0 +1,58 @@
+# File: examples/advanced/webhooks/webhook_receiver_agent.rb
+# frozen_string_literal: true
+
+# Add lib to load path
+$LOAD_PATH.unshift(File.expand_path('../../lib', __dir__))
+
+require 'legate'
+require 'json'
+
+# Example Agent designed to be triggered by an inbound webhook
+# This script defines the agent and registers it globally.
+# Another process (e.g., a web server running Legate::Web::WebhookListener)
+# would look up this definition by name to handle incoming webhooks.
+
+Legate.logger.debug 'Defining agent :webhook_receiver...'
+
+webhook_receiver_definition = Legate::AgentDefinition.new.define do |a|
+  a.name(:webhook_receiver)
+  a.description('Receives simple webhook POSTs and logs the message.')
+  a.instruction('You will receive a simple text message. Log it clearly.')
+
+  # Tools - using echo tool for explicitness.
+  a.use_tool :echo
+
+  # --- Webhook Configuration ---
+  a.webhook_enabled(true)
+
+  # 1. Validator: Use HMAC-SHA256 (validator logic would be globally registered)
+  a.webhook_validator(:hmac_sha256)
+  # Secret for HMAC should be set in the environment where the webhook listener runs.
+  # For this definition, we can reference an ENV var that the listener would also use.
+  a.webhook_secret(ENV['WEBHOOK_RECEIVER_SECRET'] || 'default-secret-for-definition-if-not-set-in-env')
+
+  # 2. Transformer: Expects JSON like {"message": "...", "source": "..."}
+  #   Returns the extracted message string for run_task input.
+  a.webhook_transformer(->(request_body) do
+    # Ensure request_body is parsed if it's a JSON string
+    parsed_body = request_body.is_a?(String) ? JSON.parse(request_body) : request_body
+    msg = parsed_body['message']
+    raise Legate::WebhookConfigurationError, "Missing or invalid 'message' in webhook payload." unless msg.is_a?(String) && !msg.empty?
+
+    "Received webhook message: '#{msg}'"
+  rescue JSON::ParserError => e
+    raise Legate::WebhookConfigurationError, "Invalid JSON in webhook payload: #{e.message}"
+  end)
+
+  # 3. Session Extractor: Use a static session ID for all triggers to this agent
+  #   Alternatively, could extract based on payload, e.g., request_body['source']
+  a.webhook_session_extractor(->(_request_body) do # Mark _request_body as unused
+    'webhook_receiver_test_session'
+  end)
+end
+
+# Register the definition globally so it can be found by name.
+Legate::GlobalDefinitionRegistry.register(webhook_receiver_definition)
+
+Legate.logger.debug "Agent definition '#{webhook_receiver_definition.name}' created and registered globally."
+Legate.logger.debug 'Note: This script only defines and registers the agent. A separate webhook listener process is needed to use it.'