legate 0.1.0

data/public/docs/core_concepts/legate_configuration.md

@@ -0,0 +1,116 @@
+# Legate Configuration
+
+This document explains how to configure the global settings for the Legate framework using the `Legate.configure` block.
+
+## 1. Overview
+
+Many aspects of the Legate's behavior, such as logging, session management, and webhook settings, can be customized globally. This is typically done once during your application's initialization phase (e.g., in `config/initializers/legate.rb` for Rails/Sinatra, or near the start of a standalone script).
+
+The configuration is managed through a singleton `Legate::Configuration` object, accessed via `Legate.configure` or `Legate.config`.
+
+## 2. Using `Legate.configure`
+
+The primary way to set configuration is using the `Legate.configure` block:
+
+```ruby
+# config/initializers/legate.rb or similar
+require 'legate'
+
+Legate.configure do |config|
+  # Note: log level is NOT configured here. It is controlled exclusively by
+  # the LEGATE_LOG_LEVEL environment variable (see section 4.1 / 5).
+
+  # Configure the session service (see legate_session_service)
+  # Sessions are always in-memory
+  config.session_service = Legate::SessionService::InMemory.new
+
+  # Configure Webhook settings (see webhooks)
+  config.webhooks.listener_enabled = true
+  config.webhooks.listen_address = "0.0.0.0"
+  config.webhooks.listen_port = 9293
+  config.webhooks.base_path = "/legate-hooks"
+  config.webhooks.enable_dynamic_agent_handler = true
+  # Register custom webhook validators...
+  # config.webhooks.register_validator(:my_validator) { |req, secret| ... }
+
+  # Configure other settings as they become available...
+end
+```
+
+*   The `Legate.configure` method yields the singleton `Legate::Configuration` instance.
+*   You modify the attributes of this `config` object within the block.
+*   This block should typically run only once during application startup.
+
+## 3. Accessing Configuration (`Legate.config`)
+
+After the initial configuration, you can access the current settings using `Legate.config`:
+
+```ruby
+# Get the configured session service later in your code
+service = Legate.config.session_service
+
+# Get the webhook base path
+base_path = Legate.config.webhooks.base_path
+```
+
+## 4. Key Configuration Areas
+
+### 4.1. Logging (`LEGATE_LOG_LEVEL`)
+
+*   The log level is **not** a `Legate::Configuration` attribute and cannot be set inside the `Legate.configure` block. Assigning `config.log_level` raises `NoMethodError`.
+*   The minimum severity level for messages logged by `Legate.logger` is controlled **only** by the `LEGATE_LOG_LEVEL` environment variable (falling back to a default derived from `RACK_ENV` when unset).
+*   Accepts: `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL`, `NONE`, `SILENT`.
+*   See `legate.rb` for the eager initialization logic of the logger.
+
+### 4.2. Session Service (`config.session_service`)
+
+*   Assign an instance of a session service implementation (`Legate::SessionService::InMemory.new`).
+*   This instance will be used by default when agents need to interact with sessions, unless a different service is explicitly passed.
+*   See `public/docs/core_concepts/legate_session_service.md` for details.
+
+### 4.3. Webhooks (`config.webhooks`)
+
+*   Accessed via `config.webhooks`, which returns an `Legate::Configuration::Webhooks` instance.
+*   Controls the built-in webhook listener and dynamic agent triggering.
+*   Settings include `listener_enabled`, `listen_address`, `listen_port`, `base_path`, `enable_dynamic_agent_handler`, etc.
+*   Also provides methods to `register_validator` for webhook security.
+*   See `public/docs/guides/webhooks.md` and `public/docs/guides/configuring_agent_webhooks.md` for details.
+
+### 4.4. Runtime Tool Loading (`config.allow_runtime_tool_load`)
+
+Controls whether the Web UI's AI **tool** builder may load a generated custom tool
+into the **running** process ("Add Tool to Legion"). Because this executes
+LLM-generated Ruby in-process, it is gated:
+
+*   **Default:** ON outside production, OFF in production
+    (`ENV['RACK_ENV'] != 'production'`).
+*   Override explicitly:
+    ```ruby
+    Legate.configure { |config| config.allow_runtime_tool_load = false }
+    ```
+*   When enabled, installing a tool also writes `tools/<name>.rb` (durable and
+    auditable; re-loaded on next boot). When disabled, the builder offers Download
+    only — place the file in `tools/` and restart to activate it.
+*   **Security:** the generated source is re-validated server-side
+    (`CodeValidator`, a *denylist* — not a sandbox), the UI requires an explicit
+    per-tool confirmation, and the web UI sits behind Basic Auth. Ruby has no true
+    in-process sandbox, so only enable this where you trust the operators. See
+    [AI-Powered Code Generators](../guides/ai_code_generators).
+
+## 5. Environment Variables
+
+Several configuration options can also be influenced by environment variables, which are often loaded via `.env` files using the `dotenv` gem (loaded by `Legate.load_environment`). Environment variables typically take precedence during initial setup:
+
+*   `LEGATE_LOG_LEVEL`: Sets the initial log level (`DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL`, `NONE`, `SILENT`).
+*   `GOOGLE_API_KEY`: The API key for Gemini LLM integration.
+*   `RACK_ENV`: `development` / `production`. Among other things it sets the default
+    of `allow_runtime_tool_load` (OFF in production) and enables secure session cookies.
+*   Other environment variables might be used internally by specific components or within your application's Legate configuration block (e.g., `ENV['NOTIFICATION_API_URL']` in custom tool examples).
+
+It's common practice to use environment variables for settings that differ between development, testing, and production environments (like API keys, etc.).
+
+## Further Reading
+
+*   [`legate_architecture_overview`](./legate_architecture_overview)
+*   [`legate_session_service`](./legate_session_service)
+*   [`webhooks`](../guides/webhooks)

data/public/docs/core_concepts/legate_definition_store.md

@@ -0,0 +1,102 @@
+# Legate Definition Store
+
+This document explains the purpose and usage of the Definition Store in the Legate framework, which is responsible for persisting and retrieving agent definitions.
+
+## 1. Purpose
+
+An agent's definition contains its core configuration: name, instructions, description, associated tools, model configuration, webhook settings, etc. While agents can be defined purely in code, storing these definitions externally allows:
+
+*   Creating and managing agents via tools like the Legate CLI or Web UI without modifying application code.
+*   Dynamically loading agent configurations at runtime.
+
+The `GlobalDefinitionRegistry` provides the in-memory storage for agent definitions.
+
+## 2. Architecture Overview
+
+```mermaid
+graph LR
+    UserInteraction["Legate CLI / Web UI"] -- Creates/Updates --> DefinitionStore["Legate::GlobalDefinitionRegistry"]
+    AgentLoader["Agent Loading Logic (e.g., Web App)"] -- Loads Definition --> DefinitionStore
+    DefinitionStore -- Reads/Writes --> Storage["Storage: In-Memory"]
+    AgentLoader -- Uses Definition --> Agent["Legate::Agent Instance"]
+
+    style DefinitionStore fill:#fcc,stroke:#333,stroke-width:2px
+    style Storage fill:#ffc,stroke:#333,stroke-width:2px
+    style Agent fill:#ccf,stroke:#333,stroke-width:2px
+```
+
+*   User interfaces (like the Legate CLI or Web UI) interact with the `GlobalDefinitionRegistry` to save, update, or list agent definitions.
+*   Application components that need to run specific agents (like the Legate Web App or a custom script) use the `GlobalDefinitionRegistry` to retrieve the definition by name.
+*   The retrieved definition data is then used to initialize an `Legate::Agent` instance.
+*   All definitions are stored in-memory via `Legate::GlobalDefinitionRegistry`.
+
+## 3. `Legate::GlobalDefinitionRegistry`
+
+This is the primary implementation provided by Legate. It stores all agent definitions in-memory.
+
+### 3.1. Initialization
+
+The `GlobalDefinitionRegistry` is a module with class-level methods, so no instantiation is needed. Definitions are registered directly:
+
+```ruby
+# Register a definition
+definition = Legate::AgentDefinition.new.define do |a|
+  a.name :my_agent
+  a.description 'My agent'
+  a.instruction 'Be helpful.'
+end
+
+Legate::GlobalDefinitionRegistry.register(definition)
+```
+
+### 3.2. Core Methods
+
+*   **`register(definition)`**: Registers an `AgentDefinition` in the registry.
+*   **`find(agent_name) -> AgentDefinition | nil`**: Retrieves the definition for a given agent name. Returns `nil` if not found.
+*   **`all -> Array<AgentDefinition>`**: Returns an array of all registered agent definitions.
+*   **`definition_exists?(agent_name) -> Boolean`**: Checks if a definition exists for the given name.
+*   **`delete_definition(agent_name)`**: Removes an agent definition from the registry.
+*   **`clear!`**: Clears all registered definitions (primarily used in testing).
+
+## 4. Usage Examples
+
+### Registering a New Definition
+
+```ruby
+definition = Legate::AgentDefinition.new.define do |a|
+  a.name :my_new_agent
+  a.description "An agent created via the registry."
+  a.instruction "Be helpful."
+  a.use_tool :calculator
+  a.use_tool :echo
+  a.model_name "gemini-2.0-flash"
+end
+
+Legate::GlobalDefinitionRegistry.register(definition)
+puts "Agent definition registered."
+```
+
+### Retrieving and Using a Definition
+
+```ruby
+agent_name = :my_new_agent
+
+definition = Legate::GlobalDefinitionRegistry.find(agent_name)
+
+if definition
+  puts "Found definition: #{definition.inspect}"
+
+  # Instantiate the agent using the definition object
+  agent_instance = Legate::Agent.new(definition: definition)
+  puts "Agent instance created: #{agent_instance.name}"
+  # agent_instance.start # Start the agent if needed
+else
+  puts "Agent definition '#{agent_name}' not found."
+end
+```
+
+## Further Reading
+
+*   [`legate_architecture_overview`](./legate_architecture_overview)
+*   [`legate_agent_lifecycle`](./legate_agent_lifecycle)
+*   [`legate_configuration`](./legate_configuration)

data/public/docs/core_concepts/legate_planner.md

@@ -0,0 +1,94 @@
+# Legate Planner
+
+This document describes the role and function of the `Legate::Planner` within the Legate framework. The Planner is a key component responsible for determining the sequence of actions (tool calls) an agent should take to fulfill a user's request.
+
+## 1. Purpose
+
+When an agent receives a user task, it often needs a strategy to achieve the goal, especially if the task requires multiple steps or the use of tools. The `Legate::Planner`'s primary purpose is to:
+
+*   Analyze the user's request in the context of the agent's instructions and conversation history.
+*   Consider the tools available to the agent (provided via `Legate::ToolRegistry`).
+*   Generate a step-by-step plan, usually consisting of tool calls with specific parameters.
+*   Handle situations where planning might fail or need revision based on tool results.
+
+Legate's default planner leverages a Language Model (LLM) to perform this reasoning and plan generation, making use of the descriptive metadata provided by each tool.
+
+## 2. Interaction with Agent
+
+The `Legate::Agent` delegates planning to the `Planner` during the `run_task` execution flow.
+
+```mermaid
+graph LR
+    Agent[Legate::Agent] -- Requests Plan --> Planner[Legate::Planner]
+    Planner -- Needs Context --> Agent
+    Agent -- Provides --> Instructions[Agent Instructions]
+    Agent -- Provides --> History[Session History]
+    Agent -- Provides --> ToolRegistry[Agent's ToolRegistry]
+    
+    Planner -- Uses --> ToolRegistry
+    Planner -- Sends Context & Tool Schemas --> LLM[Language Model]
+    LLM -- Returns Plan --> Planner
+    Planner -- Returns Plan --> Agent
+
+    style Agent fill:#ccf,stroke:#333,stroke-width:2px
+    style Planner fill:#cff,stroke:#333,stroke-width:2px
+    style LLM fill:#f9f,stroke:#333,stroke-width:2px
+    style ToolRegistry fill:#cfc,stroke:#333,stroke-width:2px
+```
+
+1.  The Agent calls `planner.plan(user_input, invocation_id)`.
+2.  The Agent provides the necessary context: its core `instruction` prompt, the current `session_history` (from the `SessionService`), and access to its `ToolRegistry`.
+3.  The Planner retrieves the metadata (name, description, parameters) for all available tools from the `ToolRegistry`.
+4.  The Planner constructs a prompt for the LLM, including the user request, agent instructions, conversation history, and the formatted list of available tools and their schemas.
+5.  The LLM processes this prompt and generates a plan, typically formatted as a list of tool calls with arguments.
+6.  The Planner parses the LLM's response into a structured plan object (e.g., an array of step hashes).
+7.  The Planner returns this structured plan to the Agent.
+8.  The Agent then proceeds to execute the steps in the plan.
+
+## 3. Planning Process & LLM Interaction
+
+The planner talks to the LLM through a pluggable adapter (`Legate::LLM::Adapter`). **Gemini is the default**, and a local **Ollama** adapter ships in the box; you can point Legate at any provider — or your own implementation — without changing your agents. See the [LLM Providers guide](../guides/llm_providers) for how to select or implement a provider.
+
+The effectiveness of the planner heavily relies on the quality of the prompt sent to the LLM and the LLM's ability to reason and follow instructions.
+
+*   **Tool Descriptions:** Clear and accurate `description` fields in your `Legate::Tool` metadata are crucial. The LLM uses these descriptions to understand when and how to use each tool.
+*   **Parameter Schemas:** Well-defined `parameters` in the tool metadata allow the LLM to determine the necessary arguments for each tool call in the plan.
+*   **Agent Instructions:** The agent's main `instruction` prompt sets the overall context and constraints for the LLM's planning process.
+*   **History:** Providing conversation history allows the planner to consider previous interactions when creating the current plan.
+*   **LLM Choice:** The specific LLM used (configured via the agent's `model_name`) significantly impacts planning capabilities.
+
+## 4. Plan Structure
+
+While the exact internal representation might vary, a plan generated by the `Legate::Planner` typically consists of a sequence of steps, where each step represents an action, most commonly a tool call. A step usually includes:
+
+The `plan` method returns a Hash with two keys:
+
+*   **`thought_process` (String):** The LLM's reasoning about how to approach the request.
+*   **`steps` (Array\<Hash\>):** The sequence of tool execution steps.
+
+Each step Hash contains:
+
+*   **`tool` (Symbol):** The name of the tool to execute.
+*   **`params` (Hash):** The arguments to pass to the tool's `execute` method.
+*   **`reason` (String):** A brief explanation of why this step is needed.
+
+## 5. Re-planning and Error Handling
+
+Planning isn't always a single-shot process:
+
+*   **Tool Errors:** If a tool execution fails during plan execution, the Agent might ask the `Planner` to revise the plan based on the error.
+*   **Ambiguity:** If the initial plan is insufficient or based on incomplete information, the agent might engage in further interaction (possibly involving the planner again) to clarify before proceeding.
+*   **No Plan:** If the LLM fails to generate a valid plan, the Planner communicates this back to the Agent, which then decides how to proceed based on its `fallback_mode`.
+
+## 6. Configuration and Customization (Future)
+
+Currently, the default planner's behavior is largely determined by the agent's configuration (instructions, tools, model). Future versions of Legate might introduce:
+
+*   Explicit planner configuration options.
+*   Support for different planning strategies or planner implementations beyond the default LLM-based approach.
+
+## Further Reading
+
+*   [`legate_architecture_overview`](./legate_architecture_overview)
+*   [`legate_agent_lifecycle`](./legate_agent_lifecycle)
+*   [`legate_tools_and_registry`](../tools/legate_tools_and_registry)

data/public/docs/core_concepts/legate_session_service.md

@@ -0,0 +1,104 @@
+# Legate Session Service
+
+This document explains the role and functionality of the Session Service within the Legate framework. The Session Service is responsible for managing the state and history of conversations between users and agents.
+
+## 1. Purpose
+
+Agents often need to maintain context over multiple turns of a conversation. This includes remembering:
+
+*   Past user inputs.
+*   Agent responses.
+*   Tools called and their results.
+*   Temporary state data relevant to the ongoing task.
+
+The Session Service provides a persistent or in-memory store for this information, encapsulated within `Legate::Session` objects.
+
+## 2. Architecture Overview
+
+```mermaid
+graph LR
+    Agent[Legate::Agent] -- Uses --> SessionService[Legate::SessionService]
+    SessionService -- Manages --> SessionObjects[Legate::Session Objects]
+    SessionObjects -- Contain --> Events[Legate::Event History]
+    SessionObjects -- Contain --> State[Session State]
+    SessionService -- Persists/Retrieves --> Storage[(Storage: In-Memory)]
+
+    style Agent fill:#ccf,stroke:#333,stroke-width:2px
+    style SessionService fill:#fcc,stroke:#333,stroke-width:2px
+    style SessionObjects fill:#eef,stroke:#333,stroke-width:1px
+    style Storage fill:#ffc,stroke:#333,stroke-width:2px
+```
+
+*   The `Legate::Agent` interacts with a configured `SessionService` implementation.
+*   The `SessionService` is responsible for creating, retrieving, saving, and deleting `Legate::Session` instances.
+*   Each `Legate::Session` holds the list of `Legate::Event`s constituting the conversation history and a key-value store for session-specific state.
+*   The `SessionService` implementation dictates how Sessions are stored (in memory).
+
+## 3. Core Interface (`Legate::SessionService::Base`)
+
+All session service implementations should adhere to the interface defined by `Legate::SessionService::Base` (though Ruby doesn't enforce interfaces strictly). Key methods include:
+
+*   **`persistent?() -> Boolean`**: Returns whether this service persists state.
+*   **`save_scoped_state(scope, key, value)`**: Saves a key-value pair within a specific scope (e.g., `'user'`, `'app'`, `'temp'`).
+*   **`load_scoped_state(scope, key) -> Object | nil`**: Retrieves a value associated with a specific key within a given scope.
+*   **`clear_scoped_state(scope, key)`**: Clears a key within a specific scope.
+*   **`append_event(session_id:, event:)`**: Adds a new `Legate::Event` to the specified session's history.
+*   **`set_state(session_id:, key:, value:)`**: Sets a key-value pair in the state associated with a session.
+*   **`get_state(session_id:, key:) -> Object | nil`**: Retrieves a value from the state associated with a session.
+
+Note: The concrete implementation `Legate::SessionService::InMemory` also provides additional methods such as `create_session`, `get_session`, and `delete_session` for full session lifecycle management.
+
+## 4. Implementation
+
+Legate provides an in-memory session service:
+
+*   **`Legate::SessionService::InMemory`**: Stores all session data directly in the Ruby process's memory using `Concurrent::Map` for thread safety.
+    *   **Pros:** Simple, no external dependencies, fast, thread-safe.
+    *   **Cons:** Data is lost when the process restarts. Not suitable for multi-process or distributed deployments.
+
+## 5. Configuration
+
+You configure the session service implementation when setting up the Legate, typically within the `Legate.configure` block:
+
+```ruby
+require 'legate/session_service/in_memory'
+
+Legate.configure do |config|
+  # Use In-Memory session service
+  config.session_service = Legate::SessionService::InMemory.new
+end
+
+# Access the configured instance later:
+service = Legate.config.session_service
+session = service.create_session(app_name: 'my_app', user_id: 'user123')
+```
+
+## 6. Interaction with `Legate::Agent`
+
+The `Legate::Agent` relies heavily on the configured Session Service during `run_task`:
+
+1.  It calls `get_session` (or `create_session` implicitly if needed) to load the session context.
+2.  It passes the `session_service` instance within the `Legate::ToolContext` to tools, allowing them potential access.
+3.  It uses `add_event_to_session` to record user input, tool requests, tool results, and agent responses, thus building the conversation history.
+4.  The `Legate::Planner` typically receives the session history (retrieved via `get_session_history` by the agent) to inform its planning process.
+
+## 7. Scoped State (`user:`, `app:`, `temp:`)
+
+The session service supports *scoped state* via key prefixes. This allows organizing key-value data by scope:
+
+*   **`user:<key>`**: Data scoped to a specific `(app_name, user_id)` pair. It is shared across all of that user's sessions within the same application, but **not** across different applications.
+*   **`app:<key>`**: Data scoped to a specific `app_name`. It is shared across all users and sessions of that application.
+*   **`temp:<key>`**: Data scoped to a single session (keyed by the session `id`).
+
+When using `set_state`, `get_state`, or `delete_state` with a key containing a valid prefix (e.g., `'user:preference'`), the value is persisted through the session **service's** scoped-state store (`save_scoped_state` / `load_scoped_state` / `clear_scoped_state`), not through the session's internal `@state` map. Plain keys without a prefix remain in the session's internal state.
+
+## 8. Serialization
+
+`Legate::Session` and `Legate::Event` objects provide `to_h` methods to convert their state into Ruby Hashes suitable for JSON serialization. Correspondingly, they have `from_h` class methods to reconstruct objects from these Hash representations.
+
+(See `Legate::Session` and `Legate::Event` for details on their attributes and serializable format).
+
+## Further Reading
+
+*   [`legate_architecture_overview`](./legate_architecture_overview)
+*   [`legate_agent_lifecycle`](./legate_agent_lifecycle)

data/public/docs/error_handling/legate_error_handling.md

@@ -0,0 +1,122 @@
+# Legate Error Handling
+
+This guide covers common Legate-specific exception classes and provides an overview of potential error scenarios and how they are typically handled within the framework.
+
+## Philosophy
+
+Legate aims to use specific error classes to help developers pinpoint the source and nature of issues. When tools encounter problems, they should generally raise an appropriate `Legate::ToolError` subclass rather than returning an error status in their result hash. The Legate agent runtime is designed to catch these exceptions and format them into a standard error event for the LLM.
+
+## Core Exception Hierarchy
+
+Most Legate-specific errors inherit from `Legate::Error < StandardError`.
+
+```mermaid
+graph TD
+    A[StandardError] --> B(Legate::Error)
+
+    B --> C1(Legate::ConfigurationError)
+    B --> C3(Legate::ToolError)
+    B --> C5(Legate::StoreError)
+    B --> C6(Legate::Mcp::Error)
+    B --> C8(Legate::WebhookConfigurationError)
+    B --> C9(Legate::InvalidPrefixError)
+    B --> C10(Legate::SerializationError)
+
+    C3 --> T1(Legate::ToolArgumentError)
+    C3 --> T2(Legate::ToolNetworkError)
+    C3 --> T3(Legate::ToolTimeoutError)
+    C3 --> T4(Legate::ToolHttpError)
+    T2 --> T2a(Legate::ToolCertificateError)
+
+    B --> DS1(Legate::DefinitionStore::Error)
+    DS1 --> DS3(Legate::DefinitionStore::StoreError)
+    DS1 --> DS4(Legate::DefinitionStore::NotFoundError)
+
+    C6 --> M1(Legate::Mcp::ConnectionError)
+    C6 --> M2(Legate::Mcp::ProtocolError)
+    C6 --> M4(Legate::Mcp::RemoteToolError)
+
+    style B fill:#f9f,stroke:#333,stroke-width:2px
+    style C3 fill:#ccf,stroke:#333,stroke-width:1px
+```
+
+> **Note:** `Legate::DefinitionStore::Error` inherits directly from `Legate::Error`; it is not a subclass of `Legate::StoreError`.
+
+## Key Legate Exception Classes
+
+### 1. `Legate::ConfigurationError`
+*   **Purpose**: Raised when there's an issue with the Legate framework's configuration. This could be due to missing required settings, invalid values for configuration parameters (e.g., in `Legate.configure` blocks or environment variables that Legate relies on).
+*   **Example Scenarios**: Missing API key, misconfigured session service type.
+*   **Typically Handled By**: Application startup checks; often fatal if core services cannot be initialized.
+
+### 2. State Errors (`Legate::InvalidPrefixError`, `Legate::SerializationError`)
+*   **`Legate::InvalidPrefixError`**: Raised when an invalid prefix is used in a state key (the recognized scoped prefixes are `user:`, `app:`, and `temp:`).
+*   **`Legate::SerializationError`**: Raised when a state value cannot be serialized for persistence.
+*   **Typically Handled By**: Session state management logic when reading or writing scoped state.
+
+### 3. `Legate::ToolError` (and its subclasses)
+This is a broad category for errors originating from within an Legate tool's execution.
+
+*   **`Legate::ToolError` (Base)**
+    *   **Purpose**: Generic error during a tool's execution that doesn't fit a more specific subclass. Often used to wrap unexpected exceptions within a tool.
+    *   **Attributes**: Can have a `cause` attribute storing the original exception.
+*   **`Legate::ToolArgumentError < Legate::ToolError`**
+    *   **Purpose**: Raised when the parameters provided to a tool are invalid (e.g., missing required parameters, incorrect data types, values out of allowed range).
+    *   **Example Scenarios**: Calculator tool receiving a string for `operand1`, WebhookTool missing the `url`.
+*   **`Legate::ToolNetworkError < Legate::ToolError`**
+    *   **Purpose**: General network-related issues encountered by a tool (often an HTTP-based tool). This excludes timeouts or specific HTTP error statuses.
+    *   **Example Scenarios**: DNS resolution failure, TCP connection refused (not due to timeout).
+*   **`Legate::ToolCertificateError < Legate::ToolNetworkError`**
+    *   **Purpose**: Specifically for SSL/TLS certificate validation failures during an HTTPS request by a tool.
+*   **`Legate::ToolTimeoutError < Legate::ToolError`**
+    *   **Purpose**: Raised when a tool operation (typically a network request) exceeds its allowed timeout.
+    *   **Example Scenarios**: HTTP request taking too long to connect or receive a response.
+*   **`Legate::ToolHttpError < Legate::ToolError`**
+    *   **Purpose**: Raised when an HTTP request made by a tool results in an unsuccessful HTTP status code (e.g., 4xx client errors, 5xx server errors).
+    *   **Attributes**: Contains a `response` attribute holding the HTTP response object (e.g., `Excon::Response`), allowing access to status, headers, and body.
+    *   **Example Scenarios**: Tool calling an API that returns a 404 Not Found or 500 Internal Server Error.
+*   **Typically Handled By**: The `Legate::Agent` catches these. The agent typically creates an error event containing the exception message, which is then presented to the LLM. The LLM might then inform the user or attempt a corrective action.
+
+### 4. `Legate::StoreError` and `Legate::DefinitionStore` Errors
+*   **`Legate::StoreError`**: Base error for failures in persistence layers used for sessions or agent definitions.
+*   **`Legate::DefinitionStore::Error`**: Base for errors specific to the agent definition store (inherits directly from `Legate::Error`).
+*   **`Legate::DefinitionStore::StoreError`**: General errors interacting with the definition store backend.
+*   **`Legate::DefinitionStore::NotFoundError`**: A specific agent definition could not be found in the store.
+*   **Example Scenarios**: Trying to load a non-existent agent from the `GlobalDefinitionRegistry`.
+*   **Typically Handled By**: Agent loading/management logic (e.g., in the Web UI or CLI); may prevent an agent from starting or being used.
+
+### 5. `Legate::Mcp::Error` (and its subclasses)
+Errors related to the Model Context Protocol (MCP) for tool communication with external tool servers.
+*   **`Legate::Mcp::ConnectionError`**: Problems establishing a connection to an MCP server (including handshake/initialization failures).
+*   **`Legate::Mcp::ProtocolError`**: Violations of the MCP JSON-RPC specifications.
+*   **`Legate::Mcp::RemoteToolError`**: An error reported by the remote MCP server during the execution of one of its tools. Carries optional `code` and `data` attributes from the remote error.
+*   **Example Scenarios**: MCP server is down, malformed JSON-RPC message, tool on MCP server fails.
+*   **Typically Handled By**: MCP client logic within Legate; often results in a `ToolError` if an agent was trying to use an MCP-hosted tool.
+
+### 6. `Legate::WebhookConfigurationError`
+*   **Purpose**: Raised for webhook configuration or processing errors within the inbound webhook listener (e.g., from a `webhook_transformer` or `webhook_session_extractor` Proc).
+*   **Example Scenarios**: A webhook payload is missing required fields, or a session ID cannot be extracted.
+*   **Typically Handled By**: The webhook listener, which translates it into an HTTP error response (e.g., `400 Bad Request`).
+
+## General Error Handling in Agents
+
+When an agent executes a tool and the tool raises one of these exceptions (especially `Legate::ToolError` subclasses):
+1.  The `Legate::Agent` runtime catches the exception.
+2.  It logs the error.
+3.  It constructs an `Legate::Event` of type `:error` (or `:tool_error`). This event typically includes:
+    *   The name of the tool that failed.
+    *   The error message from the exception.
+    *   The class name of the exception.
+    *   Sometimes, additional details or the original `cause`.
+4.  This error event is added to the session history.
+5.  The error event (or a summary) is then provided back to the Large Language Model as part of the context for its next turn.
+6.  The LLM can then decide how to proceed, which might involve:
+    *   Informing the user of the failure.
+    *   Trying a different tool or approach.
+    *   Asking the user for clarification.
+
+## HTTP Client Error Handling (`Legate::Tools::Base::HttpClient`)
+
+Tools that use the `Legate::Tools::Base::HttpClient` mixin (like `CatFacts` or `WebhookTool`) benefit from standardized error handling for HTTP operations. This mixin automatically wraps common `Excon::Error` exceptions into the more specific `Legate::ToolNetworkError`, `Legate::ToolCertificateError`, `Legate::ToolTimeoutError`, or `Legate::ToolHttpError`.
+
+This ensures consistent error reporting from tools that make external HTTP calls.