protege 0.1.0.alpha.1

data/lib/protege/events/loop_run_enqueued_event.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Protege
+  # Fired when a scheduled responsibility run is recorded pending and enqueued, before a worker picks
+  # it up (the Loop layer).
+  class LoopRunEnqueuedEvent < Event
+    channel 'protege.loop.run.enqueued'
+
+    def name         = self[:name]
+    def persona_name = self[:persona_name]
+  end
+end

data/lib/protege/events/loop_run_failed_event.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Protege
+  # Fired when a scheduled responsibility run raises (the Loop layer).
+  class LoopRunFailedEvent < Event
+    channel 'protege.loop.run.failed'
+
+    def name         = self[:name]
+    def persona_name = self[:persona_name]
+    def error        = self[:error]
+  end
+end

data/lib/protege/events/loop_run_started_event.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Protege
+  # Fired when a scheduled responsibility run begins (the Loop layer).
+  class LoopRunStartedEvent < Event
+    channel 'protege.loop.run.started'
+
+    def name         = self[:name]
+    def persona_name = self[:persona_name]
+  end
+end

data/lib/protege/events/tool_call_completed_event.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Protege
+  # Fired after a tool call returns a successful result.
+  class ToolCallCompletedEvent < Event
+    channel 'protege.inference.tool_call.completed'
+
+    def persona   = self[:persona]
+    def tool_call = self[:tool_call]
+    def result    = self[:result]
+  end
+end

data/lib/protege/events/tool_call_failed_event.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Protege
+  # Fired when a tool call raises an unhandled exception.
+  class ToolCallFailedEvent < Event
+    channel 'protege.inference.tool_call.failed'
+
+    def persona   = self[:persona]
+    def tool_call = self[:tool_call]
+    def error     = self[:error]
+  end
+end

data/lib/protege/events/tool_call_started_event.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Protege
+  # Fired immediately before a tool call is dispatched.
+  class ToolCallStartedEvent < Event
+    channel 'protege.inference.tool_call.started'
+
+    def persona   = self[:persona]
+    def tool_call = self[:tool_call]
+  end
+end

data/lib/protege/events/tool_calls_received_event.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Protege
+  # Fired when the provider returns tool calls in a single turn.
+  class ToolCallsReceivedEvent < Event
+    channel 'protege.inference.tool_calls.received'
+
+    def persona    = self[:persona]
+    def tool_calls = self[:tool_calls]
+  end
+end

data/lib/protege/extensions/hook.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Protege
+  # Base class for hooks — the surface host apps use to react to engine lifecycle events. Host apps
+  # subclass +Protege::Hook+ and declare handlers with the class-level +on+ DSL; each handler block
+  # receives a typed +Protege::Event+. The declaration contract (the +on+/+stateful+ DSL) lives in
+  # +HookMixin+, which this includes; the runtime that wires those declarations to the event bus and
+  # runs them (isolated dispatch, stateful-instance lifecycle) is +Protege::Subscribers::HookDispatcher+,
+  # installed once at boot.
+  class Hook
+    include HookMixin
+  end
+end

data/lib/protege/extensions/hook_mixin.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Protege
+  # Contract mixin for hooks — the surface host apps use to *declare* reactions to engine lifecycle
+  # events. A concrete hook subclasses +Protege::Hook+ (which includes this module) and declares
+  # handlers with the class-level +on+ DSL, naming the event classes it cares about; each handler block
+  # receives an instance of that +Protege::Event+ subclass.
+  #
+  # This module is *declaration only*. +on+ merely records the block in the class's +subscriptions+
+  # data, so a Zeitwerk reload just rebuilds that data. *Activation* — subscribing to the event bus and
+  # running handlers — is a separate concern owned by +Protege::Subscribers::HookDispatcher+, which
+  # reads this contract (+subscriptions+, +stateful?+) off each hook class when an event fires.
+  #
+  # Handler blocks run (by the dispatcher) via +instance_exec+ on a hook instance, so instance helper
+  # methods — and, for +stateful+ hooks, instance variables across a run — are available inside them.
+  #
+  # @example
+  #   class EventLoggerHook < Protege::Hook
+  #     on Protege::InferenceStartedEvent do |event|
+  #       log "START #{event.persona&.name}"
+  #     end
+  #
+  #     on Protege::ToolCallStartedEvent, Protege::ToolCallCompletedEvent do |event|
+  #       log "TOOL #{event.tool_call&.name}"
+  #     end
+  #
+  #     private
+  #
+  #     def log(line) = Protege.configuration.logger.info(line)
+  #   end
+  module HookMixin
+    # Extend the includer with +ClassMethods+ so the +on+/+stateful+ DSL becomes available.
+    #
+    # @param base [Class] the class including +Hook+
+    # @return [void]
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    # Class-level DSL mixed into every hook class via +Hook.included+.
+    module ClassMethods
+      # Declare a handler for one or more event classes.
+      #
+      # Pure declaration: records the block in +subscriptions+; the event bus is wired separately by
+      # +Protege::Subscribers::HookDispatcher+. Each argument must be a known +Protege::Event+ subclass.
+      # Listing several registers the same block under each. A single event may carry several handlers;
+      # they run in declaration order. Each block is invoked with the event instance via +instance_exec+.
+      #
+      # @param event_classes [Array<Class>] the event classes to handle (e.g. +Protege::InferenceStartedEvent+)
+      # @param block [Proc] the handler, receiving the event instance
+      # @return [void]
+      # @raise [ArgumentError] when an argument is not a known event class
+      def on(*event_classes, &block)
+        event_classes.each do |event_class|
+          unless subscriptions.key?(event_class)
+            raise ArgumentError, "unknown event #{event_class.inspect} (known: #{Protege::Event.all.join(', ')})"
+          end
+
+          subscriptions[event_class] << block
+        end
+      end
+
+      # Declare that this hook keeps state across a single run.
+      #
+      # A stateful hook reuses one instance per +correlation_id+ for the lifetime of a run, so instance
+      # variables set in one handler are visible to later handlers; the instance is evicted when the run
+      # ends. Stateless hooks (the default) get a fresh instance per event.
+      #
+      # @return [void]
+      def stateful
+        @stateful = true
+      end
+
+      # @return [Boolean] true when this hook was declared +stateful+
+      def stateful?
+        @stateful || false
+      end
+
+      # The event subscriptions, keyed by every known event class.
+      #
+      # Pre-seeded with one entry per +Protege::Event.all+ (each an empty array), so the map is also the
+      # set of valid +on+ targets. Handler blocks accumulate in declaration order.
+      #
+      # @return [Hash{Class => Array<Proc>}] each known event class mapped to its handler blocks
+      def subscriptions
+        @subscriptions ||= Protege::Event.all.index_with { [] }
+      end
+    end
+  end
+end

data/lib/protege/extensions/provider.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Protege
+  # Base class for LLM providers. Host apps subclass +Protege::Provider+, declare their id with
+  # +protege_id :symbol+, and implement +#generate(request)+ (optionally +#generate_stream+). The
+  # provider contract lives in +ProviderMixin+, which this includes; subclasses are discovered via
+  # +Provider.descendants+ (see +ProviderMixin.registered+). The request/response value objects it
+  # exchanges are the +Inference::Provider::*+ types.
+  class Provider
+    include ProviderMixin
+  end
+end

data/lib/protege/extensions/provider_mixin.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Protege
+  # Marker mixin for LLM provider extensions.
+  #
+  # A concrete provider class subclasses +Protege::Provider+ (which includes this module) and
+  # declares its symbolic identifier via the +protege_id+ class macro:
+  #
+  #   class OpenRouterProvider < Protege::Provider
+  #     protege_id :openrouter
+  #
+  #     def initialize(api_key:); @api_key = api_key; end
+  #     def generate(request); ...; end
+  #   end
+  #
+  # Providers are referenced by id (the symbol passed to +protege_id+). On include, the class is
+  # auto-tracked in +Provider.registered+; the registry uses this list to map a configured
+  # +provider_id+ to its class without scanning ObjectSpace or requiring explicit registration calls.
+  #
+  # The generation request/response value objects it exchanges live in the +Inference::Provider+
+  # namespace (+Inference::Provider::Request+, +::Response+, …).
+  #
+  # Contract:
+  #
+  #   def self.id;          end  # returns the Symbol declared above (provided by the DSL)
+  #   def generate(request); end # Request -> Response, raises a Protege::*Error on failure
+  module ProviderMixin
+    class << self
+      # Extend the including class with the +protege_id+/+id+ DSL.
+      #
+      # @param base [Class] the class that included +Provider+.
+      # @return [void]
+      def included(base)
+        base.extend(ClassMethods)
+      end
+
+      # List every concrete provider class.
+      #
+      # Reads from +Provider.descendants+ so the registry survives Zeitwerk reloads without a
+      # manual registration step.
+      #
+      # @return [Array<Class>] all provider subclasses currently loaded.
+      def registered
+        Provider.descendants
+      end
+    end
+
+    # Generate a response for +request+ (abstract).
+    #
+    # The provider contract is **hash in, hash out**: +request+ is the standard (OpenAI-compatible)
+    # request hash — +{ messages:, tools: }+ — and the return is the response hash —
+    # +{ content:, tool_calls:, finish_reason: }+ (see the providers doc). The provider adds its own
+    # model/sampling/credentials from config, and raises a +Protege::Error+ subclass on transport, auth,
+    # or parse failure. Providers never touch Protege's internal value types. Concrete providers must
+    # override this; the default body exists only to give a clear failure when one forgets to.
+    #
+    # @param _request [Hash] the request hash (unused in the default).
+    # @return [Hash] never returns; always raises.
+    # @raise [NotImplementedError] always, naming the class that failed to implement +#generate+.
+    def generate(_request)
+      raise NotImplementedError,
+            "#{self.class} must implement #generate(request_hash) -> response hash"
+    end
+
+    # Generate a response, yielding incremental chunks as they arrive.
+    #
+    # The default implementation does not truly stream: it calls +#generate+ and yields the whole
+    # text as one +:text+ chunk (only when non-blank), then returns the response hash. Providers with
+    # native streaming should override this to yield finer-grained chunks.
+    #
+    # @param request [Hash] the request hash.
+    # @yield [chunk] each streamed chunk.
+    # @yieldparam chunk [Hash] +{ type: :text | :thinking | :tool_call, content: String }+.
+    # @return [Hash] the final, complete response hash.
+    def generate_stream(request, &)
+      response = generate(request)
+      yield({ type: :text, content: response[:content] }) if response[:content].present?
+      response
+    end
+
+    # The model id this provider targets, read from its own +config.providers+ slice (+:model+).
+    # Public so the harness can record which model produced a turn (for tracing); resolved per call, so
+    # a future persona-level override is reflected here. Providers may treat a missing model as a hard
+    # error at generation time — that enforcement is theirs, not this soft reader's.
+    #
+    # @return [String, nil] the configured model id, or nil when unset
+    def model
+      Protege.configuration.provider_options(self.class.id)[:model]
+    end
+
+    # The sampling settings this provider applies beyond the model — the generation knobs (temperature,
+    # max tokens, …) that shape the output and so matter for training/reproducibility. The default is
+    # empty; a provider overrides this to expose its own knobs. Captured alongside +#model+ in a trace.
+    #
+    # @return [Hash] the sampling settings (empty by default)
+    def settings
+      {}
+    end
+
+    # Class-level DSL provided by the mixin.
+    module ClassMethods
+      # Declare the symbolic identifier this provider responds to.
+      #
+      # Call inside the class body; the configured +provider_id+ references the provider by this symbol.
+      #
+      # @param symbol [Symbol] the provider's unique identifier (e.g. +:openrouter+).
+      # @return [Symbol] the stored identifier.
+      def protege_id(symbol)
+        @protege_id = symbol
+      end
+
+      # Return the declared symbolic id.
+      #
+      # @return [Symbol] the id set via +protege_id+.
+      # @raise [Protege::ContractViolationError] when the class never called +protege_id+.
+      def id
+        @protege_id || raise(
+          Protege::ContractViolationError,
+          "#{self} must declare its id with `protege_id :<symbol>` inside the class body"
+        )
+      end
+    end
+  end
+end

data/lib/protege/extensions/resolver.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Protege
+  # Base class for resolvers — the Orchestrator's mechanism for assembling inference context (system
+  # prompts, history, retrieved knowledge). Host apps subclass +Protege::Resolver+ and implement
+  # +#resolve(context:)+, returning an +Array<Protege::ModelMessage>+ or nil. The contract lives
+  # in +ResolverMixin+, which this includes. Unlike tools, resolvers are not auto-registered — they are
+  # added explicitly to a persona's +ResolverChain+.
+  class Resolver
+    include ResolverMixin
+  end
+end

data/lib/protege/extensions/resolver_mixin.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Protege
+  # Contract mixin for resolver classes. A resolver receives a +Context+ and returns an
+  # +Array<Protege::ModelMessage>+ (one or more messages to prepend to the inference request)
+  # or +nil+ to contribute nothing. Resolvers are the Orchestrator's mechanism for assembling
+  # inference context — system prompts, conversation history, retrieved knowledge.
+  #
+  # Unlike +Tool+, resolvers are NOT auto-registered. They are explicitly added to a persona's
+  # +ResolverChain+ at declaration time. Host resolvers subclass +Protege::Resolver+, which
+  # includes this module.
+  #
+  # The role of returned messages is the developer's choice:
+  # - +role: :system+ → contributes to the system prompt
+  # - +role: :user+ / +:assistant+ → contributes to conversation history
+  #
+  # Build messages with the +#message+ helper rather than constructing +Protege::ModelMessage+ by hand
+  # — the resolver counterpart of +Tool+'s +success+/+failure+ sugar:
+  #
+  # @example
+  #   class MyResolver < Protege::Resolver
+  #     def resolve(context:)
+  #       message(role: :system, content: "You are #{context.persona.name}.")
+  #     end
+  #   end
+  module ResolverMixin
+    # Produce context messages for the inference request. Concrete resolvers must override.
+    #
+    # @param context [Protege::Orchestrator::Context] the per-delivery resolver context
+    # @return [Array<Object>, nil] messages to prepend, or nil to contribute nothing
+    # @raise [NotImplementedError] always, when not overridden by the including class
+    def resolve(context:)
+      raise NotImplementedError,
+            "#{self.class} must implement #resolve(context:) -> Array<ModelMessage> | nil"
+    end
+
+    # Build one context message to contribute from +#resolve+, without constructing
+    # +Protege::ModelMessage+ by hand — the resolver counterpart of +Tool+'s +success+/+failure+ sugar.
+    #
+    # Return the message directly (a lone message) or collect several in an array; the +ResolverChain+
+    # coerces either shape and skips a +nil+ return, so a resolver that contributes nothing just
+    # returns +nil+.
+    #
+    # @example a system prompt
+    #   message(role: :system, content: summary.to_prompt)
+    #
+    # @param role [Symbol] +:system+ (prompt), +:user+ / +:assistant+ (history), or +:tool+ (a
+    #   replayed tool result)
+    # @param content [String, Array] the text, or multimodal parts (+TextPart+ / +ImagePart+ /
+    #   +DocumentPart+)
+    # @param tool_call_id [String, nil] correlates a +role: :tool+ message back to its originating call
+    # @param tool_calls [Array, nil] the tool calls carried by a +role: :assistant+ message
+    # @return [Protege::ModelMessage] the assembled message
+    def message(role:, content:, tool_call_id: nil, tool_calls: nil)
+      Protege::ModelMessage.new(role:, content:, tool_call_id:, tool_calls:)
+    end
+  end
+end

data/lib/protege/extensions/tool.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Protege
+  # Base class for harness tools — the surface the agent uses to take action. Host apps subclass
+  # +Protege::Tool+, declare +description+/+input_schema+ via the class DSL, and implement
+  # +#use(context:, **input)+ returning a +Protege::Result+. The tool contract (registry, dispatch, the
+  # DSL, and the +#success+/+#failure+ helpers) lives in +ToolMixin+, which this includes; every subclass
+  # is auto-discovered via +Tool.descendants+ (see +ToolMixin.registered+).
+  class Tool
+    include ToolMixin
+  end
+end

data/lib/protege/extensions/tool_mixin.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+module Protege
+  # Contract mixin for harness tools — the surface the agent uses to take action within the LOGI
+  # Orchestrator. Concrete tools subclass +Protege::Tool+ (which includes this module), declare
+  # their description and JSON Schema via the class-level DSL, and implement +#use(context:, **input)+.
+  #
+  # Registration is automatic: every +Tool+ subclass is discoverable via +Tool.registered+
+  # (resolved from +Tool.descendants+, so it survives Zeitwerk reloads), and the +Harness+
+  # enumerates that list to build the LLM-visible tool catalog. Tools have no +protege_id+ DSL — the
+  # id is derived from the class basename with the +Tool+ suffix stripped, then snake_cased
+  # (+SendEmailTool+ → +:send_email+, +HTTPFetchTool+ → +:http_fetch+).
+  #
+  # Tools must return a +Protege::Result+ from +#use+ — construct one via +Result.success(**data)+ /
+  # +Result.failure(reason:, **data)+ (or the +#success+/+#failure+ helpers). The +Harness+ serializes
+  # the result to JSON for the LLM's tool message, so a failed result lets the model self-correct.
+  #
+  # @example A concrete tool
+  #   class SendEmailTool < Protege::Tool
+  #     description 'Sends an email reply to the inbound sender.'
+  #
+  #     input_schema(
+  #       type: 'object',
+  #       required: %w[subject body],
+  #       properties: {
+  #         subject: { type: 'string' },
+  #         body:    { type: 'string' }
+  #       }
+  #     )
+  #
+  #     def use(context:, subject:, body:)
+  #       # ...
+  #     end
+  #   end
+  #
+  # == Contract
+  #
+  #   def self.id;                end  # Symbol derived from class basename
+  #   def self.description;       end  # String declared via the DSL
+  #   def self.input_schema;      end  # Hash declared via the DSL (JSON Schema)
+  #   def use(context:, **input); end  # Context + parsed input → Protege::Result
+  module ToolMixin
+    class << self
+      # Extend the includer with +ClassMethods+ so the class-level DSL becomes available.
+      #
+      # @param base [Class] the class including +Tool+
+      # @return [void]
+      def included(base)
+        base.extend(ClassMethods)
+      end
+
+      # List all concrete tool classes.
+      #
+      # Resolved via +Tool.descendants+ so the registry survives Zeitwerk reloads without manual
+      # bookkeeping. Anonymous classes (nil name) are excluded.
+      #
+      # @return [Array<Class>] the registered tool classes
+      def registered
+        Tool.descendants.reject { _1.name.nil? }
+      end
+
+      # Find a tool instance by its string id.
+      #
+      # @param name [String] the tool id to look up
+      # @return [Object] a fresh instance of the matching tool class
+      # @raise [Protege::ToolNotFoundError] when no tool matches +name+
+      def find!(name)
+        klass = registered.find { _1.id.to_s == name }
+        raise Protege::ToolNotFoundError.new(name:) unless klass
+
+        klass.new
+      end
+
+      # Look up a tool by name, execute it, and pair the call with its outcome.
+      #
+      # Both failure modes resolve to a failed +Result+ so the caller (the +Harness+) never sees a
+      # raw error — the model gets a serialized failure it can self-correct from:
+      #
+      # * an exception raised inside +#use+ (or by +find!+) is caught, and
+      # * a +#use+ that returns a non-+Result+ violates the tool contract and is reported as
+      #   +Protege::InvalidToolResultError+, rather than blowing up later when the +Harness+
+      #   calls +#success?+ on the bad value.
+      #
+      # Enforcement of tool scoping lives here: a call to any tool outside the persona's effective scope
+      # (its code grant minus +disabled_tool_ids+, read from +context.persona+) is refused before +#use+
+      # runs. Advertising a narrowed catalogue in the request isn't enough — a tool disabled mid-thread
+      # stays visible to the model in earlier turns and could still be called — so dispatch is the
+      # backstop.
+      #
+      # @param tool_call [Object] the tool call carrying name and input
+      # @param context [Protege::Orchestrator::Context] the per-delivery tool context
+      # @return [Protege::ToolResult] the call paired with its result
+      def invoke(tool_call, context:)
+        if context.persona.available_tool_ids.exclude?(tool_call.name.to_sym)
+          return failed_tool_result(tool_call:,
+                                    error:     Protege::ToolNotAvailableError.new(name: tool_call.name))
+        end
+
+        tool   = find!(tool_call.name)
+        input  = (tool_call.input || {}).symbolize_keys
+        result = tool.use(context:, **input)
+
+        return Protege::ToolResult.new(tool_call:, result:) if result.is_a?(Result)
+
+        failed_tool_result(tool_call:,
+                           error:     Protege::InvalidToolResultError.new(tool: tool.class, got: result.class))
+      rescue StandardError => e
+        failed_tool_result(tool_call:, error: e)
+      end
+
+      private
+
+      # Build a failed +ToolResult+, logging the full error for operators.
+      #
+      # The agent only ever receives the serialized (backtrace-truncated) failure via the tool
+      # message; the complete error and backtrace are written to the log here so debugging context
+      # is never lost.
+      #
+      # @param tool_call [Object] the tool call that failed
+      # @param error [Exception] the captured error or contract violation
+      # @return [Protege::ToolResult] a failed result wrapping +error+
+      def failed_tool_result(tool_call:, error:)
+        Protege.configuration.logger.error(
+          "[Protege] tool #{tool_call.name} failed: #{error.class}: #{error.message}\n" \
+          "#{error.backtrace&.join("\n")}"
+        )
+        Protege::ToolResult.new(tool_call:,
+                                result:    Result.failure(reason: error))
+      end
+    end
+
+    # Execute the tool's work. Concrete tools must override.
+    #
+    # @param context [Protege::Orchestrator::Context] the per-delivery tool context
+    # @param _input [Hash] the parsed tool input keyed by symbol
+    # @return [Protege::Result] the outcome of the tool's work
+    # @raise [NotImplementedError] always, when not overridden by the including class
+    def use(context:, **_input)
+      raise NotImplementedError,
+            "#{self.class} must implement #use(context:, **input) -> Protege::Result"
+    end
+
+    # Build a successful +Protege::Result+.
+    #
+    # Call from +#use+ to signal the tool completed its work. +data+ becomes the payload the LLM sees
+    # in the tool-result message.
+    #
+    # @example
+    #   success(message_id: reply.message_id)
+    #
+    # @param data [Hash] arbitrary payload keyed by symbol
+    # @return [Protege::Result] a successful result
+    def success(**data)
+      Result.success(**data)
+    end
+
+    # Build a failed +Protege::Result+.
+    #
+    # Call from +#use+ to signal the tool could not complete its work. +reason+ may be a String or an
+    # Exception; strings are wrapped in +Protege::GenericError+. +data+ is merged into the payload.
+    #
+    # @example
+    #   failure(reason: 'recipient looks invalid', to: to)
+    #   failure(reason: e, transport: 'smtp')
+    #
+    # @param reason [String, Exception] the failure cause
+    # @param data [Hash] arbitrary payload keyed by symbol
+    # @return [Protege::Result] a failed result
+    def failure(reason:, **data)
+      Result.failure(reason:, **data)
+    end
+
+    # Class-level DSL mixed into every tool class via +Tool.included+.
+    module ClassMethods
+      # Declare or read the natural-language description shown to the LLM in the tool catalog.
+      #
+      # With an argument, sets the description; with no argument, returns the previously declared
+      # value.
+      #
+      # @param text [String, nil] the description to set, or nil to read
+      # @return [String, nil] the current description
+      def description(text = nil)
+        return @description if text.nil?
+
+        @description = text
+      end
+
+      # Declare or read the JSON Schema describing this tool's input parameters.
+      #
+      # With an argument, sets the schema; with no argument, returns the previously declared value.
+      #
+      # @param schema [Hash, nil] the JSON Schema to set, or nil to read
+      # @return [Hash, nil] the current input schema
+      def input_schema(schema = nil)
+        return @input_schema if schema.nil?
+
+        @input_schema = schema
+      end
+
+      # Return the tool's symbolic identifier, derived from the class basename with the +Tool+
+      # suffix stripped and the rest snake_cased. Every concrete tool is named +<Purpose>Tool+ by
+      # convention (so tool classes never collide with same-named models), yet the id the agent sees
+      # stays clean. Memoized per class.
+      #
+      # @example
+      #   SendEmailTool   # => :send_email
+      #   HTTPFetchTool   # => :http_fetch
+      #   EchoTool        # => :echo
+      #   Read2Tool       # => :read2
+      #
+      # @return [Symbol] the tool id
+      def id
+        @id ||= name.demodulize.delete_suffix('Tool').underscore.to_sym
+      end
+    end
+  end
+end