protege 0.1.0.alpha.2 → 0.1.0.alpha.7

data/lib/generators/protege/resolver/resolver_generator.rb

@@ -5,12 +5,12 @@ require_relative '../extension_naming'
 
 module Protege
   module Generators
-    # Scaffolds a Protege resolver — one link in a persona's context-building chain — into the host
+    # Scaffolds a Protege resolver — one link in an agent's context-building chain — into the host
     # app's resolvers directory (+config.resolvers_path+, default +app/resolvers+). A resolver
     # subclasses +Protege::Resolver+ and implements +resolve+, contributing zero or more
     # +Protege::ModelMessage+s to the prompt the harness sends the model.
     #
-    # Unlike tools, resolvers are NOT auto-discovered: add the class to a persona's chain
+    # Unlike tools, resolvers are NOT auto-discovered: add the class to an agent's chain
     # (+chain.use MyResolver+) for it to run. The +Resolver+ suffix is applied for you.
     #
     # @example

data/lib/generators/protege/resolver/templates/resolver.rb.tt

@@ -2,10 +2,10 @@
 
 # <%= extension_class_name('Resolver') %> — contributes context to the prompt before the model runs.
 #
-# A resolver is one link in a persona's chain. Subclass +Protege::Resolver+, implement +#resolve+, and
+# A resolver is one link in an agent's chain. Subclass +Protege::Resolver+, implement +#resolve+, and
 # add it to a chain to activate it (resolvers are NOT auto-discovered):
 #
-#   # in app/personas/your_persona.rb
+#   # in app/agents/your_agent.rb
 #   message_resolvers        { |chain| chain.use <%= extension_class_name('Resolver') %> }  # reply runs
 #   responsibility_resolvers { |chain| chain.use <%= extension_class_name('Resolver') %> }  # scheduled runs
 #
@@ -17,7 +17,7 @@ class <%= extension_class_name('Resolver') %> < Protege::Resolver
   # The +context+ tells you which kind of run this is (read it, never mutate it — it is frozen):
   #   - reply run:     +context.message+ is the inbound +Protege::Message+ (and +context.message.email_thread+)
   #   - scheduled run: +context.responsibility+ is the +Protege::Responsibility+; +context.message+ is nil
-  # Both always expose +context.persona+, +context.config+, and +context.logger+.
+  # Both always expose +context.agent+, +context.config+, and +context.logger+.
   #
   # Pick a +role+ for what you contribute: +:system+ for standing instructions/facts, +:user+ or
   # +:assistant+ for conversation turns, +:tool+ for a replayed tool result.
@@ -26,6 +26,6 @@ class <%= extension_class_name('Resolver') %> < Protege::Resolver
   # @return [Protege::ModelMessage, Array<Protege::ModelMessage>, nil] the contribution, or nil for none
   def resolve(context:)
     # TODO: build and return your context. Return nil when there is nothing to add.
-    message(role: :system, content: "TODO: context for #{context.persona.name}")
+    message(role: :system, content: "TODO: context for #{context.agent.name}")
   end
 end

data/lib/generators/protege/tool/templates/tool.rb.tt

@@ -2,9 +2,11 @@
 
 # <%= extension_class_name('Tool') %> — a capability the agent can call mid-conversation.
 #
-# Subclassing +Protege::Tool+ registers this tool automatically (no wiring): the harness publishes it
-# in the model's tool catalog and routes matching tool calls to +#use+. The tool's id is derived from
-# this class name with the +Tool+ suffix stripped and snake_cased — here +:<%= extension_file_name('Tool').sub(/_tool\z/, '') %>+.
+# Subclassing +Protege::Tool+ registers this tool automatically in the manifest; an agent can use it
+# once it belongs to a toolkit attached to that agent (add it in the dashboard, or run
+# `bin/rails protege:toolkits:sync` so the All Tools toolkit picks it up). When offered, the harness
+# routes matching tool calls to +#use+. The tool's id is derived from this class name with the +Tool+
+# suffix stripped and snake_cased — here +:<%= extension_file_name('Tool').sub(/_tool\z/, '') %>+.
 #
 # Fill in the three things the model relies on:
 #   1. +description+ — WHEN to reach for this tool and WHAT it does, written for the model to read.
@@ -40,11 +42,11 @@ class <%= extension_class_name('Tool') %> < Protege::Tool
   # the model as a failure, so raise freely for the genuinely exceptional.
   #
   # @param context [Protege::Orchestrator::Context] the run context — +context.message+ on a reply run
-  #   (and its +email_thread+), +context.responsibility+ on a scheduled run, plus +persona+/+logger+
+  #   (and its +email_thread+), +context.responsibility+ on a scheduled run, plus +agent+/+logger+
   # @param example [String] the example argument declared in {input_schema} (rename to your own)
   # @return [Protege::Result] the outcome handed back to the model
   def use(context:, example:)
-    # TODO: implement. `context` gives you the persona and the current message/thread or responsibility.
+    # TODO: implement. `context` gives you the agent and the current message/thread or responsibility.
     success(echo: example)
   end
 end

data/lib/protege/configuration.rb

@@ -30,6 +30,13 @@ module Protege
     # Maximum tool-calling rounds before returning the last response.
     attr_accessor :max_tool_turns
 
+    # The +X-Protege-Recursion+ hop count at which inbound mail is silently dropped — the bound on
+    # agent-to-agent reply loops (see +Gateway::RECURSION_HEADER+). Agent-sent mail stamps the header
+    # (+1+ fresh, inbound plus one on a reply); a human replying anywhere resets the chain, since mail
+    # clients never echo the header back. Defaults to 50 — roomy enough for long agent-to-agent
+    # hand-offs while still bounding a true infinite loop.
+    attr_accessor :recursion_limit
+
     # 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.
@@ -50,11 +57,11 @@ module Protege
     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
+    # +:agent+, +:provider+) write into, each relative to the app root. Defaults to the conventional
+    # +app/tools+, +app/resolvers+, +app/hooks+, +app/agents+, +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
+    attr_accessor :tools_path, :resolvers_path, :hooks_path, :agents_path, :providers_path
 
     # Per-provider options, keyed by provider id — assign a plain Hash (see {#providers}).
     attr_writer :providers
@@ -69,6 +76,11 @@ module Protege
     # {#tracing}). Off by default; nothing is captured until a host opts in.
     attr_writer :tracing
 
+    # Operational failure-alert options — assign a plain Hash, e.g.
+    # +config.failure_alerts = { to: ['ops@you.com'], from: 'alerts@your-domain.com' }+ (see
+    # {#failure_alerts}). Off by default; no alert mail is sent until a host sets +:to+.
+    attr_writer :failure_alerts
+
     # Initialize configuration with engine defaults.
     #
     # @return [void]
@@ -76,18 +88,20 @@ module Protege
       @nav_title         = '🥚 Protege'
       @console_address   = 'console@protege.local'
       @http_user_agent   = DEFAULT_HTTP_USER_AGENT
-      @max_tool_turns    = 8
+      @max_tool_turns    = 100
+      @recursion_limit   = 50
       @provider_id       = nil
       @logger            = nil
       @tools_path        = 'app/tools'
       @resolvers_path    = 'app/resolvers'
       @hooks_path        = 'app/hooks'
-      @personas_path     = 'app/personas'
+      @agents_path       = 'app/agents'
       @providers_path    = 'app/providers'
       @providers         = nil
       @attachment_policy = nil
       @inbound_access    = nil
       @tracing           = nil
+      @failure_alerts    = nil
     end
 
     # Return the configured logger, lazily resolving a default.
@@ -139,14 +153,14 @@ module Protege
     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
+    # *any* agent. This is the static layer of the access-control guardrail; the runtime,
+    # per-agent 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
+    # @example Restrict every agent 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
@@ -167,5 +181,26 @@ module Protege
     def tracing
       @tracing ||= { enabled: false }
     end
+
+    # Operational failure-alert options, a plain Hash — the opt-in seam for emailing a platform admin
+    # when inference fails. Assigned wholesale in the initializer (like {#tracing}); assignment replaces
+    # the whole Hash. Recognised keys:
+    #
+    # * +:to+ — an Array of recipient addresses. Alerting is enabled only when this is present and
+    #   non-empty, so an unconfigured engine (the default +{}+) sends nothing.
+    # * +:from+ — the sender address. For production deliverability this must be an address at a
+    #   registered +EmailDomain+ so the self-hosted MTA DKIM-signs it and it passes that domain's DMARC
+    #   policy; there is no safe way to deduce it, so it is set explicitly. Omitted → the
+    #   +ApplicationMailer+ default sender (adequate only under the +:test+ delivery method).
+    #
+    # When +:to+ is set, +Protege::Subscribers::Alerter+ emails those recipients on inference failure.
+    #
+    # @example Turn failure alerts on
+    #   config.failure_alerts = { to: ['ops@you.com'], from: 'alerts@agent.you.com' }
+    #
+    # @return [Hash] the failure-alert options, defaulting to +{}+ (disabled)
+    def failure_alerts
+      @failure_alerts ||= {}
+    end
   end
 end

data/lib/protege/engine.rb

@@ -83,11 +83,13 @@ module Protege
     # 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.
+    # re-subscribing), tracing, and the alerter (emails the platform admin on inference failure when
+    # +config.failure_alerts+ opts in). Each exposes the +install!+ contract and subscribes once here.
     config.after_initialize do
       Protege::IntrospectionBroadcaster.install!
       Protege::Subscribers::HookDispatcher.install!
       Protege::Subscribers::Tracing.install!
+      Protege::Subscribers::Alerter.install!
     end
 
     # Return the absolute path to a file in the engine's lib/ directory. Used by the engine's rake tasks

data/lib/protege/errors/tool_not_available_error.rb

@@ -1,12 +1,13 @@
 # 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.
+  # The model called a registered tool that is not in the current agent's scope for this run — the tools
+  # its attached toolkits expose to the run's sender (see +Protege::Toolable+ / +AgentToolkit+). Distinct
+  # from +ToolNotFoundError+ (the tool does not exist at all): here the tool exists but is withheld from
+  # this agent, so dispatch refuses it before +#use+ runs and the model gets a serialized failure to
+  # self-correct from. Guards the case where a tool that left scope 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")
+    def initialize(name:) = super("tool :#{name} is not available to this agent")
   end
 end

data/lib/protege/events/event.rb

@@ -10,12 +10,12 @@ module Protege
   # 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.emit(agent:, 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
+  # frozen instance of the specific event class, so +event.agent+ / +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

data/lib/protege/events/inference_chunk_event.rb

@@ -5,7 +5,7 @@ module Protege
   class InferenceChunkEvent < Event
     channel 'protege.inference.chunk'
 
-    def persona = self[:persona]
+    def agent = self[:agent]
     def thread  = self[:thread]
     def chunk   = self[:chunk]
 

data/lib/protege/events/inference_completed_event.rb

@@ -5,7 +5,7 @@ module Protege
   class InferenceCompletedEvent < Event
     channel 'protege.inference.completed'
 
-    def persona = self[:persona]
+    def agent = self[:agent]
     def message = self[:message]
     def result  = self[:result]
   end

data/lib/protege/events/inference_failed_event.rb

@@ -5,7 +5,7 @@ module Protege
   class InferenceFailedEvent < Event
     channel 'protege.inference.failed'
 
-    def persona = self[:persona]
+    def agent = self[:agent]
     def message = self[:message]
     def error   = self[:error]
   end

data/lib/protege/events/inference_generated_event.rb

@@ -5,7 +5,7 @@ module Protege
   # 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;
+  # and nothing else (no agent/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'

data/lib/protege/events/inference_max_turns_reached_event.rb

@@ -5,7 +5,7 @@ module Protege
   class InferenceMaxTurnsReachedEvent < Event
     channel 'protege.inference.max_turns_reached'
 
-    def persona    = self[:persona]
+    def agent = self[:agent]
     def turn       = self[:turn]
     def tool_calls = self[:tool_calls]
   end

data/lib/protege/events/inference_started_event.rb

@@ -5,7 +5,7 @@ module Protege
   class InferenceStartedEvent < Event
     channel 'protege.inference.started'
 
-    def persona = self[:persona]
+    def agent = self[:agent]
     def message = self[:message]
   end
 end

data/lib/protege/events/loop_run_completed_event.rb

@@ -6,6 +6,6 @@ module Protege
     channel 'protege.loop.run.completed'
 
     def name         = self[:name]
-    def persona_name = self[:persona_name]
+    def agent_name = self[:agent_name]
   end
 end

data/lib/protege/events/loop_run_enqueued_event.rb

@@ -7,6 +7,6 @@ module Protege
     channel 'protege.loop.run.enqueued'
 
     def name         = self[:name]
-    def persona_name = self[:persona_name]
+    def agent_name = self[:agent_name]
   end
 end

data/lib/protege/events/loop_run_failed_event.rb

@@ -6,7 +6,7 @@ module Protege
     channel 'protege.loop.run.failed'
 
     def name         = self[:name]
-    def persona_name = self[:persona_name]
+    def agent_name = self[:agent_name]
     def error        = self[:error]
   end
 end

data/lib/protege/events/loop_run_started_event.rb

@@ -6,6 +6,6 @@ module Protege
     channel 'protege.loop.run.started'
 
     def name         = self[:name]
-    def persona_name = self[:persona_name]
+    def agent_name = self[:agent_name]
   end
 end

data/lib/protege/events/tool_call_completed_event.rb

@@ -5,7 +5,7 @@ module Protege
   class ToolCallCompletedEvent < Event
     channel 'protege.inference.tool_call.completed'
 
-    def persona   = self[:persona]
+    def agent = self[:agent]
     def tool_call = self[:tool_call]
     def result    = self[:result]
   end

data/lib/protege/events/tool_call_failed_event.rb

@@ -5,7 +5,7 @@ module Protege
   class ToolCallFailedEvent < Event
     channel 'protege.inference.tool_call.failed'
 
-    def persona   = self[:persona]
+    def agent = self[:agent]
     def tool_call = self[:tool_call]
     def error     = self[:error]
   end

data/lib/protege/events/tool_call_started_event.rb

@@ -5,7 +5,7 @@ module Protege
   class ToolCallStartedEvent < Event
     channel 'protege.inference.tool_call.started'
 
-    def persona   = self[:persona]
+    def agent = self[:agent]
     def tool_call = self[:tool_call]
   end
 end

data/lib/protege/events/tool_calls_received_event.rb

@@ -5,7 +5,7 @@ module Protege
   class ToolCallsReceivedEvent < Event
     channel 'protege.inference.tool_calls.received'
 
-    def persona    = self[:persona]
+    def agent = self[:agent]
     def tool_calls = self[:tool_calls]
   end
 end

data/lib/protege/extensions/hook.rb

@@ -9,5 +9,6 @@ module Protege
   # installed once at boot.
   class Hook
     include HookMixin
+    include Protege::Manifested
   end
 end

data/lib/protege/extensions/hook_mixin.rb

@@ -17,7 +17,7 @@ module Protege
   # @example
   #   class EventLoggerHook < Protege::Hook
   #     on Protege::InferenceStartedEvent do |event|
-  #       log "START #{event.persona&.name}"
+  #       log "START #{event.agent&.name}"
   #     end
   #
   #     on Protege::ToolCallStartedEvent, Protege::ToolCallCompletedEvent do |event|

data/lib/protege/extensions/manifest.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Protege
+  # The read-only facade over the extension registries — one place the dashboard asks "what extensions of
+  # this type exist, and what is their metadata?". Generalizes the tools-only +ToolMixin.registered+ into a
+  # uniform lookup across all four types, each row a plain {Entry} carrying the {Manifested} metadata plus
+  # the class itself.
+  module Manifest
+    # One registered extension, flattened to its manifest metadata for the UI and for bindings. +summary+
+    # is the short human-facing blurb; +description+ is the verbose, LLM-facing text (a tool's schema text).
+    Entry = Data.define(:type, :id, :display_name, :summary, :description, :klass)
+
+    # The extension base class for each manifest type (referenced lazily so the facade loads before them).
+    BASES = {
+      tool:     'Protege::Tool',
+      provider: 'Protege::Provider',
+      hook:     'Protege::Hook',
+      resolver: 'Protege::Resolver'
+    }.freeze
+
+    class << self
+      # Every registered extension of a type, as {Entry}s sorted by display name.
+      #
+      # @param type [Symbol] one of +:tool+, +:provider+, +:hook+, +:resolver+
+      # @return [Array<Entry>] the registered extensions' manifest entries
+      def registered(type)
+        base(type).registered.map { |klass| entry_for(type:, klass:) }.sort_by(&:display_name)
+      end
+
+      # The manifest entry for a single extension id, or nil when none is registered under it.
+      #
+      # @param type [Symbol] the manifest type
+      # @param id [Symbol] the extension id to look up
+      # @return [Entry, nil] the matching entry, or nil
+      def entry(type:, id:)
+        klass = base(type).registered.find { |candidate| candidate.id == id }
+        entry_for(type:, klass:) if klass
+      end
+
+      private
+
+      # Resolve a manifest type to its extension base class.
+      #
+      # @param type [Symbol] the manifest type
+      # @return [Class] the extension base class
+      def base(type)
+        BASES.fetch(type).constantize
+      end
+
+      # Build an {Entry} from a registered extension class.
+      #
+      # @param type [Symbol] the manifest type
+      # @param klass [Class] the extension class
+      # @return [Entry] the manifest entry
+      def entry_for(type:, klass:)
+        Entry.new(
+          type:,
+          id:           klass.id,
+          display_name: klass.display_name,
+          summary:      klass.summary,
+          description:  klass.description,
+          klass:
+        )
+      end
+    end
+  end
+end

data/lib/protege/extensions/manifested.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Protege
+  # Uniform, UI-facing metadata for every registered extension — the "Manifest" layer of the extension
+  # framework. Mixed once into each extension base class (+Protege::Tool+/+Provider+/+Hook+/+Resolver+) so
+  # a dashboard can list any of them by the same handful of attributes, regardless of how each type
+  # registers or activates. Defining the surface here, in one concern, is what lets bindings (e.g.
+  # Toolkits) reference extensions uniformly instead of hand-wiring a registry per type.
+  #
+  # Provides, at the class level: a stable +id+ (name-derived, or explicit via {ClassMethods#manifest_id}),
+  # a human +display_name+ (defaulting to the titleized id), an optional +description+, and +registered+
+  # (the loaded, named concrete subclasses of the base it is called on). Enumeration is descendant-based,
+  # like the tools registry, so it survives Zeitwerk reloads and skips anonymous classes.
+  module Manifested
+    extend ActiveSupport::Concern
+
+    # Class-level metadata surface added to every extension base.
+    module ClassMethods
+      # The extension's stable symbolic id — the manifest key a binding references and the dashboard
+      # shows. Defaults to the class basename with a trailing +Tool+/+Provider+/+Hook+/+Resolver+ suffix
+      # stripped and the rest snake_cased; override with {#manifest_id} when the id must be explicit (a
+      # provider, whose id is matched against +config.provider_id+). Memoized per class.
+      #
+      # @return [Symbol] the extension id
+      def id
+        @id ||= name.demodulize.sub(/(?:Tool|Provider|Hook|Resolver)\z/, '').underscore.to_sym
+      end
+
+      # Declare an explicit id, overriding the name-derived default.
+      #
+      # @param value [Symbol, String] the explicit id
+      # @return [Symbol] the stored id
+      def manifest_id(value)
+        @id = value.to_sym
+      end
+
+      # A human-readable label for the dashboard: the declared name, or the titleized id by default. Pass
+      # a value to set it.
+      #
+      # @param value [String, nil] the display name to set, or nil to read
+      # @return [String] the display name
+      def display_name(value = nil)
+        return @display_name || id.to_s.titleize if value.nil?
+
+        @display_name = value
+      end
+
+      # A natural-language description of the extension: the declared value, or nil when unset. Pass a
+      # value to set it. For a tool this is the *LLM-facing* text published in the model's tool schema —
+      # verbose and model-directed. For a short, human-facing dashboard blurb, use {#summary} instead.
+      #
+      # @param value [String, nil] the description to set, or nil to read
+      # @return [String, nil] the description
+      def description(value = nil)
+        return @description if value.nil?
+
+        @description = value
+      end
+
+      # A short, human-facing one-liner for the dashboard — what an operator reads when picking this
+      # extension. Distinct from {#description}, which for tools is the verbose text sent to the model.
+      # The declared value, or nil when unset. Pass a value to set it.
+      #
+      # @param value [String, nil] the summary to set, or nil to read
+      # @return [String, nil] the summary
+      def summary(value = nil)
+        return @summary if value.nil?
+
+        @summary = value
+      end
+
+      # The loaded, named concrete subclasses of this extension base — its registry. Anonymous classes
+      # (nil name) are skipped; descendant-based so it survives Zeitwerk reloads without bookkeeping.
+      #
+      # @return [Array<Class>] the registered extension classes
+      def registered
+        descendants.reject { _1.name.nil? }
+      end
+    end
+  end
+end

data/lib/protege/extensions/provider.rb

@@ -8,5 +8,6 @@ module Protege
   # exchanges are the +Inference::Provider::*+ types.
   class Provider
     include ProviderMixin
+    include Protege::Manifested
   end
 end

data/lib/protege/extensions/provider_mixin.rb

@@ -80,7 +80,7 @@ module Protege
 
     # 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
+    # a future agent-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
@@ -97,27 +97,19 @@ module Protege
       {}
     end
 
-    # Class-level DSL provided by the mixin.
+    # Class-level DSL provided by the mixin. The provider's +id+ (and the rest of its manifest metadata)
+    # comes from the shared +Extensions::Manifested+ concern; +protege_id+ is the provider-facing name for
+    # its explicit-id override, kept because a provider's id must match +config.provider_id+ exactly rather
+    # than be derived from the class name.
     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.
+      # Declare the symbolic identifier this provider responds to — an explicit override of the
+      # name-derived manifest id. 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"
-        )
+        manifest_id(symbol)
       end
     end
   end

data/lib/protege/extensions/resolver.rb

@@ -5,8 +5,9 @@ module Protege
   # 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+.
+  # added explicitly to an agent's +ResolverChain+.
   class Resolver
     include ResolverMixin
+    include Protege::Manifested
   end
 end

data/lib/protege/extensions/resolver_mixin.rb

@@ -6,7 +6,7 @@ module Protege
   # 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
+  # Unlike +Tool+, resolvers are NOT auto-registered. They are explicitly added to an agent's
   # +ResolverChain+ at declaration time. Host resolvers subclass +Protege::Resolver+, which
   # includes this module.
   #
@@ -20,7 +20,7 @@ module Protege
   # @example
   #   class MyResolver < Protege::Resolver
   #     def resolve(context:)
-  #       message(role: :system, content: "You are #{context.persona.name}.")
+  #       message(role: :system, content: "You are #{context.agent.name}.")
   #     end
   #   end
   module ResolverMixin

data/lib/protege/extensions/tool.rb

@@ -8,5 +8,6 @@ module Protege
   # is auto-discovered via +Tool.descendants+ (see +ToolMixin.registered+).
   class Tool
     include ToolMixin
+    include Protege::Manifested
   end
 end