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

data/app/models/protege/message.rb

@@ -7,7 +7,7 @@ module Protege
   # UI, the inbox, and the +ThreadHistoryResolver+ resolver all read from this model. The underlying
   # +ActionMailbox::InboundEmail+ is retained only as a raw delivery-pipeline artifact; application
   # logic never queries it directly. Every message belongs to exactly one +EmailThread+ and one
-  # +Persona+, and inbound messages link back to the +InboundEmail+ they were ingested from.
+  # +Agent+, and inbound messages link back to the +InboundEmail+ they were ingested from.
   #
   # == Lifecycle (inbound)
   #
@@ -15,7 +15,7 @@ module Protege
   #   processing  → InferenceJob is running
   #   processed   → InferenceJob completed successfully
   #   failed      → InferenceJob raised; error captured in +last_processing_error+
-  #   bounced     → no matching persona; handled in AgentMailbox before a job is queued
+  #   bounced     → no matching agent; handled in AgentMailbox before a job is queued
   #
   # == Lifecycle (outbound)
   #
@@ -28,7 +28,7 @@ module Protege
 
     # ── Associations ────────────────────────────────────────────────────────
 
-    belongs_to :persona,       class_name: 'Protege::Persona'
+    belongs_to :agent, class_name: 'Protege::Agent'
     belongs_to :email_thread,  class_name: 'Protege::EmailThread', inverse_of: :messages
     # Optional: only inbound messages originate from an ActionMailbox record.
     belongs_to :inbound_email, class_name: 'ActionMailbox::InboundEmail', optional: true
@@ -64,8 +64,9 @@ module Protege
 
     # ── Validations ─────────────────────────────────────────────────────────
 
-    # Message-ID is the dedup key; uniqueness keeps retries idempotent.
-    validates :message_id,   presence: true, uniqueness: true
+    # Message-ID is the dedup key; uniqueness is per agent so one email to several proteges records a
+    # message for each, while a single agent's retries stay idempotent.
+    validates :message_id,   presence: true, uniqueness: { scope: :agent_id }
     validates :direction,    presence: true
     validates :from_address, presence: true
     validates :sent_at,      presence: true
@@ -86,19 +87,19 @@ module Protege
       # Ingest an +ActionMailbox::InboundEmail+ into a persisted, processing +Message+.
       #
       # Finds or creates the owning +EmailThread+, copies all mail-derived attributes onto the
-      # record, and transitions it to +processing+. Keyed on +inbound_email_id+, so calling it
-      # again for the same inbound email updates the existing record rather than duplicating it —
-      # making it safe to invoke on job retry.
+      # record, and transitions it to +processing+. Keyed on +inbound_email_id+ *and* +agent+, so a
+      # retry for the same agent updates its existing record, while a different agent addressed by the
+      # same email gets its own — one inbound email maps to one message per handling agent.
       #
       # @param inbound_email [ActionMailbox::InboundEmail] the raw received email
-      # @param persona [Protege::Persona] the persona the email routed to
+      # @param agent [Protege::Agent] the agent the email routed to
       # @return [Protege::Message] the saved message in the +processing+ state
-      def ingest!(inbound_email:, persona:)
+      def ingest!(inbound_email:, agent:)
         mail   = inbound_email.mail
-        thread = EmailThread.find_or_create_for(mail:, persona:)
+        thread = EmailThread.find_or_create_for(mail:, agent:)
 
-        find_or_initialize_by(inbound_email_id: inbound_email.id).tap do |record|
-          record.assign_from_mail(mail:, thread:, persona:, inbound_email:)
+        find_or_initialize_by(inbound_email_id: inbound_email.id, agent:).tap do |record|
+          record.assign_from_mail(mail:, thread:, agent:, inbound_email:)
           record.start_processing!
         end
       end
@@ -111,14 +112,14 @@ module Protege
       # @param mail [Mail::Message] the parsed email to copy attributes from
       # @param direction [Symbol, String] +:inbound+ or +:outbound+
       # @param thread [Protege::EmailThread] the owning thread
-      # @param persona [Protege::Persona] the persona the message belongs to
+      # @param agent [Protege::Agent] the agent the message belongs to
       # @param inbound_email [ActionMailbox::InboundEmail, nil] the source record, if any
       # @param attach_from_mail [Boolean] rebuild attachments from the mail's parts (true for inbound,
       #   whose files arrive as bytes); pass false for outbound, where the caller attaches known blobs.
       # @return [Protege::Message] an unsaved message with attributes assigned
-      def build_from_mail(mail:, direction:, thread:, persona:, inbound_email: nil, attach_from_mail: true)
+      def build_from_mail(mail:, direction:, thread:, agent:, inbound_email: nil, attach_from_mail: true)
         new.tap do |record|
-          record.assign_from_mail(mail:, thread:, persona:, inbound_email:, attach_from_mail:)
+          record.assign_from_mail(mail:, thread:, agent:, inbound_email:, attach_from_mail:)
           record.direction = direction
         end
       end
@@ -237,20 +238,20 @@ module Protege
 
     # Copy every RFC 2822-derived attribute from a +Mail::Message+ onto this record.
     #
-    # Shared by both {.ingest!} and {.build_from_mail}. Sets the thread/persona associations and
+    # Shared by both {.ingest!} and {.build_from_mail}. Sets the thread/agent associations and
     # then delegates the header, body, and threading field groups to private helpers so the work
     # stays within Active Record's metrics budget. Does not save.
     #
     # @param mail [Mail::Message] the parsed email to read attributes from
     # @param thread [Protege::EmailThread] the owning thread
-    # @param persona [Protege::Persona] the persona the message belongs to
+    # @param agent [Protege::Agent] the agent the message belongs to
     # @param inbound_email [ActionMailbox::InboundEmail, nil] the source record, if any
     # @param attach_from_mail [Boolean] rebuild attachments from the mail's MIME parts; true for inbound
     #   (files arrive as bytes), false for outbound (the caller attaches the known blobs by reference).
     # @return [void]
-    def assign_from_mail(mail:, thread:, persona:, inbound_email: nil, attach_from_mail: true)
+    def assign_from_mail(mail:, thread:, agent:, inbound_email: nil, attach_from_mail: true)
       self.email_thread  = thread
-      self.persona       = persona
+      self.agent         = agent
       self.inbound_email = inbound_email
 
       assign_envelope_from(mail)
@@ -299,6 +300,21 @@ module Protege
       )
     end
 
+    # How many agent hops this message has already taken, read from the linked raw inbound email's
+    # +X-Protege-Recursion+ header. Zero for human mail (mail clients never echo the header back) and
+    # when the raw email is gone (Action Mailbox incinerates it eventually) — either way the chain
+    # resets, which is the intended behavior. A reply to this message stamps this count plus one (see
+    # +Gateway::RECURSION_HEADER+).
+    #
+    # @return [Integer] the inbound hop count, or 0 when untracked
+    def recursion_hops
+      raw = inbound_email&.mail
+      return 0 unless raw
+
+      field = raw.header[Gateway::RECURSION_HEADER]
+      field ? field.value.to_i : 0
+    end
+
     private
 
     # Assemble {#to_llm_text} from the standard header, the readable body (when present), and an optional

data/app/models/protege/responsibility.rb

@@ -1,29 +1,29 @@
 # frozen_string_literal: true
 
 module Protege
-  # A persona's standing, cron-scheduled duty — the record behind the Loop layer (the "L" of LOGI).
+  # An agent's standing, cron-scheduled duty — the record behind the Loop layer (the "L" of LOGI).
   #
   # Where an inbound email drives the reactive path, a responsibility drives the *proactive* one: on
-  # its +schedule+ (a 5-field cron string) the Loop scheduler runs the owning persona's
+  # its +schedule+ (a 5-field cron string) the Loop scheduler runs the owning agent's
   # +responsibility_resolvers+ chain, seeded with this responsibility's +instructions+ as the opening user
-  # turn. The persona decides what to do from there (typically sending mail via +send_email+).
+  # turn. The agent decides what to do from there (typically sending mail via +send_email+).
   #
-  # Responsibilities are lean, dashboard-managed records — not a developer subclass; the per-persona
-  # resolver chain lives on the +Persona+, so a responsibility is just "which persona, what task, how
+  # Responsibilities are lean, dashboard-managed records — not a developer subclass; the per-agent
+  # resolver chain lives on the +Agent+, so a responsibility is just "which agent, what task, how
   # often." Each execution is tracked by a +ResponsibilityRun+.
   class Responsibility < ApplicationRecord
     self.table_name = 'protege_responsibilities'
 
     # ── Concerns ──────────────────────────────────────────────────────────────
 
-    # Keep the persona's Responsibilities sidebar live (append/replace/remove).
+    # Keep the agent's Responsibilities sidebar live (append/replace/remove).
     include BroadcastableResponsibility
 
     # ── Associations ──────────────────────────────────────────────────────────
 
-    # The persona that carries out this duty; its +responsibility_resolvers+ chain assembles context
+    # The agent that carries out this duty; its +responsibility_resolvers+ chain assembles context
     # and its identity is the enforced +From+ on any mail the run sends.
-    belongs_to :persona, class_name: 'Protege::Persona'
+    belongs_to :agent, class_name: 'Protege::Agent'
 
     # Every execution of this responsibility, newest interesting for the dashboard; destroyed with it.
     has_many :responsibility_runs,
@@ -48,14 +48,14 @@ module Protege
     # Only responsibilities currently enabled to fire.
     scope :active, -> { where(active: true) }
 
-    # Only responsibilities whose persona is active (not archived) — archiving a persona stops its
+    # Only responsibilities whose agent is active (not archived) — archiving an agent stops its
     # scheduled runs. The scheduler intersects this with {.active}.
-    scope :with_active_persona, -> { joins(:persona).merge(Protege::Persona.active) }
+    scope :with_active_agent, -> { joins(:agent).merge(Protege::Agent.active) }
 
     # ── Instance methods ────────────────────────────────────────────────────
 
     # Whether this responsibility should fire at +time+ — active and its cron matches that minute.
-    # The scheduler calls this each tick (over the {.with_active_persona} set, so an archived persona's
+    # The scheduler calls this each tick (over the {.with_active_agent} set, so an archived agent's
     # duties are already excluded); there is no precomputed next-run, only minute matching.
     #
     # @param time [Time] the moment to test (the tick's +Time.current+)
@@ -78,7 +78,7 @@ module Protege
       run                             = responsibility_runs.create!(status: :pending, correlation_id: SecureRandom.uuid)
       Protege::Current.correlation_id = run.correlation_id
 
-      LoopRunEnqueuedEvent.emit(name:, persona_name: persona.name)
+      LoopRunEnqueuedEvent.emit(name:, agent_name: agent.name)
       ResponsibilityJob.perform_later(run_id: run.id)
       run
     end

data/app/models/protege/tool_use.rb

@@ -13,7 +13,7 @@ module Protege
   # result (the tool loop produces them 1:1). +run_id+ groups one harness run, +turn_index+ the
   # tool-calling round within it, and +position+ the order within a round (an assistant turn may request
   # several calls at once). +tool_call_id+ correlates the call to its result when history is replayed.
-  # +persona_id+ is denormalized for per-persona queries.
+  # +agent_id+ is denormalized for per-agent queries.
   class ToolUse < ApplicationRecord
     # Upper bound on a stored +arguments+/+result+ JSON payload, so a huge tool result (e.g. a large
     # +web_fetch+ body) can't bloat the row. Replay truncates further still (see +#replay_result+).
@@ -24,8 +24,8 @@ module Protege
 
     # ── Associations ────────────────────────────────────────────────────────
 
-    belongs_to :source,  polymorphic: true
-    belongs_to :persona, class_name: 'Protege::Persona'
+    belongs_to :source, polymorphic: true
+    belongs_to :agent, class_name: 'Protege::Agent'
 
     # ── Validations ─────────────────────────────────────────────────────────
 
@@ -78,18 +78,18 @@ module Protege
       # finds the existing rows instead of duplicating them.
       #
       # @param source [Protege::Message, Protege::ResponsibilityRun] the run's owning record
-      # @param persona [Protege::Persona] the persona handling the run
+      # @param agent [Protege::Agent] the agent handling the run
       # @param run_id [String, nil] id grouping this harness run
       # @param turn_index [Integer] the tool-calling round within the run (0-based)
       # @param tool_calls [Array<Protege::Inference::Provider::ToolCall>] the calls the model requested
       # @param tool_results [Array<Protege::ToolResult>] the paired results
       # @return [Array<Protege::ToolUse>] the recorded rows
-      def record_round(source:, persona:, run_id:, turn_index:, tool_calls:, tool_results:)
+      def record_round(source:, agent:, run_id:, turn_index:, tool_calls:, tool_results:)
         transaction do
           tool_calls.each_with_index.map do |call, position|
             result = tool_results[position]
             find_or_create_by!(source:, run_id:, turn_index:, position:) do |use|
-              use.persona      = persona
+              use.agent        = agent
               use.tool_call_id = call.id
               use.tool_name    = call.name
               use.arguments    = clip(call.input.to_json, limit: STORED_PAYLOAD_LIMIT)

data/app/models/protege/toolkit.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Protege
+  # A toolkit — the first "Binding" of the extension framework. A global, dashboard-managed, reusable
+  # bundle of tools (referenced by their manifest ids) and nothing more: it says *what* tools travel
+  # together, not *who* may use them. Permission is a property of the attachment — see +AgentToolkit+ —
+  # so the same toolkit given to two agents can be gated differently, with no tool-list duplication.
+  #
+  # Member tools are a +member_tool_ids+ JSON id list (a checklist over the tool manifest), reconciled
+  # against the live manifest at read time so a stale id (a tool since removed from the code) is skipped.
+  #
+  # A toolkit may be a *system* toolkit — one the engine guarantees exists, identified by a stable +key+
+  # rather than its (renameable) display name (see +Protege::SystemToolkits+). The +all_tools+ system kit
+  # is auto-maintained to hold every registered tool; +default_tools+ is auto-attached to each new agent.
+  # System toolkits can't be deleted from the dashboard. User-created toolkits leave +key+ nil.
+  class Toolkit < ApplicationRecord
+    # The stable key of the auto-maintained toolkit holding every registered tool.
+    ALL_TOOLS_KEY = 'all_tools'
+
+    # The stable key of the toolkit auto-attached to every new agent.
+    DEFAULT_TOOLS_KEY = 'default_tools'
+
+    # ── Concerns ────────────────────────────────────────────────────────────
+
+    # Keep the Toolkits sidebar live (append/replace/remove).
+    include BroadcastableToolkit
+
+    # ── Serialization ─────────────────────────────────────────────────────────
+
+    serialize :member_tool_ids, coder: JSON
+
+    # ── Associations ────────────────────────────────────────────────────────
+
+    with_options dependent: :destroy do
+      has_many :agent_toolkits, class_name: 'Protege::AgentToolkit'
+    end
+    has_many :agents, through: :agent_toolkits
+
+    # ── Callbacks ─────────────────────────────────────────────────────────────
+
+    before_validation :normalize_member_tool_ids
+    before_destroy    :protect_system_toolkit
+
+    # ── Validations ─────────────────────────────────────────────────────────
+
+    validates :name, presence: true, uniqueness: true
+    validates :key,  uniqueness: true, allow_nil: true
+
+    # ── Lookups ─────────────────────────────────────────────────────────────
+
+    class << self
+      # The auto-maintained "All Tools" system toolkit, or nil before it has been synced.
+      #
+      # @return [Protege::Toolkit, nil]
+      def all_tools
+        find_by(key: ALL_TOOLS_KEY)
+      end
+
+      # The "Default Tools" system toolkit auto-attached to new agents, or nil before it has been synced.
+      #
+      # @return [Protege::Toolkit, nil]
+      def default_tools
+        find_by(key: DEFAULT_TOOLS_KEY)
+      end
+    end
+
+    # ── Instance methods ──────────────────────────────────────────────────────
+
+    # Whether this is an engine-managed system toolkit (carries a +key+) — such toolkits can't be deleted,
+    # and +all_tools+ has its membership maintained by the engine rather than the operator.
+    #
+    # @return [Boolean] true when the toolkit is keyed
+    def system?
+      key.present?
+    end
+
+    # Whether this toolkit includes a given tool id.
+    #
+    # @param tool_id [Symbol, String] the tool id to test
+    # @return [Boolean] true when the id is a member
+    def covers?(tool_id)
+      member_tool_ids.map(&:to_sym).include?(tool_id.to_sym)
+    end
+
+    # The member tools that still exist, as manifest entries — stale ids (naming a removed tool) are
+    # dropped, so a toolkit tolerates a member whose tool has since been deleted from the code.
+    #
+    # @return [Array<Protege::Manifest::Entry>] the live member tools
+    def member_tools
+      ids = member_tool_ids.map(&:to_sym)
+      Manifest.registered(:tool).select { |entry| ids.include?(entry.id) }
+    end
+
+    private
+
+    # Coerce +member_tool_ids+ to a clean, deduped array of non-blank strings — so the checklist column
+    # stays tidy however it was assigned (symbols, blanks, duplicates).
+    #
+    # @return [void]
+    def normalize_member_tool_ids
+      self.member_tool_ids = Array(member_tool_ids).map(&:to_s).reject(&:blank?).uniq
+    end
+
+    # Halt destruction of a system toolkit — the engine depends on it existing (it would be recreated on
+    # the next sync anyway). User toolkits (no key) delete normally.
+    #
+    # @return [void]
+    def protect_system_toolkit
+      return unless system?
+
+      errors.add(:base, 'System toolkits cannot be deleted.')
+      throw :abort
+    end
+  end
+end

data/app/models/protege/trace.rb

@@ -9,7 +9,7 @@ module Protege
   # enough to *replay* against the *current* prompts.
   #
   # Deliberately **isolated and minimal**: no associations, no foreign keys, and no identity columns
-  # (persona/provider) — a trace records only what affects training, plus a human review verdict. The
+  # (agent/provider) — a trace records only what affects training, plus a human review verdict. The
   # table can be truncated or dropped without touching anything else. +correlation_id+ + +turn_index+
   # group the turns of one run for retry-safe dedup. Written only by the tracing subscriber
   # (+Protege::Subscribers::Tracing+); reviewed and labeled in the dashboard.

data/app/providers/protege/open_router_provider.rb

@@ -125,6 +125,8 @@ module Protege
       post = build_stream_post(uri, payload)
 
       http.request(post) do |response|
+        raise_for_stream_status(response)
+
         buffer = ''
 
         response.read_body do |chunk|
@@ -137,6 +139,21 @@ module Protege
       end
     end
 
+    # Surface a non-2xx streaming response as the matching +Protege::Error+, mirroring +raise_for_status+
+    # for the non-streaming path. A streamed error (e.g. HTTP 402 insufficient credits) arrives as a normal
+    # response whose body is the JSON error, not an SSE event stream — without this it would be parsed as
+    # empty tokens and swallowed, so the run would silently produce no output and no failure event.
+    #
+    # @param response [Net::HTTPResponse] the streaming response, before its body is consumed as SSE
+    # @return [void]
+    # @raise [Protege::Error] the error class matching a non-2xx status
+    def raise_for_stream_status(response)
+      code = response.code.to_i
+      return if (200..299).cover?(code)
+
+      raise_for_status(Struct.new(:status, :body).new(code, response.read_body))
+    end
+
     # Construct the Net::HTTP transport for an SSE request.
     #
     # @param uri [URI] the fully resolved chat-completions endpoint

data/app/resolvers/README.md

@@ -4,7 +4,7 @@
 > User-facing docs live in `site/developer-experience/extensions/resolvers.md`; this file is the
 > precise contract for contributors working in the engine.
 
-A **resolver** assembles the context the LLM sees *before* an inference run. Each persona declares an
+A **resolver** assembles the context the LLM sees *before* an inference run. Each agent declares an
 ordered chain of resolvers (`message_resolvers` for replies, `responsibility_resolvers` for scheduled
 runs); the harness runs the chain, concatenates every resolver's output, and hands the result to the
 provider as the opening messages of the request.
@@ -157,7 +157,7 @@ right, and the request is well-formed.
 
 | Attribute        | Type                          | Reply run           | Scheduled run |
 |------------------|-------------------------------|---------------------|---------------|
-| `persona`        | `Protege::Persona`            | present             | present |
+| `agent`        | `Protege::Agent`            | present             | present |
 | `config`         | `Protege::Configuration`      | present (frozen)    | present (frozen) |
 | `logger`         | `Logger`                      | present             | present |
 | `correlation_id` | `String, nil`                 | present             | present |
@@ -173,7 +173,7 @@ they never mutate it.
 ## Built-in resolvers
 
 All live in `app/resolvers/protege/` as flat `Protege::<Name>` constants (e.g.
-`Protege::ThreadHistoryResolver`); a persona names one by that constant. Each returns a `ModelMessage`,
+`Protege::ThreadHistoryResolver`); an agent names one by that constant. Each returns a `ModelMessage`,
 an array of them, or `nil`.
 
 ### `ThreadHistoryResolver`
@@ -218,7 +218,7 @@ Loads ActiveRecord record(s) and contributes them as one message — the DB coun
 ### `LoadTextResolver`
 
 The computed-text primitive: a block returns a `String`, contributed as one message. The clean way to
-inject a persona's DB-column system prompt.
+inject an agent's DB-column system prompt.
 
 - **Constructor:** `initialize(role: :system, &block)` — the **required** block receives the context and
   returns the text.

data/app/resolvers/protege/load_file_resolver.rb

@@ -6,22 +6,22 @@ module Protege
   # prompt, a knowledge document, few-shot examples — by choosing the +role+ of the emitted message.
   #
   # The path is given either statically or as a block that receives the resolver context, so it can
-  # be derived from the inbound message or persona (e.g. a per-persona prompt file). Path resolution
+  # be derived from the inbound message or agent (e.g. a per-agent prompt file). Path resolution
   # mirrors ordinary shell intuition, so the same resolver works in development and in any production
   # deployment:
-  # - a relative path (+config/personas/agent.md+, +./agent.md+) resolves against the host app root
+  # - a relative path (+config/agents/agent.md+, +./agent.md+) resolves against the host app root
   #   (+Rails.root+) — i.e. a file deployed with the app, which is reliably readable everywhere.
   # - an absolute path (+/data/prompts/agent.md+) is used as-is, so an attached volume or mounted
   #   secret just needs its fully-qualified path.
   #
   # LoadFileResolver is a *developer-wired* resolver, never a model-callable tool — the path is author-trusted
-  # code, so even absolute reads carry the same trust as any code in the persona. A missing file is a
+  # code, so even absolute reads carry the same trust as any code in the agent. A missing file is a
   # misconfiguration and raises +Protege::ResolverFileNotFoundError+; a blank file contributes
   # nothing (returns +nil+).
   #
   #   resolvers do |chain|
-  #     chain.use Protege::LoadFileResolver, 'config/personas/agent.md'
-  #     chain.use(Protege::LoadFileResolver) { |ctx| "config/personas/#{ctx.persona.name.parameterize}.md" }
+  #     chain.use Protege::LoadFileResolver, 'config/agents/agent.md'
+  #     chain.use(Protege::LoadFileResolver) { |ctx| "config/agents/#{ctx.agent.name.parameterize}.md" }
   #   end
   class LoadFileResolver < Protege::Resolver
     # @param path [String, nil] file to read; relative paths resolve against +Rails.root+, absolute

data/app/resolvers/protege/load_text_resolver.rb

@@ -3,11 +3,11 @@
 module Protege
   # General-purpose resolver that runs a block and contributes its returned String as one context
   # message — the computed-text sibling of +LoadFileResolver+ (text from a file) and +LoadRecordResolver+ (text from
-  # records). The block receives the resolver context, so the text can be derived from the persona or
-  # the inbound message. The canonical use is a persona's system prompt held in a column:
+  # records). The block receives the resolver context, so the text can be derived from the agent or
+  # the inbound message. The canonical use is an agent's system prompt held in a column:
   #
   #   resolvers do |chain|
-  #     chain.use(Protege::LoadTextResolver, role: :system) { |ctx| ctx.persona.instructions }
+  #     chain.use(Protege::LoadTextResolver, role: :system) { |ctx| ctx.agent.instructions }
   #   end
   #
   # +role+ chooses how the text enters the conversation (+:system+ for a prompt, +:user+/+:assistant+

data/app/resolvers/protege/thread_history_resolver.rb

@@ -90,7 +90,7 @@ module Protege
     # @return [Array<Protege::ModelMessage>] the assistant turn followed by its results
     def round_messages(rows)
       assistant = message(role: :assistant, content: '', tool_calls: rows.map(&:to_provider_tool_call))
-      
+
       results   = rows.map do |row|
         message(role: :tool, tool_call_id: row.tool_call_id, content: row.replay_result(limit: REPLAY_RESULT_LIMIT))
       end

data/app/services/protege/message_search.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 module Protege
-  # Cross-persona email search behind the console's search page — a PORO service object (not an
-  # ActiveRecord model, and not the persona-scoped +search_emails+ agent tool).
+  # Cross-agent email search behind the console's search page — a PORO service object (not an
+  # ActiveRecord model, and not the agent-scoped +search_emails+ agent tool).
   #
   # Each field narrows the +Message+ relation: +from+ scans the sender, +recipients+ spans the
   # to/cc/bcc lists, +subject+ and +body+ (text + html) scan their columns, and +attachments+ matches

data/app/services/protege/system_toolkits.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Protege
+  # Maintains the engine's *system* toolkits — the two toolkit records the framework guarantees exist,
+  # identified by a stable +key+ (see +Toolkit+):
+  #
+  # * **All Tools** (+all_tools+) — always holds every registered tool. Its membership is engine-owned:
+  #   each sync rewrites it to the live tool manifest, so a tool added in code shows up automatically and
+  #   an operator's edits don't stick.
+  # * **Default Tools** (+default_tools+) — auto-attached to every new agent (see +Toolable+). The engine
+  #   only *seeds* it (with +send_email+, so a fresh agent can at least reply) on first creation;
+  #   thereafter its membership is the operator's to curate, so later syncs leave it alone.
+  #
+  # Sync is idempotent and safe to run repeatedly. It runs like any other seed data — not at boot (writing
+  # to the DB from an initializer is an anti-pattern): the +protege:toolkits:sync+ rake task on deploy and
+  # the host's +db/seeds.rb+ in development. Both eager-load the app first so the tool manifest is complete
+  # (rake tasks don't eager-load by default), which is what makes All Tools capture every registered tool.
+  class SystemToolkits
+    class << self
+      # Ensure both system toolkits exist and refresh All Tools' membership.
+      #
+      # @return [void]
+      def sync!
+        new.sync!
+      end
+    end
+
+    # Ensure both system toolkits exist and refresh All Tools' membership.
+    #
+    # @return [void]
+    def sync!
+      sync_all_tools
+      ensure_default_tools
+    end
+
+    private
+
+    # Create or update the All Tools toolkit so it holds every registered tool.
+    #
+    # @return [void]
+    def sync_all_tools
+      toolkit = Toolkit.find_or_initialize_by(key: Toolkit::ALL_TOOLS_KEY)
+
+      toolkit.name            = 'All Tools'
+      toolkit.description     = 'Automatically managed — always contains every registered tool, refreshed ' \
+                                'on each deploy. Its members are not editable. Attach it to an agent to ' \
+                                'grant the full tool catalogue.'
+      toolkit.member_tool_ids = Manifest.registered(:tool).map { |entry| entry.id.to_s }
+      toolkit.save!
+    end
+
+    # Ensure the Default Tools toolkit exists. On first creation it is seeded with +send_email+ so a new
+    # agent is immediately able to reply; on later syncs its membership is left untouched (operator-owned).
+    #
+    # @return [void]
+    def ensure_default_tools
+      toolkit = Toolkit.find_or_initialize_by(key: Toolkit::DEFAULT_TOOLS_KEY)
+      return unless toolkit.new_record?
+
+      toolkit.name            = 'Default Tools'
+      toolkit.description     = 'Attached to every new agent automatically. Curate its members to set the ' \
+                                'baseline tools an agent starts with.'
+      toolkit.member_tool_ids = ['send_email']
+      toolkit.save!
+    end
+  end
+end

data/app/tools/protege/create_file_tool.rb

@@ -40,6 +40,8 @@ module Protege
       rows, for html/svg write the markup, for json write the JSON.
     DESC
 
+    summary 'Create a file (CSV, HTML, Markdown, JSON…) to attach to an email.'
+
     input_schema(
       type:                 'object',
       additionalProperties: false,

data/app/tools/protege/read_attachment_tool.rb

@@ -5,7 +5,7 @@ module Protege
   # publishes it in the LLM's tool catalog (id +:read_attachment+).
   #
   # The agent learns a file's blob id from the +ThreadHistoryResolver+/inbound note ("…, id: 123") or
-  # from +create_file+. Resolution is by blob id (see +Protege::StoredFile.find+); persona scoping is
+  # from +create_file+. Resolution is by blob id (see +Protege::StoredFile.find+); agent scoping is
   # deferred to a later pass (see the blob-currency spec §9), so any known blob id currently resolves.
   # Behaviour by type:
   #
@@ -23,6 +23,8 @@ module Protege
       shown to you directly to view. Other types (such as video or archives) can't be read.
     DESC
 
+    summary 'Read a file from the conversation by its id.'
+
     input_schema(
       type:                 'object',
       additionalProperties: false,