protege 0.1.0.alpha.1

data/lib/protege/configuration.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+# See +Protege+ in protege.rb for the root namespace overview. This file reopens the module to
+# define the process-wide +Configuration+ object and its +Protege.configure+ accessors.
+module Protege
+  # Holds the process-wide Protege configuration set via +Protege.configure+. A single instance is
+  # memoized on the +Protege+ module and read throughout the LOGI pipeline — the Orchestrator reads
+  # +max_tool_turns+, the Inference layer reads +provider_id+ (each provider reads its own model /
+  # sampling / credentials from its +providers+ slice), and the Gateway reads +console_address+.
+  # Mutated once at boot from a Rails initializer; treated as read-only thereafter (the Orchestrator
+  # even freezes it per delivery via +Context+).
+  #
+  # @example Configure in a Rails initializer
+  #   Protege.configure do |config|
+  #     config.provider_id = :openrouter
+  #     config.providers   = { openrouter: { model: 'anthropic/claude-sonnet-4-5' } }
+  #   end
+  class Configuration
+    # Generic, real-looking browser User-Agent sent by the built-in web tools (+web_search+,
+    # +web_fetch+) by default. Deliberately unbranded — a plain Chrome string that blends in — since
+    # some origins reject or fingerprint unusual agents.
+    DEFAULT_HTTP_USER_AGENT =
+      'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 ' \
+      '(KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36'
+
+    # Symbolic id of the inference provider extension (e.g. +:openrouter+). The model, sampling, and
+    # credentials for that provider live in its {#providers} slice, not here.
+    attr_accessor :provider_id
+
+    # Maximum tool-calling rounds before returning the last response.
+    attr_accessor :max_tool_turns
+
+    # Email address representing the dashboard user in local conversations. Messages from the
+    # dashboard use this as their +from_address+, and outbound replies to this address skip SMTP
+    # delivery.
+    attr_accessor :console_address
+
+    # Brand shown in the dashboard nav header. Override to white-label the console, e.g.
+    # +config.nav_title = 'Acme Support'+. Defaults to +'🥚 Protege'+.
+    attr_accessor :nav_title
+
+    # User-Agent the built-in web tools (+web_search+, +web_fetch+) send on outbound HTTP. Defaults to
+    # {DEFAULT_HTTP_USER_AGENT} — a generic browser string, not a Protege-branded one. Override to adopt
+    # your host machine's own browser agent, e.g.
+    # +config.http_user_agent = ENV.fetch('HTTP_USER_AGENT', Protege::Configuration::DEFAULT_HTTP_USER_AGENT)+.
+    attr_accessor :http_user_agent
+
+    # Sets the logger used throughout the engine. Override in an initializer to route Protege output
+    # to a dedicated log target, e.g. +config.logger = Logger.new(Rails.root.join('log/protege.log'))+.
+    attr_writer :logger
+
+    # Destination directories the extension scaffold generators (+protege:tool+, +:resolver+, +:hook+,
+    # +:persona+, +:provider+) write into, each relative to the app root. Defaults to the conventional
+    # +app/tools+, +app/resolvers+, +app/hooks+, +app/personas+, +app/providers+. Override in the
+    # initializer if a host groups its extensions elsewhere (e.g. +config.tools_path = 'app/agents/tools'+);
+    # the target must stay under an autoloaded path so Rails still loads the extension.
+    attr_accessor :tools_path, :resolvers_path, :hooks_path, :personas_path, :providers_path
+
+    # Per-provider options, keyed by provider id — assign a plain Hash (see {#providers}).
+    attr_writer :providers
+
+    # The inbound attachment limits — assign a +Gateway.build_attachment_policy+.
+    attr_writer :attachment_policy
+
+    # Set the global inbound access policy — assign a +Gateway.build_access_policy+.
+    attr_writer :inbound_access
+
+    # Inference tracing options — assign a plain Hash, e.g. +config.tracing = { enabled: true }+ (see
+    # {#tracing}). Off by default; nothing is captured until a host opts in.
+    attr_writer :tracing
+
+    # Initialize configuration with engine defaults.
+    #
+    # @return [void]
+    def initialize
+      @nav_title         = '🥚 Protege'
+      @console_address   = 'console@protege.local'
+      @http_user_agent   = DEFAULT_HTTP_USER_AGENT
+      @max_tool_turns    = 8
+      @provider_id       = nil
+      @logger            = nil
+      @tools_path        = 'app/tools'
+      @resolvers_path    = 'app/resolvers'
+      @hooks_path        = 'app/hooks'
+      @personas_path     = 'app/personas'
+      @providers_path    = 'app/providers'
+      @providers         = nil
+      @attachment_policy = nil
+      @inbound_access    = nil
+      @tracing           = nil
+    end
+
+    # Return the configured logger, lazily resolving a default.
+    #
+    # Falls back to +Rails.logger+ when running inside a Rails application, or a plain stdout logger
+    # otherwise (useful in isolated tests and scripts).
+    #
+    # @return [Logger] the active logger
+    def logger
+      @logger ||= defined?(Rails) ? Rails.logger : Logger.new($stdout)
+    end
+
+    # Per-provider options, a plain Hash keyed by provider id — the Rails-style config seam every
+    # provider (built-in or host-written) reads its settings from. Assigned wholesale in the initializer;
+    # assignment replaces the whole Hash, so include every provider you configure:
+    #
+    #   config.providers = {
+    #     openrouter: { api_key: ENV['OPENROUTER_API_KEY'], base_url: '...' },
+    #     my_llm:     { api_key: ENV['MY_LLM_KEY'], region: 'us' }
+    #   }
+    #
+    # Defaults to +{ openrouter: {} }+ so the built-in is harmless when unused. A provider reads its own
+    # slice via {#provider_options} (keyed by its +protege_id+). Values are opaque to the engine — a
+    # host-written provider may put any keys it likes under its own id and read them back here.
+    #
+    # @return [Hash{Symbol=>Hash}] per-provider options keyed by provider id
+    def providers
+      @providers ||= { openrouter: {} }
+    end
+
+    # The options Hash for one provider, by id — the seam a +Protege::Provider+ reads its settings from
+    # (typically +provider_options(self.class.id)+). Nil-safe: returns an empty Hash when the provider
+    # has no configured slice.
+    #
+    # @param id [Symbol] the provider id (its +protege_id+)
+    # @return [Hash] that provider's options, or +{}+ when unconfigured
+    def provider_options(id)
+      providers[id] || {}
+    end
+
+    # The inbound attachment limits, assigned in the initializer via
+    # +config.attachment_policy = Gateway.build_attachment_policy(...)+. Defaults to the engine's
+    # standard limits (10 MB/attachment, 10/message, 25 MB total). Consulted by the inbound mailbox and
+    # the +send_email+ tool.
+    #
+    # @return [Protege::Gateway::AttachmentPolicy] the attachment policy
+    def attachment_policy
+      @attachment_policy ||= Gateway.build_attachment_policy
+    end
+
+    # The global inbound access policy — the committed, org-wide ceiling on which senders may reach
+    # *any* persona. This is the static layer of the access-control guardrail; the runtime,
+    # per-persona layer lives in +Protege::AccessRule+ records, and +AccessControl+ intersects the two
+    # (each layer can only narrow, never widen).
+    #
+    # Defaults to a bare permit-everyone policy, built lazily on first read so an unconfigured engine
+    # imposes no constraint.
+    #
+    # @example Restrict every persona to the company domain
+    #   config.inbound_access = Protege::Gateway.build_access_policy(allow: ['*@company.co'])
+    #
+    # @return [Protege::Gateway::AccessPolicy] the configured policy, or a permit-everyone default
+    def inbound_access
+      @inbound_access || Gateway.build_access_policy
+    end
+
+    # Inference tracing options, a plain Hash — the on/off seam for durable turn snapshots. Assigned
+    # wholesale in the initializer (like {#providers}); assignment replaces the whole Hash. Defaults to
+    # +{ enabled: false }+, so an unconfigured engine records nothing. When +enabled+ is truthy, the
+    # harness emits a per-turn +InferenceGeneratedEvent+ that the tracing subscriber snapshots into
+    # +Protege::Trace+ rows.
+    #
+    # @example Turn tracing on
+    #   config.tracing = { enabled: true }
+    #
+    # @return [Hash] the tracing options, defaulting to +{ enabled: false }+
+    def tracing
+      @tracing ||= { enabled: false }
+    end
+  end
+end

data/lib/protege/engine.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require 'rails'
+
+# Rails-layer runtime dependencies used by the engine's +app/+ (views, controllers, helpers): Slim
+# templating for the +.slim+ views, and Pagy for dashboard pagination. Required here, with the Engine,
+# rather than in +protege.rb+ (which loads only the plain-Ruby core entry points).
+require 'slim-rails'
+require 'pagy'
+require 'pagy/extras/overflow'
+
+module Protege
+  # Rails engine that mounts Protege into a host application. This is the boot seam of the LOGI
+  # pipeline: it wires inbound email to the Gateway via Action Mailbox routing, exposes the engine's
+  # +lib/+ to autoloading so Orchestrator/Inference constructs resolve lazily, shares route helpers
+  # into the host's view context for Turbo broadcasts, and installs the inference stream broadcaster
+  # and engine migrations. It runs an isolated +Protege+ namespace so host and engine constants never
+  # collide.
+  class Engine < ::Rails::Engine
+    isolate_namespace Protege
+
+    # Expose engine lib/ to Rails autoloading (Harness, Provider, etc.). lib/ is autoload-only — not
+    # eager loaded — so Zeitwerk never tries to map filenames like version.rb to class constants.
+    config.autoload_paths << File.expand_path('..', __dir__)
+
+    # Add engine migrations to the host app so bin/rails db:migrate picks them up.
+    initializer 'protege.migrations' do |app|
+      config.paths['db/migrate'].expanded.each do |path|
+        app.config.paths['db/migrate'] << path
+      end
+    end
+
+    # Clamp an out-of-range +?page=+ to the last page rather than raising +Pagy::OverflowError+ (via the
+    # +overflow+ extra required above), so a stale or hand-typed page number degrades gracefully. We use
+    # only Pagy's lightweight metadata object and render our own sidebar footer markup.
+    initializer 'protege.pagy' do
+      Pagy::DEFAULT[:overflow] = :last_page
+    end
+
+    # Keep non-autoloadable lib/ subdirs out of Zeitwerk. Generators are loaded by Rails' generator
+    # system (and their +Protege::Generators::+ constants don't match the lib-rooted path Zeitwerk would
+    # expect); tasks are .rake. Apps would use +config.autoload_lib(ignore:)+, but that's unavailable
+    # for engines, so ignore explicitly — the form the autoloading guide documents for this case.
+    initializer 'protege.ignore_lib_non_autoloadable', before: :setup_main_autoloader do
+      Rails.autoloaders.main.ignore(lib_path('generators'),
+                                    lib_path('tasks'))
+    end
+
+    # Collapse the directories that merely group top-level constants so their files resolve to flat
+    # constants without a namespace segment: +errors/timeout_error.rb+ → +Protege::TimeoutError+ (not
+    # +Protege::Errors::TimeoutError+), +types/result.rb+ → +Protege::Result+, +extensions/tool.rb+ →
+    # +Protege::Tool+, +events/inference_started_event.rb+ → +Protege::InferenceStartedEvent+. The
+    # directories organize the files; +collapse+ keeps the constants flat.
+    initializer 'protege.collapse_shared', before: :setup_main_autoloader do
+      Rails.autoloaders.main.collapse lib_path('protege/errors')
+      Rails.autoloaders.main.collapse lib_path('protege/events')
+      Rails.autoloaders.main.collapse lib_path('protege/extensions')
+      Rails.autoloaders.main.collapse lib_path('protege/types')
+    end
+
+    # Route inbound Action Mailbox email addressed to a Protege domain to Protege::AgentMailbox — the
+    # Gateway's inbound edge. Scoped by +Gateway.claims?+ (matches a registered +EmailDomain+) rather
+    # than a catch-all, so mounting Protege into a host that also uses Action Mailbox never hijacks the
+    # host's other inbound mail; non-Protege mail falls through to the host's own routing.
+    initializer 'protege.action_mailbox_routing' do
+      ActiveSupport.on_load(:action_mailbox) do
+        routing ->(inbound_email) { Protege::Gateway.claims?(inbound_email:) } => 'protege/agent'
+      end
+    end
+
+    # Add the engine's route helpers to the host app's view context so partials rendered outside a request
+    # (e.g. Turbo broadcasts via ApplicationController.render) can resolve helpers like +thread_path+ without
+    # explicit host-app configuration.
+    initializer 'protege.add_route_helpers' do
+      ActiveSupport.on_load(:action_controller) do
+        helper Protege::Engine.routes.url_helpers
+      end
+    end
+
+    # Expose engine route helpers to all controllers and view contexts once routes are fully
+    # initialised. This ensures partials rendered outside a request (e.g. Turbo broadcasts via
+    # ApplicationController.render) can resolve helpers like +thread_path+ without explicit host-app
+    # configuration, and installs the engine's event subscribers (all under +Protege::Subscribers+): the
+    # introspection broadcaster (console activity feed), the hook dispatcher (fans events to host hooks —
+    # its dispatch reads +HookDispatcher+'s registry live, so reloaded hooks are picked up without
+    # re-subscribing), and tracing. Each exposes the +install!+ contract and subscribes once here.
+    config.after_initialize do
+      Protege::IntrospectionBroadcaster.install!
+      Protege::Subscribers::HookDispatcher.install!
+      Protege::Subscribers::Tracing.install!
+    end
+
+    # Return the absolute path to a file in the engine's lib/ directory. Used by the engine's rake tasks
+    # to locate templates and other static assets.
+    #
+    # @param rel_path [String] the relative path from lib/
+    # @return [String]
+    def lib_path(rel_path)
+      lib = File.expand_path('..', __dir__)
+      File.join(lib, rel_path)
+    end
+  end
+end

data/lib/protege/errors/bad_request_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Protege
+  # the provider rejected the request as malformed
+  class BadRequestError < Error
+    def initialize(detail = nil) = super(detail || 'the provider rejected the request as malformed')
+  end
+end

data/lib/protege/errors/contract_violation_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Protege
+  # provider contract violated
+  class ContractViolationError < Error
+    def initialize(detail = nil) = super(detail || 'provider contract violated')
+  end
+end

data/lib/protege/errors/error.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Protege
+  # Base class for every Protege error. Rescue +Protege::Error+ to catch anything the engine raises
+  # without knowing the specific subclass; the concrete errors are flat top-level constants
+  # (+Protege::TimeoutError+, +Protege::ToolNotFoundError+, …) defined in +lib/protege/errors/+ (a
+  # collapsed autoload dir, so they read as +Protege::+ rather than +Protege::Errors::+).
+  #
+  # Errors are ownerless, pipeline-wide types, so they live at the top level (next to +Result+ and
+  # +Event+) rather than inside the Loop/Orchestrator/Gateway/Inference behavior namespaces.
+  class Error < StandardError
+    # Provider failures a later attempt may clear — a job's +retry_on+ list.
+    TRANSIENT = [
+      InternalError,
+      RateLimitedError,
+      TimeoutError,
+      UnavailableError
+    ].freeze
+
+    # Provider failures retrying cannot help — a job's +discard_on+ list.
+    PERMANENT = [
+      BadRequestError,
+      ContractViolationError,
+      InvalidModelError,
+      ResponseParseFailedError,
+      UnauthorizedError,
+      UnsupportedCapabilityError
+    ].freeze
+  end
+end

data/lib/protege/errors/generic_error.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Protege
+  # Wraps a plain-string reason so callers that expect an Exception on +Result#error+ always get one.
+  # Built automatically by +Result.failure+ when handed a String rather than an Exception.
+  class GenericError < Error; end
+end

data/lib/protege/errors/internal_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Protege
+  # the provider reported an internal error
+  class InternalError < Error
+    def initialize(detail = nil) = super(detail || 'the provider reported an internal error')
+  end
+end

data/lib/protege/errors/invalid_model_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Protege
+  # the configured model is not recognized by the provider
+  class InvalidModelError < Error
+    def initialize(detail = nil) = super(detail || 'the configured model is not recognized by the provider')
+  end
+end

data/lib/protege/errors/invalid_tool_result_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Protege
+  # A tool's +#use+ returned something other than a +Protege::Result+. Tools must build their return
+  # value via +Result.success+ / +Result.failure+.
+  class InvalidToolResultError < Error
+    def initialize(tool:, got:) = super("#{tool}#use must return a Protege::Result, got #{got}")
+  end
+end

data/lib/protege/errors/rate_limited_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Protege
+  # the provider is rate limiting requests
+  class RateLimitedError < Error
+    def initialize(detail = nil) = super(detail || 'the provider is rate limiting requests')
+  end
+end

data/lib/protege/errors/resolver_file_not_found_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Protege
+  # A +LoadFileResolver+'s configured path does not exist — a developer misconfiguration (the path is
+  # author-supplied), so we fail loudly rather than silently contributing nothing.
+  class ResolverFileNotFoundError < Error
+    def initialize(path:, absolute:) = super("no file at #{absolute} (from path #{path.inspect})")
+  end
+end

data/lib/protege/errors/response_parse_failed_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Protege
+  # the provider response could not be parsed
+  class ResponseParseFailedError < Error
+    def initialize(detail = nil) = super(detail || 'the provider response could not be parsed')
+  end
+end

data/lib/protege/errors/timeout_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Protege
+  # the provider request timed out
+  class TimeoutError < Error
+    def initialize(detail = nil) = super(detail || 'the provider request timed out')
+  end
+end

data/lib/protege/errors/tool_not_available_error.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Protege
+  # The model called a registered tool that is not in the current persona's scope — its code grant
+  # minus +disabled_tool_ids+ (see +Protege::ToolScoped+). Distinct from +ToolNotFoundError+ (the tool
+  # does not exist at all): here the tool exists but is withheld from this persona, so dispatch refuses
+  # it before +#use+ runs and the model gets a serialized failure to self-correct from. Guards the case
+  # where a tool disabled mid-thread is still visible to the model in earlier turns.
+  class ToolNotAvailableError < Error
+    def initialize(name:) = super("tool :#{name} is not available to this persona")
+  end
+end

data/lib/protege/errors/tool_not_found_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Protege
+  # The model requested a tool whose name is not in +ToolMixin.registered+. Distinct from runtime
+  # errors raised inside +#use+, which the harness wraps into the tool result so the model self-corrects.
+  class ToolNotFoundError < Error
+    def initialize(name:) = super("no tool registered for :#{name}")
+  end
+end

data/lib/protege/errors/unauthorized_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Protege
+  # the provider rejected authentication
+  class UnauthorizedError < Error
+    def initialize(detail = nil) = super(detail || 'the provider rejected authentication')
+  end
+end

data/lib/protege/errors/unavailable_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Protege
+  # the provider is unavailable
+  class UnavailableError < Error
+    def initialize(detail = nil) = super(detail || 'the provider is unavailable')
+  end
+end

data/lib/protege/errors/unsupported_capability_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Protege
+  # the provider/model does not support the requested capability
+  class UnsupportedCapabilityError < Error
+    def initialize(detail = nil) = super(detail || 'the provider/model does not support the requested capability')
+  end
+end

data/lib/protege/events/event.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Protege
+  # Base class for every Protege event — both the typed, nil-safe wrapper handed to subscribers and the
+  # class-level publish/subscribe surface. Concrete events are one flat class each (+InferenceStartedEvent+,
+  # +ToolCallCompletedEvent+, …) in +lib/protege/events/+ (a collapsed autoload dir, so they read as
+  # +Protege::+ rather than +Protege::Events::+), mirroring the +Protege::*Error+ hierarchy.
+  #
+  # Each subclass declares its +ActiveSupport::Notifications+ topic with the +channel+ class macro (the
+  # same class-attribute style as a provider's +protege_id+) and writes a plain reader per payload key.
+  # Publishing and subscribing go through the subclass:
+  #
+  #   Protege::InferenceCompletedEvent.emit(persona:, message:, result:)   # engine internals
+  #   Protege::InferenceCompletedEvent.subscribe { |event| event.result }  # host / broadcaster
+  #
+  # +correlation_id+ is injected automatically from +Protege::Current+ into every emitted event — set it
+  # once in +AgentMailbox+ and it rides through the whole processing run. A subscriber's block receives a
+  # frozen instance of the specific event class, so +event.persona+ / +event.result+ read the payload
+  # with named, nil-safe accessors (and +event[:key]+ reaches anything without a dedicated reader).
+  class Event
+    # @return [Hash] the underlying payload hash
+    attr_reader :payload
+
+    # Wrap a raw notification payload; frozen so subscribers can't mutate shared state.
+    #
+    # @param payload [Hash] the event payload as published by {emit}
+    # @return [void]
+    def initialize(payload)
+      @payload = payload
+      freeze
+    end
+
+    # @return [String, nil] the per-run correlation id injected by {emit}
+    def correlation_id = @payload[:correlation_id]
+
+    # Read an arbitrary payload key not covered by a named reader.
+    #
+    # @param key [Symbol] the payload key
+    # @return [Object, nil] the value, or nil when absent
+    def [](key) = @payload[key]
+
+    class << self
+      # Declare (with an argument) or read (without) this event's +ActiveSupport::Notifications+ topic.
+      # Called in the subclass body — the same class-attribute idiom as a provider's +protege_id+.
+      #
+      # @param value [String, nil] the topic to set, or nil to read the declared one
+      # @return [String] the topic
+      def channel(value = nil)
+        value ? @channel = value : @channel
+      end
+
+      # Publish this event, injecting +correlation_id+ from +Protege::Current+ so callers never pass it.
+      #
+      # @param payload [Hash] the event's payload keyed by symbol
+      # @return [void]
+      def emit(**payload)
+        ActiveSupport::Notifications.instrument(channel,
+                                                correlation_id: Protege::Current.correlation_id,
+                                                **payload)
+      end
+
+      # Subscribe to this event, yielding a typed instance of this class (not the raw payload hash).
+      #
+      # @yieldparam event [Protege::Event] the wrapped event
+      # @return [Object] the subscription handle returned by +ActiveSupport::Notifications+
+      def subscribe(&block)
+        ActiveSupport::Notifications.subscribe(channel) do |_name, _start, _finish, _id, payload|
+          block.call new(payload)
+        end
+      end
+
+      # Every concrete event class, in fire order. Built lazily on first call (at boot, by
+      # +Subscribers::HookDispatcher.install!+), so each subclass is autoloaded only when referenced
+      # here — after this base and its +channel+ macro are defined — keeping +lib/+ autoload-only with
+      # no load-order constraint.
+      #
+      # @return [Array<Class>] the event classes
+      def all
+        @all ||= [
+          InferenceStartedEvent,
+          InferenceGeneratedEvent,
+          InferenceCompletedEvent,
+          InferenceFailedEvent,
+          ToolCallsReceivedEvent,
+          ToolCallStartedEvent,
+          ToolCallCompletedEvent,
+          ToolCallFailedEvent,
+          InferenceMaxTurnsReachedEvent,
+          InferenceChunkEvent,
+          LoopRunEnqueuedEvent,
+          LoopRunStartedEvent,
+          LoopRunCompletedEvent,
+          LoopRunFailedEvent
+        ].freeze
+      end
+    end
+  end
+end

data/lib/protege/events/inference_chunk_event.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Protege
+  # Fired for each token chunk during streaming inference.
+  class InferenceChunkEvent < Event
+    channel 'protege.inference.chunk'
+
+    def persona = self[:persona]
+    def thread  = self[:thread]
+    def chunk   = self[:chunk]
+
+    # The decoded text of the streamed chunk, if any.
+    #
+    # @return [String, nil] the chunk's +:content+ as a string, or nil when there is no chunk
+    def chunk_content = chunk && chunk[:content].to_s
+  end
+end

data/lib/protege/events/inference_completed_event.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Protege
+  # Fired after the tool loop returns a final, tool-free response.
+  class InferenceCompletedEvent < Event
+    channel 'protege.inference.completed'
+
+    def persona = self[:persona]
+    def message = self[:message]
+    def result  = self[:result]
+  end
+end

data/lib/protege/events/inference_failed_event.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Protege
+  # Fired when a run raises before completing.
+  class InferenceFailedEvent < Event
+    channel 'protege.inference.failed'
+
+    def persona = self[:persona]
+    def message = self[:message]
+    def error   = self[:error]
+  end
+end

data/lib/protege/events/inference_generated_event.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Protege
+  # Fired after every single provider generation within the tool loop — once per turn, including the
+  # final tool-free turn. Unlike +InferenceCompletedEvent+ (one per run, carrying only the final
+  # result), this carries the wire +request+ as sent, the +response+ it produced, and the inference
+  # settings (+model+ + +settings+) that shaped it — everything a trace needs to be a training example,
+  # and nothing else (no persona/provider identity). This is the seam the tracing subscriber listens on;
+  # +correlation_id+ (from +Protege::Current+) and +turn+ group the turns of one run for dedup.
+  class InferenceGeneratedEvent < Event
+    channel 'protege.inference.generated'
+
+    def turn     = self[:turn]
+    def request  = self[:request]
+    def response = self[:response]
+    def model    = self[:model]
+    def settings = self[:settings]
+  end
+end

data/lib/protege/events/inference_max_turns_reached_event.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Protege
+  # Fired when the tool loop hits the max turn count without completing.
+  class InferenceMaxTurnsReachedEvent < Event
+    channel 'protege.inference.max_turns_reached'
+
+    def persona    = self[:persona]
+    def turn       = self[:turn]
+    def tool_calls = self[:tool_calls]
+  end
+end

data/lib/protege/events/inference_started_event.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Protege
+  # Fired at the start of the tool loop, before the first provider call.
+  class InferenceStartedEvent < Event
+    channel 'protege.inference.started'
+
+    def persona = self[:persona]
+    def message = self[:message]
+  end
+end

data/lib/protege/events/loop_run_completed_event.rb

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