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

data/lib/protege/orchestrator/harness.rb

@@ -18,12 +18,12 @@ module Protege
     #
     # +Protege::Current.correlation_id+ must be set before calling so that emitted events carry the id
     # automatically. Collaborates with +Inference+ (request building and generation), +Tool+ (dispatch
-    # and registry), the persona's +ResolverChain+ (context assembly), and the +Protege::*Event+ classes
+    # and registry), the agent's +ResolverChain+ (context assembly), and the +Protege::*Event+ classes
     # (observability).
     #
     # @example
-    #   ReplyHarness.run(persona:, message:)
-    #   ResponsibilityHarness.run(persona:, responsibility:)
+    #   ReplyHarness.run(agent:, message:)
+    #   ResponsibilityHarness.run(agent:, responsibility:)
     #
     # == Lifecycle
     #
@@ -45,10 +45,10 @@ module Protege
         end
       end
 
-      # @param persona [Protege::Persona] the persona handling the run
+      # @param agent [Protege::Agent] the agent handling the run
       # @return [void]
-      def initialize(persona:)
-        @persona = persona
+      def initialize(agent:)
+        @agent = agent
       end
 
       # Entry point. Emit lifecycle events around the tool loop.
@@ -61,22 +61,22 @@ module Protege
       # @return [Object] the final +Provider::Response+
       # @raise [StandardError] re-raised after +inference_failed+ is emitted
       def run
-        InferenceStartedEvent.emit(persona:, message:)
+        InferenceStartedEvent.emit(agent:, message:)
 
         result = run_tool_loop
 
-        InferenceCompletedEvent.emit(persona:, message:, result:)
+        InferenceCompletedEvent.emit(agent:, message:, result:)
 
         result
       rescue StandardError => e
-        InferenceFailedEvent.emit(persona:, message:, error: e)
+        InferenceFailedEvent.emit(agent:, message:, error: e)
         raise
       end
 
       private
 
-      # @return [Protege::Persona] the persona handling the run
-      attr_reader :persona
+      # @return [Protege::Agent] the agent handling the run
+      attr_reader :agent
 
       # ── Kind-specific hooks (subclasses override) ─────────────────────────────
 
@@ -134,11 +134,11 @@ module Protege
           return final if final.tool_calls.blank?
 
           if turn >= (max_loop_iterations - 1)
-            InferenceMaxTurnsReachedEvent.emit(persona:, turn:, tool_calls: final.tool_calls)
+            InferenceMaxTurnsReachedEvent.emit(agent:, turn:, tool_calls: final.tool_calls)
             break
           end
 
-          ToolCallsReceivedEvent.emit(persona:, tool_calls: final.tool_calls)
+          ToolCallsReceivedEvent.emit(agent:, tool_calls: final.tool_calls)
 
           tool_results = final.tool_calls.map { invoke_tool(_1) }
           record_tool_round(turn:, response: final, tool_results:)
@@ -175,7 +175,7 @@ module Protege
       # Emit the per-turn trace event: the wire request (+Request#to_wire+ — the very serialization the
       # API call uses, so the snapshot is exact), the response, and the inference settings that shaped it
       # (+model+ + +settings+, pulled from the provider the harness resolves — not global config — so a
-      # future persona-level override is captured). Best-effort: any failure is logged and swallowed, so
+      # future agent-level override is captured). Best-effort: any failure is logged and swallowed, so
       # building or publishing the event can never abort a run whose side effects may already have run.
       #
       # @param turn [Integer] this generation's turn index
@@ -205,7 +205,7 @@ module Protege
       def run_generation(request)
         if streaming?
           Inference.generate_stream(request) do |chunk|
-            InferenceChunkEvent.emit(persona:, thread: message.email_thread, chunk:)
+            InferenceChunkEvent.emit(agent:, thread: message.email_thread, chunk:)
           end
         else
           Inference.generate(request)
@@ -254,14 +254,14 @@ module Protege
       # @param tool_call [Object] the tool call to dispatch
       # @return [Protege::ToolResult] the call paired with its outcome
       def invoke_tool(tool_call)
-        ToolCallStartedEvent.emit(persona:, tool_call:)
+        ToolCallStartedEvent.emit(agent:, tool_call:)
 
         tool_result = ToolMixin.invoke(tool_call, context:)
 
         if tool_result.result.success?
-          ToolCallCompletedEvent.emit(persona:, tool_call:, result: tool_result.result)
+          ToolCallCompletedEvent.emit(agent:, tool_call:, result: tool_result.result)
         else
-          ToolCallFailedEvent.emit(persona:, tool_call:, error: tool_result.result.error)
+          ToolCallFailedEvent.emit(agent:, tool_call:, error: tool_result.result.error)
         end
 
         tool_result
@@ -284,19 +284,21 @@ module Protege
         end
       end
 
-      # Assemble the first +Provider::Request+ from the opening user turn, the persona's effective
+      # Assemble the first +Provider::Request+ from the opening user turn, the agent's effective
       # (scoped) tool set, inference config, and any context messages contributed by resolvers.
       #
-      # The catalogue is +persona.available_tools+ rather than the whole registry, so a persona's
-      # code-declared grant and the operator's +disabled_tool_ids+ override bound what the model is
-      # offered — on both the reply and the scheduled path, since both inherit this base method. Later
-      # turns re-use +previous.tools+ (see +Inference.extend_request+), so the scope holds for the run.
+      # The catalogue is +agent.available_tools_for(context:)+ rather than the whole registry, so the
+      # agent's attached toolkits — and each attachment's sender gate — bound what the model is offered,
+      # on both the reply and the scheduled path, since both inherit this base method (the context's
+      # sender, or its absence on a scheduled run, drives toolkit gating). Later turns re-use
+      # +previous.tools+ (see +Inference.extend_request+), and a reply run has one fixed sender, so the
+      # scope holds for the run.
       #
       # @return [Object] the initial provider request
       def build_initial_request
         Inference.build_request(
           user_content:,
-          tools:            persona.available_tools,
+          tools:            agent.available_tools_for(context:),
           context_messages: resolvers.run(context)
         )
       end

data/lib/protege/orchestrator/reply_context.rb

@@ -9,12 +9,12 @@ module Protege
       # @return [Object] the inbound message being processed
       attr_reader :message
 
-      # @param persona [Protege::Persona] the persona handling the run
+      # @param agent [Protege::Agent] the agent handling the run
       # @param message [Object] the inbound message being processed
       # @return [void]
-      def initialize(persona:, message:)
+      def initialize(agent:, message:)
         @message = message
-        super(persona:)
+        super(agent:)
       end
     end
   end

data/lib/protege/orchestrator/reply_harness.rb

@@ -2,16 +2,16 @@
 
 module Protege
   module Orchestrator
-    # The reactive run — answering one inbound email. Runs the receiving persona's +message_resolvers+
+    # The reactive run — answering one inbound email. Runs the receiving agent's +message_resolvers+
     # chain, opens the turn with the message body (plus any viewable attachments as vision parts), and
     # streams tokens when the message came from the console. The +Harness+ base owns the tool loop;
     # this subclass only supplies the reply-specific hooks.
     class ReplyHarness < Harness
-      # @param persona [Protege::Persona] the persona that received the message
+      # @param agent [Protege::Agent] the agent that received the message
       # @param message [Object] the inbound message to respond to
       # @return [void]
-      def initialize(persona:, message:)
-        super(persona:)
+      def initialize(agent:, message:)
+        super(agent:)
         @message = message
       end
 
@@ -20,9 +20,9 @@ module Protege
       # @return [Object] the inbound message being answered (overrides the base nil)
       attr_reader :message
 
-      # @return [Orchestrator::ResolverChain] the persona's reply chain
+      # @return [Orchestrator::ResolverChain] the agent's reply chain
       def resolvers
-        persona.message_resolvers
+        agent.message_resolvers
       end
 
       # @return [String, Array<Object>] the message body, or body-plus-attachment parts
@@ -32,7 +32,7 @@ module Protege
 
       # @return [Orchestrator::ReplyContext] the shared per-run context carrying the message
       def context
-        @context ||= ReplyContext.new(persona:, message:)
+        @context ||= ReplyContext.new(agent:, message:)
       end
 
       # Persist this tool-calling round as +ToolUse+ rows owned by the inbound message, so a later turn's
@@ -47,7 +47,7 @@ module Protege
       def persist_tool_round(turn:, response:, tool_results:)
         Protege::ToolUse.record_round(
           source:       message,
-          persona:,
+          agent:,
           run_id:       Protege::Current.correlation_id,
           turn_index:   turn,
           tool_calls:   response.tool_calls,

data/lib/protege/orchestrator/resolver_chain.rb

@@ -2,8 +2,8 @@
 
 module Protege
   module Orchestrator
-    # Ordered list of resolver classes that build inference context for one persona. Configured at
-    # persona declaration time (via +Persona::Config#resolvers+) and run once per
+    # Ordered list of resolver classes that build inference context for one agent. Configured at
+    # agent declaration time (via +Agent::Config#resolvers+) and run once per
     # +Harness#build_initial_request+ call.
     #
     # Each resolver runs independently and returns +Array<ModelMessage>+ or +nil+. The chain
@@ -18,7 +18,7 @@ module Protege
     #
     # @example
     #   chain = ResolverChain.new
-    #   chain.use Protege::LoadFileResolver, 'app/personas/agent/PERSONA.md'
+    #   chain.use Protege::LoadFileResolver, 'app/agents/executive/AGENT.md'
     #   chain.use(Protege::LoadRecordResolver) { |ctx| Account.find_by(email: ctx.message.from_address) }
     #   chain.use Protege::ThreadHistoryResolver
     #

data/lib/protege/orchestrator/responsibility_context.rb

@@ -4,18 +4,18 @@ module Protege
   module Orchestrator
     # Context for a proactive run — one driven by a scheduled +Responsibility+ (the Loop layer). Adds
     # the +responsibility+ to the shared +Context+ surface so tools and resolvers can reach the duty
-    # being carried out (its prompt, schedule, owning persona). The +#message+ accessor inherited from
+    # being carried out (its prompt, schedule, owning agent). The +#message+ accessor inherited from
     # +Context+ stays nil, so reply-only tools (e.g. +send_email+ in reply mode) degrade gracefully.
     class ResponsibilityContext < Context
       # @return [Protege::Responsibility] the responsibility being fulfilled
       attr_reader :responsibility
 
-      # @param persona [Protege::Persona] the persona carrying out the responsibility
+      # @param agent [Protege::Agent] the agent carrying out the responsibility
       # @param responsibility [Protege::Responsibility] the scheduled duty being run
       # @return [void]
-      def initialize(persona:, responsibility:)
+      def initialize(agent:, responsibility:)
         @responsibility = responsibility
-        super(persona:)
+        super(agent:)
       end
     end
   end

data/lib/protege/orchestrator/responsibility_harness.rb

@@ -3,18 +3,18 @@
 module Protege
   module Orchestrator
     # The proactive run — carrying out one scheduled +Responsibility+ (the Loop layer). Runs the
-    # persona's +responsibility_resolvers+ chain, which assembles the *entire* message list — including
+    # agent's +responsibility_resolvers+ chain, which assembles the *entire* message list — including
     # the responsibility's instructions (e.g. via +LoadTextResolver(role: :user) { ctx.responsibility.instructions }+).
     # The harness injects no user turn of its own (it inherits the base +user_content+ default of nil):
     # context assembly is the resolver chain's job. There is no inbound message and no streaming. The
     # +Harness+ base owns the tool loop; this subclass only supplies the responsibility-specific hooks.
     class ResponsibilityHarness < Harness
-      # @param persona [Protege::Persona] the persona carrying out the responsibility
+      # @param agent [Protege::Agent] the agent carrying out the responsibility
       # @param responsibility [Protege::Responsibility] the scheduled duty to run
       # @param responsibility_run [Protege::ResponsibilityRun] the run record this execution belongs to
       # @return [void]
-      def initialize(persona:, responsibility:, responsibility_run:)
-        super(persona:)
+      def initialize(agent:, responsibility:, responsibility_run:)
+        super(agent:)
         @responsibility     = responsibility
         @responsibility_run = responsibility_run
       end
@@ -27,14 +27,14 @@ module Protege
       # @return [Protege::ResponsibilityRun] the run record this execution belongs to
       attr_reader :responsibility_run
 
-      # @return [Orchestrator::ResolverChain] the persona's scheduled-run chain
+      # @return [Orchestrator::ResolverChain] the agent's scheduled-run chain
       def resolvers
-        persona.responsibility_resolvers
+        agent.responsibility_resolvers
       end
 
       # @return [Orchestrator::ResponsibilityContext] the shared per-run context carrying the responsibility
       def context
-        @context ||= ResponsibilityContext.new(persona:, responsibility:)
+        @context ||= ResponsibilityContext.new(agent:, responsibility:)
       end
 
       # Persist this tool-calling round as +ToolUse+ rows owned by the +ResponsibilityRun+ — an audit
@@ -48,7 +48,7 @@ module Protege
       def persist_tool_round(turn:, response:, tool_results:)
         Protege::ToolUse.record_round(
           source:       responsibility_run,
-          persona:,
+          agent:,
           run_id:       Protege::Current.correlation_id,
           turn_index:   turn,
           tool_calls:   response.tool_calls,

data/lib/protege/orchestrator.rb

@@ -8,7 +8,7 @@ module Protege
   # The +Harness+ is this layer's primary construct: given one inbound message, it builds a provider
   # request, runs the multi-turn tool loop, and produces a final response. Supporting constructs in
   # this namespace include the +Context+ value objects passed to extensions, the +Tool+ and
-  # +Resolver+ contracts, and the +ResolverChain+ that assembles inference context per persona.
+  # +Resolver+ contracts, and the +ResolverChain+ that assembles inference context per agent.
   #
   # Module methods here are the cross-namespace entry points. Callers (jobs, the +Extension+ tool mixin)
   # use these rather than reaching into +Harness+ subclasses or +ToolResult+/+Error+ directly.
@@ -17,21 +17,21 @@ module Protege
 
     # Run a reactive reply generation for an inbound message.
     #
-    # @param persona [Protege::Persona] the receiving persona
+    # @param agent [Protege::Agent] the receiving agent
     # @param message [Protege::Message] the inbound message to answer
     # @return [Object] the harness result
-    def reply(persona:, message:)
-      ReplyHarness.run(persona:, message:)
+    def reply(agent:, message:)
+      ReplyHarness.run(agent:, message:)
     end
 
     # Run a proactive generation for a scheduled responsibility.
     #
-    # @param persona [Protege::Persona] the persona carrying out the duty
+    # @param agent [Protege::Agent] the agent carrying out the duty
     # @param responsibility [Protege::Responsibility] the scheduled duty
     # @param responsibility_run [Protege::ResponsibilityRun] the run record being executed
     # @return [Object] the harness result
-    def run_responsibility(persona:, responsibility:, responsibility_run:)
-      ResponsibilityHarness.run(persona:, responsibility:, responsibility_run:)
+    def run_responsibility(agent:, responsibility:, responsibility_run:)
+      ResponsibilityHarness.run(agent:, responsibility:, responsibility_run:)
     end
   end
 end

data/lib/protege/subscribers/alerter.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Protege
+  module Subscribers
+    # The operational-alert subscriber — emails the platform admin when an inference run fails. A peer of
+    # +Subscribers::Tracing+ / +HookDispatcher+ / +IntrospectionBroadcaster+, installed once at boot.
+    # Subscribes to +InferenceFailedEvent+ and, when a host has opted in via +config.failure_alerts+,
+    # sends a +Protege::AlertMailer+ notice carrying the error and the run's correlation id.
+    #
+    # Opt-in and best-effort by design:
+    #
+    # * Off until +config.failure_alerts[:to]+ is set, and it will not send without a +:from+ — there is
+    #   no deliverable default sender (a real +:from+ must be a DKIM-signable address at a registered
+    #   +EmailDomain+), so a +:to+ with no +:from+ is a misconfiguration that logs and sends nothing.
+    # * +InferenceFailedEvent+ fires once per failed *run*, and the job layer retries a transient failure
+    #   up to three times — so a single failing message emits the event several times, all sharing one
+    #   correlation id. Delivery is deduped on that id so the retry storm collapses to one alert, and a
+    #   global per-window cap guards against a systemic outage flooding the admin.
+    # * The event is emitted from inside the Harness's rescue, right before it re-raises, and
+    #   +ActiveSupport::Notifications+ propagates subscriber exceptions — so this module rescues
+    #   everything internally. An alert failure must never mask the inference error that triggered it.
+    module Alerter
+      extend self
+
+      # How long a run's correlation id suppresses duplicate alerts (covers the retry backoff window).
+      DEDUP_TTL = 1.hour
+
+      # Cache key + ceiling + window for the systemic-outage flood guard.
+      GLOBAL_KEY = 'protege:alert:global'
+      GLOBAL_CAP = 10
+      GLOBAL_TTL = 1.hour
+
+      # Live subscription handles, retained so {reset!} can detach them.
+      @handles = []
+
+      # Subscribe the alerter to inference failures — the subscriber's +install!+ contract. Idempotent;
+      # called once at boot from the engine's +after_initialize+.
+      #
+      # @return [void]
+      def install!
+        return unless @handles.empty?
+
+        @handles = [InferenceFailedEvent.subscribe { |event| alert(event) }]
+      end
+
+      # Detach every subscription — the subscriber's +reset!+ contract, for boot re-wiring and tests.
+      #
+      # @return [void]
+      def reset!
+        @handles.each { |handle| ActiveSupport::Notifications.unsubscribe(handle) }
+        @handles = []
+      end
+
+      private
+
+      # Email the configured recipients about one failed run. Best-effort: gated on opt-in config,
+      # deduped, capped, and wrapped so any failure is logged and swallowed.
+      #
+      # @param event [Protege::InferenceFailedEvent] the failure event
+      # @return [void]
+      def alert(event)
+        return unless enabled?
+        return unless first_failure?(event)
+        return unless under_global_cap?
+
+        Protege::AlertMailer.inference_failed(
+          error_class:    event.error.class.name,
+          error_message:  event.error.message,
+          correlation_id: event.correlation_id
+        ).deliver_now
+      rescue StandardError => e
+        logger.error("[Protege] alert delivery failed: #{e.class}: #{e.message}")
+      end
+
+      # Whether alerting is configured to send. Requires recipients and a sender: without a deliverable
+      # +:from+ there is nothing safe to send from, so a +:to+ alone is a logged misconfiguration.
+      #
+      # @return [Boolean]
+      def enabled?
+        alerts = Protege.configuration.failure_alerts
+        return false if Array(alerts[:to]).reject(&:blank?).empty?
+
+        if alerts[:from].blank?
+          logger.warn('[Protege] failure_alerts :to is set but :from is missing; not sending ' \
+                      '(a deliverable :from at a registered EmailDomain is required)')
+          return false
+        end
+
+        true
+      end
+
+      # Claim the first alert for this run's correlation id, so the job's retry storm sends only one.
+      # Returns true only for the first failure seen within {DEDUP_TTL}.
+      #
+      # @param event [Protege::InferenceFailedEvent] the failure event
+      # @return [Boolean]
+      def first_failure?(event)
+        Rails.cache.write("protege:alert:#{event.correlation_id}", true, expires_in: DEDUP_TTL, unless_exist: true)
+      end
+
+      # Whether this alert is within the global per-window cap. A best-effort read-modify-write (not
+      # atomic) — adequate as a flood guard, and store-agnostic (no reliance on +increment+ semantics).
+      #
+      # @return [Boolean]
+      def under_global_cap?
+        count = (Rails.cache.read(GLOBAL_KEY) || 0) + 1
+        Rails.cache.write(GLOBAL_KEY, count, expires_in: GLOBAL_TTL)
+        count <= GLOBAL_CAP
+      end
+
+      # @return [Logger] the engine logger
+      def logger
+        Protege.configuration.logger
+      end
+    end
+  end
+end

data/lib/protege/subscribers/tracing.rb

@@ -14,7 +14,7 @@ module Protege
     #
     # A trace records only what affects training: the wire +request+ and +response+ (each already
     # serialized by the value object's own +#to_wire+, the same bytes the API exchange uses) and the
-    # inference settings (+model+ + +settings+). No persona/provider identity is stored, and this module
+    # inference settings (+model+ + +settings+). No agent/provider identity is stored, and this module
     # does no serialization of its own — it just persists what the event carries.
     module Tracing
       extend self

data/lib/protege/version.rb

@@ -2,5 +2,5 @@
 
 module Protege
   # Current gem version, following Semantic Versioning.
-  VERSION = '0.1.0.alpha.2'
+  VERSION = '0.1.0.alpha.7'
 end

data/lib/protege.rb

@@ -9,12 +9,12 @@ require 'protege/engine'
 # Rails application into an agentic workspace.
 #
 # Protege is structured around the LOGI pipeline:
-# - **L**oop — scheduled responsibilities that drive personas on a cron tick.
+# - **L**oop — scheduled responsibilities that drive agents on a cron tick.
 # - **O**rchestrator — the +Harness+ multi-turn tool loop that runs inference and dispatches tools.
 # - **G**ateway — Action Mailbox inbound delivery and SMTP outbound delivery.
 # - **I**nference — provider adapters that talk to model APIs.
 #
-# Email is the channel, the host Rails app is the workspace, and personas, tools, providers,
+# Email is the channel, the host Rails app is the workspace, and agents, tools, providers,
 # resolvers, and hooks all participate as extensions. Requiring this file loads only the engine
 # entry points; runtime constructs are resolved through Rails autoloading once the engine boots.
 #

data/lib/tasks/protege_tasks.rake

@@ -1,6 +1,18 @@
 # frozen_string_literal: true
 
 namespace :protege do
+  namespace :toolkits do
+    desc 'Ensure the system toolkits (All Tools / Default Tools) exist and refresh All Tools to the ' \
+         'full tool registry. Idempotent — run on each deploy (e.g. after db:migrate).'
+    task sync: :environment do
+      # Rake tasks don't eager-load by default, so the tool manifest would be incomplete; force it so
+      # All Tools captures every registered tool.
+      Rails.application.eager_load!
+      Protege::SystemToolkits.sync!
+      puts "Synced system toolkits — All Tools has #{Protege::Toolkit.all_tools&.member_tool_ids&.size} tools."
+    end
+  end
+
   namespace :css do
     desc "Build the Protege engine's compiled Tailwind CSS. " \
          'Run this after changing engine views. Requires tailwindcss-rails in the host app.'