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

data/app/helpers/protege/responsibilities_helper.rb

@@ -3,12 +3,12 @@
 module Protege
   # View helpers for responsibility pages — status display and run-history formatting.
   module ResponsibilitiesHelper
-    # Fetch every +Responsibility+ (persona eager-loaded) for the global sidebar listing. The model's
+    # Fetch every +Responsibility+ (agent eager-loaded) for the global sidebar listing. The model's
     # default scope already orders by name.
     #
     # @return [ActiveRecord::Relation<Protege::Responsibility>] all responsibilities
     def all_responsibilities
-      Responsibility.includes(:persona)
+      Responsibility.includes(:agent)
     end
 
     # Render a status dot reflecting whether a responsibility is active.

data/app/helpers/protege/threads_helper.rb

@@ -11,18 +11,18 @@ module Protege
       EmailThread.order(last_message_at: :desc)
     end
 
-    # List the active personas eligible for the compose form.
+    # List the active agents eligible for the compose form.
     #
-    # @return [ActiveRecord::Relation<Protege::Persona>] personas eligible for selection
-    def available_personas
-      Persona.active
+    # @return [ActiveRecord::Relation<Protege::Agent>] agents eligible for selection
+    def available_agents
+      Agent.active
     end
 
-    # Format the available personas as +[label, id]+ pairs for a select dropdown.
+    # Format the available agents as +[label, id]+ pairs for a select dropdown.
     #
     # @return [Array<Array(String, Integer)>] option label/value pairs
-    def available_persona_options
-      available_personas.map { |persona| ["#{persona.name} <#{persona.email_address}>", persona.id] }
+    def available_agent_options
+      available_agents.map { |agent| ["#{agent.name} <#{agent.email_address}>", agent.id] }
     end
 
     # Format a thread subject with its message count for sidebar display.
@@ -34,7 +34,7 @@ module Protege
     # @return [String] the subject, suffixed with the count when it exceeds one
     def thread_title(thread)
       subject = thread.subject.presence || '(no subject)'
-      thread.message_count > 1 ? "#{thread.persona.name} - #{subject} (#{thread.message_count})" : subject
+      thread.message_count > 1 ? "#{thread.agent.name} - #{subject} (#{thread.message_count})" : subject
     end
 
     # Format the thread's last-activity date for sidebar display.
@@ -53,7 +53,7 @@ module Protege
       thread.latest_message&.text_body.to_s.lines.first.to_s.strip.presence || '—'
     end
 
-    # Render the thread detail header — subject, persona, message count, last
+    # Render the thread detail header — subject, agent, message count, last
     # activity, and thread ID. An optional block renders actions beside the title.
     #
     # @param thread [Protege::EmailThread] the thread whose header to render
@@ -81,14 +81,14 @@ module Protege
       end
     end
 
-    # Render the metadata row — persona, message count, and last activity.
+    # Render the metadata row — agent, message count, and last activity.
     #
     # @param thread [Protege::EmailThread] the thread whose metadata to render
     # @return [ActiveSupport::SafeBuffer] the metadata row markup
     def thread_header_meta(thread)
       tag.div(class: 'mt-1 flex items-center gap-3 text-xs', style: 'color: var(--text-muted)') do
         tag.span do
-          'Persona: '.html_safe + tag.span(thread.persona.name, class: 'font-medium')
+          'Agent: '.html_safe + tag.span(thread.agent.name, class: 'font-medium')
         end +
           tag.span(pluralize(thread.message_count, 'message')) +
           thread_header_last_activity(thread)

data/app/helpers/protege/toolkits_helper.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Protege
+  # View helpers for the toolkit dashboard. The member-tool checklist is built from the uniform extension
+  # manifest; the allow/deny gate is edited as +ToolkitRule+ child rows (see the toolkit-rules partials).
+  # The overview helpers keep computed display values (tool names, proactive/count labels) out of the
+  # templates.
+  module ToolkitsHelper
+    # Every +Toolkit+ for the global sidebar listing, ordered by name.
+    #
+    # @return [ActiveRecord::Relation<Protege::Toolkit>] all toolkits
+    def all_toolkits
+      Toolkit.order(:name)
+    end
+
+    # The tool manifest entries offered as the member-tool checklist — the toolkit equivalent of
+    # +AgentsHelper#agent_tool_options+, built from the uniform extension manifest.
+    #
+    # @return [Array<Protege::Manifest::Entry>] the selectable tools
+    def toolkit_tool_options
+      Manifest.registered(:tool)
+    end
+
+    # The labelled summary rows shown in a toolkit's overview card.
+    #
+    # @param toolkit [Protege::Toolkit] the toolkit
+    # @return [Hash{String=>String}] the info-card rows
+    def toolkit_overview(toolkit)
+      { 'Tools' => toolkit_member_tool_names(toolkit) }
+    end
+
+    # A short "N tools" label for a toolkit listing.
+    #
+    # @param toolkit [Protege::Toolkit] the toolkit
+    # @return [String] the pluralized tool count
+    def toolkit_tool_count_label(toolkit)
+      pluralize(toolkit.member_tool_ids.size, 'tool')
+    end
+
+    # The badge colour for a gate rule — green for allow, red for deny.
+    #
+    # @param rule [Protege::AgentToolkitRule] the rule
+    # @return [Symbol] +:green+ or +:red+
+    def gate_rule_kind_color(rule)
+      rule.allow? ? :green : :red
+    end
+
+    # The toolkits not yet attached to an agent — the options for its attach form.
+    #
+    # @param agent [Protege::Agent] the agent
+    # @return [ActiveRecord::Relation<Protege::Toolkit>] the attachable toolkits, by name
+    def attachable_toolkits(agent)
+      Toolkit.where.not(id: agent.toolkit_ids).order(:name)
+    end
+
+    private
+
+    # The toolkit's member-tool display names, comma-joined, or "None".
+    #
+    # @param toolkit [Protege::Toolkit] the toolkit
+    # @return [String] the joined tool names
+    def toolkit_member_tool_names(toolkit)
+      toolkit.member_tools.map(&:display_name).join(', ').presence || 'None'
+    end
+  end
+end

data/app/hooks/protege/event_logger_hook.rb

@@ -9,14 +9,14 @@ module Protege
   # at boot; each +on+ block receives a typed +Protege::Event+ and runs isolated, so a logging
   # error can never break inference. As a built-in it is always active.
   class EventLoggerHook < Protege::Hook
-    # Log the start of an inference run for a persona.
+    # Log the start of an inference run for an agent.
     on InferenceStartedEvent do |event|
-      log "[#{ts}] #{cid(event)} INF START persona=#{event.persona&.name}"
+      log "[#{ts}] #{cid(event)} INF START agent=#{event.agent&.name}"
     end
 
-    # Log the completion of an inference run for a persona.
+    # Log the completion of an inference run for an agent.
     on InferenceCompletedEvent do |event|
-      log "[#{ts}] #{cid(event)} INF DONE persona=#{event.persona&.name}"
+      log "[#{ts}] #{cid(event)} INF DONE agent=#{event.agent&.name}"
     end
 
     # Log the set of tool calls the model requested in a single turn.
@@ -52,22 +52,22 @@ module Protege
 
     # Log a scheduled responsibility run being enqueued — pending, awaiting a worker (the Loop layer).
     on LoopRunEnqueuedEvent do |event|
-      log "[#{ts}] #{cid(event)} LOOP PENDING #{event.name} persona=#{event.persona_name}"
+      log "[#{ts}] #{cid(event)} LOOP PENDING #{event.name} agent=#{event.agent_name}"
     end
 
     # Log the start of a scheduled responsibility run (the Loop layer).
     on LoopRunStartedEvent do |event|
-      log "[#{ts}] #{cid(event)} LOOP START #{event.name} persona=#{event.persona_name}"
+      log "[#{ts}] #{cid(event)} LOOP START #{event.name} agent=#{event.agent_name}"
     end
 
     # Log the successful completion of a scheduled responsibility run.
     on LoopRunCompletedEvent do |event|
-      log "[#{ts}] #{cid(event)} LOOP DONE #{event.name} persona=#{event.persona_name}"
+      log "[#{ts}] #{cid(event)} LOOP DONE #{event.name} agent=#{event.agent_name}"
     end
 
     # Log a failed scheduled responsibility run with its error class, message, and short backtrace.
     on LoopRunFailedEvent do |event|
-      log "[#{ts}] #{cid(event)} LOOP FAIL #{event.name} persona=#{event.persona_name} " \
+      log "[#{ts}] #{cid(event)} LOOP FAIL #{event.name} agent=#{event.agent_name} " \
           "#{event.error&.class}: #{event.error&.message}\n    #{error_backtrace(event.error)}"
     end
 

data/app/jobs/protege/console_inference_job.rb

@@ -13,7 +13,7 @@ module Protege
   # == Lifecycle
   #
   # 1. Restore the correlation ID for event tracing.
-  # 2. Find the +Message+ and +Persona+ from their IDs.
+  # 2. Find the +Message+ and +Agent+ from their IDs.
   # 3. Transition the message to +processing+.
   # 4. Run the inference loop (+Harness+).
   # 5. Mark the message +processed+ on success, +failed+ on error.
@@ -23,17 +23,17 @@ module Protege
     # Process one pre-persisted console message end to end.
     #
     # @param message_id [Integer] primary key of the pre-persisted +Message+ record
-    # @param persona_id [Integer] primary key of the +Persona+; STI loads the correct subclass
+    # @param agent_id [Integer] primary key of the +Agent+; STI loads the correct subclass
     # @param correlation_id [String] trace token forwarded from the console request
     # @return [void]
     # @raise [StandardError] re-raised after being recorded on the message, to trigger retries
-    def perform(message_id:, persona_id:, correlation_id:)
+    def perform(message_id:, agent_id:, correlation_id:)
       restore_correlation_id(correlation_id)
 
       message = Message.find(message_id)
-      persona = Persona.find(persona_id)
+      agent   = Agent.find(agent_id)
 
-      process(message:, persona:)
+      process(message:, agent:)
     rescue StandardError => e
       message&.mark_failed!(e)
       raise
@@ -44,12 +44,12 @@ module Protege
     # Run the message through the inference loop and record success.
     #
     # @param message [Protege::Message] the message to process
-    # @param persona [Protege::Persona] the persona handling it
+    # @param agent [Protege::Agent] the agent handling it
     # @return [void]
-    def process(message:, persona:)
+    def process(message:, agent:)
       message.start_processing!
 
-      Orchestrator.reply(persona:, message:)
+      Orchestrator.reply(agent:, message:)
 
       message.mark_processed!
     end

data/app/jobs/protege/inference_job.rb

@@ -3,8 +3,8 @@
 module Protege
   # Runs one inbound email through the full Protege inference pipeline (the "I" of LOGI).
   #
-  # Enqueued by +AgentMailbox+ once persona routing succeeds. The job re-hydrates the raw email and
-  # persona from their IDs, ingests a +Message+, runs the Orchestrator's +Harness+, and records the
+  # Enqueued by +AgentMailbox+ once agent routing succeeds. The job re-hydrates the raw email and
+  # agent from their IDs, ingests a +Message+, runs the Orchestrator's +Harness+, and records the
   # outcome on the message. IDs (not objects) are passed across the async boundary so the queue
   # adapter can serialize and safely retry the job across process restarts.
   #
@@ -18,25 +18,25 @@ module Protege
     # Process one inbound email end to end: ingest, run inference, record the result.
     #
     # @param inbound_email_id [Integer] id of the +ActionMailbox::InboundEmail+ to process
-    # @param persona_id [Integer] primary key of the +Protege::Persona+; STI loads the subclass
+    # @param agent_id [Integer] primary key of the +Protege::Agent+; STI loads the subclass
     # @param correlation_id [String] the RFC 2822 Message-ID set by +AgentMailbox+ for tracing
     # @return [void]
     # @raise [StandardError] re-raised after being recorded on the message, to trigger retries
-    def perform(inbound_email_id:, persona_id:, correlation_id:)
+    def perform(inbound_email_id:, agent_id:, correlation_id:)
       restore_correlation_id(correlation_id)
 
-      # Re-hydrate the raw email and the target persona from their IDs.
+      # Re-hydrate the raw email and the target agent from their IDs.
       # IDs are passed rather than objects so Solid Queue can serialize
       # the job and retry it safely across process restarts.
       inbound_email = ActionMailbox::InboundEmail.find(inbound_email_id)
-      persona       = Persona.find(persona_id)
+      agent         = Agent.find(agent_id)
 
       # Parse the raw email, find-or-create the EmailThread, and persist
       # a Protege::Message record with processing_status: :processing.
       # Returns the saved message so we can update its lifecycle below.
-      message = Message.ingest!(inbound_email:, persona:)
+      message = Message.ingest!(inbound_email:, agent:)
 
-      process(message:, persona:)
+      process(message:, agent:)
     rescue StandardError => e
       # Capture the error on the message record before re-raising so the
       # job can be inspected and manually re-queued without losing context.
@@ -49,10 +49,10 @@ module Protege
     # Run the message through the inference loop and record success.
     #
     # @param message [Protege::Message] the message to process
-    # @param persona [Protege::Persona] the persona handling it
+    # @param agent [Protege::Agent] the agent handling it
     # @return [void]
-    def process(message:, persona:)
-      Orchestrator.reply(persona:, message:)
+    def process(message:, agent:)
+      Orchestrator.reply(agent:, message:)
 
       message.mark_processed!
     end

data/app/jobs/protege/responsibility_job.rb

@@ -3,7 +3,7 @@
 module Protege
   # Carries out one scheduled responsibility run — the Loop layer's worker (the "L" of LOGI driving the
   # "I"). Enqueued by +Responsibility#dispatch!+ with the id of a +pending+ +ResponsibilityRun+; it
-  # advances that run to running, runs the persona through +ResponsibilityHarness+, and records the
+  # advances that run to running, runs the agent through +ResponsibilityHarness+, and records the
   # outcome on the run. The run id (not the object) is passed across the async boundary so the queue
   # adapter can serialize the job.
   #
@@ -21,15 +21,15 @@ module Protege
     # @param run_id [Integer] id of the pending +ResponsibilityRun+ to carry out
     # @return [void]
     def perform(run_id:)
-      responsibility_run = ResponsibilityRun.eager_load(responsibility: :persona).find(run_id)
+      responsibility_run = ResponsibilityRun.eager_load(responsibility: :agent).find(run_id)
       # Adopt the trace id minted at dispatch (Responsibility#dispatch!) so the whole run lifecycle
       # shares it; fall back to a fresh one for a run created some other way (e.g. in a test).
       restore_correlation_id(responsibility_run.correlation_id || SecureRandom.uuid)
 
       responsibility = responsibility_run.responsibility
-      persona        = responsibility.persona
+      agent          = responsibility.agent
 
-      process(responsibility_run:, responsibility:, persona:)
+      process(responsibility_run:, responsibility:, agent:)
     rescue StandardError => e
       # Record the failure without re-raising — the cron schedule, not ActiveJob, drives the retry.
       responsibility_run&.mark_failed!(e)
@@ -42,16 +42,16 @@ module Protege
     #
     # @param responsibility_run [Protege::ResponsibilityRun] the run to carry out
     # @param responsibility [Protege::Responsibility] the responsibility to handle
-    # @param persona [Protege::Persona] the persona handling the responsibility
+    # @param agent [Protege::Agent] the agent handling the responsibility
     # @return [void]
-    def process(responsibility_run:, responsibility:, persona:)
+    def process(responsibility_run:, responsibility:, agent:)
       responsibility_run.start!
-      LoopRunStartedEvent.emit(name: responsibility.name, persona_name: persona.name)
+      LoopRunStartedEvent.emit(name: responsibility.name, agent_name: agent.name)
 
-      Orchestrator.run_responsibility(persona:, responsibility:, responsibility_run:)
+      Orchestrator.run_responsibility(agent:, responsibility:, responsibility_run:)
 
       responsibility_run.mark_completed!
-      LoopRunCompletedEvent.emit(name: responsibility.name, persona_name: persona.name)
+      LoopRunCompletedEvent.emit(name: responsibility.name, agent_name: agent.name)
     end
 
     # Emit +loop_run_failed+ for a recorded failure — omitted when the run never loaded (e.g. the
@@ -64,7 +64,7 @@ module Protege
       return unless responsibility_run
 
       responsibility = responsibility_run.responsibility
-      LoopRunFailedEvent.emit(name: responsibility.name, persona_name: responsibility.persona.name, error:)
+      LoopRunFailedEvent.emit(name: responsibility.name, agent_name: responsibility.agent.name, error:)
     end
   end
 end

data/app/mailboxes/protege/agent_mailbox.rb

@@ -4,52 +4,76 @@ module Protege
   # Inbound edge of the Gateway: routes every received email toward the inference pipeline.
   #
   # Action Mailbox delivers parsed mail here, exposing +mail+ and +inbound_email+ as instance
-  # methods and calling {#process} as the single entry point. The mailbox resolves the target
-  # persona by recipient address, then hands off to +Gateway.accept_smtp_message+, which enqueues
-  # +InferenceJob+. The inbound Message-ID is forwarded as the correlation ID so the trace token
-  # survives the async boundary and is restored inside the job.
+  # methods and calling {#process} as the single entry point. The mailbox resolves every agent
+  # addressed in the +To:+ header, then hands each off to +Gateway.accept_smtp_message+, which enqueues
+  # an +InferenceJob+ per agent — so an email to several proteges is handled by each independently. The
+  # inbound Message-ID is forwarded as the correlation ID so the trace token survives the async boundary
+  # and is restored inside the job.
   #
   # == Recursion guard
   #
-  # Outbound mail carries an +X-Protege-Recursion+ budget header. Any inbound email whose budget has
-  # reached zero (or below) is silently dropped, preventing infinite loops when one persona replies
-  # to another. Unroutable mail (no matching persona) is bounced with an unrouted notice instead.
+  # Agent-sent mail carries an +X-Protege-Recursion+ hop-count header (+Gateway::RECURSION_HEADER+):
+  # +1+ on fresh mail, the inbound count plus one on a reply. A human mail client never echoes the
+  # header back, so conversations with people don't accumulate — only an unbroken Protege-to-Protege
+  # reply chain does. Any inbound email whose count has reached the configured limit
+  # (+config.recursion_limit+, default 50) is silently dropped, preventing infinite loops when one agent
+  # replies to another. Unroutable mail (no matching agent) is bounced with an unrouted notice instead.
   #
   # == Access guardrail
   #
-  # Once routed, the sender is checked against the persona's inbound access guardrail
-  # (+Gateway::AccessControl+): the committed global ceiling intersected with the persona's runtime rules. A
-  # sender that fails any layer is bounced with an access-denied notice and never reaches inference.
+  # Each addressed agent is checked against its own inbound access guardrail
+  # (+Gateway::AccessControl+): the committed global ceiling intersected with that agent's runtime rules.
+  # The email is delivered only to the agents that permit the sender; if none do, it is bounced with an
+  # access-denied notice and never reaches inference.
   class AgentMailbox < ActionMailbox::Base
-    # Route the inbound email: drop on exhausted recursion budget, bounce when unrouted or when the
-    # sender fails the access guardrail, else accept.
+    # Route the inbound email: drop on exhausted recursion budget, bounce when no addressed agent
+    # matches, bounce when the sender may reach none of them, bounce on an attachment breach, else accept
+    # it for every addressed agent the sender is permitted to reach (one email to several proteges is
+    # handled by each independently).
     #
     # @return [void]
     def process
       return handle_recursion_limit       if recursion_limit_reached?
-      return bounce_with_unrouted         if persona.nil?
-      return bounce_with_access_denied    unless sender_permitted?
+      return bounce_with_unrouted         if agents.empty?
+      return bounce_with_access_denied    if permitted_agents.empty?
       return bounce_with_attachment_error if attachment_violation
 
-      Gateway.accept_smtp_message(inbound_email:, persona:)
+      permitted_agents.each { |agent| Gateway.accept_smtp_message(inbound_email:, agent:) }
     end
 
     private
 
-    # Report whether the sender may reach the routed persona, per the access guardrail.
+    # Every active agent addressed on the email — the proteges it is for. Scans both +To:+ and +Cc:+
+    # (so a protege reached only as a Cc recipient, e.g. on a reply-all, is still handled), preserving
+    # order and collapsing duplicates. +Agent.lookup+ strips plus-tag subaddresses before matching, and
+    # scanning all recipients (not just the first) is what lets a protege be reached wherever it appears.
     #
-    # @return [Boolean] true when every access layer permits the sender
-    def sender_permitted?
-      Gateway.permits?(persona:, address: mail.from.first)
+    # @return [Array<Protege::Agent>] the matched agents, possibly empty
+    def agents
+      @agents ||= recipient_addresses.filter_map { |address| Protege::Agent.lookup(address) }.uniq
     end
 
-    # Resolve and memoise the persona for the email's primary recipient.
+    # Every address the email was sent to, across +To:+ and +Cc:+.
     #
-    # Uses +Persona.lookup+, which strips plus-tag subaddresses before matching.
+    # @return [Array<String>] the combined recipient addresses
+    def recipient_addresses
+      Array(mail.to) + Array(mail.cc)
+    end
+
+    # The addressed agents the sender is actually permitted to reach, per each one's access guardrail.
+    # An email may be delivered to some proteges and withheld from others on the same +To:+ line.
     #
-    # @return [Protege::Persona, nil] the routed persona, or nil when none matches
-    def persona
-      @persona ||= Protege::Persona.lookup(mail.to.first)
+    # @return [Array<Protege::Agent>] the permitted subset of {agents}
+    def permitted_agents
+      @permitted_agents ||= agents.select { |agent| sender_permitted_for?(agent) }
+    end
+
+    # Report whether the sender may reach one agent, per its access guardrail.
+    #
+    # @param agent [Protege::Agent] the addressed agent
+    # @return [Boolean] true when every access layer permits the sender
+    def sender_permitted_for?(agent)
+      Gateway.permits?(agent:, address: mail.from.first)
     end
 
     # The attachment-limit breach for this email, or nil when its attachments are within the limits.
@@ -64,15 +88,16 @@ module Protege
       end
     end
 
-    # Report whether the +X-Protege-Recursion+ budget has been exhausted.
+    # Report whether the +X-Protege-Recursion+ hop count has reached the configured limit.
     #
-    # @return [Boolean] true when the header is present and its value is zero or below
+    # @return [Boolean] true when the header is present and its count is at or above
+    #   +config.recursion_limit+
     def recursion_limit_reached?
-      header = mail.header['X-Protege-Recursion']
-      header.present? && header.value.to_i <= 0
+      header = mail.header[Gateway::RECURSION_HEADER]
+      header.present? && header.value.to_i >= Protege.configuration.recursion_limit
     end
 
-    # Silently drop the message when the recursion budget is exhausted — no reply, no error.
+    # Silently drop the message when the recursion hop count is exhausted — no reply, no error.
     #
     # @return [void]
     def handle_recursion_limit; end

data/app/mailers/protege/alert_mailer.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Protege
+  # Operational alert mail — emailed to the platform admin when an inference run fails and cannot be
+  # recovered. A sibling of the Gateway's bounce notices ({ApplicationMailer}): both are operational
+  # mail the engine originates itself, not agent conversation (so neither goes through
+  # +Gateway.deliver+, which is agent/thread-scoped). Sent by +Protege::Subscribers::Alerter+ off the
+  # +InferenceFailedEvent+; the recipients and sender come from +config.failure_alerts+.
+  #
+  # The alert is deliberately trigger-agnostic — it carries only the error and the run's correlation id,
+  # not agent/message specifics, so the same notice serves agent-based and non-agent failures
+  # alike (the correlation id is the thread back to the full trace). The body renders from
+  # +alert_mailer/inference_failed.text.erb+ through the engine's +mailer+ text layout — the engine's
+  # first template-rendered mail (the bounce notices use inline bodies).
+  class AlertMailer < ApplicationMailer
+    # Alert the configured recipients that an inference run failed.
+    #
+    # +:to+ and +:from+ are read from +config.failure_alerts+. There is no valid default sender — a
+    # deliverable +:from+ must be an address at a registered +EmailDomain+ (so the self-hosted MTA
+    # DKIM-signs it), so the +Alerter+ only invokes this mailer once +:from+ is configured; it is passed
+    # through verbatim here rather than defaulted.
+    #
+    # @param error_class [String] the error's class name (also names the subject)
+    # @param error_message [String] the error's message
+    # @param correlation_id [String, nil] the run's correlation id, for tracing the failure
+    # @return [Mail::Message] the alert addressed to the configured recipients
+    def inference_failed(error_class:, error_message:, correlation_id:)
+      @error_class    = error_class
+      @error_message  = error_message
+      @correlation_id = correlation_id
+
+      alerts = Protege.configuration.failure_alerts
+
+      mail(
+        from:    alerts[:from],
+        to:      alerts[:to],
+        subject: "[Protege] Inference failed: #{error_class}"
+      )
+    end
+  end
+end

data/app/mailers/protege/application_mailer.rb

@@ -4,17 +4,18 @@ module Protege
   # Base mailer for the Protege engine and home of the Gateway's bounce notices.
   #
   # Sits at the outbound edge of the Gateway. +AgentMailbox+ returns these notices to Action Mailbox's
-  # +bounce_with+ when an inbound email can't be accepted — no matching persona ({#unrouted_bounce}) or
-  # a sender rejected by the access guardrail ({#access_denied_bounce}). The default +from:+ address is
-  # a deliberate placeholder: a host application should override it through
-  # +config.action_mailer.default_options+ in an initializer, or per-mailer, so outbound mail
-  # originates from a domain it actually controls.
+  # +bounce_with+ when an inbound email can't be accepted — no matching agent ({#unrouted_bounce}) or
+  # a sender rejected by the access guardrail ({#access_denied_bounce}). The sender is the host's
+  # app-wide default (+config.action_mailer.default_options+) when one is set, falling back to a
+  # deliberate placeholder — set the app-wide default so outbound mail originates from a domain the
+  # host actually controls.
   class ApplicationMailer < ActionMailer::Base
-    # Placeholder sender; override in the host app so mail comes from a domain you control.
-    default from: 'from@example.com'
+    # Resolved lazily per mail so the host's +config.action_mailer.default_options+ wins even though
+    # this subclass declares its own default (a literal here would shadow the app-wide setting).
+    default from: -> { ActionMailer::Base.default[:from] || 'from@example.com' }
     layout 'mailer'
 
-    # Bounce an inbound email that matched no persona back to its sender.
+    # Bounce an inbound email that matched no agent back to its sender.
     #
     # Returned to +AgentMailbox#bounce_with_unrouted+, which hands it to Action Mailbox's +bounce_with+
     # for delivery. The body is built inline (no template/layout) so a bounce can never fail to render.

data/app/models/concerns/protege/broadcastable_agent.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Protege
+  # Drives real-time Turbo Stream broadcasting for +Agent+ records — keeping the Agents sidebar
+  # live: the row is appended on create, replaced on update, and removed on destroy. First-page viewers
+  # subscribe via +turbo_stream_from "protege:agents"+ (see +SidebarHelper#sidebar_stream+).
+  module BroadcastableAgent
+    extend ActiveSupport::Concern
+
+    # Turbo Stream channel for all +Agent+ records.
+    # @return [String]
+    STREAM = 'protege:agents'
+
+    included do
+      after_create_commit  :broadcast_agent_created
+      after_update_commit  :broadcast_agent_updated
+      after_destroy_commit :broadcast_agent_removed
+    end
+
+    private
+
+    # Append this agent's row to the Agents sidebar on creation.
+    #
+    # @return [void]
+    def broadcast_agent_created
+      broadcast_append_to STREAM,
+                          target:  'agents_list',
+                          partial: 'protege/agents/agent_sidebar_item',
+                          locals:  { agent: self }
+    end
+
+    # Replace this agent's sidebar row in place when its attributes change.
+    #
+    # @return [void]
+    def broadcast_agent_updated
+      broadcast_replace_to STREAM,
+                           target:  ActionView::RecordIdentifier.dom_id(self),
+                           partial: 'protege/agents/agent_sidebar_item',
+                           locals:  { agent: self }
+    end
+
+    # Remove this agent's sidebar row on destruction.
+    #
+    # @return [void]
+    def broadcast_agent_removed
+      broadcast_remove_to STREAM,
+                          target: ActionView::RecordIdentifier.dom_id(self)
+    end
+  end
+end

data/app/models/concerns/protege/broadcastable_toolkit.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Protege
+  # Drives real-time Turbo Stream broadcasting for +Toolkit+ records — keeping the (global) Toolkits
+  # sidebar live: the row is appended on create, replaced on update, and removed on destroy. First-page
+  # viewers subscribe via +turbo_stream_from "protege:toolkits"+ (see +SidebarHelper#sidebar_stream+).
+  module BroadcastableToolkit
+    extend ActiveSupport::Concern
+
+    # Turbo Stream channel for all +Toolkit+ records.
+    # @return [String]
+    STREAM = 'protege:toolkits'
+
+    included do
+      after_create_commit  :broadcast_toolkit_created
+      after_update_commit  :broadcast_toolkit_updated
+      after_destroy_commit :broadcast_toolkit_removed
+    end
+
+    private
+
+    # Append this toolkit's row to the Toolkits sidebar on creation.
+    #
+    # @return [void]
+    def broadcast_toolkit_created
+      broadcast_append_to STREAM,
+                          target:  'toolkits_list',
+                          partial: 'protege/toolkits/toolkit_sidebar_item',
+                          locals:  { toolkit: self }
+    end
+
+    # Replace this toolkit's sidebar row in place when its attributes change.
+    #
+    # @return [void]
+    def broadcast_toolkit_updated
+      broadcast_replace_to STREAM,
+                           target:  ActionView::RecordIdentifier.dom_id(self),
+                           partial: 'protege/toolkits/toolkit_sidebar_item',
+                           locals:  { toolkit: self }
+    end
+
+    # Remove this toolkit's sidebar row on destroy.
+    #
+    # @return [void]
+    def broadcast_toolkit_removed
+      broadcast_remove_to STREAM, target: ActionView::RecordIdentifier.dom_id(self)
+    end
+  end
+end