legate 0.1.0

data/public/docs/guides/mcp_server_exposure.md

@@ -0,0 +1,206 @@
+# Exposing Legate Components via MCP
+
+This guide explains how to make your `Legate::Tool`s (and experimentally, `Legate::Agent`s) available to external MCP clients. This is achieved by using provided adapters with the [`fast-mcp`](https://github.com/yjacquin/fast-mcp) Ruby gem, which handles the MCP server implementation.
+
+**Prerequisite**: You must have the `fast-mcp` gem included in your project's Gemfile and installed (`bundle add fast_mcp`).
+
+## Architecture Overview: Legate as MCP Service Provider
+
+The following diagram illustrates how Legate components are wrapped and exposed via `fast-mcp`:
+
+```mermaid
+graph LR
+    subgraph Your Ruby Application / Script
+        LegateTool["Your Legate::Tool Class"] -- Wrapped by --> Adapter["Legate::Mcp::Server::LegateToolAdapter"]
+        LegateAgent["Your Legate::Agent Definition/Instance"] -- Wrapped by --> AgentAdapter["Legate::Mcp::Server::LegateAgentAdapter"]
+        Adapter -- Registers with --> FastMcpServer["fast-mcp Server Instance"]
+        AgentAdapter -- Registers with --> FastMcpServer
+        FastMcpServer -- Manages --> Transport["fast-mcp Transport (STDIO/Rack)"]
+    end
+
+    subgraph External MCP Client
+        MCP_Client["External MCP Client"]
+    end
+
+    Transport -- JSON-RPC --> MCP_Client
+
+    style LegateTool fill:#ccf,stroke:#333,stroke-width:2px
+    style LegateAgent fill:#ccf,stroke:#333,stroke-width:2px
+    style Adapter fill:#cff,stroke:#333,stroke-width:2px
+    style AgentAdapter fill:#cff,stroke:#333,stroke-width:2px
+    style FastMcpServer fill:#fcf,stroke:#333,stroke-width:2px
+    style MCP_Client fill:#f9f,stroke:#333,stroke-width:2px
+```
+
+**Key Components:**
+
+*   **`Legate::Tool` / `Legate::Agent`**: Your existing Legate components.
+*   **`Legate::Mcp::Server::LegateToolAdapter`**: Wraps an `Legate::Tool` class to make it compatible with `fast-mcp`.
+*   **`Legate::Mcp::Server::LegateAgentAdapter` / `LegateDirectAgentAdapter`**: Wraps an `Legate::Agent` (either a registry definition or a direct instance) to expose it as a single MCP tool.
+*   **`fast-mcp Server Instance`**: The MCP server provided by the `fast-mcp` gem.
+*   **`fast-mcp Transport`**: How the `fast-mcp` server communicates (e.g., STDIO, Rack middleware for HTTP/SSE).
+
+## 1. Exposing Legate Tools
+
+Use the `Legate::Mcp::Server::LegateToolAdapter.wrap` method to create a `fast-mcp` compatible tool class from your existing `Legate::Tool` subclass.
+
+### 1.1. Wrapping a Tool
+
+```ruby
+require 'legate'
+require 'fast_mcp'
+require 'legate/mcp/server/legate_tool_adapter'
+require 'legate/tools/calculator' # Example Legate tool
+
+# Configure Legate logger if needed
+# Legate.configure { |c| c.log_level = Logger::INFO }
+
+# 1. Wrap your Legate::Tool class
+AdaptedCalculatorTool = Legate::Mcp::Server::LegateToolAdapter.wrap(Legate::Tools::Calculator)
+
+# 2. Create and configure the fast-mcp server
+mcp_server = FastMcp::Server.new(
+  name: 'legate-tool-server',
+  version: Legate::VERSION,
+  logger: Legate.logger # Optional: Use Legate's logger
+)
+
+# 3. Register the adapted tool with the fast-mcp server
+mcp_server.register_tool(AdaptedCalculatorTool)
+
+# 4. Start the server (e.g., using STDIO transport)
+Legate.logger.info("Starting Legate MCP Tool Server via STDIO...")
+mcp_server.start # This will block and listen on STDIN/STDOUT
+```
+
+### 1.2. How it Works (Tool Adapter)
+
+*   `LegateToolAdapter.wrap(YourLegateToolClass)`:
+    *   Retrieves metadata (name, description, parameters) from `YourLegateToolClass`.
+    *   Uses `Legate::Mcp::Util::SchemaConverter.legate_to_dry_schema` to convert Legate parameter definitions into a `Dry::Schema` block for `fast-mcp` argument validation. (See [Schema Conversion Details](../advanced/mcp_schema_conversion))
+    *   Dynamically creates a new class that inherits from `FastMcp::Tool`.
+    *   The `call` method of this new class will:
+        *   Instantiate `YourLegateToolClass`.
+        *   Create a dummy `Legate::ToolContext` (as there's no Legate session in this server context).
+        *   Execute `your_legate_tool_instance.execute(params, dummy_context)`.
+        *   Translate the Legate result hash (`{status: :success, result: ...}` or `{status: :error, ...}`) into a format `fast-mcp` expects (either direct result or raises an error).
+
+### 1.3. Handling Asynchronous Legate Tools
+
+If your Legate tool is asynchronous (returns `{status: :pending, job_id: ...}`), the `LegateToolAdapter` will return a corresponding MCP-friendly pending response (e.g., `{'status': 'pending', 'job_id': '...'}`).
+
+To allow clients to check the status of these jobs, you **must** also wrap and expose the `Legate::Tools::CheckJobStatusTool`:
+
+```ruby
+require 'legate/tools/base_async_job_tool' # If defining your own async tool
+require 'legate/tools/sleepy_tool'       # Example Legate async tool
+require 'legate/tools/check_job_status_tool'
+
+# ... (fast_mcp server setup) ...
+
+AdaptedSleepyTool = Legate::Mcp::Server::LegateToolAdapter.wrap(Legate::Tools::SleepyTool)
+AdaptedCheckJobStatusTool = Legate::Mcp::Server::LegateToolAdapter.wrap(Legate::Tools::CheckJobStatusTool)
+
+mcp_server.register_tool(AdaptedSleepyTool)
+mcp_server.register_tool(AdaptedCheckJobStatusTool) # Crucial for async tools!
+
+# ... (start server) ...
+```
+Clients will then call your async tool, get a `job_id`, and use the exposed `check_job_status` tool to poll for completion.
+
+## 2. Exposing Legate Agents (Experimental)
+
+You can wrap an entire Legate Agent and expose its `run_task` functionality as a single MCP tool. This is useful for providing a simple, prompt-based interface to your agent for external MCP clients.
+
+Two adapters are available:
+
+*   **`Legate::Mcp::Server::LegateAgentAdapter`**: For agents defined and stored in the **`GlobalDefinitionRegistry`** (e.g., created via `legate agent save`).
+*   **`Legate::Mcp::Server::LegateDirectAgentAdapter`**: For `Legate::Agent` instances created directly in your Ruby code.
+
+### 2.1. Using `LegateAgentAdapter` (Registry Definition)
+
+**Prerequisites:**
+*   Your agent definition must exist in the `GlobalDefinitionRegistry`.
+*   An `Legate::SessionService` instance is needed by the adapter for temporary session management.
+
+```ruby
+require 'legate/mcp/server/legate_agent_adapter'
+require 'legate/session_service/in_memory'
+
+AGENT_NAME_IN_REGISTRY = 'my_chat_agent' # The name of your agent in the registry
+session_service = Legate::SessionService::InMemory.new
+
+# 1. Wrap the agent definition from the registry
+AdaptedRegistryAgent = Legate::Mcp::Server::LegateAgentAdapter.wrap(AGENT_NAME_IN_REGISTRY, session_service)
+
+# 2. Setup fast-mcp server and register AdaptedRegistryAgent
+# ... (as shown in Tool Adapter example) ...
+mcp_server.register_tool(AdaptedRegistryAgent)
+# ... (start server) ...
+```
+This will expose a tool named something like `run_agent_my_chat_agent` that accepts a `prompt` argument.
+
+### 2.2. Using `LegateDirectAgentAdapter` (Ruby Instance)
+
+**Prerequisites:**
+*   An `Legate::Agent` instance created in your Ruby code.
+*   An `Legate::SessionService` instance.
+
+```ruby
+require 'legate/mcp/server/legate_direct_agent_adapter'
+require 'legate/session_service/in_memory'
+require 'legate/tools/echo' # Example tool for the agent
+
+# 1. Create your Legate Agent instance from a definition.
+#    Tools are selected on the definition via use_tool; ensure the tool
+#    class is registered globally so the agent can find it.
+Legate::GlobalToolManager.register_tool(Legate::Tools::Echo)
+
+agent_definition = Legate::AgentDefinition.new.define do |a|
+  a.name :my_code_defined_agent
+  a.instruction 'Echo the user input.'
+  a.use_tool :echo
+end
+
+my_agent_instance = Legate::Agent.new(definition: agent_definition)
+# Do NOT call my_agent_instance.start() here if only using for MCP wrapping.
+
+session_service = Legate::SessionService::InMemory.new
+
+# 2. Wrap the agent *instance*
+AdaptedDirectAgent = Legate::Mcp::Server::LegateDirectAgentAdapter.wrap(my_agent_instance, session_service)
+
+# 3. Setup fast-mcp server and register AdaptedDirectAgent
+# ... (as shown in Tool Adapter example) ...
+mcp_server.register_tool(AdaptedDirectAgent)
+# ... (start server) ...
+```
+This will expose a tool named `run_agent_my_code_defined_agent`.
+
+### 2.3. Agent Adapter Limitations (Current Version)
+
+*   **Stateless Execution**: Each call to the wrapped agent tool via MCP is treated as a new, isolated interaction. A temporary Legate session is created for the `run_task` call and then deleted. There is no persistent conversation history between MCP calls to the agent tool.
+*   **Tool Availability**: For the `LegateAgentAdapter` (registry-based), any tools specified in the agent's definition must be available in the global `Legate::ToolRegistry` of the Ruby process running the MCP server.
+
+## 3. Server Setup with `fast-mcp`
+
+`fast-mcp` offers different ways to run the MCP server:
+
+*   **STDIO Server (`FastMcp::Server.new` or `FastMcp::Server::Stdio.new`)**:
+    *   Listens for JSON-RPC messages on standard input and writes responses to standard output.
+    *   Ideal for local development, integration with tools that manage child processes (like `mcp-inspector`), or simple standalone tool/agent servers.
+    *   Start by calling `mcp_server.start`.
+    *   See `examples/15_mcp_server.rb`.
+*   **Rack Middleware (`FastMcp.rack_middleware`)**:
+    *   Integrates the MCP server into any Rack-based web application (e.g., Sinatra, Rails).
+    *   Adds MCP endpoints (typically `/mcp/messages` for POST and `/mcp/sse` for Server-Sent Events) to your existing app.
+    *   Allows clients to connect via HTTP/SSE.
+    *   See `examples/advanced/mcp/mcp_server_rack.rb`.
+
+Refer to the [`fast-mcp` documentation](https://github.com/yjacquin/fast-mcp) for more details on server setup, authentication, and other advanced features.
+
+## 4. Security Considerations
+
+*   When exposing tools and agents via MCP, you are making their functionality available to any client that can connect to your `fast-mcp` server.
+*   If using the Rack middleware for an HTTP-accessible server, consider appropriate network security (firewalls, private networks) and authentication mechanisms if needed. `fast-mcp` provides options for token-based authentication (`FastMcp.authenticated_rack_middleware`) and origin checks.
+*   Be mindful of the capabilities of the Legate tools and agents you expose. Avoid exposing components that could lead to unintended actions or data access if called by unauthorized clients. 

data/public/docs/guides/rails_integration.md

@@ -0,0 +1,128 @@
+# Rails integration
+
+Legate runs in any Ruby program, but it ships first-class glue for Rails: a
+durable ActiveRecord session store, a Railtie, and an install generator. None of
+it is loaded unless you ask for it — `require 'legate'` never touches Rails or
+ActiveRecord.
+
+## Install
+
+Add the gem and require the Rails integration:
+
+```ruby
+# Gemfile
+gem 'legate', require: 'legate/rails'
+```
+
+Then run the generator and migrate:
+
+```sh
+bin/rails generate legate:install
+bin/rails db:migrate
+```
+
+That creates two files:
+
+- **`db/migrate/…_create_legate_tables.rb`** — the schema for the session store
+  (`legate_sessions`, `legate_events`, `legate_scoped_states`).
+- **`config/initializers/legate.rb`** — points Legate at the ActiveRecord store
+  and maps `GEMINI_API_KEY` → `GOOGLE_API_KEY` for the planner.
+
+The initializer wires the store explicitly, so you stay in control:
+
+```ruby
+require 'legate/session_service/active_record'
+
+Legate.configure do |config|
+  config.session_service = Legate::SessionService::ActiveRecord.new
+end
+```
+
+(Prefer Rails encrypted credentials for the API key in production rather than a
+plain env var.)
+
+## Durable sessions
+
+With the ActiveRecord store configured, every conversation — its events and its
+state — is persisted to your database and survives restarts. The store behaves
+exactly like the in-memory one within a single run (the agent sees one live
+`Session` object), but writes through on every change, so another process or a
+later request re-hydrates the committed history:
+
+```ruby
+service = Legate.config.session_service               # the AR store
+session = service.create_session(app_name: 'support', user_id: current_user.id)
+
+agent.run_task(session_id: session.id, user_input: params[:message], session_service: service)
+
+# …later, another request / process:
+restored = service.get_session(session_id: session.id)
+restored.events   # the full persisted history
+restored.get_state(:some_key)
+```
+
+`persistent?` returns `true`, and scoped state (`user:` / `app:` / `temp:` keys)
+is persisted too.
+
+## Running agents in the background (ActiveJob)
+
+Agent runs can take many seconds — do them off the request thread. Because the
+store is durable, the controller enqueues a job and reads the result back from
+the persisted session when it's done (poll, or push via Turbo/ActionCable):
+
+```ruby
+class LegateRunJob < ApplicationJob
+  queue_as :default
+
+  def perform(agent_name:, session_id:, message:)
+    agent = MyAgents.build(agent_name)   # your factory: definition -> started Agent
+    agent.run_task(
+      session_id: session_id,
+      user_input: message,
+      session_service: Legate.config.session_service,
+    )
+    # The final answer + full history are now persisted on the session.
+  end
+end
+```
+
+```ruby
+# app/controllers/messages_controller.rb
+session = Legate.config.session_service.create_session(app_name: 'support', user_id: current_user.id)
+LegateRunJob.perform_later(agent_name: 'support', session_id: session.id, message: params[:message])
+render json: { session_id: session.id }
+```
+
+Pair this with [event streaming](streaming): pass an `on_event:` callback to
+`run_task` inside the job to broadcast progress over ActionCable as each tool
+runs.
+
+## Without Rails
+
+The store is plain ActiveRecord — you can use it in any Ruby program. Establish a
+connection and create the tables yourself:
+
+```ruby
+require 'active_record'
+require 'legate/session_service/active_record'
+
+ActiveRecord::Base.establish_connection(adapter: 'sqlite3', database: 'legate.db')
+Legate::SessionService::ActiveRecord.create_tables!   # idempotent
+
+Legate.configure { |c| c.session_service = Legate::SessionService::ActiveRecord.new }
+```
+
+The host application owns the connection and pool; Legate doesn't manage it.
+
+## Notes
+
+- Event content and state are stored as JSON. Resumed (historical) event content
+  comes back with string keys — the live run uses in-memory objects with their
+  original keys, so this only affects how you read prior turns.
+- The schema is portable across SQLite, PostgreSQL, and MySQL (JSON stored as
+  text); the generated migration matches `ActiveRecord.create_tables!`.
+
+## Related
+
+- [Streaming agent events](streaming) — progress over ActionCable from a job.
+- [LLM Providers](llm_providers) — configuring the model in the initializer.

data/public/docs/guides/sending_outbound_webhooks.md

@@ -0,0 +1,227 @@
+# Sending Outbound Webhooks from Legate Agents
+
+The Legate Agents often need to notify external systems upon completing a task or when a specific event occurs. This can be achieved by sending outbound HTTP requests, commonly known as webhooks.
+
+## Architecture Overview: Sending Outbound Webhooks
+
+The following diagram illustrates the two primary ways an Legate Agent can send outbound webhooks:
+
+```mermaid
+graph TD
+    subgraph Legate Agent Process
+        Agent[Legate::Agent]
+        Planner[Legate::Planner]
+        WebhookTool[Legate::Tools::WebhookTool]
+        CustomTool[Your Custom Tool with HttpClient]
+        HttpClient[Legate::Tools::Base::HttpClient]
+
+        Agent -- Task Prompt --> Planner
+        Planner -- Selects Tool --> WebhookTool
+        Planner -- Selects Tool --> CustomTool
+        CustomTool -- Uses --> HttpClient
+    end
+
+    subgraph External Systems
+        ExternalService1[External Service A]
+        ExternalService2[External Service B]
+    end
+
+    WebhookTool -- HTTP POST --> ExternalService1
+    HttpClient -- HTTP Request (GET/HEAD/POST/PUT etc.) --> ExternalService2
+
+    style Agent fill:#ccf,stroke:#333,stroke-width:2px
+    style Planner fill:#ccf,stroke:#333,stroke-width:2px
+    style WebhookTool fill:#cff,stroke:#333,stroke-width:2px
+    style CustomTool fill:#cff,stroke:#333,stroke-width:2px
+    style HttpClient fill:#cff,stroke:#333,stroke-width:2px
+    style ExternalService1 fill:#f9f,stroke:#333,stroke-width:2px
+    style ExternalService2 fill:#f9f,stroke:#333,stroke-width:2px
+```
+
+**Key Scenarios Depicted:**
+
+1.  **Using `WebhookTool`:** The agent, guided by the planner, uses the built-in `WebhookTool` to send a (typically POST) request to an external service.
+2.  **Using a Custom Tool with `HttpClient`:** The agent, guided by the planner, invokes a custom-developed tool. This custom tool then utilizes the `Legate::Tools::Base::HttpClient` module to make more complex or varied HTTP requests to another (or the same) external service.
+
+There are two primary ways to send outbound webhooks from within the Legate framework:
+
+1.  **Using the built-in `WebhookTool`:** A convenient tool specifically designed for sending standard HTTP POST requests with JSON payloads, including optional HMAC-SHA256 signing. This is the recommended approach for common webhook integrations.
+2.  **Using the `HttpClient` module within a Custom Tool:** For more complex scenarios requiring different HTTP methods (GET, PUT, etc.), custom headers, non-JSON bodies, or more intricate logic before/after the request, you can create a custom tool that utilizes the `Legate::Tools::Base::HttpClient` mixin.
+
+## 1. Using the `WebhookTool`
+
+The `Legate::Tools::WebhookTool` provides a simple interface for sending POST requests.
+
+### Adding the Tool to your Agent
+
+Ensure the tool is available to your agent by including it in the agent definition:
+
+```ruby
+# my_notifying_agent.rb
+Legate::Agent.define do |a|
+  a.name :my_notifying_agent
+  a.description "Performs a task and notifies an external system."
+  # ... other config ...
+
+  a.use_tool :webhook_tool # Make the tool available
+end
+```
+
+### Instructing the Agent
+
+You instruct the agent to use the tool within its task prompt, providing the necessary parameters.
+
+**`WebhookTool` Parameters:**
+
+*   `url` (String, required): The target URL to send the POST request to.
+*   `payload` (Hash | String, required): The data to send.
+    *   If a `Hash` is provided, it will be automatically encoded as JSON, and the `Content-Type` header will be set to `application/json; charset=utf-8`.
+    *   If a `String` is provided, it will be sent as the raw request body. You might need to specify a `Content-Type` via the `headers` parameter if the receiving system requires it.
+*   `secret` (String, optional): If provided, the tool will calculate an HMAC-SHA256 signature of the request body using this secret. The signature will be added to the request headers as `X-Hub-Signature-256: sha256=<calculated_signature>`. **Note:** Passing secrets directly in agent prompts can have security implications. Consider if a custom tool with configured secrets is more appropriate for sensitive integrations.
+*   `headers` (Hash, optional): Additional custom headers to include in the request (e.g., `{'Authorization': 'Bearer ...'}`). These are merged with default headers like `User-Agent` and the automatically added `Content-Type` (for Hash payloads) or `X-Hub-Signature-256` (if `secret` is used).
+
+**Example Agent Prompt:**
+
+```
+"Analyze the provided data file. Once the analysis is complete and saved, use the `webhook_tool` to notify the monitoring system. Send a POST request with the following parameters:
+- url: 'https://monitor.example.com/api/v1/updates'
+- payload: A JSON object like {'task_id': '12345', 'status': 'completed', 'result_summary': 'Analysis finished successfully.'}
+- secret: 'my-monitoring-api-secret'
+- headers: {'X-Source-System': 'Legate-Agent'}"
+```
+
+### Result
+
+The `webhook_tool` will return a result indicating success or failure:
+
+*   **Success:** `{ status: :success, result: { response_status: <Integer>, response_body: <String> } }`
+*   **Failure:** Raises an `Legate::ToolError` (or a subclass like `Legate::ToolHttpError`, `Legate::ToolTimeoutError`) which the agent should handle or report.
+
+## 2. Using `HttpClient` in a Custom Tool
+
+For more control over the HTTP request (e.g., using methods other than POST, sending non-JSON data, complex authentication headers, custom retry logic), create a dedicated custom tool that includes the `Legate::Tools::Base::HttpClient` module.
+
+**Important:** The agent itself *cannot* directly call `http_get`, `http_post`, etc. It must invoke a *custom tool* that encapsulates this logic.
+
+### Creating the Custom Tool
+
+```ruby
+# lib/my_app/tools/notification_tool.rb
+require 'legate/tool'
+require 'legate/tools/base/http_client'
+require 'json'
+require 'openssl' # If manual signing is needed
+
+module MyApp
+  module Tools
+    # The tool name :notification_tool is inferred from the class name.
+    # (To override, use `self.explicit_tool_name = :some_name`.)
+    class NotificationTool < Legate::Tool
+      include Legate::Tools::Base::HttpClient
+
+      tool_description "Sends notifications to a specific internal system."
+
+      parameter :endpoint, type: :string, required: true, description: "The API endpoint path (e.g., '/events')."
+      parameter :event_data, type: :hash, required: true, description: "Data for the notification payload."
+      # NOTE: `default:` is not applied by the framework; defaults are handled in
+      # perform_execution below (e.g. `params[:http_method] || 'POST'`).
+      parameter :http_method, type: :string, required: false, description: "HTTP method (POST, PUT, etc.). Defaults to POST."
+
+      def initialize(**options)
+        super(**options)
+        # Setup HttpClient - read base URL/secret from ENV or config
+        # IMPORTANT: Avoid hardcoding secrets!
+        @api_base_url = ENV.fetch('NOTIFICATION_API_URL', 'https://internal.example.com/api')
+        @api_secret = ENV['NOTIFICATION_API_SECRET'] # Optional secret
+
+        setup_http_client(
+          base_url: @api_base_url,
+          headers: { 'Accept' => 'application/json' },
+          options: { read_timeout: 10 }
+        )
+      end
+
+      private
+
+      def perform_execution(params, context)
+        endpoint = params[:endpoint]
+        event_data = params[:event_data]
+        # Handle the default in code; the `default:` parameter option is not applied.
+        http_method = (params[:http_method] || 'POST').downcase.to_sym
+
+        request_headers = {}
+        request_body = JSON.generate(event_data) rescue event_data.to_s # Ensure JSON encoding
+
+        # Example: Manual HMAC Signing (if not using WebhookTool's secret param)
+        if @api_secret
+          signature = OpenSSL::HMAC.hexdigest('sha256', @api_secret, request_body)
+          request_headers['X-Internal-Signature-256'] = "sha256=#{signature}"
+        end
+        # Always set Content-Type for JSON body when using HttpClient directly
+        request_headers['Content-Type'] = 'application/json; charset=utf-8'
+
+        begin
+          response = make_request(
+            http_method,
+            endpoint, # Path relative to base_url
+            body: request_body,
+            headers: request_headers
+          )
+          Legate.logger.info "NotificationTool: Successfully sent #{http_method.upcase} to #{endpoint}. Status: #{response.status}"
+          # Return a success indicator
+          { status: :success, response_code: response.status }
+        rescue Legate::ToolHttpError => e
+          Legate.logger.error "NotificationTool: HTTP Error sending to #{endpoint}. Status: #{e.response&.status}. Body: #{e.response&.body}"
+          # Re-raise or return structured error
+          raise Legate::ToolError, "Failed to send notification (HTTP #{e.response&.status})"
+        rescue Legate::ToolError => e # Includes timeouts, network errors etc.
+          Legate.logger.error "NotificationTool: Error sending to #{endpoint}: #{e.message}"
+          # Re-raise or return structured error
+          raise Legate::ToolError, "Failed to send notification: #{e.message}"
+        end
+      end
+    end
+  end
+end
+```
+
+*(See [`http_client_usage`](./http_client_usage) for full details on using the `HttpClient` module).*
+
+### Adding the Custom Tool to your Agent
+
+```ruby
+# my_complex_agent.rb
+# require 'my_app/tools/notification_tool' # Make sure tool class is loaded
+
+Legate::Agent.define do |a|
+  a.name :my_complex_agent
+  # ...
+
+  a.use_tool :notification_tool # Use the custom tool
+end
+```
+
+### Instructing the Agent (to use the Custom Tool)
+
+```
+"After processing the order (ID: #{order_id}), use the `notification_tool` to inform the fulfillment system. Use the endpoint '/order_updates' and send the following event_data as JSON: {'orderId': '#{order_id}', 'status': 'processed', 'items': [...]}. Use the default POST method."
+```
+
+## Choosing the Right Approach
+
+*   Use **`WebhookTool`** if:
+    *   You need to send a simple HTTP POST request.
+    *   Your payload is typically JSON (Hash).
+    *   You need standard HMAC-SHA256 signing (`X-Hub-Signature-256`).
+    *   You are comfortable with the agent prompt potentially containing the signing secret (use with caution).
+*   Use **`HttpClient` in a Custom Tool** if:
+    *   You need to use other HTTP methods (GET, HEAD, PUT, DELETE, etc.).
+    *   You need to send non-JSON request bodies (e.g., XML, form data) and manage `Content-Type` manually.
+    *   You require complex custom headers or authentication schemes beyond simple HMAC.
+    *   You need to perform logic before or after the HTTP request within the tool itself.
+    *   You want to manage API secrets within the tool's configuration (e.g., via ENV variables) rather than passing them via agent parameters.
+
+## Security Considerations
+
+*   **Secrets Management:** Avoid hardcoding secrets. Use environment variables or a dedicated configuration management system to provide secrets (like API keys or webhook signing keys) to your custom tools or potentially to the `WebhookTool`'s `secret` parameter (though configuring them in the tool is generally safer than passing via LLM prompt).
+*   **URL Validation:** Ensure the URLs being targeted by your webhooks are intended and trusted. Be cautious if URLs are dynamically generated based on user input. 

data/public/docs/guides/streaming.md

@@ -0,0 +1,112 @@
+# Streaming agent events
+
+An agent task can take many seconds — it may call several tools before it
+answers. Rather than block until the final result, you can **stream the agent's
+lifecycle events as they happen**: the user message, each tool request, each tool
+result, and the final answer. This is how you build a responsive "thinking…
+calling search… answering" experience instead of a frozen spinner.
+
+## `on_event` — the streaming callback
+
+`Agent#run_task` accepts an optional `on_event:` proc. It's called with each
+`Legate::Event` the moment it's appended to the session, while the task runs:
+
+```ruby
+agent.run_task(
+  session_id: session.id,
+  user_input: 'Find the population of France and double it',
+  session_service: session_service,
+  on_event: ->(event) do
+    case event.role
+    when :user         then puts "▶ #{event.content}"
+    when :tool_request then puts "  → calling #{event.tool_name}"
+    when :tool_result  then puts "  ← #{event.content[:result]}"
+    when :agent        then puts "✓ #{event.content[:result]}"
+    end
+  end
+)
+```
+
+The events you'll see, in order:
+
+| `event.role`   | When | `event.content` |
+|----------------|------|-----------------|
+| `:user`        | task starts | the user input string |
+| `:tool_request`| before each tool runs | the params; `event.tool_name` is the tool |
+| `:tool_result` | after each tool runs | `{ status:, result: / error_message: }` |
+| `:agent`       | task finishes | the final result hash |
+
+`on_event` is **purely additive**: the method still returns the final `Event`, and
+omitting `on_event` leaves behavior exactly as before. It works for both the
+default plan-then-execute strategy and the [agentic `:react` loop](agentic_agents)
+— every event flows through the same session funnel.
+
+### How it works
+
+Every event an agent produces is persisted through `SessionService#append_event`.
+The service broadcasts each appended event to subscribers of that session
+(`EventBroadcast`), and `run_task` subscribes your `on_event` for the duration of
+the run, tearing the subscription down afterward. Delivery is synchronous and
+in order on the running thread, so a streaming HTTP response can write each frame
+as it arrives.
+
+## Server-Sent Events over HTTP
+
+The web app exposes the stream as SSE:
+
+```
+POST /agents/:name/stream     (form field: message=…, plus the CSRF token)
+Content-Type: text/event-stream
+```
+
+Each appended event is sent as an `event: message` frame; the run ends with an
+`event: done` frame carrying the final result (or `event: error`):
+
+```
+event: message
+data: {"role":"user","content":"double the population of France",…}
+
+event: message
+data: {"role":"tool_request","tool_name":"search","content":{…},…}
+
+event: message
+data: {"role":"tool_result","content":{"status":"success","result":"67 million"},…}
+
+event: done
+data: {"role":"agent","content":{"status":"success","result":"134 million"},…}
+```
+
+The frame payloads are `Event#to_h` (JSON, ISO-8601 timestamps). Because the
+endpoint is CSRF-protected it can't be consumed by a bare `EventSource` (which is
+GET-only and can't send the token); use `fetch` with a streaming reader:
+
+```js
+const res = await fetch(`/agents/${name}/stream`, {
+  method: 'POST',
+  headers: { 'X-CSRF-Token': csrfToken, 'Content-Type': 'application/x-www-form-urlencoded' },
+  body: new URLSearchParams({ message }),
+});
+const reader = res.body.pipeThrough(new TextDecoderStream()).getReader();
+for (;;) {
+  const { value, done } = await reader.read();
+  if (done) break;
+  // parse SSE frames out of `value`…
+}
+```
+
+Each request runs as a fresh one-shot session.
+
+## Scope: steps, not tokens
+
+Streaming here is **step/event** level — you get each tool call and result as it
+happens. Legate agents always plan and call tools rather than emitting free-form
+model prose, and in the agentic loop the final answer arrives whole inside one
+decision, so there's no separate token stream to forward. Token-level streaming
+is a possible future addition (an adapter `supports_streaming?` capability); it
+isn't needed to solve the "no feedback during a long run" problem, which event
+streaming already does.
+
+## Related
+
+- [Agentic Agents](agentic_agents) — multi-step runs where streaming shines.
+- [Legate Planner](../core_concepts/legate_planner) — what produces the steps.