protege 0.1.0.alpha.2 → 0.1.0.alpha.8

data/lib/generators/protege/install/install_generator.rb

@@ -1,14 +1,14 @@
 # frozen_string_literal: true
 
 require 'rails/generators/base'
-require_relative '../persona/persona_generator'
+require_relative '../agent/agent_generator'
 
 module Protege
   module Generators
     # Bootstraps Protege into a host Rails app — the one command to go from +gem 'protege'+ to a
     # runnable dashboard. It installs the Rails frameworks Protege depends on (Active Storage for
     # attachments, Action Mailbox for inbound mail), writes a fully-documented initializer, mounts the
-    # engine, wires the Loop's recurring tick, and scaffolds a starter persona. The steps it cannot do
+    # engine, wires the Loop's recurring tick, and scaffolds a starter agent. The steps it cannot do
     # safely for you — wrapping the mount in your own authentication, running migrations, setting
     # credentials — are printed as next steps.
     #
@@ -17,7 +17,7 @@ module Protege
     class InstallGenerator < Rails::Generators::Base
       source_root File.expand_path('templates', __dir__)
 
-      desc 'Install Protege into the host app: initializer, engine mount, recurring tick, and a starter persona.'
+      desc 'Install Protege into the host app: initializer, engine mount, recurring tick, and a starter agent.'
 
       # The recurring job entry that drives the Loop scheduler — one tick a minute fires due
       # responsibilities. Written at column zero; {#indented_tick} nests it under an environment key.
@@ -76,12 +76,12 @@ module Protege
         end
       end
 
-      # Scaffold a starter +Agent+ persona by delegating to the persona generator (single source of
-      # truth for the persona template).
+      # Scaffold a starter +ExecutiveAgent+ by delegating to the agent generator (single source of
+      # truth for the agent template).
       #
       # @return [void]
-      def create_starter_persona
-        invoke Protege::Generators::PersonaGenerator, ['Agent']
+      def create_starter_agent
+        invoke Protege::Generators::AgentGenerator, ['Executive']
       end
 
       # Print the wiring the generator can't safely automate.
@@ -96,19 +96,27 @@ module Protege
             1. Run the migrations (Active Storage, Action Mailbox, and Protege's own):
                  bin/rails db:migrate
 
-            2. WRAP THE ENGINE MOUNT in your authentication in config/routes.rb — the engine ships no
+            2. Sync the system toolkits (creates "All Tools" and "Default Tools"; agents you create
+               afterwards auto-attach Default Tools, so they can reply out of the box). Run it on
+               every deploy, after db:migrate:
+                 bin/rails protege:toolkits:sync
+
+            3. WRAP THE ENGINE MOUNT in your authentication in config/routes.rb — the engine ships no
                auth of its own. An unwrapped mount exposes the dashboard to anyone.
 
-            3. Set your provider credentials (the defaults read OpenRouter from ENV):
+            4. Set your provider credentials (the defaults read OpenRouter from ENV):
                  OPENROUTER_API_KEY=sk-...   (and OPENROUTER_MODEL to pick a model)
 
-            4. Let extensions register in development by loading them eagerly — add to
+            5. Let extensions register in development by loading them eagerly — add to
                config/environments/development.rb:
                  config.eager_load = true
                (tools/providers/hooks are discovered as loaded subclasses).
 
-            5. Create your first persona + email domain (dashboard, or a db/seeds.rb bootstrap) so
+            6. Create your first agent + email domain (dashboard, or a db/seeds.rb bootstrap) so
                inbound mail has somewhere to route. Then boot and open /protege.
+
+               Or, for a ready-to-chat development setup in one command (covers steps 2 and 6):
+                 bin/rails protege:setup:dev
         STEPS
       end
 

data/lib/generators/protege/install/templates/initializer.rb.tt

@@ -16,8 +16,13 @@ Protege.configure do |config|
 
   # ── Inference ─────────────────────────────────────────────────────────────────
 
-  # Maximum tool-calling rounds before the harness returns the last response. (default: 8)
-  # config.max_tool_turns = 8
+  # Maximum tool-calling rounds before the harness returns the last response. (default: 100)
+  # config.max_tool_turns = 100
+
+  # X-Protege-Recursion hop count at which inbound mail is silently dropped — bounds agent-to-agent
+  # reply loops. A human replying anywhere resets the chain (mail clients don't echo the header).
+  # (default: 50)
+  # config.recursion_limit = 50
 
   # Symbolic id of the provider extension to run inference through; must match a registered provider's
   # +protege_id+ (here the built-in OpenRouter's :openrouter). (default: nil)
@@ -47,8 +52,8 @@ Protege.configure do |config|
 
   # ── Inbound access control ──────────────────────────────────────────────────
 
-  # Global ceiling on which senders may reach ANY persona — the committed layer of the access guardrail.
-  # Per-persona rules (managed in the dashboard) only narrow this further, never widen it. Patterns are
+  # Global ceiling on which senders may reach ANY agent — the committed layer of the access guardrail.
+  # Per-agent rules (managed in the dashboard) only narrow this further, never widen it. Patterns are
   # an exact address or a single "*" wildcard. Defaults to permit-all.
   # config.inbound_access = Protege::Gateway.build_access_policy(allow: ['*@your-company.com'])
   # config.inbound_access = Protege::Gateway.build_access_policy(deny: ['*@spam.example'])
@@ -68,15 +73,21 @@ Protege.configure do |config|
 
   # ── Extension scaffold paths ──────────────────────────────────────────────────
 
-  # Where the `bin/rails g protege:{tool,resolver,hook,persona,provider}` generators write. Defaults to
+  # Where the `bin/rails g protege:{tool,resolver,hook,agent,provider}` generators write. Defaults to
   # the conventional app/ directories; override if you group extensions elsewhere (must stay under an
   # autoloaded path).
   # config.tools_path     = 'app/tools'
   # config.resolvers_path = 'app/resolvers'
   # config.hooks_path     = 'app/hooks'
-  # config.personas_path  = 'app/personas'
+  # config.agents_path  = 'app/agents'
   # config.providers_path = 'app/providers'
 
+  # ── Failure alerts ──────────────────────────────────────────────────────────
+
+  # Email the platform operator when an inference run fails (sent via Action Mailer, outside the
+  # agent's own mail flow). Off by default; no alert is sent until `to:` is set.
+  # config.failure_alerts = { to: ['ops@example.com'], from: 'alerts@your-domain.com' }
+
   # ── Logging ─────────────────────────────────────────────────────────────────
 
   # Logger for engine output; defaults to Rails.logger. Override to route to a dedicated target:

data/lib/generators/protege/postfix/templates/deploy/mail/MAIL.md

@@ -101,7 +101,7 @@ Pre-stage the TXT records anytime. Do **not** change the MX until you cut over (
 2. Deploy the app and **boot the accessory** (Kamal `deploy` does not manage accessories):
    `kamal accessory boot mail`.
 3. Point the **MX** at `agent.example.com` (priority 10). Inbound now arrives at your box.
-4. Validate: `kamal accessory logs mail`; email the persona from Gmail → reply lands with
+4. Validate: `kamal accessory logs mail`; email the agent from Gmail → reply lands with
    **SPF/DKIM/DMARC = pass** ("Show original"). Score at [mail-tester.com](https://www.mail-tester.com)
    and iterate on reputation.
 
@@ -126,7 +126,7 @@ Our own outbound (the app container, on RFC1918) skips all three — only remote
   first-run window: deploy with `monitor`, watch `kamal accessory logs mail` for `dmarc=fail` on
   legitimate senders, then switch to `enforce` and redeploy (no image rebuild needed).
 
-To verify: from a Gmail account, email the persona and confirm a normal message is delivered with
+To verify: from a Gmail account, email the agent and confirm a normal message is delivered with
 `dmarc=pass`; a spoofing attempt against a `p=reject` domain is refused at SMTP (visible in the logs).
 
 ## Rollback

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